"Fossies" - the Fresh Open Source Software Archive

Member "numpy-1.16.4/numpy/core/_add_newdocs.py" (27 May 2019, 203038 Bytes) of package /linux/misc/numpy-1.16.4.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Python source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "_add_newdocs.py" see the Fossies "Dox" file reference documentation.

    1 """
    2 This is only meant to add docs to objects defined in C-extension modules.
    3 The purpose is to allow easier editing of the docstrings without
    4 requiring a re-compile.
    5 
    6 NOTE: Many of the methods of ndarray have corresponding functions.
    7       If you update these docstrings, please keep also the ones in
    8       core/fromnumeric.py, core/defmatrix.py up-to-date.
    9 
   10 """
   11 from __future__ import division, absolute_import, print_function
   12 
   13 from numpy.core import numerictypes as _numerictypes
   14 from numpy.core import dtype
   15 from numpy.core.function_base import add_newdoc
   16 
   17 ###############################################################################
   18 #
   19 # flatiter
   20 #
   21 # flatiter needs a toplevel description
   22 #
   23 ###############################################################################
   24 
   25 add_newdoc('numpy.core', 'flatiter',
   26     """
   27     Flat iterator object to iterate over arrays.
   28 
   29     A `flatiter` iterator is returned by ``x.flat`` for any array `x`.
   30     It allows iterating over the array as if it were a 1-D array,
   31     either in a for-loop or by calling its `next` method.
   32 
   33     Iteration is done in row-major, C-style order (the last
   34     index varying the fastest). The iterator can also be indexed using
   35     basic slicing or advanced indexing.
   36 
   37     See Also
   38     --------
   39     ndarray.flat : Return a flat iterator over an array.
   40     ndarray.flatten : Returns a flattened copy of an array.
   41 
   42     Notes
   43     -----
   44     A `flatiter` iterator can not be constructed directly from Python code
   45     by calling the `flatiter` constructor.
   46 
   47     Examples
   48     --------
   49     >>> x = np.arange(6).reshape(2, 3)
   50     >>> fl = x.flat
   51     >>> type(fl)
   52     <type 'numpy.flatiter'>
   53     >>> for item in fl:
   54     ...     print(item)
   55     ...
   56     0
   57     1
   58     2
   59     3
   60     4
   61     5
   62 
   63     >>> fl[2:4]
   64     array([2, 3])
   65 
   66     """)
   67 
   68 # flatiter attributes
   69 
   70 add_newdoc('numpy.core', 'flatiter', ('base',
   71     """
   72     A reference to the array that is iterated over.
   73 
   74     Examples
   75     --------
   76     >>> x = np.arange(5)
   77     >>> fl = x.flat
   78     >>> fl.base is x
   79     True
   80 
   81     """))
   82 
   83 
   84 
   85 add_newdoc('numpy.core', 'flatiter', ('coords',
   86     """
   87     An N-dimensional tuple of current coordinates.
   88 
   89     Examples
   90     --------
   91     >>> x = np.arange(6).reshape(2, 3)
   92     >>> fl = x.flat
   93     >>> fl.coords
   94     (0, 0)
   95     >>> fl.next()
   96     0
   97     >>> fl.coords
   98     (0, 1)
   99 
  100     """))
  101 
  102 
  103 
  104 add_newdoc('numpy.core', 'flatiter', ('index',
  105     """
  106     Current flat index into the array.
  107 
  108     Examples
  109     --------
  110     >>> x = np.arange(6).reshape(2, 3)
  111     >>> fl = x.flat
  112     >>> fl.index
  113     0
  114     >>> fl.next()
  115     0
  116     >>> fl.index
  117     1
  118 
  119     """))
  120 
  121 # flatiter functions
  122 
  123 add_newdoc('numpy.core', 'flatiter', ('__array__',
  124     """__array__(type=None) Get array from iterator
  125 
  126     """))
  127 
  128 
  129 add_newdoc('numpy.core', 'flatiter', ('copy',
  130     """
  131     copy()
  132 
  133     Get a copy of the iterator as a 1-D array.
  134 
  135     Examples
  136     --------
  137     >>> x = np.arange(6).reshape(2, 3)
  138     >>> x
  139     array([[0, 1, 2],
  140            [3, 4, 5]])
  141     >>> fl = x.flat
  142     >>> fl.copy()
  143     array([0, 1, 2, 3, 4, 5])
  144 
  145     """))
  146 
  147 
  148 ###############################################################################
  149 #
  150 # nditer
  151 #
  152 ###############################################################################
  153 
  154 add_newdoc('numpy.core', 'nditer',
  155     """
  156     Efficient multi-dimensional iterator object to iterate over arrays.
  157     To get started using this object, see the
  158     :ref:`introductory guide to array iteration <arrays.nditer>`.
  159 
  160     Parameters
  161     ----------
  162     op : ndarray or sequence of array_like
  163         The array(s) to iterate over.
  164     flags : sequence of str, optional
  165         Flags to control the behavior of the iterator.
  166 
  167           * "buffered" enables buffering when required.
  168           * "c_index" causes a C-order index to be tracked.
  169           * "f_index" causes a Fortran-order index to be tracked.
  170           * "multi_index" causes a multi-index, or a tuple of indices
  171             with one per iteration dimension, to be tracked.
  172           * "common_dtype" causes all the operands to be converted to
  173             a common data type, with copying or buffering as necessary.
  174           * "copy_if_overlap" causes the iterator to determine if read
  175             operands have overlap with write operands, and make temporary
  176             copies as necessary to avoid overlap. False positives (needless
  177             copying) are possible in some cases.
  178           * "delay_bufalloc" delays allocation of the buffers until
  179             a reset() call is made. Allows "allocate" operands to
  180             be initialized before their values are copied into the buffers.
  181           * "external_loop" causes the `values` given to be
  182             one-dimensional arrays with multiple values instead of
  183             zero-dimensional arrays.
  184           * "grow_inner" allows the `value` array sizes to be made
  185             larger than the buffer size when both "buffered" and
  186             "external_loop" is used.
  187           * "ranged" allows the iterator to be restricted to a sub-range
  188             of the iterindex values.
  189           * "refs_ok" enables iteration of reference types, such as
  190             object arrays.
  191           * "reduce_ok" enables iteration of "readwrite" operands
  192             which are broadcasted, also known as reduction operands.
  193           * "zerosize_ok" allows `itersize` to be zero.
  194     op_flags : list of list of str, optional
  195         This is a list of flags for each operand. At minimum, one of
  196         "readonly", "readwrite", or "writeonly" must be specified.
  197 
  198           * "readonly" indicates the operand will only be read from.
  199           * "readwrite" indicates the operand will be read from and written to.
  200           * "writeonly" indicates the operand will only be written to.
  201           * "no_broadcast" prevents the operand from being broadcasted.
  202           * "contig" forces the operand data to be contiguous.
  203           * "aligned" forces the operand data to be aligned.
  204           * "nbo" forces the operand data to be in native byte order.
  205           * "copy" allows a temporary read-only copy if required.
  206           * "updateifcopy" allows a temporary read-write copy if required.
  207           * "allocate" causes the array to be allocated if it is None
  208             in the `op` parameter.
  209           * "no_subtype" prevents an "allocate" operand from using a subtype.
  210           * "arraymask" indicates that this operand is the mask to use
  211             for selecting elements when writing to operands with the
  212             'writemasked' flag set. The iterator does not enforce this,
  213             but when writing from a buffer back to the array, it only
  214             copies those elements indicated by this mask.
  215           * 'writemasked' indicates that only elements where the chosen
  216             'arraymask' operand is True will be written to.
  217           * "overlap_assume_elementwise" can be used to mark operands that are
  218             accessed only in the iterator order, to allow less conservative
  219             copying when "copy_if_overlap" is present.
  220     op_dtypes : dtype or tuple of dtype(s), optional
  221         The required data type(s) of the operands. If copying or buffering
  222         is enabled, the data will be converted to/from their original types.
  223     order : {'C', 'F', 'A', 'K'}, optional
  224         Controls the iteration order. 'C' means C order, 'F' means
  225         Fortran order, 'A' means 'F' order if all the arrays are Fortran
  226         contiguous, 'C' order otherwise, and 'K' means as close to the
  227         order the array elements appear in memory as possible. This also
  228         affects the element memory order of "allocate" operands, as they
  229         are allocated to be compatible with iteration order.
  230         Default is 'K'.
  231     casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
  232         Controls what kind of data casting may occur when making a copy
  233         or buffering.  Setting this to 'unsafe' is not recommended,
  234         as it can adversely affect accumulations.
  235 
  236           * 'no' means the data types should not be cast at all.
  237           * 'equiv' means only byte-order changes are allowed.
  238           * 'safe' means only casts which can preserve values are allowed.
  239           * 'same_kind' means only safe casts or casts within a kind,
  240             like float64 to float32, are allowed.
  241           * 'unsafe' means any data conversions may be done.
  242     op_axes : list of list of ints, optional
  243         If provided, is a list of ints or None for each operands.
  244         The list of axes for an operand is a mapping from the dimensions
  245         of the iterator to the dimensions of the operand. A value of
  246         -1 can be placed for entries, causing that dimension to be
  247         treated as "newaxis".
  248     itershape : tuple of ints, optional
  249         The desired shape of the iterator. This allows "allocate" operands
  250         with a dimension mapped by op_axes not corresponding to a dimension
  251         of a different operand to get a value not equal to 1 for that
  252         dimension.
  253     buffersize : int, optional
  254         When buffering is enabled, controls the size of the temporary
  255         buffers. Set to 0 for the default value.
  256 
  257     Attributes
  258     ----------
  259     dtypes : tuple of dtype(s)
  260         The data types of the values provided in `value`. This may be
  261         different from the operand data types if buffering is enabled.
  262         Valid only before the iterator is closed.
  263     finished : bool
  264         Whether the iteration over the operands is finished or not.
  265     has_delayed_bufalloc : bool
  266         If True, the iterator was created with the "delay_bufalloc" flag,
  267         and no reset() function was called on it yet.
  268     has_index : bool
  269         If True, the iterator was created with either the "c_index" or
  270         the "f_index" flag, and the property `index` can be used to
  271         retrieve it.
  272     has_multi_index : bool
  273         If True, the iterator was created with the "multi_index" flag,
  274         and the property `multi_index` can be used to retrieve it.
  275     index
  276         When the "c_index" or "f_index" flag was used, this property
  277         provides access to the index. Raises a ValueError if accessed
  278         and `has_index` is False.
  279     iterationneedsapi : bool
  280         Whether iteration requires access to the Python API, for example
  281         if one of the operands is an object array.
  282     iterindex : int
  283         An index which matches the order of iteration.
  284     itersize : int
  285         Size of the iterator.
  286     itviews
  287         Structured view(s) of `operands` in memory, matching the reordered
  288         and optimized iterator access pattern. Valid only before the iterator
  289         is closed.
  290     multi_index
  291         When the "multi_index" flag was used, this property
  292         provides access to the index. Raises a ValueError if accessed
  293         accessed and `has_multi_index` is False.
  294     ndim : int
  295         The iterator's dimension.
  296     nop : int
  297         The number of iterator operands.
  298     operands : tuple of operand(s)
  299         The array(s) to be iterated over. Valid only before the iterator is
  300         closed.
  301     shape : tuple of ints
  302         Shape tuple, the shape of the iterator.
  303     value
  304         Value of `operands` at current iteration. Normally, this is a
  305         tuple of array scalars, but if the flag "external_loop" is used,
  306         it is a tuple of one dimensional arrays.
  307 
  308     Notes
  309     -----
  310     `nditer` supersedes `flatiter`.  The iterator implementation behind
  311     `nditer` is also exposed by the NumPy C API.
  312 
  313     The Python exposure supplies two iteration interfaces, one which follows
  314     the Python iterator protocol, and another which mirrors the C-style
  315     do-while pattern.  The native Python approach is better in most cases, but
  316     if you need the iterator's coordinates or index, use the C-style pattern.
  317 
  318     Examples
  319     --------
  320     Here is how we might write an ``iter_add`` function, using the
  321     Python iterator protocol::
  322 
  323         def iter_add_py(x, y, out=None):
  324             addop = np.add
  325             it = np.nditer([x, y, out], [],
  326                         [['readonly'], ['readonly'], ['writeonly','allocate']])
  327             with it:
  328                 for (a, b, c) in it:
  329                     addop(a, b, out=c)
  330             return it.operands[2]
  331 
  332     Here is the same function, but following the C-style pattern::
  333 
  334         def iter_add(x, y, out=None):
  335             addop = np.add
  336 
  337             it = np.nditer([x, y, out], [],
  338                         [['readonly'], ['readonly'], ['writeonly','allocate']])
  339             with it:
  340                 while not it.finished:
  341                     addop(it[0], it[1], out=it[2])
  342                     it.iternext()
  343 
  344                 return it.operands[2]
  345 
  346     Here is an example outer product function::
  347 
  348         def outer_it(x, y, out=None):
  349             mulop = np.multiply
  350 
  351             it = np.nditer([x, y, out], ['external_loop'],
  352                     [['readonly'], ['readonly'], ['writeonly', 'allocate']],
  353                     op_axes=[list(range(x.ndim)) + [-1] * y.ndim,
  354                              [-1] * x.ndim + list(range(y.ndim)),
  355                              None])
  356             with it:
  357                 for (a, b, c) in it:
  358                     mulop(a, b, out=c)
  359                 return it.operands[2]
  360 
  361         >>> a = np.arange(2)+1
  362         >>> b = np.arange(3)+1
  363         >>> outer_it(a,b)
  364         array([[1, 2, 3],
  365                [2, 4, 6]])
  366 
  367     Here is an example function which operates like a "lambda" ufunc::
  368 
  369         def luf(lamdaexpr, *args, **kwargs):
  370             "luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)"
  371             nargs = len(args)
  372             op = (kwargs.get('out',None),) + args
  373             it = np.nditer(op, ['buffered','external_loop'],
  374                     [['writeonly','allocate','no_broadcast']] +
  375                                     [['readonly','nbo','aligned']]*nargs,
  376                     order=kwargs.get('order','K'),
  377                     casting=kwargs.get('casting','safe'),
  378                     buffersize=kwargs.get('buffersize',0))
  379             while not it.finished:
  380                 it[0] = lamdaexpr(*it[1:])
  381                 it.iternext()
  382                 return it.operands[0]
  383 
  384         >>> a = np.arange(5)
  385         >>> b = np.ones(5)
  386         >>> luf(lambda i,j:i*i + j/2, a, b)
  387         array([  0.5,   1.5,   4.5,   9.5,  16.5])
  388 
  389     If operand flags `"writeonly"` or `"readwrite"` are used the operands may
  390     be views into the original data with the `WRITEBACKIFCOPY` flag. In this case
  391     nditer must be used as a context manager or the nditer.close
  392     method must be called before using the result. The temporary
  393     data will be written back to the original data when the `__exit__`
  394     function is called but not before:
  395 
  396         >>> a = np.arange(6, dtype='i4')[::-2]
  397         >>> with nditer(a, [],
  398         ...        [['writeonly', 'updateifcopy']],
  399         ...        casting='unsafe',
  400         ...        op_dtypes=[np.dtype('f4')]) as i:
  401         ...    x = i.operands[0]
  402         ...    x[:] = [-1, -2, -3]
  403         ...    # a still unchanged here
  404         >>> a, x
  405         array([-1, -2, -3]), array([-1, -2, -3])
  406 
  407     It is important to note that once the iterator is exited, dangling
  408     references (like `x` in the example) may or may not share data with
  409     the original data `a`. If writeback semantics were active, i.e. if
  410     `x.base.flags.writebackifcopy` is `True`, then exiting the iterator
  411     will sever the connection between `x` and `a`, writing to `x` will
  412     no longer write to `a`. If writeback semantics are not active, then
  413     `x.data` will still point at some part of `a.data`, and writing to
  414     one will affect the other.
  415 
  416     """)
  417 
  418 # nditer methods
  419 
  420 add_newdoc('numpy.core', 'nditer', ('copy',
  421     """
  422     copy()
  423 
  424     Get a copy of the iterator in its current state.
  425 
  426     Examples
  427     --------
  428     >>> x = np.arange(10)
  429     >>> y = x + 1
  430     >>> it = np.nditer([x, y])
  431     >>> it.next()
  432     (array(0), array(1))
  433     >>> it2 = it.copy()
  434     >>> it2.next()
  435     (array(1), array(2))
  436 
  437     """))
  438 
  439 add_newdoc('numpy.core', 'nditer', ('operands',
  440     """
  441     operands[`Slice`]
  442 
  443     The array(s) to be iterated over. Valid only before the iterator is closed.
  444     """))
  445 
  446 add_newdoc('numpy.core', 'nditer', ('debug_print',
  447     """
  448     debug_print()
  449 
  450     Print the current state of the `nditer` instance and debug info to stdout.
  451 
  452     """))
  453 
  454 add_newdoc('numpy.core', 'nditer', ('enable_external_loop',
  455     """
  456     enable_external_loop()
  457 
  458     When the "external_loop" was not used during construction, but
  459     is desired, this modifies the iterator to behave as if the flag
  460     was specified.
  461 
  462     """))
  463 
  464 add_newdoc('numpy.core', 'nditer', ('iternext',
  465     """
  466     iternext()
  467 
  468     Check whether iterations are left, and perform a single internal iteration
  469     without returning the result.  Used in the C-style pattern do-while
  470     pattern.  For an example, see `nditer`.
  471 
  472     Returns
  473     -------
  474     iternext : bool
  475         Whether or not there are iterations left.
  476 
  477     """))
  478 
  479 add_newdoc('numpy.core', 'nditer', ('remove_axis',
  480     """
  481     remove_axis(i)
  482 
  483     Removes axis `i` from the iterator. Requires that the flag "multi_index"
  484     be enabled.
  485 
  486     """))
  487 
  488 add_newdoc('numpy.core', 'nditer', ('remove_multi_index',
  489     """
  490     remove_multi_index()
  491 
  492     When the "multi_index" flag was specified, this removes it, allowing
  493     the internal iteration structure to be optimized further.
  494 
  495     """))
  496 
  497 add_newdoc('numpy.core', 'nditer', ('reset',
  498     """
  499     reset()
  500 
  501     Reset the iterator to its initial state.
  502 
  503     """))
  504 
  505 add_newdoc('numpy.core', 'nested_iters',
  506     """
  507     Create nditers for use in nested loops
  508 
  509     Create a tuple of `nditer` objects which iterate in nested loops over
  510     different axes of the op argument. The first iterator is used in the
  511     outermost loop, the last in the innermost loop. Advancing one will change
  512     the subsequent iterators to point at its new element.
  513 
  514     Parameters
  515     ----------
  516     op : ndarray or sequence of array_like
  517         The array(s) to iterate over.
  518 
  519     axes : list of list of int
  520         Each item is used as an "op_axes" argument to an nditer
  521 
  522     flags, op_flags, op_dtypes, order, casting, buffersize (optional)
  523         See `nditer` parameters of the same name
  524 
  525     Returns
  526     -------
  527     iters : tuple of nditer
  528         An nditer for each item in `axes`, outermost first
  529 
  530     See Also
  531     --------
  532     nditer
  533 
  534     Examples
  535     --------
  536 
  537     Basic usage. Note how y is the "flattened" version of
  538     [a[:, 0, :], a[:, 1, 0], a[:, 2, :]] since we specified
  539     the first iter's axes as [1]
  540 
  541     >>> a = np.arange(12).reshape(2, 3, 2)
  542     >>> i, j = np.nested_iters(a, [[1], [0, 2]], flags=["multi_index"])
  543     >>> for x in i:
  544     ...      print(i.multi_index)
  545     ...      for y in j:
  546     ...          print('', j.multi_index, y)
  547 
  548     (0,)
  549      (0, 0) 0
  550      (0, 1) 1
  551      (1, 0) 6
  552      (1, 1) 7
  553     (1,)
  554      (0, 0) 2
  555      (0, 1) 3
  556      (1, 0) 8
  557      (1, 1) 9
  558     (2,)
  559      (0, 0) 4
  560      (0, 1) 5
  561      (1, 0) 10
  562      (1, 1) 11
  563 
  564     """)
  565 
  566 add_newdoc('numpy.core', 'nditer', ('close',
  567     """
  568     close()
  569 
  570     Resolve all writeback semantics in writeable operands.
  571 
  572     See Also
  573     --------
  574 
  575     :ref:`nditer-context-manager`
  576 
  577     """))
  578 
  579 
  580 ###############################################################################
  581 #
  582 # broadcast
  583 #
  584 ###############################################################################
  585 
  586 add_newdoc('numpy.core', 'broadcast',
  587     """
  588     Produce an object that mimics broadcasting.
  589 
  590     Parameters
  591     ----------
  592     in1, in2, ... : array_like
  593         Input parameters.
  594 
  595     Returns
  596     -------
  597     b : broadcast object
  598         Broadcast the input parameters against one another, and
  599         return an object that encapsulates the result.
  600         Amongst others, it has ``shape`` and ``nd`` properties, and
  601         may be used as an iterator.
  602 
  603     See Also
  604     --------
  605     broadcast_arrays
  606     broadcast_to
  607 
  608     Examples
  609     --------
  610 
  611     Manually adding two vectors, using broadcasting:
  612 
  613     >>> x = np.array([[1], [2], [3]])
  614     >>> y = np.array([4, 5, 6])
  615     >>> b = np.broadcast(x, y)
  616 
  617     >>> out = np.empty(b.shape)
  618     >>> out.flat = [u+v for (u,v) in b]
  619     >>> out
  620     array([[ 5.,  6.,  7.],
  621            [ 6.,  7.,  8.],
  622            [ 7.,  8.,  9.]])
  623 
  624     Compare against built-in broadcasting:
  625 
  626     >>> x + y
  627     array([[5, 6, 7],
  628            [6, 7, 8],
  629            [7, 8, 9]])
  630 
  631     """)
  632 
  633 # attributes
  634 
  635 add_newdoc('numpy.core', 'broadcast', ('index',
  636     """
  637     current index in broadcasted result
  638 
  639     Examples
  640     --------
  641     >>> x = np.array([[1], [2], [3]])
  642     >>> y = np.array([4, 5, 6])
  643     >>> b = np.broadcast(x, y)
  644     >>> b.index
  645     0
  646     >>> b.next(), b.next(), b.next()
  647     ((1, 4), (1, 5), (1, 6))
  648     >>> b.index
  649     3
  650 
  651     """))
  652 
  653 add_newdoc('numpy.core', 'broadcast', ('iters',
  654     """
  655     tuple of iterators along ``self``'s "components."
  656 
  657     Returns a tuple of `numpy.flatiter` objects, one for each "component"
  658     of ``self``.
  659 
  660     See Also
  661     --------
  662     numpy.flatiter
  663 
  664     Examples
  665     --------
  666     >>> x = np.array([1, 2, 3])
  667     >>> y = np.array([[4], [5], [6]])
  668     >>> b = np.broadcast(x, y)
  669     >>> row, col = b.iters
  670     >>> row.next(), col.next()
  671     (1, 4)
  672 
  673     """))
  674 
  675 add_newdoc('numpy.core', 'broadcast', ('ndim',
  676     """
  677     Number of dimensions of broadcasted result. Alias for `nd`.
  678 
  679     .. versionadded:: 1.12.0
  680 
  681     Examples
  682     --------
  683     >>> x = np.array([1, 2, 3])
  684     >>> y = np.array([[4], [5], [6]])
  685     >>> b = np.broadcast(x, y)
  686     >>> b.ndim
  687     2
  688 
  689     """))
  690 
  691 add_newdoc('numpy.core', 'broadcast', ('nd',
  692     """
  693     Number of dimensions of broadcasted result. For code intended for NumPy
  694     1.12.0 and later the more consistent `ndim` is preferred.
  695 
  696     Examples
  697     --------
  698     >>> x = np.array([1, 2, 3])
  699     >>> y = np.array([[4], [5], [6]])
  700     >>> b = np.broadcast(x, y)
  701     >>> b.nd
  702     2
  703 
  704     """))
  705 
  706 add_newdoc('numpy.core', 'broadcast', ('numiter',
  707     """
  708     Number of iterators possessed by the broadcasted result.
  709 
  710     Examples
  711     --------
  712     >>> x = np.array([1, 2, 3])
  713     >>> y = np.array([[4], [5], [6]])
  714     >>> b = np.broadcast(x, y)
  715     >>> b.numiter
  716     2
  717 
  718     """))
  719 
  720 add_newdoc('numpy.core', 'broadcast', ('shape',
  721     """
  722     Shape of broadcasted result.
  723 
  724     Examples
  725     --------
  726     >>> x = np.array([1, 2, 3])
  727     >>> y = np.array([[4], [5], [6]])
  728     >>> b = np.broadcast(x, y)
  729     >>> b.shape
  730     (3, 3)
  731 
  732     """))
  733 
  734 add_newdoc('numpy.core', 'broadcast', ('size',
  735     """
  736     Total size of broadcasted result.
  737 
  738     Examples
  739     --------
  740     >>> x = np.array([1, 2, 3])
  741     >>> y = np.array([[4], [5], [6]])
  742     >>> b = np.broadcast(x, y)
  743     >>> b.size
  744     9
  745 
  746     """))
  747 
  748 add_newdoc('numpy.core', 'broadcast', ('reset',
  749     """
  750     reset()
  751 
  752     Reset the broadcasted result's iterator(s).
  753 
  754     Parameters
  755     ----------
  756     None
  757 
  758     Returns
  759     -------
  760     None
  761 
  762     Examples
  763     --------
  764     >>> x = np.array([1, 2, 3])
  765     >>> y = np.array([[4], [5], [6]]
  766     >>> b = np.broadcast(x, y)
  767     >>> b.index
  768     0
  769     >>> b.next(), b.next(), b.next()
  770     ((1, 4), (2, 4), (3, 4))
  771     >>> b.index
  772     3
  773     >>> b.reset()
  774     >>> b.index
  775     0
  776 
  777     """))
  778 
  779 ###############################################################################
  780 #
  781 # numpy functions
  782 #
  783 ###############################################################################
  784 
  785 add_newdoc('numpy.core.multiarray', 'array',
  786     """
  787     array(object, dtype=None, copy=True, order='K', subok=False, ndmin=0)
  788 
  789     Create an array.
  790 
  791     Parameters
  792     ----------
  793     object : array_like
  794         An array, any object exposing the array interface, an object whose
  795         __array__ method returns an array, or any (nested) sequence.
  796     dtype : data-type, optional
  797         The desired data-type for the array.  If not given, then the type will
  798         be determined as the minimum type required to hold the objects in the
  799         sequence.  This argument can only be used to 'upcast' the array.  For
  800         downcasting, use the .astype(t) method.
  801     copy : bool, optional
  802         If true (default), then the object is copied.  Otherwise, a copy will
  803         only be made if __array__ returns a copy, if obj is a nested sequence,
  804         or if a copy is needed to satisfy any of the other requirements
  805         (`dtype`, `order`, etc.).
  806     order : {'K', 'A', 'C', 'F'}, optional
  807         Specify the memory layout of the array. If object is not an array, the
  808         newly created array will be in C order (row major) unless 'F' is
  809         specified, in which case it will be in Fortran order (column major).
  810         If object is an array the following holds.
  811 
  812         ===== ========= ===================================================
  813         order  no copy                     copy=True
  814         ===== ========= ===================================================
  815         'K'   unchanged F & C order preserved, otherwise most similar order
  816         'A'   unchanged F order if input is F and not C, otherwise C order
  817         'C'   C order   C order
  818         'F'   F order   F order
  819         ===== ========= ===================================================
  820 
  821         When ``copy=False`` and a copy is made for other reasons, the result is
  822         the same as if ``copy=True``, with some exceptions for `A`, see the
  823         Notes section. The default order is 'K'.
  824     subok : bool, optional
  825         If True, then sub-classes will be passed-through, otherwise
  826         the returned array will be forced to be a base-class array (default).
  827     ndmin : int, optional
  828         Specifies the minimum number of dimensions that the resulting
  829         array should have.  Ones will be pre-pended to the shape as
  830         needed to meet this requirement.
  831 
  832     Returns
  833     -------
  834     out : ndarray
  835         An array object satisfying the specified requirements.
  836 
  837     See Also
  838     --------
  839     empty_like : Return an empty array with shape and type of input.
  840     ones_like : Return an array of ones with shape and type of input.
  841     zeros_like : Return an array of zeros with shape and type of input.
  842     full_like : Return a new array with shape of input filled with value.
  843     empty : Return a new uninitialized array.
  844     ones : Return a new array setting values to one.
  845     zeros : Return a new array setting values to zero.
  846     full : Return a new array of given shape filled with value.
  847 
  848 
  849     Notes
  850     -----
  851     When order is 'A' and `object` is an array in neither 'C' nor 'F' order,
  852     and a copy is forced by a change in dtype, then the order of the result is
  853     not necessarily 'C' as expected. This is likely a bug.
  854 
  855     Examples
  856     --------
  857     >>> np.array([1, 2, 3])
  858     array([1, 2, 3])
  859 
  860     Upcasting:
  861 
  862     >>> np.array([1, 2, 3.0])
  863     array([ 1.,  2.,  3.])
  864 
  865     More than one dimension:
  866 
  867     >>> np.array([[1, 2], [3, 4]])
  868     array([[1, 2],
  869            [3, 4]])
  870 
  871     Minimum dimensions 2:
  872 
  873     >>> np.array([1, 2, 3], ndmin=2)
  874     array([[1, 2, 3]])
  875 
  876     Type provided:
  877 
  878     >>> np.array([1, 2, 3], dtype=complex)
  879     array([ 1.+0.j,  2.+0.j,  3.+0.j])
  880 
  881     Data-type consisting of more than one element:
  882 
  883     >>> x = np.array([(1,2),(3,4)],dtype=[('a','<i4'),('b','<i4')])
  884     >>> x['a']
  885     array([1, 3])
  886 
  887     Creating an array from sub-classes:
  888 
  889     >>> np.array(np.mat('1 2; 3 4'))
  890     array([[1, 2],
  891            [3, 4]])
  892 
  893     >>> np.array(np.mat('1 2; 3 4'), subok=True)
  894     matrix([[1, 2],
  895             [3, 4]])
  896 
  897     """)
  898 
  899 add_newdoc('numpy.core.multiarray', 'empty',
  900     """
  901     empty(shape, dtype=float, order='C')
  902 
  903     Return a new array of given shape and type, without initializing entries.
  904 
  905     Parameters
  906     ----------
  907     shape : int or tuple of int
  908         Shape of the empty array, e.g., ``(2, 3)`` or ``2``.
  909     dtype : data-type, optional
  910         Desired output data-type for the array, e.g, `numpy.int8`. Default is
  911         `numpy.float64`.
  912     order : {'C', 'F'}, optional, default: 'C'
  913         Whether to store multi-dimensional data in row-major
  914         (C-style) or column-major (Fortran-style) order in
  915         memory.
  916 
  917     Returns
  918     -------
  919     out : ndarray
  920         Array of uninitialized (arbitrary) data of the given shape, dtype, and
  921         order.  Object arrays will be initialized to None.
  922 
  923     See Also
  924     --------
  925     empty_like : Return an empty array with shape and type of input.
  926     ones : Return a new array setting values to one.
  927     zeros : Return a new array setting values to zero.
  928     full : Return a new array of given shape filled with value.
  929 
  930 
  931     Notes
  932     -----
  933     `empty`, unlike `zeros`, does not set the array values to zero,
  934     and may therefore be marginally faster.  On the other hand, it requires
  935     the user to manually set all the values in the array, and should be
  936     used with caution.
  937 
  938     Examples
  939     --------
  940     >>> np.empty([2, 2])
  941     array([[ -9.74499359e+001,   6.69583040e-309],
  942            [  2.13182611e-314,   3.06959433e-309]])         #random
  943 
  944     >>> np.empty([2, 2], dtype=int)
  945     array([[-1073741821, -1067949133],
  946            [  496041986,    19249760]])                     #random
  947 
  948     """)
  949 
  950 add_newdoc('numpy.core.multiarray', 'scalar',
  951     """
  952     scalar(dtype, obj)
  953 
  954     Return a new scalar array of the given type initialized with obj.
  955 
  956     This function is meant mainly for pickle support. `dtype` must be a
  957     valid data-type descriptor. If `dtype` corresponds to an object
  958     descriptor, then `obj` can be any object, otherwise `obj` must be a
  959     string. If `obj` is not given, it will be interpreted as None for object
  960     type and as zeros for all other types.
  961 
  962     """)
  963 
  964 add_newdoc('numpy.core.multiarray', 'zeros',
  965     """
  966     zeros(shape, dtype=float, order='C')
  967 
  968     Return a new array of given shape and type, filled with zeros.
  969 
  970     Parameters
  971     ----------
  972     shape : int or tuple of ints
  973         Shape of the new array, e.g., ``(2, 3)`` or ``2``.
  974     dtype : data-type, optional
  975         The desired data-type for the array, e.g., `numpy.int8`.  Default is
  976         `numpy.float64`.
  977     order : {'C', 'F'}, optional, default: 'C'
  978         Whether to store multi-dimensional data in row-major
  979         (C-style) or column-major (Fortran-style) order in
  980         memory.
  981 
  982     Returns
  983     -------
  984     out : ndarray
  985         Array of zeros with the given shape, dtype, and order.
  986 
  987     See Also
  988     --------
  989     zeros_like : Return an array of zeros with shape and type of input.
  990     empty : Return a new uninitialized array.
  991     ones : Return a new array setting values to one.
  992     full : Return a new array of given shape filled with value.
  993 
  994     Examples
  995     --------
  996     >>> np.zeros(5)
  997     array([ 0.,  0.,  0.,  0.,  0.])
  998 
  999     >>> np.zeros((5,), dtype=int)
 1000     array([0, 0, 0, 0, 0])
 1001 
 1002     >>> np.zeros((2, 1))
 1003     array([[ 0.],
 1004            [ 0.]])
 1005 
 1006     >>> s = (2,2)
 1007     >>> np.zeros(s)
 1008     array([[ 0.,  0.],
 1009            [ 0.,  0.]])
 1010 
 1011     >>> np.zeros((2,), dtype=[('x', 'i4'), ('y', 'i4')]) # custom dtype
 1012     array([(0, 0), (0, 0)],
 1013           dtype=[('x', '<i4'), ('y', '<i4')])
 1014 
 1015     """)
 1016 
 1017 add_newdoc('numpy.core.multiarray', 'set_typeDict',
 1018     """set_typeDict(dict)
 1019 
 1020     Set the internal dictionary that can look up an array type using a
 1021     registered code.
 1022 
 1023     """)
 1024 
 1025 add_newdoc('numpy.core.multiarray', 'fromstring',
 1026     """
 1027     fromstring(string, dtype=float, count=-1, sep='')
 1028 
 1029     A new 1-D array initialized from text data in a string.
 1030 
 1031     Parameters
 1032     ----------
 1033     string : str
 1034         A string containing the data.
 1035     dtype : data-type, optional
 1036         The data type of the array; default: float.  For binary input data,
 1037         the data must be in exactly this format.
 1038     count : int, optional
 1039         Read this number of `dtype` elements from the data.  If this is
 1040         negative (the default), the count will be determined from the
 1041         length of the data.
 1042     sep : str, optional
 1043         The string separating numbers in the data; extra whitespace between
 1044         elements is also ignored.
 1045 
 1046         .. deprecated:: 1.14
 1047             If this argument is not provided, `fromstring` falls back on the
 1048             behaviour of `frombuffer` after encoding unicode string inputs as
 1049             either utf-8 (python 3), or the default encoding (python 2).
 1050 
 1051     Returns
 1052     -------
 1053     arr : ndarray
 1054         The constructed array.
 1055 
 1056     Raises
 1057     ------
 1058     ValueError
 1059         If the string is not the correct size to satisfy the requested
 1060         `dtype` and `count`.
 1061 
 1062     See Also
 1063     --------
 1064     frombuffer, fromfile, fromiter
 1065 
 1066     Examples
 1067     --------
 1068     >>> np.fromstring('1 2', dtype=int, sep=' ')
 1069     array([1, 2])
 1070     >>> np.fromstring('1, 2', dtype=int, sep=',')
 1071     array([1, 2])
 1072 
 1073     """)
 1074 
 1075 add_newdoc('numpy.core.multiarray', 'compare_chararrays',
 1076     """
 1077     compare_chararrays(a, b, cmp_op, rstrip)
 1078 
 1079     Performs element-wise comparison of two string arrays using the
 1080     comparison operator specified by `cmp_op`.
 1081 
 1082     Parameters
 1083     ----------
 1084     a, b : array_like
 1085         Arrays to be compared.
 1086     cmp_op : {"<", "<=", "==", ">=", ">", "!="}
 1087         Type of comparison.
 1088     rstrip : Boolean
 1089         If True, the spaces at the end of Strings are removed before the comparison.
 1090 
 1091     Returns
 1092     -------
 1093     out : ndarray
 1094         The output array of type Boolean with the same shape as a and b.
 1095 
 1096     Raises
 1097     ------
 1098     ValueError
 1099         If `cmp_op` is not valid.
 1100     TypeError
 1101         If at least one of `a` or `b` is a non-string array
 1102 
 1103     Examples
 1104     --------
 1105     >>> a = np.array(["a", "b", "cde"])
 1106     >>> b = np.array(["a", "a", "dec"])
 1107     >>> np.compare_chararrays(a, b, ">", True)
 1108     array([False,  True, False])
 1109 
 1110     """)
 1111 
 1112 add_newdoc('numpy.core.multiarray', 'fromiter',
 1113     """
 1114     fromiter(iterable, dtype, count=-1)
 1115 
 1116     Create a new 1-dimensional array from an iterable object.
 1117 
 1118     Parameters
 1119     ----------
 1120     iterable : iterable object
 1121         An iterable object providing data for the array.
 1122     dtype : data-type
 1123         The data-type of the returned array.
 1124     count : int, optional
 1125         The number of items to read from *iterable*.  The default is -1,
 1126         which means all data is read.
 1127 
 1128     Returns
 1129     -------
 1130     out : ndarray
 1131         The output array.
 1132 
 1133     Notes
 1134     -----
 1135     Specify `count` to improve performance.  It allows ``fromiter`` to
 1136     pre-allocate the output array, instead of resizing it on demand.
 1137 
 1138     Examples
 1139     --------
 1140     >>> iterable = (x*x for x in range(5))
 1141     >>> np.fromiter(iterable, float)
 1142     array([  0.,   1.,   4.,   9.,  16.])
 1143 
 1144     """)
 1145 
 1146 add_newdoc('numpy.core.multiarray', 'fromfile',
 1147     """
 1148     fromfile(file, dtype=float, count=-1, sep='')
 1149 
 1150     Construct an array from data in a text or binary file.
 1151 
 1152     A highly efficient way of reading binary data with a known data-type,
 1153     as well as parsing simply formatted text files.  Data written using the
 1154     `tofile` method can be read using this function.
 1155 
 1156     Parameters
 1157     ----------
 1158     file : file or str
 1159         Open file object or filename.
 1160     dtype : data-type
 1161         Data type of the returned array.
 1162         For binary files, it is used to determine the size and byte-order
 1163         of the items in the file.
 1164     count : int
 1165         Number of items to read. ``-1`` means all items (i.e., the complete
 1166         file).
 1167     sep : str
 1168         Separator between items if file is a text file.
 1169         Empty ("") separator means the file should be treated as binary.
 1170         Spaces (" ") in the separator match zero or more whitespace characters.
 1171         A separator consisting only of spaces must match at least one
 1172         whitespace.
 1173 
 1174     See also
 1175     --------
 1176     load, save
 1177     ndarray.tofile
 1178     loadtxt : More flexible way of loading data from a text file.
 1179 
 1180     Notes
 1181     -----
 1182     Do not rely on the combination of `tofile` and `fromfile` for
 1183     data storage, as the binary files generated are are not platform
 1184     independent.  In particular, no byte-order or data-type information is
 1185     saved.  Data can be stored in the platform independent ``.npy`` format
 1186     using `save` and `load` instead.
 1187 
 1188     Examples
 1189     --------
 1190     Construct an ndarray:
 1191 
 1192     >>> dt = np.dtype([('time', [('min', int), ('sec', int)]),
 1193     ...                ('temp', float)])
 1194     >>> x = np.zeros((1,), dtype=dt)
 1195     >>> x['time']['min'] = 10; x['temp'] = 98.25
 1196     >>> x
 1197     array([((10, 0), 98.25)],
 1198           dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])
 1199 
 1200     Save the raw data to disk:
 1201 
 1202     >>> import os
 1203     >>> fname = os.tmpnam()
 1204     >>> x.tofile(fname)
 1205 
 1206     Read the raw data from disk:
 1207 
 1208     >>> np.fromfile(fname, dtype=dt)
 1209     array([((10, 0), 98.25)],
 1210           dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])
 1211 
 1212     The recommended way to store and load data:
 1213 
 1214     >>> np.save(fname, x)
 1215     >>> np.load(fname + '.npy')
 1216     array([((10, 0), 98.25)],
 1217           dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])
 1218 
 1219     """)
 1220 
 1221 add_newdoc('numpy.core.multiarray', 'frombuffer',
 1222     """
 1223     frombuffer(buffer, dtype=float, count=-1, offset=0)
 1224 
 1225     Interpret a buffer as a 1-dimensional array.
 1226 
 1227     Parameters
 1228     ----------
 1229     buffer : buffer_like
 1230         An object that exposes the buffer interface.
 1231     dtype : data-type, optional
 1232         Data-type of the returned array; default: float.
 1233     count : int, optional
 1234         Number of items to read. ``-1`` means all data in the buffer.
 1235     offset : int, optional
 1236         Start reading the buffer from this offset (in bytes); default: 0.
 1237 
 1238     Notes
 1239     -----
 1240     If the buffer has data that is not in machine byte-order, this should
 1241     be specified as part of the data-type, e.g.::
 1242 
 1243       >>> dt = np.dtype(int)
 1244       >>> dt = dt.newbyteorder('>')
 1245       >>> np.frombuffer(buf, dtype=dt)
 1246 
 1247     The data of the resulting array will not be byteswapped, but will be
 1248     interpreted correctly.
 1249 
 1250     Examples
 1251     --------
 1252     >>> s = 'hello world'
 1253     >>> np.frombuffer(s, dtype='S1', count=5, offset=6)
 1254     array(['w', 'o', 'r', 'l', 'd'],
 1255           dtype='|S1')
 1256 
 1257     >>> np.frombuffer(b'\\x01\\x02', dtype=np.uint8)
 1258     array([1, 2], dtype=uint8)
 1259     >>> np.frombuffer(b'\\x01\\x02\\x03\\x04\\x05', dtype=np.uint8, count=3)
 1260     array([1, 2, 3], dtype=uint8)
 1261 
 1262     """)
 1263 
 1264 add_newdoc('numpy.core', 'fastCopyAndTranspose',
 1265     """_fastCopyAndTranspose(a)""")
 1266 
 1267 add_newdoc('numpy.core.multiarray', 'correlate',
 1268     """cross_correlate(a,v, mode=0)""")
 1269 
 1270 add_newdoc('numpy.core.multiarray', 'arange',
 1271     """
 1272     arange([start,] stop[, step,], dtype=None)
 1273 
 1274     Return evenly spaced values within a given interval.
 1275 
 1276     Values are generated within the half-open interval ``[start, stop)``
 1277     (in other words, the interval including `start` but excluding `stop`).
 1278     For integer arguments the function is equivalent to the Python built-in
 1279     `range` function, but returns an ndarray rather than a list.
 1280 
 1281     When using a non-integer step, such as 0.1, the results will often not
 1282     be consistent.  It is better to use `numpy.linspace` for these cases.
 1283 
 1284     Parameters
 1285     ----------
 1286     start : number, optional
 1287         Start of interval.  The interval includes this value.  The default
 1288         start value is 0.
 1289     stop : number
 1290         End of interval.  The interval does not include this value, except
 1291         in some cases where `step` is not an integer and floating point
 1292         round-off affects the length of `out`.
 1293     step : number, optional
 1294         Spacing between values.  For any output `out`, this is the distance
 1295         between two adjacent values, ``out[i+1] - out[i]``.  The default
 1296         step size is 1.  If `step` is specified as a position argument,
 1297         `start` must also be given.
 1298     dtype : dtype
 1299         The type of the output array.  If `dtype` is not given, infer the data
 1300         type from the other input arguments.
 1301 
 1302     Returns
 1303     -------
 1304     arange : ndarray
 1305         Array of evenly spaced values.
 1306 
 1307         For floating point arguments, the length of the result is
 1308         ``ceil((stop - start)/step)``.  Because of floating point overflow,
 1309         this rule may result in the last element of `out` being greater
 1310         than `stop`.
 1311 
 1312     See Also
 1313     --------
 1314     linspace : Evenly spaced numbers with careful handling of endpoints.
 1315     ogrid: Arrays of evenly spaced numbers in N-dimensions.
 1316     mgrid: Grid-shaped arrays of evenly spaced numbers in N-dimensions.
 1317 
 1318     Examples
 1319     --------
 1320     >>> np.arange(3)
 1321     array([0, 1, 2])
 1322     >>> np.arange(3.0)
 1323     array([ 0.,  1.,  2.])
 1324     >>> np.arange(3,7)
 1325     array([3, 4, 5, 6])
 1326     >>> np.arange(3,7,2)
 1327     array([3, 5])
 1328 
 1329     """)
 1330 
 1331 add_newdoc('numpy.core.multiarray', '_get_ndarray_c_version',
 1332     """_get_ndarray_c_version()
 1333 
 1334     Return the compile time NDARRAY_VERSION number.
 1335 
 1336     """)
 1337 
 1338 add_newdoc('numpy.core.multiarray', '_reconstruct',
 1339     """_reconstruct(subtype, shape, dtype)
 1340 
 1341     Construct an empty array. Used by Pickles.
 1342 
 1343     """)
 1344 
 1345 
 1346 add_newdoc('numpy.core.multiarray', 'set_string_function',
 1347     """
 1348     set_string_function(f, repr=1)
 1349 
 1350     Internal method to set a function to be used when pretty printing arrays.
 1351 
 1352     """)
 1353 
 1354 add_newdoc('numpy.core.multiarray', 'set_numeric_ops',
 1355     """
 1356     set_numeric_ops(op1=func1, op2=func2, ...)
 1357 
 1358     Set numerical operators for array objects.
 1359 
 1360     .. deprecated:: 1.16
 1361 
 1362         For the general case, use :c:func:`PyUFunc_ReplaceLoopBySignature`.
 1363         For ndarray subclasses, define the ``__array_ufunc__`` method and
 1364         override the relevant ufunc.
 1365 
 1366     Parameters
 1367     ----------
 1368     op1, op2, ... : callable
 1369         Each ``op = func`` pair describes an operator to be replaced.
 1370         For example, ``add = lambda x, y: np.add(x, y) % 5`` would replace
 1371         addition by modulus 5 addition.
 1372 
 1373     Returns
 1374     -------
 1375     saved_ops : list of callables
 1376         A list of all operators, stored before making replacements.
 1377 
 1378     Notes
 1379     -----
 1380     .. WARNING::
 1381        Use with care!  Incorrect usage may lead to memory errors.
 1382 
 1383     A function replacing an operator cannot make use of that operator.
 1384     For example, when replacing add, you may not use ``+``.  Instead,
 1385     directly call ufuncs.
 1386 
 1387     Examples
 1388     --------
 1389     >>> def add_mod5(x, y):
 1390     ...     return np.add(x, y) % 5
 1391     ...
 1392     >>> old_funcs = np.set_numeric_ops(add=add_mod5)
 1393 
 1394     >>> x = np.arange(12).reshape((3, 4))
 1395     >>> x + x
 1396     array([[0, 2, 4, 1],
 1397            [3, 0, 2, 4],
 1398            [1, 3, 0, 2]])
 1399 
 1400     >>> ignore = np.set_numeric_ops(**old_funcs) # restore operators
 1401 
 1402     """)
 1403 
 1404 add_newdoc('numpy.core.multiarray', 'promote_types',
 1405     """
 1406     promote_types(type1, type2)
 1407 
 1408     Returns the data type with the smallest size and smallest scalar
 1409     kind to which both ``type1`` and ``type2`` may be safely cast.
 1410     The returned data type is always in native byte order.
 1411 
 1412     This function is symmetric, but rarely associative.
 1413 
 1414     Parameters
 1415     ----------
 1416     type1 : dtype or dtype specifier
 1417         First data type.
 1418     type2 : dtype or dtype specifier
 1419         Second data type.
 1420 
 1421     Returns
 1422     -------
 1423     out : dtype
 1424         The promoted data type.
 1425 
 1426     Notes
 1427     -----
 1428     .. versionadded:: 1.6.0
 1429 
 1430     Starting in NumPy 1.9, promote_types function now returns a valid string
 1431     length when given an integer or float dtype as one argument and a string
 1432     dtype as another argument. Previously it always returned the input string
 1433     dtype, even if it wasn't long enough to store the max integer/float value
 1434     converted to a string.
 1435 
 1436     See Also
 1437     --------
 1438     result_type, dtype, can_cast
 1439 
 1440     Examples
 1441     --------
 1442     >>> np.promote_types('f4', 'f8')
 1443     dtype('float64')
 1444 
 1445     >>> np.promote_types('i8', 'f4')
 1446     dtype('float64')
 1447 
 1448     >>> np.promote_types('>i8', '<c8')
 1449     dtype('complex128')
 1450 
 1451     >>> np.promote_types('i4', 'S8')
 1452     dtype('S11')
 1453 
 1454     An example of a non-associative case:
 1455 
 1456     >>> p = np.promote_types
 1457     >>> p('S', p('i1', 'u1'))
 1458     dtype('S6')
 1459     >>> p(p('S', 'i1'), 'u1')
 1460     dtype('S4')
 1461 
 1462     """)
 1463 
 1464 add_newdoc('numpy.core.multiarray', 'newbuffer',
 1465     """
 1466     newbuffer(size)
 1467 
 1468     Return a new uninitialized buffer object.
 1469 
 1470     Parameters
 1471     ----------
 1472     size : int
 1473         Size in bytes of returned buffer object.
 1474 
 1475     Returns
 1476     -------
 1477     newbuffer : buffer object
 1478         Returned, uninitialized buffer object of `size` bytes.
 1479 
 1480     """)
 1481 
 1482 add_newdoc('numpy.core.multiarray', 'getbuffer',
 1483     """
 1484     getbuffer(obj [,offset[, size]])
 1485 
 1486     Create a buffer object from the given object referencing a slice of
 1487     length size starting at offset.
 1488 
 1489     Default is the entire buffer. A read-write buffer is attempted followed
 1490     by a read-only buffer.
 1491 
 1492     Parameters
 1493     ----------
 1494     obj : object
 1495 
 1496     offset : int, optional
 1497 
 1498     size : int, optional
 1499 
 1500     Returns
 1501     -------
 1502     buffer_obj : buffer
 1503 
 1504     Examples
 1505     --------
 1506     >>> buf = np.getbuffer(np.ones(5), 1, 3)
 1507     >>> len(buf)
 1508     3
 1509     >>> buf[0]
 1510     '\\x00'
 1511     >>> buf
 1512     <read-write buffer for 0x8af1e70, size 3, offset 1 at 0x8ba4ec0>
 1513 
 1514     """)
 1515 
 1516 add_newdoc('numpy.core.multiarray', 'c_einsum',
 1517     """
 1518     c_einsum(subscripts, *operands, out=None, dtype=None, order='K',
 1519            casting='safe')
 1520 
 1521     *This documentation shadows that of the native python implementation of the `einsum` function,
 1522     except all references and examples related to the `optimize` argument (v 0.12.0) have been removed.*
 1523 
 1524     Evaluates the Einstein summation convention on the operands.
 1525 
 1526     Using the Einstein summation convention, many common multi-dimensional,
 1527     linear algebraic array operations can be represented in a simple fashion.
 1528     In *implicit* mode `einsum` computes these values.
 1529 
 1530     In *explicit* mode, `einsum` provides further flexibility to compute
 1531     other array operations that might not be considered classical Einstein
 1532     summation operations, by disabling, or forcing summation over specified
 1533     subscript labels.
 1534 
 1535     See the notes and examples for clarification.
 1536 
 1537     Parameters
 1538     ----------
 1539     subscripts : str
 1540         Specifies the subscripts for summation as comma separated list of
 1541         subscript labels. An implicit (classical Einstein summation)
 1542         calculation is performed unless the explicit indicator '->' is
 1543         included as well as subscript labels of the precise output form.
 1544     operands : list of array_like
 1545         These are the arrays for the operation.
 1546     out : ndarray, optional
 1547         If provided, the calculation is done into this array.
 1548     dtype : {data-type, None}, optional
 1549         If provided, forces the calculation to use the data type specified.
 1550         Note that you may have to also give a more liberal `casting`
 1551         parameter to allow the conversions. Default is None.
 1552     order : {'C', 'F', 'A', 'K'}, optional
 1553         Controls the memory layout of the output. 'C' means it should
 1554         be C contiguous. 'F' means it should be Fortran contiguous,
 1555         'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise.
 1556         'K' means it should be as close to the layout as the inputs as
 1557         is possible, including arbitrarily permuted axes.
 1558         Default is 'K'.
 1559     casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
 1560         Controls what kind of data casting may occur.  Setting this to
 1561         'unsafe' is not recommended, as it can adversely affect accumulations.
 1562 
 1563           * 'no' means the data types should not be cast at all.
 1564           * 'equiv' means only byte-order changes are allowed.
 1565           * 'safe' means only casts which can preserve values are allowed.
 1566           * 'same_kind' means only safe casts or casts within a kind,
 1567             like float64 to float32, are allowed.
 1568           * 'unsafe' means any data conversions may be done.
 1569 
 1570         Default is 'safe'.
 1571     optimize : {False, True, 'greedy', 'optimal'}, optional
 1572         Controls if intermediate optimization should occur. No optimization
 1573         will occur if False and True will default to the 'greedy' algorithm.
 1574         Also accepts an explicit contraction list from the ``np.einsum_path``
 1575         function. See ``np.einsum_path`` for more details. Defaults to False.
 1576 
 1577     Returns
 1578     -------
 1579     output : ndarray
 1580         The calculation based on the Einstein summation convention.
 1581 
 1582     See Also
 1583     --------
 1584     einsum_path, dot, inner, outer, tensordot, linalg.multi_dot
 1585 
 1586     Notes
 1587     -----
 1588     .. versionadded:: 1.6.0
 1589 
 1590     The Einstein summation convention can be used to compute
 1591     many multi-dimensional, linear algebraic array operations. `einsum`
 1592     provides a succinct way of representing these.
 1593 
 1594     A non-exhaustive list of these operations,
 1595     which can be computed by `einsum`, is shown below along with examples:
 1596 
 1597     * Trace of an array, :py:func:`numpy.trace`.
 1598     * Return a diagonal, :py:func:`numpy.diag`.
 1599     * Array axis summations, :py:func:`numpy.sum`.
 1600     * Transpositions and permutations, :py:func:`numpy.transpose`.
 1601     * Matrix multiplication and dot product, :py:func:`numpy.matmul` :py:func:`numpy.dot`.
 1602     * Vector inner and outer products, :py:func:`numpy.inner` :py:func:`numpy.outer`.
 1603     * Broadcasting, element-wise and scalar multiplication, :py:func:`numpy.multiply`.
 1604     * Tensor contractions, :py:func:`numpy.tensordot`.
 1605     * Chained array operations, in efficient calculation order, :py:func:`numpy.einsum_path`.
 1606 
 1607     The subscripts string is a comma-separated list of subscript labels,
 1608     where each label refers to a dimension of the corresponding operand.
 1609     Whenever a label is repeated it is summed, so ``np.einsum('i,i', a, b)``
 1610     is equivalent to :py:func:`np.inner(a,b) <numpy.inner>`. If a label
 1611     appears only once, it is not summed, so ``np.einsum('i', a)`` produces a
 1612     view of ``a`` with no changes. A further example ``np.einsum('ij,jk', a, b)``
 1613     describes traditional matrix multiplication and is equivalent to
 1614     :py:func:`np.matmul(a,b) <numpy.matmul>`. Repeated subscript labels in one
 1615     operand take the diagonal. For example, ``np.einsum('ii', a)`` is equivalent
 1616     to :py:func:`np.trace(a) <numpy.trace>`.
 1617 
 1618     In *implicit mode*, the chosen subscripts are important
 1619     since the axes of the output are reordered alphabetically.  This
 1620     means that ``np.einsum('ij', a)`` doesn't affect a 2D array, while
 1621     ``np.einsum('ji', a)`` takes its transpose. Additionally,
 1622     ``np.einsum('ij,jk', a, b)`` returns a matrix multiplication, while,
 1623     ``np.einsum('ij,jh', a, b)`` returns the transpose of the
 1624     multiplication since subscript 'h' precedes subscript 'i'.
 1625 
 1626     In *explicit mode* the output can be directly controlled by
 1627     specifying output subscript labels.  This requires the
 1628     identifier '->' as well as the list of output subscript labels.
 1629     This feature increases the flexibility of the function since
 1630     summing can be disabled or forced when required. The call
 1631     ``np.einsum('i->', a)`` is like :py:func:`np.sum(a, axis=-1) <numpy.sum>`,
 1632     and ``np.einsum('ii->i', a)`` is like :py:func:`np.diag(a) <numpy.diag>`.
 1633     The difference is that `einsum` does not allow broadcasting by default.
 1634     Additionally ``np.einsum('ij,jh->ih', a, b)`` directly specifies the
 1635     order of the output subscript labels and therefore returns matrix
 1636     multiplication, unlike the example above in implicit mode.
 1637 
 1638     To enable and control broadcasting, use an ellipsis.  Default
 1639     NumPy-style broadcasting is done by adding an ellipsis
 1640     to the left of each term, like ``np.einsum('...ii->...i', a)``.
 1641     To take the trace along the first and last axes,
 1642     you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix
 1643     product with the left-most indices instead of rightmost, one can do
 1644     ``np.einsum('ij...,jk...->ik...', a, b)``.
 1645 
 1646     When there is only one operand, no axes are summed, and no output
 1647     parameter is provided, a view into the operand is returned instead
 1648     of a new array.  Thus, taking the diagonal as ``np.einsum('ii->i', a)``
 1649     produces a view (changed in version 1.10.0).
 1650 
 1651     `einsum` also provides an alternative way to provide the subscripts
 1652     and operands as ``einsum(op0, sublist0, op1, sublist1, ..., [sublistout])``.
 1653     If the output shape is not provided in this format `einsum` will be
 1654     calculated in implicit mode, otherwise it will be performed explicitly.
 1655     The examples below have corresponding `einsum` calls with the two
 1656     parameter methods.
 1657 
 1658     .. versionadded:: 1.10.0
 1659 
 1660     Views returned from einsum are now writeable whenever the input array
 1661     is writeable. For example, ``np.einsum('ijk...->kji...', a)`` will now
 1662     have the same effect as :py:func:`np.swapaxes(a, 0, 2) <numpy.swapaxes>`
 1663     and ``np.einsum('ii->i', a)`` will return a writeable view of the diagonal
 1664     of a 2D array.
 1665 
 1666     Examples
 1667     --------
 1668     >>> a = np.arange(25).reshape(5,5)
 1669     >>> b = np.arange(5)
 1670     >>> c = np.arange(6).reshape(2,3)
 1671 
 1672     Trace of a matrix:
 1673 
 1674     >>> np.einsum('ii', a)
 1675     60
 1676     >>> np.einsum(a, [0,0])
 1677     60
 1678     >>> np.trace(a)
 1679     60
 1680 
 1681     Extract the diagonal (requires explicit form):
 1682 
 1683     >>> np.einsum('ii->i', a)
 1684     array([ 0,  6, 12, 18, 24])
 1685     >>> np.einsum(a, [0,0], [0])
 1686     array([ 0,  6, 12, 18, 24])
 1687     >>> np.diag(a)
 1688     array([ 0,  6, 12, 18, 24])
 1689 
 1690     Sum over an axis (requires explicit form):
 1691 
 1692     >>> np.einsum('ij->i', a)
 1693     array([ 10,  35,  60,  85, 110])
 1694     >>> np.einsum(a, [0,1], [0])
 1695     array([ 10,  35,  60,  85, 110])
 1696     >>> np.sum(a, axis=1)
 1697     array([ 10,  35,  60,  85, 110])
 1698 
 1699     For higher dimensional arrays summing a single axis can be done with ellipsis:
 1700 
 1701     >>> np.einsum('...j->...', a)
 1702     array([ 10,  35,  60,  85, 110])
 1703     >>> np.einsum(a, [Ellipsis,1], [Ellipsis])
 1704     array([ 10,  35,  60,  85, 110])
 1705 
 1706     Compute a matrix transpose, or reorder any number of axes:
 1707 
 1708     >>> np.einsum('ji', c)
 1709     array([[0, 3],
 1710            [1, 4],
 1711            [2, 5]])
 1712     >>> np.einsum('ij->ji', c)
 1713     array([[0, 3],
 1714            [1, 4],
 1715            [2, 5]])
 1716     >>> np.einsum(c, [1,0])
 1717     array([[0, 3],
 1718            [1, 4],
 1719            [2, 5]])
 1720     >>> np.transpose(c)
 1721     array([[0, 3],
 1722            [1, 4],
 1723            [2, 5]])
 1724 
 1725     Vector inner products:
 1726 
 1727     >>> np.einsum('i,i', b, b)
 1728     30
 1729     >>> np.einsum(b, [0], b, [0])
 1730     30
 1731     >>> np.inner(b,b)
 1732     30
 1733 
 1734     Matrix vector multiplication:
 1735 
 1736     >>> np.einsum('ij,j', a, b)
 1737     array([ 30,  80, 130, 180, 230])
 1738     >>> np.einsum(a, [0,1], b, [1])
 1739     array([ 30,  80, 130, 180, 230])
 1740     >>> np.dot(a, b)
 1741     array([ 30,  80, 130, 180, 230])
 1742     >>> np.einsum('...j,j', a, b)
 1743     array([ 30,  80, 130, 180, 230])
 1744 
 1745     Broadcasting and scalar multiplication:
 1746 
 1747     >>> np.einsum('..., ...', 3, c)
 1748     array([[ 0,  3,  6],
 1749            [ 9, 12, 15]])
 1750     >>> np.einsum(',ij', 3, c)
 1751     array([[ 0,  3,  6],
 1752            [ 9, 12, 15]])
 1753     >>> np.einsum(3, [Ellipsis], c, [Ellipsis])
 1754     array([[ 0,  3,  6],
 1755            [ 9, 12, 15]])
 1756     >>> np.multiply(3, c)
 1757     array([[ 0,  3,  6],
 1758            [ 9, 12, 15]])
 1759 
 1760     Vector outer product:
 1761 
 1762     >>> np.einsum('i,j', np.arange(2)+1, b)
 1763     array([[0, 1, 2, 3, 4],
 1764            [0, 2, 4, 6, 8]])
 1765     >>> np.einsum(np.arange(2)+1, [0], b, [1])
 1766     array([[0, 1, 2, 3, 4],
 1767            [0, 2, 4, 6, 8]])
 1768     >>> np.outer(np.arange(2)+1, b)
 1769     array([[0, 1, 2, 3, 4],
 1770            [0, 2, 4, 6, 8]])
 1771 
 1772     Tensor contraction:
 1773 
 1774     >>> a = np.arange(60.).reshape(3,4,5)
 1775     >>> b = np.arange(24.).reshape(4,3,2)
 1776     >>> np.einsum('ijk,jil->kl', a, b)
 1777     array([[ 4400.,  4730.],
 1778            [ 4532.,  4874.],
 1779            [ 4664.,  5018.],
 1780            [ 4796.,  5162.],
 1781            [ 4928.,  5306.]])
 1782     >>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3])
 1783     array([[ 4400.,  4730.],
 1784            [ 4532.,  4874.],
 1785            [ 4664.,  5018.],
 1786            [ 4796.,  5162.],
 1787            [ 4928.,  5306.]])
 1788     >>> np.tensordot(a,b, axes=([1,0],[0,1]))
 1789     array([[ 4400.,  4730.],
 1790            [ 4532.,  4874.],
 1791            [ 4664.,  5018.],
 1792            [ 4796.,  5162.],
 1793            [ 4928.,  5306.]])
 1794 
 1795     Writeable returned arrays (since version 1.10.0):
 1796 
 1797     >>> a = np.zeros((3, 3))
 1798     >>> np.einsum('ii->i', a)[:] = 1
 1799     >>> a
 1800     array([[ 1.,  0.,  0.],
 1801            [ 0.,  1.,  0.],
 1802            [ 0.,  0.,  1.]])
 1803 
 1804     Example of ellipsis use:
 1805 
 1806     >>> a = np.arange(6).reshape((3,2))
 1807     >>> b = np.arange(12).reshape((4,3))
 1808     >>> np.einsum('ki,jk->ij', a, b)
 1809     array([[10, 28, 46, 64],
 1810            [13, 40, 67, 94]])
 1811     >>> np.einsum('ki,...k->i...', a, b)
 1812     array([[10, 28, 46, 64],
 1813            [13, 40, 67, 94]])
 1814     >>> np.einsum('k...,jk', a, b)
 1815     array([[10, 28, 46, 64],
 1816            [13, 40, 67, 94]])
 1817 
 1818     """)
 1819 
 1820 
 1821 ##############################################################################
 1822 #
 1823 # Documentation for ndarray attributes and methods
 1824 #
 1825 ##############################################################################
 1826 
 1827 
 1828 ##############################################################################
 1829 #
 1830 # ndarray object
 1831 #
 1832 ##############################################################################
 1833 
 1834 
 1835 add_newdoc('numpy.core.multiarray', 'ndarray',
 1836     """
 1837     ndarray(shape, dtype=float, buffer=None, offset=0,
 1838             strides=None, order=None)
 1839 
 1840     An array object represents a multidimensional, homogeneous array
 1841     of fixed-size items.  An associated data-type object describes the
 1842     format of each element in the array (its byte-order, how many bytes it
 1843     occupies in memory, whether it is an integer, a floating point number,
 1844     or something else, etc.)
 1845 
 1846     Arrays should be constructed using `array`, `zeros` or `empty` (refer
 1847     to the See Also section below).  The parameters given here refer to
 1848     a low-level method (`ndarray(...)`) for instantiating an array.
 1849 
 1850     For more information, refer to the `numpy` module and examine the
 1851     methods and attributes of an array.
 1852 
 1853     Parameters
 1854     ----------
 1855     (for the __new__ method; see Notes below)
 1856 
 1857     shape : tuple of ints
 1858         Shape of created array.
 1859     dtype : data-type, optional
 1860         Any object that can be interpreted as a numpy data type.
 1861     buffer : object exposing buffer interface, optional
 1862         Used to fill the array with data.
 1863     offset : int, optional
 1864         Offset of array data in buffer.
 1865     strides : tuple of ints, optional
 1866         Strides of data in memory.
 1867     order : {'C', 'F'}, optional
 1868         Row-major (C-style) or column-major (Fortran-style) order.
 1869 
 1870     Attributes
 1871     ----------
 1872     T : ndarray
 1873         Transpose of the array.
 1874     data : buffer
 1875         The array's elements, in memory.
 1876     dtype : dtype object
 1877         Describes the format of the elements in the array.
 1878     flags : dict
 1879         Dictionary containing information related to memory use, e.g.,
 1880         'C_CONTIGUOUS', 'OWNDATA', 'WRITEABLE', etc.
 1881     flat : numpy.flatiter object
 1882         Flattened version of the array as an iterator.  The iterator
 1883         allows assignments, e.g., ``x.flat = 3`` (See `ndarray.flat` for
 1884         assignment examples; TODO).
 1885     imag : ndarray
 1886         Imaginary part of the array.
 1887     real : ndarray
 1888         Real part of the array.
 1889     size : int
 1890         Number of elements in the array.
 1891     itemsize : int
 1892         The memory use of each array element in bytes.
 1893     nbytes : int
 1894         The total number of bytes required to store the array data,
 1895         i.e., ``itemsize * size``.
 1896     ndim : int
 1897         The array's number of dimensions.
 1898     shape : tuple of ints
 1899         Shape of the array.
 1900     strides : tuple of ints
 1901         The step-size required to move from one element to the next in
 1902         memory. For example, a contiguous ``(3, 4)`` array of type
 1903         ``int16`` in C-order has strides ``(8, 2)``.  This implies that
 1904         to move from element to element in memory requires jumps of 2 bytes.
 1905         To move from row-to-row, one needs to jump 8 bytes at a time
 1906         (``2 * 4``).
 1907     ctypes : ctypes object
 1908         Class containing properties of the array needed for interaction
 1909         with ctypes.
 1910     base : ndarray
 1911         If the array is a view into another array, that array is its `base`
 1912         (unless that array is also a view).  The `base` array is where the
 1913         array data is actually stored.
 1914 
 1915     See Also
 1916     --------
 1917     array : Construct an array.
 1918     zeros : Create an array, each element of which is zero.
 1919     empty : Create an array, but leave its allocated memory unchanged (i.e.,
 1920             it contains "garbage").
 1921     dtype : Create a data-type.
 1922 
 1923     Notes
 1924     -----
 1925     There are two modes of creating an array using ``__new__``:
 1926 
 1927     1. If `buffer` is None, then only `shape`, `dtype`, and `order`
 1928        are used.
 1929     2. If `buffer` is an object exposing the buffer interface, then
 1930        all keywords are interpreted.
 1931 
 1932     No ``__init__`` method is needed because the array is fully initialized
 1933     after the ``__new__`` method.
 1934 
 1935     Examples
 1936     --------
 1937     These examples illustrate the low-level `ndarray` constructor.  Refer
 1938     to the `See Also` section above for easier ways of constructing an
 1939     ndarray.
 1940 
 1941     First mode, `buffer` is None:
 1942 
 1943     >>> np.ndarray(shape=(2,2), dtype=float, order='F')
 1944     array([[ -1.13698227e+002,   4.25087011e-303],
 1945            [  2.88528414e-306,   3.27025015e-309]])         #random
 1946 
 1947     Second mode:
 1948 
 1949     >>> np.ndarray((2,), buffer=np.array([1,2,3]),
 1950     ...            offset=np.int_().itemsize,
 1951     ...            dtype=int) # offset = 1*itemsize, i.e. skip first element
 1952     array([2, 3])
 1953 
 1954     """)
 1955 
 1956 
 1957 ##############################################################################
 1958 #
 1959 # ndarray attributes
 1960 #
 1961 ##############################################################################
 1962 
 1963 
 1964 add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_interface__',
 1965     """Array protocol: Python side."""))
 1966 
 1967 
 1968 add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_finalize__',
 1969     """None."""))
 1970 
 1971 
 1972 add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_priority__',
 1973     """Array priority."""))
 1974 
 1975 
 1976 add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_struct__',
 1977     """Array protocol: C-struct side."""))
 1978 
 1979 
 1980 add_newdoc('numpy.core.multiarray', 'ndarray', ('_as_parameter_',
 1981     """Allow the array to be interpreted as a ctypes object by returning the
 1982     data-memory location as an integer
 1983 
 1984     """))
 1985 
 1986 
 1987 add_newdoc('numpy.core.multiarray', 'ndarray', ('base',
 1988     """
 1989     Base object if memory is from some other object.
 1990 
 1991     Examples
 1992     --------
 1993     The base of an array that owns its memory is None:
 1994 
 1995     >>> x = np.array([1,2,3,4])
 1996     >>> x.base is None
 1997     True
 1998 
 1999     Slicing creates a view, whose memory is shared with x:
 2000 
 2001     >>> y = x[2:]
 2002     >>> y.base is x
 2003     True
 2004 
 2005     """))
 2006 
 2007 
 2008 add_newdoc('numpy.core.multiarray', 'ndarray', ('ctypes',
 2009     """
 2010     An object to simplify the interaction of the array with the ctypes
 2011     module.
 2012 
 2013     This attribute creates an object that makes it easier to use arrays
 2014     when calling shared libraries with the ctypes module. The returned
 2015     object has, among others, data, shape, and strides attributes (see
 2016     Notes below) which themselves return ctypes objects that can be used
 2017     as arguments to a shared library.
 2018 
 2019     Parameters
 2020     ----------
 2021     None
 2022 
 2023     Returns
 2024     -------
 2025     c : Python object
 2026         Possessing attributes data, shape, strides, etc.
 2027 
 2028     See Also
 2029     --------
 2030     numpy.ctypeslib
 2031 
 2032     Notes
 2033     -----
 2034     Below are the public attributes of this object which were documented
 2035     in "Guide to NumPy" (we have omitted undocumented public attributes,
 2036     as well as documented private attributes):
 2037 
 2038     .. autoattribute:: numpy.core._internal._ctypes.data
 2039 
 2040     .. autoattribute:: numpy.core._internal._ctypes.shape
 2041 
 2042     .. autoattribute:: numpy.core._internal._ctypes.strides
 2043 
 2044     .. automethod:: numpy.core._internal._ctypes.data_as
 2045 
 2046     .. automethod:: numpy.core._internal._ctypes.shape_as
 2047 
 2048     .. automethod:: numpy.core._internal._ctypes.strides_as
 2049 
 2050     If the ctypes module is not available, then the ctypes attribute
 2051     of array objects still returns something useful, but ctypes objects
 2052     are not returned and errors may be raised instead. In particular,
 2053     the object will still have the as parameter attribute which will
 2054     return an integer equal to the data attribute.
 2055 
 2056     Examples
 2057     --------
 2058     >>> import ctypes
 2059     >>> x
 2060     array([[0, 1],
 2061            [2, 3]])
 2062     >>> x.ctypes.data
 2063     30439712
 2064     >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
 2065     <ctypes.LP_c_long object at 0x01F01300>
 2066     >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
 2067     c_long(0)
 2068     >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
 2069     c_longlong(4294967296L)
 2070     >>> x.ctypes.shape
 2071     <numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
 2072     >>> x.ctypes.shape_as(ctypes.c_long)
 2073     <numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
 2074     >>> x.ctypes.strides
 2075     <numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
 2076     >>> x.ctypes.strides_as(ctypes.c_longlong)
 2077     <numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>
 2078 
 2079     """))
 2080 
 2081 
 2082 add_newdoc('numpy.core.multiarray', 'ndarray', ('data',
 2083     """Python buffer object pointing to the start of the array's data."""))
 2084 
 2085 
 2086 add_newdoc('numpy.core.multiarray', 'ndarray', ('dtype',
 2087     """
 2088     Data-type of the array's elements.
 2089 
 2090     Parameters
 2091     ----------
 2092     None
 2093 
 2094     Returns
 2095     -------
 2096     d : numpy dtype object
 2097 
 2098     See Also
 2099     --------
 2100     numpy.dtype
 2101 
 2102     Examples
 2103     --------
 2104     >>> x
 2105     array([[0, 1],
 2106            [2, 3]])
 2107     >>> x.dtype
 2108     dtype('int32')
 2109     >>> type(x.dtype)
 2110     <type 'numpy.dtype'>
 2111 
 2112     """))
 2113 
 2114 
 2115 add_newdoc('numpy.core.multiarray', 'ndarray', ('imag',
 2116     """
 2117     The imaginary part of the array.
 2118 
 2119     Examples
 2120     --------
 2121     >>> x = np.sqrt([1+0j, 0+1j])
 2122     >>> x.imag
 2123     array([ 0.        ,  0.70710678])
 2124     >>> x.imag.dtype
 2125     dtype('float64')
 2126 
 2127     """))
 2128 
 2129 
 2130 add_newdoc('numpy.core.multiarray', 'ndarray', ('itemsize',
 2131     """
 2132     Length of one array element in bytes.
 2133 
 2134     Examples
 2135     --------
 2136     >>> x = np.array([1,2,3], dtype=np.float64)
 2137     >>> x.itemsize
 2138     8
 2139     >>> x = np.array([1,2,3], dtype=np.complex128)
 2140     >>> x.itemsize
 2141     16
 2142 
 2143     """))
 2144 
 2145 
 2146 add_newdoc('numpy.core.multiarray', 'ndarray', ('flags',
 2147     """
 2148     Information about the memory layout of the array.
 2149 
 2150     Attributes
 2151     ----------
 2152     C_CONTIGUOUS (C)
 2153         The data is in a single, C-style contiguous segment.
 2154     F_CONTIGUOUS (F)
 2155         The data is in a single, Fortran-style contiguous segment.
 2156     OWNDATA (O)
 2157         The array owns the memory it uses or borrows it from another object.
 2158     WRITEABLE (W)
 2159         The data area can be written to.  Setting this to False locks
 2160         the data, making it read-only.  A view (slice, etc.) inherits WRITEABLE
 2161         from its base array at creation time, but a view of a writeable
 2162         array may be subsequently locked while the base array remains writeable.
 2163         (The opposite is not true, in that a view of a locked array may not
 2164         be made writeable.  However, currently, locking a base object does not
 2165         lock any views that already reference it, so under that circumstance it
 2166         is possible to alter the contents of a locked array via a previously
 2167         created writeable view onto it.)  Attempting to change a non-writeable
 2168         array raises a RuntimeError exception.
 2169     ALIGNED (A)
 2170         The data and all elements are aligned appropriately for the hardware.
 2171     WRITEBACKIFCOPY (X)
 2172         This array is a copy of some other array. The C-API function
 2173         PyArray_ResolveWritebackIfCopy must be called before deallocating
 2174         to the base array will be updated with the contents of this array.
 2175     UPDATEIFCOPY (U)
 2176         (Deprecated, use WRITEBACKIFCOPY) This array is a copy of some other array.
 2177         When this array is
 2178         deallocated, the base array will be updated with the contents of
 2179         this array.
 2180     FNC
 2181         F_CONTIGUOUS and not C_CONTIGUOUS.
 2182     FORC
 2183         F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
 2184     BEHAVED (B)
 2185         ALIGNED and WRITEABLE.
 2186     CARRAY (CA)
 2187         BEHAVED and C_CONTIGUOUS.
 2188     FARRAY (FA)
 2189         BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.
 2190 
 2191     Notes
 2192     -----
 2193     The `flags` object can be accessed dictionary-like (as in ``a.flags['WRITEABLE']``),
 2194     or by using lowercased attribute names (as in ``a.flags.writeable``). Short flag
 2195     names are only supported in dictionary access.
 2196 
 2197     Only the WRITEBACKIFCOPY, UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be
 2198     changed by the user, via direct assignment to the attribute or dictionary
 2199     entry, or by calling `ndarray.setflags`.
 2200 
 2201     The array flags cannot be set arbitrarily:
 2202 
 2203     - UPDATEIFCOPY can only be set ``False``.
 2204     - WRITEBACKIFCOPY can only be set ``False``.
 2205     - ALIGNED can only be set ``True`` if the data is truly aligned.
 2206     - WRITEABLE can only be set ``True`` if the array owns its own memory
 2207       or the ultimate owner of the memory exposes a writeable buffer
 2208       interface or is a string.
 2209 
 2210     Arrays can be both C-style and Fortran-style contiguous simultaneously.
 2211     This is clear for 1-dimensional arrays, but can also be true for higher
 2212     dimensional arrays.
 2213 
 2214     Even for contiguous arrays a stride for a given dimension
 2215     ``arr.strides[dim]`` may be *arbitrary* if ``arr.shape[dim] == 1``
 2216     or the array has no elements.
 2217     It does *not* generally hold that ``self.strides[-1] == self.itemsize``
 2218     for C-style contiguous arrays or ``self.strides[0] == self.itemsize`` for
 2219     Fortran-style contiguous arrays is true.
 2220     """))
 2221 
 2222 
 2223 add_newdoc('numpy.core.multiarray', 'ndarray', ('flat',
 2224     """
 2225     A 1-D iterator over the array.
 2226 
 2227     This is a `numpy.flatiter` instance, which acts similarly to, but is not
 2228     a subclass of, Python's built-in iterator object.
 2229 
 2230     See Also
 2231     --------
 2232     flatten : Return a copy of the array collapsed into one dimension.
 2233 
 2234     flatiter
 2235 
 2236     Examples
 2237     --------
 2238     >>> x = np.arange(1, 7).reshape(2, 3)
 2239     >>> x
 2240     array([[1, 2, 3],
 2241            [4, 5, 6]])
 2242     >>> x.flat[3]
 2243     4
 2244     >>> x.T
 2245     array([[1, 4],
 2246            [2, 5],
 2247            [3, 6]])
 2248     >>> x.T.flat[3]
 2249     5
 2250     >>> type(x.flat)
 2251     <type 'numpy.flatiter'>
 2252 
 2253     An assignment example:
 2254 
 2255     >>> x.flat = 3; x
 2256     array([[3, 3, 3],
 2257            [3, 3, 3]])
 2258     >>> x.flat[[1,4]] = 1; x
 2259     array([[3, 1, 3],
 2260            [3, 1, 3]])
 2261 
 2262     """))
 2263 
 2264 
 2265 add_newdoc('numpy.core.multiarray', 'ndarray', ('nbytes',
 2266     """
 2267     Total bytes consumed by the elements of the array.
 2268 
 2269     Notes
 2270     -----
 2271     Does not include memory consumed by non-element attributes of the
 2272     array object.
 2273 
 2274     Examples
 2275     --------
 2276     >>> x = np.zeros((3,5,2), dtype=np.complex128)
 2277     >>> x.nbytes
 2278     480
 2279     >>> np.prod(x.shape) * x.itemsize
 2280     480
 2281 
 2282     """))
 2283 
 2284 
 2285 add_newdoc('numpy.core.multiarray', 'ndarray', ('ndim',
 2286     """
 2287     Number of array dimensions.
 2288 
 2289     Examples
 2290     --------
 2291     >>> x = np.array([1, 2, 3])
 2292     >>> x.ndim
 2293     1
 2294     >>> y = np.zeros((2, 3, 4))
 2295     >>> y.ndim
 2296     3
 2297 
 2298     """))
 2299 
 2300 
 2301 add_newdoc('numpy.core.multiarray', 'ndarray', ('real',
 2302     """
 2303     The real part of the array.
 2304 
 2305     Examples
 2306     --------
 2307     >>> x = np.sqrt([1+0j, 0+1j])
 2308     >>> x.real
 2309     array([ 1.        ,  0.70710678])
 2310     >>> x.real.dtype
 2311     dtype('float64')
 2312 
 2313     See Also
 2314     --------
 2315     numpy.real : equivalent function
 2316 
 2317     """))
 2318 
 2319 
 2320 add_newdoc('numpy.core.multiarray', 'ndarray', ('shape',
 2321     """
 2322     Tuple of array dimensions.
 2323 
 2324     The shape property is usually used to get the current shape of an array,
 2325     but may also be used to reshape the array in-place by assigning a tuple of
 2326     array dimensions to it.  As with `numpy.reshape`, one of the new shape
 2327     dimensions can be -1, in which case its value is inferred from the size of
 2328     the array and the remaining dimensions. Reshaping an array in-place will
 2329     fail if a copy is required.
 2330 
 2331     Examples
 2332     --------
 2333     >>> x = np.array([1, 2, 3, 4])
 2334     >>> x.shape
 2335     (4,)
 2336     >>> y = np.zeros((2, 3, 4))
 2337     >>> y.shape
 2338     (2, 3, 4)
 2339     >>> y.shape = (3, 8)
 2340     >>> y
 2341     array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
 2342            [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
 2343            [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
 2344     >>> y.shape = (3, 6)
 2345     Traceback (most recent call last):
 2346       File "<stdin>", line 1, in <module>
 2347     ValueError: total size of new array must be unchanged
 2348     >>> np.zeros((4,2))[::2].shape = (-1,)
 2349     Traceback (most recent call last):
 2350       File "<stdin>", line 1, in <module>
 2351     AttributeError: incompatible shape for a non-contiguous array
 2352 
 2353     See Also
 2354     --------
 2355     numpy.reshape : similar function
 2356     ndarray.reshape : similar method
 2357 
 2358     """))
 2359 
 2360 
 2361 add_newdoc('numpy.core.multiarray', 'ndarray', ('size',
 2362     """
 2363     Number of elements in the array.
 2364 
 2365     Equal to ``np.prod(a.shape)``, i.e., the product of the array's
 2366     dimensions.
 2367 
 2368     Notes
 2369     -----
 2370     `a.size` returns a standard arbitrary precision Python integer. This
 2371     may not be the case with other methods of obtaining the same value
 2372     (like the suggested ``np.prod(a.shape)``, which returns an instance
 2373     of ``np.int_``), and may be relevant if the value is used further in
 2374     calculations that may overflow a fixed size integer type.
 2375 
 2376     Examples
 2377     --------
 2378     >>> x = np.zeros((3, 5, 2), dtype=np.complex128)
 2379     >>> x.size
 2380     30
 2381     >>> np.prod(x.shape)
 2382     30
 2383 
 2384     """))
 2385 
 2386 
 2387 add_newdoc('numpy.core.multiarray', 'ndarray', ('strides',
 2388     """
 2389     Tuple of bytes to step in each dimension when traversing an array.
 2390 
 2391     The byte offset of element ``(i[0], i[1], ..., i[n])`` in an array `a`
 2392     is::
 2393 
 2394         offset = sum(np.array(i) * a.strides)
 2395 
 2396     A more detailed explanation of strides can be found in the
 2397     "ndarray.rst" file in the NumPy reference guide.
 2398 
 2399     Notes
 2400     -----
 2401     Imagine an array of 32-bit integers (each 4 bytes)::
 2402 
 2403       x = np.array([[0, 1, 2, 3, 4],
 2404                     [5, 6, 7, 8, 9]], dtype=np.int32)
 2405 
 2406     This array is stored in memory as 40 bytes, one after the other
 2407     (known as a contiguous block of memory).  The strides of an array tell
 2408     us how many bytes we have to skip in memory to move to the next position
 2409     along a certain axis.  For example, we have to skip 4 bytes (1 value) to
 2410     move to the next column, but 20 bytes (5 values) to get to the same
 2411     position in the next row.  As such, the strides for the array `x` will be
 2412     ``(20, 4)``.
 2413 
 2414     See Also
 2415     --------
 2416     numpy.lib.stride_tricks.as_strided
 2417 
 2418     Examples
 2419     --------
 2420     >>> y = np.reshape(np.arange(2*3*4), (2,3,4))
 2421     >>> y
 2422     array([[[ 0,  1,  2,  3],
 2423             [ 4,  5,  6,  7],
 2424             [ 8,  9, 10, 11]],
 2425            [[12, 13, 14, 15],
 2426             [16, 17, 18, 19],
 2427             [20, 21, 22, 23]]])
 2428     >>> y.strides
 2429     (48, 16, 4)
 2430     >>> y[1,1,1]
 2431     17
 2432     >>> offset=sum(y.strides * np.array((1,1,1)))
 2433     >>> offset/y.itemsize
 2434     17
 2435 
 2436     >>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
 2437     >>> x.strides
 2438     (32, 4, 224, 1344)
 2439     >>> i = np.array([3,5,2,2])
 2440     >>> offset = sum(i * x.strides)
 2441     >>> x[3,5,2,2]
 2442     813
 2443     >>> offset / x.itemsize
 2444     813
 2445 
 2446     """))
 2447 
 2448 
 2449 add_newdoc('numpy.core.multiarray', 'ndarray', ('T',
 2450     """
 2451     Same as self.transpose(), except that self is returned if
 2452     self.ndim < 2.
 2453 
 2454     Examples
 2455     --------
 2456     >>> x = np.array([[1.,2.],[3.,4.]])
 2457     >>> x
 2458     array([[ 1.,  2.],
 2459            [ 3.,  4.]])
 2460     >>> x.T
 2461     array([[ 1.,  3.],
 2462            [ 2.,  4.]])
 2463     >>> x = np.array([1.,2.,3.,4.])
 2464     >>> x
 2465     array([ 1.,  2.,  3.,  4.])
 2466     >>> x.T
 2467     array([ 1.,  2.,  3.,  4.])
 2468 
 2469     """))
 2470 
 2471 
 2472 ##############################################################################
 2473 #
 2474 # ndarray methods
 2475 #
 2476 ##############################################################################
 2477 
 2478 
 2479 add_newdoc('numpy.core.multiarray', 'ndarray', ('__array__',
 2480     """ a.__array__(|dtype) -> reference if type unchanged, copy otherwise.
 2481 
 2482     Returns either a new reference to self if dtype is not given or a new array
 2483     of provided data type if dtype is different from the current dtype of the
 2484     array.
 2485 
 2486     """))
 2487 
 2488 
 2489 add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_prepare__',
 2490     """a.__array_prepare__(obj) -> Object of same type as ndarray object obj.
 2491 
 2492     """))
 2493 
 2494 
 2495 add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_wrap__',
 2496     """a.__array_wrap__(obj) -> Object of same type as ndarray object a.
 2497 
 2498     """))
 2499 
 2500 
 2501 add_newdoc('numpy.core.multiarray', 'ndarray', ('__copy__',
 2502     """a.__copy__()
 2503 
 2504     Used if :func:`copy.copy` is called on an array. Returns a copy of the array.
 2505 
 2506     Equivalent to ``a.copy(order='K')``.
 2507 
 2508     """))
 2509 
 2510 
 2511 add_newdoc('numpy.core.multiarray', 'ndarray', ('__deepcopy__',
 2512     """a.__deepcopy__(memo, /) -> Deep copy of array.
 2513 
 2514     Used if :func:`copy.deepcopy` is called on an array.
 2515 
 2516     """))
 2517 
 2518 
 2519 add_newdoc('numpy.core.multiarray', 'ndarray', ('__reduce__',
 2520     """a.__reduce__()
 2521 
 2522     For pickling.
 2523 
 2524     """))
 2525 
 2526 
 2527 add_newdoc('numpy.core.multiarray', 'ndarray', ('__setstate__',
 2528     """a.__setstate__(state, /)
 2529 
 2530     For unpickling.
 2531 
 2532     The `state` argument must be a sequence that contains the following
 2533     elements:
 2534 
 2535     Parameters
 2536     ----------
 2537     version : int
 2538         optional pickle version. If omitted defaults to 0.
 2539     shape : tuple
 2540     dtype : data-type
 2541     isFortran : bool
 2542     rawdata : string or list
 2543         a binary string with the data (or a list if 'a' is an object array)
 2544 
 2545     """))
 2546 
 2547 
 2548 add_newdoc('numpy.core.multiarray', 'ndarray', ('all',
 2549     """
 2550     a.all(axis=None, out=None, keepdims=False)
 2551 
 2552     Returns True if all elements evaluate to True.
 2553 
 2554     Refer to `numpy.all` for full documentation.
 2555 
 2556     See Also
 2557     --------
 2558     numpy.all : equivalent function
 2559 
 2560     """))
 2561 
 2562 
 2563 add_newdoc('numpy.core.multiarray', 'ndarray', ('any',
 2564     """
 2565     a.any(axis=None, out=None, keepdims=False)
 2566 
 2567     Returns True if any of the elements of `a` evaluate to True.
 2568 
 2569     Refer to `numpy.any` for full documentation.
 2570 
 2571     See Also
 2572     --------
 2573     numpy.any : equivalent function
 2574 
 2575     """))
 2576 
 2577 
 2578 add_newdoc('numpy.core.multiarray', 'ndarray', ('argmax',
 2579     """
 2580     a.argmax(axis=None, out=None)
 2581 
 2582     Return indices of the maximum values along the given axis.
 2583 
 2584     Refer to `numpy.argmax` for full documentation.
 2585 
 2586     See Also
 2587     --------
 2588     numpy.argmax : equivalent function
 2589 
 2590     """))
 2591 
 2592 
 2593 add_newdoc('numpy.core.multiarray', 'ndarray', ('argmin',
 2594     """
 2595     a.argmin(axis=None, out=None)
 2596 
 2597     Return indices of the minimum values along the given axis of `a`.
 2598 
 2599     Refer to `numpy.argmin` for detailed documentation.
 2600 
 2601     See Also
 2602     --------
 2603     numpy.argmin : equivalent function
 2604 
 2605     """))
 2606 
 2607 
 2608 add_newdoc('numpy.core.multiarray', 'ndarray', ('argsort',
 2609     """
 2610     a.argsort(axis=-1, kind='quicksort', order=None)
 2611 
 2612     Returns the indices that would sort this array.
 2613 
 2614     Refer to `numpy.argsort` for full documentation.
 2615 
 2616     See Also
 2617     --------
 2618     numpy.argsort : equivalent function
 2619 
 2620     """))
 2621 
 2622 
 2623 add_newdoc('numpy.core.multiarray', 'ndarray', ('argpartition',
 2624     """
 2625     a.argpartition(kth, axis=-1, kind='introselect', order=None)
 2626 
 2627     Returns the indices that would partition this array.
 2628 
 2629     Refer to `numpy.argpartition` for full documentation.
 2630 
 2631     .. versionadded:: 1.8.0
 2632 
 2633     See Also
 2634     --------
 2635     numpy.argpartition : equivalent function
 2636 
 2637     """))
 2638 
 2639 
 2640 add_newdoc('numpy.core.multiarray', 'ndarray', ('astype',
 2641     """
 2642     a.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
 2643 
 2644     Copy of the array, cast to a specified type.
 2645 
 2646     Parameters
 2647     ----------
 2648     dtype : str or dtype
 2649         Typecode or data-type to which the array is cast.
 2650     order : {'C', 'F', 'A', 'K'}, optional
 2651         Controls the memory layout order of the result.
 2652         'C' means C order, 'F' means Fortran order, 'A'
 2653         means 'F' order if all the arrays are Fortran contiguous,
 2654         'C' order otherwise, and 'K' means as close to the
 2655         order the array elements appear in memory as possible.
 2656         Default is 'K'.
 2657     casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
 2658         Controls what kind of data casting may occur. Defaults to 'unsafe'
 2659         for backwards compatibility.
 2660 
 2661           * 'no' means the data types should not be cast at all.
 2662           * 'equiv' means only byte-order changes are allowed.
 2663           * 'safe' means only casts which can preserve values are allowed.
 2664           * 'same_kind' means only safe casts or casts within a kind,
 2665             like float64 to float32, are allowed.
 2666           * 'unsafe' means any data conversions may be done.
 2667     subok : bool, optional
 2668         If True, then sub-classes will be passed-through (default), otherwise
 2669         the returned array will be forced to be a base-class array.
 2670     copy : bool, optional
 2671         By default, astype always returns a newly allocated array. If this
 2672         is set to false, and the `dtype`, `order`, and `subok`
 2673         requirements are satisfied, the input array is returned instead
 2674         of a copy.
 2675 
 2676     Returns
 2677     -------
 2678     arr_t : ndarray
 2679         Unless `copy` is False and the other conditions for returning the input
 2680         array are satisfied (see description for `copy` input parameter), `arr_t`
 2681         is a new array of the same shape as the input array, with dtype, order
 2682         given by `dtype`, `order`.
 2683 
 2684     Notes
 2685     -----
 2686     Starting in NumPy 1.9, astype method now returns an error if the string
 2687     dtype to cast to is not long enough in 'safe' casting mode to hold the max
 2688     value of integer/float array that is being casted. Previously the casting
 2689     was allowed even if the result was truncated.
 2690 
 2691     Raises
 2692     ------
 2693     ComplexWarning
 2694         When casting from complex to float or int. To avoid this,
 2695         one should use ``a.real.astype(t)``.
 2696 
 2697     Examples
 2698     --------
 2699     >>> x = np.array([1, 2, 2.5])
 2700     >>> x
 2701     array([ 1. ,  2. ,  2.5])
 2702 
 2703     >>> x.astype(int)
 2704     array([1, 2, 2])
 2705 
 2706     """))
 2707 
 2708 
 2709 add_newdoc('numpy.core.multiarray', 'ndarray', ('byteswap',
 2710     """
 2711     a.byteswap(inplace=False)
 2712 
 2713     Swap the bytes of the array elements
 2714 
 2715     Toggle between low-endian and big-endian data representation by
 2716     returning a byteswapped array, optionally swapped in-place.
 2717 
 2718     Parameters
 2719     ----------
 2720     inplace : bool, optional
 2721         If ``True``, swap bytes in-place, default is ``False``.
 2722 
 2723     Returns
 2724     -------
 2725     out : ndarray
 2726         The byteswapped array. If `inplace` is ``True``, this is
 2727         a view to self.
 2728 
 2729     Examples
 2730     --------
 2731     >>> A = np.array([1, 256, 8755], dtype=np.int16)
 2732     >>> map(hex, A)
 2733     ['0x1', '0x100', '0x2233']
 2734     >>> A.byteswap(inplace=True)
 2735     array([  256,     1, 13090], dtype=int16)
 2736     >>> map(hex, A)
 2737     ['0x100', '0x1', '0x3322']
 2738 
 2739     Arrays of strings are not swapped
 2740 
 2741     >>> A = np.array(['ceg', 'fac'])
 2742     >>> A.byteswap()
 2743     array(['ceg', 'fac'],
 2744           dtype='|S3')
 2745 
 2746     """))
 2747 
 2748 
 2749 add_newdoc('numpy.core.multiarray', 'ndarray', ('choose',
 2750     """
 2751     a.choose(choices, out=None, mode='raise')
 2752 
 2753     Use an index array to construct a new array from a set of choices.
 2754 
 2755     Refer to `numpy.choose` for full documentation.
 2756 
 2757     See Also
 2758     --------
 2759     numpy.choose : equivalent function
 2760 
 2761     """))
 2762 
 2763 
 2764 add_newdoc('numpy.core.multiarray', 'ndarray', ('clip',
 2765     """
 2766     a.clip(min=None, max=None, out=None)
 2767 
 2768     Return an array whose values are limited to ``[min, max]``.
 2769     One of max or min must be given.
 2770 
 2771     Refer to `numpy.clip` for full documentation.
 2772 
 2773     See Also
 2774     --------
 2775     numpy.clip : equivalent function
 2776 
 2777     """))
 2778 
 2779 
 2780 add_newdoc('numpy.core.multiarray', 'ndarray', ('compress',
 2781     """
 2782     a.compress(condition, axis=None, out=None)
 2783 
 2784     Return selected slices of this array along given axis.
 2785 
 2786     Refer to `numpy.compress` for full documentation.
 2787 
 2788     See Also
 2789     --------
 2790     numpy.compress : equivalent function
 2791 
 2792     """))
 2793 
 2794 
 2795 add_newdoc('numpy.core.multiarray', 'ndarray', ('conj',
 2796     """
 2797     a.conj()
 2798 
 2799     Complex-conjugate all elements.
 2800 
 2801     Refer to `numpy.conjugate` for full documentation.
 2802 
 2803     See Also
 2804     --------
 2805     numpy.conjugate : equivalent function
 2806 
 2807     """))
 2808 
 2809 
 2810 add_newdoc('numpy.core.multiarray', 'ndarray', ('conjugate',
 2811     """
 2812     a.conjugate()
 2813 
 2814     Return the complex conjugate, element-wise.
 2815 
 2816     Refer to `numpy.conjugate` for full documentation.
 2817 
 2818     See Also
 2819     --------
 2820     numpy.conjugate : equivalent function
 2821 
 2822     """))
 2823 
 2824 
 2825 add_newdoc('numpy.core.multiarray', 'ndarray', ('copy',
 2826     """
 2827     a.copy(order='C')
 2828 
 2829     Return a copy of the array.
 2830 
 2831     Parameters
 2832     ----------
 2833     order : {'C', 'F', 'A', 'K'}, optional
 2834         Controls the memory layout of the copy. 'C' means C-order,
 2835         'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
 2836         'C' otherwise. 'K' means match the layout of `a` as closely
 2837         as possible. (Note that this function and :func:`numpy.copy` are very
 2838         similar, but have different default values for their order=
 2839         arguments.)
 2840 
 2841     See also
 2842     --------
 2843     numpy.copy
 2844     numpy.copyto
 2845 
 2846     Examples
 2847     --------
 2848     >>> x = np.array([[1,2,3],[4,5,6]], order='F')
 2849 
 2850     >>> y = x.copy()
 2851 
 2852     >>> x.fill(0)
 2853 
 2854     >>> x
 2855     array([[0, 0, 0],
 2856            [0, 0, 0]])
 2857 
 2858     >>> y
 2859     array([[1, 2, 3],
 2860            [4, 5, 6]])
 2861 
 2862     >>> y.flags['C_CONTIGUOUS']
 2863     True
 2864 
 2865     """))
 2866 
 2867 
 2868 add_newdoc('numpy.core.multiarray', 'ndarray', ('cumprod',
 2869     """
 2870     a.cumprod(axis=None, dtype=None, out=None)
 2871 
 2872     Return the cumulative product of the elements along the given axis.
 2873 
 2874     Refer to `numpy.cumprod` for full documentation.
 2875 
 2876     See Also
 2877     --------
 2878     numpy.cumprod : equivalent function
 2879 
 2880     """))
 2881 
 2882 
 2883 add_newdoc('numpy.core.multiarray', 'ndarray', ('cumsum',
 2884     """
 2885     a.cumsum(axis=None, dtype=None, out=None)
 2886 
 2887     Return the cumulative sum of the elements along the given axis.
 2888 
 2889     Refer to `numpy.cumsum` for full documentation.
 2890 
 2891     See Also
 2892     --------
 2893     numpy.cumsum : equivalent function
 2894 
 2895     """))
 2896 
 2897 
 2898 add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal',
 2899     """
 2900     a.diagonal(offset=0, axis1=0, axis2=1)
 2901 
 2902     Return specified diagonals. In NumPy 1.9 the returned array is a
 2903     read-only view instead of a copy as in previous NumPy versions.  In
 2904     a future version the read-only restriction will be removed.
 2905 
 2906     Refer to :func:`numpy.diagonal` for full documentation.
 2907 
 2908     See Also
 2909     --------
 2910     numpy.diagonal : equivalent function
 2911 
 2912     """))
 2913 
 2914 
 2915 add_newdoc('numpy.core.multiarray', 'ndarray', ('dot',
 2916     """
 2917     a.dot(b, out=None)
 2918 
 2919     Dot product of two arrays.
 2920 
 2921     Refer to `numpy.dot` for full documentation.
 2922 
 2923     See Also
 2924     --------
 2925     numpy.dot : equivalent function
 2926 
 2927     Examples
 2928     --------
 2929     >>> a = np.eye(2)
 2930     >>> b = np.ones((2, 2)) * 2
 2931     >>> a.dot(b)
 2932     array([[ 2.,  2.],
 2933            [ 2.,  2.]])
 2934 
 2935     This array method can be conveniently chained:
 2936 
 2937     >>> a.dot(b).dot(b)
 2938     array([[ 8.,  8.],
 2939            [ 8.,  8.]])
 2940 
 2941     """))
 2942 
 2943 
 2944 add_newdoc('numpy.core.multiarray', 'ndarray', ('dump',
 2945     """a.dump(file)
 2946 
 2947     Dump a pickle of the array to the specified file.
 2948     The array can be read back with pickle.load or numpy.load.
 2949 
 2950     Parameters
 2951     ----------
 2952     file : str
 2953         A string naming the dump file.
 2954 
 2955     """))
 2956 
 2957 
 2958 add_newdoc('numpy.core.multiarray', 'ndarray', ('dumps',
 2959     """
 2960     a.dumps()
 2961 
 2962     Returns the pickle of the array as a string.
 2963     pickle.loads or numpy.loads will convert the string back to an array.
 2964 
 2965     Parameters
 2966     ----------
 2967     None
 2968 
 2969     """))
 2970 
 2971 
 2972 add_newdoc('numpy.core.multiarray', 'ndarray', ('fill',
 2973     """
 2974     a.fill(value)
 2975 
 2976     Fill the array with a scalar value.
 2977 
 2978     Parameters
 2979     ----------
 2980     value : scalar
 2981         All elements of `a` will be assigned this value.
 2982 
 2983     Examples
 2984     --------
 2985     >>> a = np.array([1, 2])
 2986     >>> a.fill(0)
 2987     >>> a
 2988     array([0, 0])
 2989     >>> a = np.empty(2)
 2990     >>> a.fill(1)
 2991     >>> a
 2992     array([ 1.,  1.])
 2993 
 2994     """))
 2995 
 2996 
 2997 add_newdoc('numpy.core.multiarray', 'ndarray', ('flatten',
 2998     """
 2999     a.flatten(order='C')
 3000 
 3001     Return a copy of the array collapsed into one dimension.
 3002 
 3003     Parameters
 3004     ----------
 3005     order : {'C', 'F', 'A', 'K'}, optional
 3006         'C' means to flatten in row-major (C-style) order.
 3007         'F' means to flatten in column-major (Fortran-
 3008         style) order. 'A' means to flatten in column-major
 3009         order if `a` is Fortran *contiguous* in memory,
 3010         row-major order otherwise. 'K' means to flatten
 3011         `a` in the order the elements occur in memory.
 3012         The default is 'C'.
 3013 
 3014     Returns
 3015     -------
 3016     y : ndarray
 3017         A copy of the input array, flattened to one dimension.
 3018 
 3019     See Also
 3020     --------
 3021     ravel : Return a flattened array.
 3022     flat : A 1-D flat iterator over the array.
 3023 
 3024     Examples
 3025     --------
 3026     >>> a = np.array([[1,2], [3,4]])
 3027     >>> a.flatten()
 3028     array([1, 2, 3, 4])
 3029     >>> a.flatten('F')
 3030     array([1, 3, 2, 4])
 3031 
 3032     """))
 3033 
 3034 
 3035 add_newdoc('numpy.core.multiarray', 'ndarray', ('getfield',
 3036     """
 3037     a.getfield(dtype, offset=0)
 3038 
 3039     Returns a field of the given array as a certain type.
 3040 
 3041     A field is a view of the array data with a given data-type. The values in
 3042     the view are determined by the given type and the offset into the current
 3043     array in bytes. The offset needs to be such that the view dtype fits in the
 3044     array dtype; for example an array of dtype complex128 has 16-byte elements.
 3045     If taking a view with a 32-bit integer (4 bytes), the offset needs to be
 3046     between 0 and 12 bytes.
 3047 
 3048     Parameters
 3049     ----------
 3050     dtype : str or dtype
 3051         The data type of the view. The dtype size of the view can not be larger
 3052         than that of the array itself.
 3053     offset : int
 3054         Number of bytes to skip before beginning the element view.
 3055 
 3056     Examples
 3057     --------
 3058     >>> x = np.diag([1.+1.j]*2)
 3059     >>> x[1, 1] = 2 + 4.j
 3060     >>> x
 3061     array([[ 1.+1.j,  0.+0.j],
 3062            [ 0.+0.j,  2.+4.j]])
 3063     >>> x.getfield(np.float64)
 3064     array([[ 1.,  0.],
 3065            [ 0.,  2.]])
 3066 
 3067     By choosing an offset of 8 bytes we can select the complex part of the
 3068     array for our view:
 3069 
 3070     >>> x.getfield(np.float64, offset=8)
 3071     array([[ 1.,  0.],
 3072        [ 0.,  4.]])
 3073 
 3074     """))
 3075 
 3076 
 3077 add_newdoc('numpy.core.multiarray', 'ndarray', ('item',
 3078     """
 3079     a.item(*args)
 3080 
 3081     Copy an element of an array to a standard Python scalar and return it.
 3082 
 3083     Parameters
 3084     ----------
 3085     \\*args : Arguments (variable number and type)
 3086 
 3087         * none: in this case, the method only works for arrays
 3088           with one element (`a.size == 1`), which element is
 3089           copied into a standard Python scalar object and returned.
 3090 
 3091         * int_type: this argument is interpreted as a flat index into
 3092           the array, specifying which element to copy and return.
 3093 
 3094         * tuple of int_types: functions as does a single int_type argument,
 3095           except that the argument is interpreted as an nd-index into the
 3096           array.
 3097 
 3098     Returns
 3099     -------
 3100     z : Standard Python scalar object
 3101         A copy of the specified element of the array as a suitable
 3102         Python scalar
 3103 
 3104     Notes
 3105     -----
 3106     When the data type of `a` is longdouble or clongdouble, item() returns
 3107     a scalar array object because there is no available Python scalar that
 3108     would not lose information. Void arrays return a buffer object for item(),
 3109     unless fields are defined, in which case a tuple is returned.
 3110 
 3111     `item` is very similar to a[args], except, instead of an array scalar,
 3112     a standard Python scalar is returned. This can be useful for speeding up
 3113     access to elements of the array and doing arithmetic on elements of the
 3114     array using Python's optimized math.
 3115 
 3116     Examples
 3117     --------
 3118     >>> x = np.random.randint(9, size=(3, 3))
 3119     >>> x
 3120     array([[3, 1, 7],
 3121            [2, 8, 3],
 3122            [8, 5, 3]])
 3123     >>> x.item(3)
 3124     2
 3125     >>> x.item(7)
 3126     5
 3127     >>> x.item((0, 1))
 3128     1
 3129     >>> x.item((2, 2))
 3130     3
 3131 
 3132     """))
 3133 
 3134 
 3135 add_newdoc('numpy.core.multiarray', 'ndarray', ('itemset',
 3136     """
 3137     a.itemset(*args)
 3138 
 3139     Insert scalar into an array (scalar is cast to array's dtype, if possible)
 3140 
 3141     There must be at least 1 argument, and define the last argument
 3142     as *item*.  Then, ``a.itemset(*args)`` is equivalent to but faster
 3143     than ``a[args] = item``.  The item should be a scalar value and `args`
 3144     must select a single item in the array `a`.
 3145 
 3146     Parameters
 3147     ----------
 3148     \\*args : Arguments
 3149         If one argument: a scalar, only used in case `a` is of size 1.
 3150         If two arguments: the last argument is the value to be set
 3151         and must be a scalar, the first argument specifies a single array
 3152         element location. It is either an int or a tuple.
 3153 
 3154     Notes
 3155     -----
 3156     Compared to indexing syntax, `itemset` provides some speed increase
 3157     for placing a scalar into a particular location in an `ndarray`,
 3158     if you must do this.  However, generally this is discouraged:
 3159     among other problems, it complicates the appearance of the code.
 3160     Also, when using `itemset` (and `item`) inside a loop, be sure
 3161     to assign the methods to a local variable to avoid the attribute
 3162     look-up at each loop iteration.
 3163 
 3164     Examples
 3165     --------
 3166     >>> x = np.random.randint(9, size=(3, 3))
 3167     >>> x
 3168     array([[3, 1, 7],
 3169            [2, 8, 3],
 3170            [8, 5, 3]])
 3171     >>> x.itemset(4, 0)
 3172     >>> x.itemset((2, 2), 9)
 3173     >>> x
 3174     array([[3, 1, 7],
 3175            [2, 0, 3],
 3176            [8, 5, 9]])
 3177 
 3178     """))
 3179 
 3180 
 3181 add_newdoc('numpy.core.multiarray', 'ndarray', ('max',
 3182     """
 3183     a.max(axis=None, out=None, keepdims=False)
 3184 
 3185     Return the maximum along a given axis.
 3186 
 3187     Refer to `numpy.amax` for full documentation.
 3188 
 3189     See Also
 3190     --------
 3191     numpy.amax : equivalent function
 3192 
 3193     """))
 3194 
 3195 
 3196 add_newdoc('numpy.core.multiarray', 'ndarray', ('mean',
 3197     """
 3198     a.mean(axis=None, dtype=None, out=None, keepdims=False)
 3199 
 3200     Returns the average of the array elements along given axis.
 3201 
 3202     Refer to `numpy.mean` for full documentation.
 3203 
 3204     See Also
 3205     --------
 3206     numpy.mean : equivalent function
 3207 
 3208     """))
 3209 
 3210 
 3211 add_newdoc('numpy.core.multiarray', 'ndarray', ('min',
 3212     """
 3213     a.min(axis=None, out=None, keepdims=False)
 3214 
 3215     Return the minimum along a given axis.
 3216 
 3217     Refer to `numpy.amin` for full documentation.
 3218 
 3219     See Also
 3220     --------
 3221     numpy.amin : equivalent function
 3222 
 3223     """))
 3224 
 3225 
 3226 add_newdoc('numpy.core.multiarray', 'shares_memory',
 3227     """
 3228     shares_memory(a, b, max_work=None)
 3229 
 3230     Determine if two arrays share memory
 3231 
 3232     Parameters
 3233     ----------
 3234     a, b : ndarray
 3235         Input arrays
 3236     max_work : int, optional
 3237         Effort to spend on solving the overlap problem (maximum number
 3238         of candidate solutions to consider). The following special
 3239         values are recognized:
 3240 
 3241         max_work=MAY_SHARE_EXACT  (default)
 3242             The problem is solved exactly. In this case, the function returns
 3243             True only if there is an element shared between the arrays.
 3244         max_work=MAY_SHARE_BOUNDS
 3245             Only the memory bounds of a and b are checked.
 3246 
 3247     Raises
 3248     ------
 3249     numpy.TooHardError
 3250         Exceeded max_work.
 3251 
 3252     Returns
 3253     -------
 3254     out : bool
 3255 
 3256     See Also
 3257     --------
 3258     may_share_memory
 3259 
 3260     Examples
 3261     --------
 3262     >>> np.may_share_memory(np.array([1,2]), np.array([5,8,9]))
 3263     False
 3264 
 3265     """)
 3266 
 3267 
 3268 add_newdoc('numpy.core.multiarray', 'may_share_memory',
 3269     """
 3270     may_share_memory(a, b, max_work=None)
 3271 
 3272     Determine if two arrays might share memory
 3273 
 3274     A return of True does not necessarily mean that the two arrays
 3275     share any element.  It just means that they *might*.
 3276 
 3277     Only the memory bounds of a and b are checked by default.
 3278 
 3279     Parameters
 3280     ----------
 3281     a, b : ndarray
 3282         Input arrays
 3283     max_work : int, optional
 3284         Effort to spend on solving the overlap problem.  See
 3285         `shares_memory` for details.  Default for ``may_share_memory``
 3286         is to do a bounds check.
 3287 
 3288     Returns
 3289     -------
 3290     out : bool
 3291 
 3292     See Also
 3293     --------
 3294     shares_memory
 3295 
 3296     Examples
 3297     --------
 3298     >>> np.may_share_memory(np.array([1,2]), np.array([5,8,9]))
 3299     False
 3300     >>> x = np.zeros([3, 4])
 3301     >>> np.may_share_memory(x[:,0], x[:,1])
 3302     True
 3303 
 3304     """)
 3305 
 3306 
 3307 add_newdoc('numpy.core.multiarray', 'ndarray', ('newbyteorder',
 3308     """
 3309     arr.newbyteorder(new_order='S')
 3310 
 3311     Return the array with the same data viewed with a different byte order.
 3312 
 3313     Equivalent to::
 3314 
 3315         arr.view(arr.dtype.newbytorder(new_order))
 3316 
 3317     Changes are also made in all fields and sub-arrays of the array data
 3318     type.
 3319 
 3320 
 3321 
 3322     Parameters
 3323     ----------
 3324     new_order : string, optional
 3325         Byte order to force; a value from the byte order specifications
 3326         below. `new_order` codes can be any of:
 3327 
 3328         * 'S' - swap dtype from current to opposite endian
 3329         * {'<', 'L'} - little endian
 3330         * {'>', 'B'} - big endian
 3331         * {'=', 'N'} - native order
 3332         * {'|', 'I'} - ignore (no change to byte order)
 3333 
 3334         The default value ('S') results in swapping the current
 3335         byte order. The code does a case-insensitive check on the first
 3336         letter of `new_order` for the alternatives above.  For example,
 3337         any of 'B' or 'b' or 'biggish' are valid to specify big-endian.
 3338 
 3339 
 3340     Returns
 3341     -------
 3342     new_arr : array
 3343         New array object with the dtype reflecting given change to the
 3344         byte order.
 3345 
 3346     """))
 3347 
 3348 
 3349 add_newdoc('numpy.core.multiarray', 'ndarray', ('nonzero',
 3350     """
 3351     a.nonzero()
 3352 
 3353     Return the indices of the elements that are non-zero.
 3354 
 3355     Refer to `numpy.nonzero` for full documentation.
 3356 
 3357     See Also
 3358     --------
 3359     numpy.nonzero : equivalent function
 3360 
 3361     """))
 3362 
 3363 
 3364 add_newdoc('numpy.core.multiarray', 'ndarray', ('prod',
 3365     """
 3366     a.prod(axis=None, dtype=None, out=None, keepdims=False)
 3367 
 3368     Return the product of the array elements over the given axis
 3369 
 3370     Refer to `numpy.prod` for full documentation.
 3371 
 3372     See Also
 3373     --------
 3374     numpy.prod : equivalent function
 3375 
 3376     """))
 3377 
 3378 
 3379 add_newdoc('numpy.core.multiarray', 'ndarray', ('ptp',
 3380     """
 3381     a.ptp(axis=None, out=None, keepdims=False)
 3382 
 3383     Peak to peak (maximum - minimum) value along a given axis.
 3384 
 3385     Refer to `numpy.ptp` for full documentation.
 3386 
 3387     See Also
 3388     --------
 3389     numpy.ptp : equivalent function
 3390 
 3391     """))
 3392 
 3393 
 3394 add_newdoc('numpy.core.multiarray', 'ndarray', ('put',
 3395     """
 3396     a.put(indices, values, mode='raise')
 3397 
 3398     Set ``a.flat[n] = values[n]`` for all `n` in indices.
 3399 
 3400     Refer to `numpy.put` for full documentation.
 3401 
 3402     See Also
 3403     --------
 3404     numpy.put : equivalent function
 3405 
 3406     """))
 3407 
 3408 add_newdoc('numpy.core.multiarray', 'copyto',
 3409     """
 3410     copyto(dst, src, casting='same_kind', where=True)
 3411 
 3412     Copies values from one array to another, broadcasting as necessary.
 3413 
 3414     Raises a TypeError if the `casting` rule is violated, and if
 3415     `where` is provided, it selects which elements to copy.
 3416 
 3417     .. versionadded:: 1.7.0
 3418 
 3419     Parameters
 3420     ----------
 3421     dst : ndarray
 3422         The array into which values are copied.
 3423     src : array_like
 3424         The array from which values are copied.
 3425     casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
 3426         Controls what kind of data casting may occur when copying.
 3427 
 3428           * 'no' means the data types should not be cast at all.
 3429           * 'equiv' means only byte-order changes are allowed.
 3430           * 'safe' means only casts which can preserve values are allowed.
 3431           * 'same_kind' means only safe casts or casts within a kind,
 3432             like float64 to float32, are allowed.
 3433           * 'unsafe' means any data conversions may be done.
 3434     where : array_like of bool, optional
 3435         A boolean array which is broadcasted to match the dimensions
 3436         of `dst`, and selects elements to copy from `src` to `dst`
 3437         wherever it contains the value True.
 3438 
 3439     """)
 3440 
 3441 add_newdoc('numpy.core.multiarray', 'putmask',
 3442     """
 3443     putmask(a, mask, values)
 3444 
 3445     Changes elements of an array based on conditional and input values.
 3446 
 3447     Sets ``a.flat[n] = values[n]`` for each n where ``mask.flat[n]==True``.
 3448 
 3449     If `values` is not the same size as `a` and `mask` then it will repeat.
 3450     This gives behavior different from ``a[mask] = values``.
 3451 
 3452     Parameters
 3453     ----------
 3454     a : array_like
 3455         Target array.
 3456     mask : array_like
 3457         Boolean mask array. It has to be the same shape as `a`.
 3458     values : array_like
 3459         Values to put into `a` where `mask` is True. If `values` is smaller
 3460         than `a` it will be repeated.
 3461 
 3462     See Also
 3463     --------
 3464     place, put, take, copyto
 3465 
 3466     Examples
 3467     --------
 3468     >>> x = np.arange(6).reshape(2, 3)
 3469     >>> np.putmask(x, x>2, x**2)
 3470     >>> x
 3471     array([[ 0,  1,  2],
 3472            [ 9, 16, 25]])
 3473 
 3474     If `values` is smaller than `a` it is repeated:
 3475 
 3476     >>> x = np.arange(5)
 3477     >>> np.putmask(x, x>1, [-33, -44])
 3478     >>> x
 3479     array([  0,   1, -33, -44, -33])
 3480 
 3481     """)
 3482 
 3483 
 3484 add_newdoc('numpy.core.multiarray', 'ndarray', ('ravel',
 3485     """
 3486     a.ravel([order])
 3487 
 3488     Return a flattened array.
 3489 
 3490     Refer to `numpy.ravel` for full documentation.
 3491 
 3492     See Also
 3493     --------
 3494     numpy.ravel : equivalent function
 3495 
 3496     ndarray.flat : a flat iterator on the array.
 3497 
 3498     """))
 3499 
 3500 
 3501 add_newdoc('numpy.core.multiarray', 'ndarray', ('repeat',
 3502     """
 3503     a.repeat(repeats, axis=None)
 3504 
 3505     Repeat elements of an array.
 3506 
 3507     Refer to `numpy.repeat` for full documentation.
 3508 
 3509     See Also
 3510     --------
 3511     numpy.repeat : equivalent function
 3512 
 3513     """))
 3514 
 3515 
 3516 add_newdoc('numpy.core.multiarray', 'ndarray', ('reshape',
 3517     """
 3518     a.reshape(shape, order='C')
 3519 
 3520     Returns an array containing the same data with a new shape.
 3521 
 3522     Refer to `numpy.reshape` for full documentation.
 3523 
 3524     See Also
 3525     --------
 3526     numpy.reshape : equivalent function
 3527 
 3528     Notes
 3529     -----
 3530     Unlike the free function `numpy.reshape`, this method on `ndarray` allows
 3531     the elements of the shape parameter to be passed in as separate arguments.
 3532     For example, ``a.reshape(10, 11)`` is equivalent to
 3533     ``a.reshape((10, 11))``.
 3534 
 3535     """))
 3536 
 3537 
 3538 add_newdoc('numpy.core.multiarray', 'ndarray', ('resize',
 3539     """
 3540     a.resize(new_shape, refcheck=True)
 3541 
 3542     Change shape and size of array in-place.
 3543 
 3544     Parameters
 3545     ----------
 3546     new_shape : tuple of ints, or `n` ints
 3547         Shape of resized array.
 3548     refcheck : bool, optional
 3549         If False, reference count will not be checked. Default is True.
 3550 
 3551     Returns
 3552     -------
 3553     None
 3554 
 3555     Raises
 3556     ------
 3557     ValueError
 3558         If `a` does not own its own data or references or views to it exist,
 3559         and the data memory must be changed.
 3560         PyPy only: will always raise if the data memory must be changed, since
 3561         there is no reliable way to determine if references or views to it
 3562         exist.
 3563 
 3564     SystemError
 3565         If the `order` keyword argument is specified. This behaviour is a
 3566         bug in NumPy.
 3567 
 3568     See Also
 3569     --------
 3570     resize : Return a new array with the specified shape.
 3571 
 3572     Notes
 3573     -----
 3574     This reallocates space for the data area if necessary.
 3575 
 3576     Only contiguous arrays (data elements consecutive in memory) can be
 3577     resized.
 3578 
 3579     The purpose of the reference count check is to make sure you
 3580     do not use this array as a buffer for another Python object and then
 3581     reallocate the memory. However, reference counts can increase in
 3582     other ways so if you are sure that you have not shared the memory
 3583     for this array with another Python object, then you may safely set
 3584     `refcheck` to False.
 3585 
 3586     Examples
 3587     --------
 3588     Shrinking an array: array is flattened (in the order that the data are
 3589     stored in memory), resized, and reshaped:
 3590 
 3591     >>> a = np.array([[0, 1], [2, 3]], order='C')
 3592     >>> a.resize((2, 1))
 3593     >>> a
 3594     array([[0],
 3595            [1]])
 3596 
 3597     >>> a = np.array([[0, 1], [2, 3]], order='F')
 3598     >>> a.resize((2, 1))
 3599     >>> a
 3600     array([[0],
 3601            [2]])
 3602 
 3603     Enlarging an array: as above, but missing entries are filled with zeros:
 3604 
 3605     >>> b = np.array([[0, 1], [2, 3]])
 3606     >>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
 3607     >>> b
 3608     array([[0, 1, 2],
 3609            [3, 0, 0]])
 3610 
 3611     Referencing an array prevents resizing...
 3612 
 3613     >>> c = a
 3614     >>> a.resize((1, 1))
 3615     Traceback (most recent call last):
 3616     ...
 3617     ValueError: cannot resize an array that has been referenced ...
 3618 
 3619     Unless `refcheck` is False:
 3620 
 3621     >>> a.resize((1, 1), refcheck=False)
 3622     >>> a
 3623     array([[0]])
 3624     >>> c
 3625     array([[0]])
 3626 
 3627     """))
 3628 
 3629 
 3630 add_newdoc('numpy.core.multiarray', 'ndarray', ('round',
 3631     """
 3632     a.round(decimals=0, out=None)
 3633 
 3634     Return `a` with each element rounded to the given number of decimals.
 3635 
 3636     Refer to `numpy.around` for full documentation.
 3637 
 3638     See Also
 3639     --------
 3640     numpy.around : equivalent function
 3641 
 3642     """))
 3643 
 3644 
 3645 add_newdoc('numpy.core.multiarray', 'ndarray', ('searchsorted',
 3646     """
 3647     a.searchsorted(v, side='left', sorter=None)
 3648 
 3649     Find indices where elements of v should be inserted in a to maintain order.
 3650 
 3651     For full documentation, see `numpy.searchsorted`
 3652 
 3653     See Also
 3654     --------
 3655     numpy.searchsorted : equivalent function
 3656 
 3657     """))
 3658 
 3659 
 3660 add_newdoc('numpy.core.multiarray', 'ndarray', ('setfield',
 3661     """
 3662     a.setfield(val, dtype, offset=0)
 3663 
 3664     Put a value into a specified place in a field defined by a data-type.
 3665 
 3666     Place `val` into `a`'s field defined by `dtype` and beginning `offset`
 3667     bytes into the field.
 3668 
 3669     Parameters
 3670     ----------
 3671     val : object
 3672         Value to be placed in field.
 3673     dtype : dtype object
 3674         Data-type of the field in which to place `val`.
 3675     offset : int, optional
 3676         The number of bytes into the field at which to place `val`.
 3677 
 3678     Returns
 3679     -------
 3680     None
 3681 
 3682     See Also
 3683     --------
 3684     getfield
 3685 
 3686     Examples
 3687     --------
 3688     >>> x = np.eye(3)
 3689     >>> x.getfield(np.float64)
 3690     array([[ 1.,  0.,  0.],
 3691            [ 0.,  1.,  0.],
 3692            [ 0.,  0.,  1.]])
 3693     >>> x.setfield(3, np.int32)
 3694     >>> x.getfield(np.int32)
 3695     array([[3, 3, 3],
 3696            [3, 3, 3],
 3697            [3, 3, 3]])
 3698     >>> x
 3699     array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
 3700            [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
 3701            [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
 3702     >>> x.setfield(np.eye(3), np.int32)
 3703     >>> x
 3704     array([[ 1.,  0.,  0.],
 3705            [ 0.,  1.,  0.],
 3706            [ 0.,  0.,  1.]])
 3707 
 3708     """))
 3709 
 3710 
 3711 add_newdoc('numpy.core.multiarray', 'ndarray', ('setflags',
 3712     """
 3713     a.setflags(write=None, align=None, uic=None)
 3714 
 3715     Set array flags WRITEABLE, ALIGNED, (WRITEBACKIFCOPY and UPDATEIFCOPY),
 3716     respectively.
 3717 
 3718     These Boolean-valued flags affect how numpy interprets the memory
 3719     area used by `a` (see Notes below). The ALIGNED flag can only
 3720     be set to True if the data is actually aligned according to the type.
 3721     The WRITEBACKIFCOPY and (deprecated) UPDATEIFCOPY flags can never be set
 3722     to True. The flag WRITEABLE can only be set to True if the array owns its
 3723     own memory, or the ultimate owner of the memory exposes a writeable buffer
 3724     interface, or is a string. (The exception for string is made so that
 3725     unpickling can be done without copying memory.)
 3726 
 3727     Parameters
 3728     ----------
 3729     write : bool, optional
 3730         Describes whether or not `a` can be written to.
 3731     align : bool, optional
 3732         Describes whether or not `a` is aligned properly for its type.
 3733     uic : bool, optional
 3734         Describes whether or not `a` is a copy of another "base" array.
 3735 
 3736     Notes
 3737     -----
 3738     Array flags provide information about how the memory area used
 3739     for the array is to be interpreted. There are 7 Boolean flags
 3740     in use, only four of which can be changed by the user:
 3741     WRITEBACKIFCOPY, UPDATEIFCOPY, WRITEABLE, and ALIGNED.
 3742 
 3743     WRITEABLE (W) the data area can be written to;
 3744 
 3745     ALIGNED (A) the data and strides are aligned appropriately for the hardware
 3746     (as determined by the compiler);
 3747 
 3748     UPDATEIFCOPY (U) (deprecated), replaced by WRITEBACKIFCOPY;
 3749 
 3750     WRITEBACKIFCOPY (X) this array is a copy of some other array (referenced
 3751     by .base). When the C-API function PyArray_ResolveWritebackIfCopy is
 3752     called, the base array will be updated with the contents of this array.
 3753 
 3754     All flags can be accessed using the single (upper case) letter as well
 3755     as the full name.
 3756 
 3757     Examples
 3758     --------
 3759     >>> y
 3760     array([[3, 1, 7],
 3761            [2, 0, 0],
 3762            [8, 5, 9]])
 3763     >>> y.flags
 3764       C_CONTIGUOUS : True
 3765       F_CONTIGUOUS : False
 3766       OWNDATA : True
 3767       WRITEABLE : True
 3768       ALIGNED : True
 3769       WRITEBACKIFCOPY : False
 3770       UPDATEIFCOPY : False
 3771     >>> y.setflags(write=0, align=0)
 3772     >>> y.flags
 3773       C_CONTIGUOUS : True
 3774       F_CONTIGUOUS : False
 3775       OWNDATA : True
 3776       WRITEABLE : False
 3777       ALIGNED : False
 3778       WRITEBACKIFCOPY : False
 3779       UPDATEIFCOPY : False
 3780     >>> y.setflags(uic=1)
 3781     Traceback (most recent call last):
 3782       File "<stdin>", line 1, in <module>
 3783     ValueError: cannot set WRITEBACKIFCOPY flag to True
 3784 
 3785     """))
 3786 
 3787 
 3788 add_newdoc('numpy.core.multiarray', 'ndarray', ('sort',
 3789     """
 3790     a.sort(axis=-1, kind='quicksort', order=None)
 3791 
 3792     Sort an array, in-place.
 3793 
 3794     Parameters
 3795     ----------
 3796     axis : int, optional
 3797         Axis along which to sort. Default is -1, which means sort along the
 3798         last axis.
 3799     kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
 3800         Sorting algorithm. Default is 'quicksort'.
 3801     order : str or list of str, optional
 3802         When `a` is an array with fields defined, this argument specifies
 3803         which fields to compare first, second, etc.  A single field can
 3804         be specified as a string, and not all fields need be specified,
 3805         but unspecified fields will still be used, in the order in which
 3806         they come up in the dtype, to break ties.
 3807 
 3808     See Also
 3809     --------
 3810     numpy.sort : Return a sorted copy of an array.
 3811     argsort : Indirect sort.
 3812     lexsort : Indirect stable sort on multiple keys.
 3813     searchsorted : Find elements in sorted array.
 3814     partition: Partial sort.
 3815 
 3816     Notes
 3817     -----
 3818     See ``sort`` for notes on the different sorting algorithms.
 3819 
 3820     Examples
 3821     --------
 3822     >>> a = np.array([[1,4], [3,1]])
 3823     >>> a.sort(axis=1)
 3824     >>> a
 3825     array([[1, 4],
 3826            [1, 3]])
 3827     >>> a.sort(axis=0)
 3828     >>> a
 3829     array([[1, 3],
 3830            [1, 4]])
 3831 
 3832     Use the `order` keyword to specify a field to use when sorting a
 3833     structured array:
 3834 
 3835     >>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
 3836     >>> a.sort(order='y')
 3837     >>> a
 3838     array([('c', 1), ('a', 2)],
 3839           dtype=[('x', '|S1'), ('y', '<i4')])
 3840 
 3841     """))
 3842 
 3843 
 3844 add_newdoc('numpy.core.multiarray', 'ndarray', ('partition',
 3845     """
 3846     a.partition(kth, axis=-1, kind='introselect', order=None)
 3847 
 3848     Rearranges the elements in the array in such a way that the value of the
 3849     element in kth position is in the position it would be in a sorted array.
 3850     All elements smaller than the kth element are moved before this element and
 3851     all equal or greater are moved behind it. The ordering of the elements in
 3852     the two partitions is undefined.
 3853 
 3854     .. versionadded:: 1.8.0
 3855 
 3856     Parameters
 3857     ----------
 3858     kth : int or sequence of ints
 3859         Element index to partition by. The kth element value will be in its
 3860         final sorted position and all smaller elements will be moved before it
 3861         and all equal or greater elements behind it.
 3862         The order of all elements in the partitions is undefined.
 3863         If provided with a sequence of kth it will partition all elements
 3864         indexed by kth of them into their sorted position at once.
 3865     axis : int, optional
 3866         Axis along which to sort. Default is -1, which means sort along the
 3867         last axis.
 3868     kind : {'introselect'}, optional
 3869         Selection algorithm. Default is 'introselect'.
 3870     order : str or list of str, optional
 3871         When `a` is an array with fields defined, this argument specifies
 3872         which fields to compare first, second, etc. A single field can
 3873         be specified as a string, and not all fields need to be specified,
 3874         but unspecified fields will still be used, in the order in which
 3875         they come up in the dtype, to break ties.
 3876 
 3877     See Also
 3878     --------
 3879     numpy.partition : Return a parititioned copy of an array.
 3880     argpartition : Indirect partition.
 3881     sort : Full sort.
 3882 
 3883     Notes
 3884     -----
 3885     See ``np.partition`` for notes on the different algorithms.
 3886 
 3887     Examples
 3888     --------
 3889     >>> a = np.array([3, 4, 2, 1])
 3890     >>> a.partition(3)
 3891     >>> a
 3892     array([2, 1, 3, 4])
 3893 
 3894     >>> a.partition((1, 3))
 3895     array([1, 2, 3, 4])
 3896     """))
 3897 
 3898 
 3899 add_newdoc('numpy.core.multiarray', 'ndarray', ('squeeze',
 3900     """
 3901     a.squeeze(axis=None)
 3902 
 3903     Remove single-dimensional entries from the shape of `a`.
 3904 
 3905     Refer to `numpy.squeeze` for full documentation.
 3906 
 3907     See Also
 3908     --------
 3909     numpy.squeeze : equivalent function
 3910 
 3911     """))
 3912 
 3913 
 3914 add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
 3915     """
 3916     a.std(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
 3917 
 3918     Returns the standard deviation of the array elements along given axis.
 3919 
 3920     Refer to `numpy.std` for full documentation.
 3921 
 3922     See Also
 3923     --------
 3924     numpy.std : equivalent function
 3925 
 3926     """))
 3927 
 3928 
 3929 add_newdoc('numpy.core.multiarray', 'ndarray', ('sum',
 3930     """
 3931     a.sum(axis=None, dtype=None, out=None, keepdims=False)
 3932 
 3933     Return the sum of the array elements over the given axis.
 3934 
 3935     Refer to `numpy.sum` for full documentation.
 3936 
 3937     See Also
 3938     --------
 3939     numpy.sum : equivalent function
 3940 
 3941     """))
 3942 
 3943 
 3944 add_newdoc('numpy.core.multiarray', 'ndarray', ('swapaxes',
 3945     """
 3946     a.swapaxes(axis1, axis2)
 3947 
 3948     Return a view of the array with `axis1` and `axis2` interchanged.
 3949 
 3950     Refer to `numpy.swapaxes` for full documentation.
 3951 
 3952     See Also
 3953     --------
 3954     numpy.swapaxes : equivalent function
 3955 
 3956     """))
 3957 
 3958 
 3959 add_newdoc('numpy.core.multiarray', 'ndarray', ('take',
 3960     """
 3961     a.take(indices, axis=None, out=None, mode='raise')
 3962 
 3963     Return an array formed from the elements of `a` at the given indices.
 3964 
 3965     Refer to `numpy.take` for full documentation.
 3966 
 3967     See Also
 3968     --------
 3969     numpy.take : equivalent function
 3970 
 3971     """))
 3972 
 3973 
 3974 add_newdoc('numpy.core.multiarray', 'ndarray', ('tofile',
 3975     """
 3976     a.tofile(fid, sep="", format="%s")
 3977 
 3978     Write array to a file as text or binary (default).
 3979 
 3980     Data is always written in 'C' order, independent of the order of `a`.
 3981     The data produced by this method can be recovered using the function
 3982     fromfile().
 3983 
 3984     Parameters
 3985     ----------
 3986     fid : file or str
 3987         An open file object, or a string containing a filename.
 3988     sep : str
 3989         Separator between array items for text output.
 3990         If "" (empty), a binary file is written, equivalent to
 3991         ``file.write(a.tobytes())``.
 3992     format : str
 3993         Format string for text file output.
 3994         Each entry in the array is formatted to text by first converting
 3995         it to the closest Python type, and then using "format" % item.
 3996 
 3997     Notes
 3998     -----
 3999     This is a convenience function for quick storage of array data.
 4000     Information on endianness and precision is lost, so this method is not a
 4001     good choice for files intended to archive data or transport data between
 4002     machines with different endianness. Some of these problems can be overcome
 4003     by outputting the data as text files, at the expense of speed and file
 4004     size.
 4005 
 4006     When fid is a file object, array contents are directly written to the
 4007     file, bypassing the file object's ``write`` method. As a result, tofile
 4008     cannot be used with files objects supporting compression (e.g., GzipFile)
 4009     or file-like objects that do not support ``fileno()`` (e.g., BytesIO).
 4010 
 4011     """))
 4012 
 4013 
 4014 add_newdoc('numpy.core.multiarray', 'ndarray', ('tolist',
 4015     """
 4016     a.tolist()
 4017 
 4018     Return the array as a (possibly nested) list.
 4019 
 4020     Return a copy of the array data as a (nested) Python list.
 4021     Data items are converted to the nearest compatible Python type.
 4022 
 4023     Parameters
 4024     ----------
 4025     none
 4026 
 4027     Returns
 4028     -------
 4029     y : list
 4030         The possibly nested list of array elements.
 4031 
 4032     Notes
 4033     -----
 4034     The array may be recreated, ``a = np.array(a.tolist())``.
 4035 
 4036     Examples
 4037     --------
 4038     >>> a = np.array([1, 2])
 4039     >>> a.tolist()
 4040     [1, 2]
 4041     >>> a = np.array([[1, 2], [3, 4]])
 4042     >>> list(a)
 4043     [array([1, 2]), array([3, 4])]
 4044     >>> a.tolist()
 4045     [[1, 2], [3, 4]]
 4046 
 4047     """))
 4048 
 4049 
 4050 tobytesdoc = """
 4051     a.{name}(order='C')
 4052 
 4053     Construct Python bytes containing the raw data bytes in the array.
 4054 
 4055     Constructs Python bytes showing a copy of the raw contents of
 4056     data memory. The bytes object can be produced in either 'C' or 'Fortran',
 4057     or 'Any' order (the default is 'C'-order). 'Any' order means C-order
 4058     unless the F_CONTIGUOUS flag in the array is set, in which case it
 4059     means 'Fortran' order.
 4060 
 4061     {deprecated}
 4062 
 4063     Parameters
 4064     ----------
 4065     order : {{'C', 'F', None}}, optional
 4066         Order of the data for multidimensional arrays:
 4067         C, Fortran, or the same as for the original array.
 4068 
 4069     Returns
 4070     -------
 4071     s : bytes
 4072         Python bytes exhibiting a copy of `a`'s raw data.
 4073 
 4074     Examples
 4075     --------
 4076     >>> x = np.array([[0, 1], [2, 3]])
 4077     >>> x.tobytes()
 4078     b'\\x00\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
 4079     >>> x.tobytes('C') == x.tobytes()
 4080     True
 4081     >>> x.tobytes('F')
 4082     b'\\x00\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
 4083 
 4084     """
 4085 
 4086 add_newdoc('numpy.core.multiarray', 'ndarray',
 4087            ('tostring', tobytesdoc.format(name='tostring',
 4088                                           deprecated=
 4089                                           'This function is a compatibility '
 4090                                           'alias for tobytes. Despite its '
 4091                                           'name it returns bytes not '
 4092                                           'strings.')))
 4093 add_newdoc('numpy.core.multiarray', 'ndarray',
 4094            ('tobytes', tobytesdoc.format(name='tobytes',
 4095                                          deprecated='.. versionadded:: 1.9.0')))
 4096 
 4097 add_newdoc('numpy.core.multiarray', 'ndarray', ('trace',
 4098     """
 4099     a.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)
 4100 
 4101     Return the sum along diagonals of the array.
 4102 
 4103     Refer to `numpy.trace` for full documentation.
 4104 
 4105     See Also
 4106     --------
 4107     numpy.trace : equivalent function
 4108 
 4109     """))
 4110 
 4111 
 4112 add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose',
 4113     """
 4114     a.transpose(*axes)
 4115 
 4116     Returns a view of the array with axes transposed.
 4117 
 4118     For a 1-D array, this has no effect. (To change between column and
 4119     row vectors, first cast the 1-D array into a matrix object.)
 4120     For a 2-D array, this is the usual matrix transpose.
 4121     For an n-D array, if axes are given, their order indicates how the
 4122     axes are permuted (see Examples). If axes are not provided and
 4123     ``a.shape = (i[0], i[1], ... i[n-2], i[n-1])``, then
 4124     ``a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0])``.
 4125 
 4126     Parameters
 4127     ----------
 4128     axes : None, tuple of ints, or `n` ints
 4129 
 4130      * None or no argument: reverses the order of the axes.
 4131 
 4132      * tuple of ints: `i` in the `j`-th place in the tuple means `a`'s
 4133        `i`-th axis becomes `a.transpose()`'s `j`-th axis.
 4134 
 4135      * `n` ints: same as an n-tuple of the same ints (this form is
 4136        intended simply as a "convenience" alternative to the tuple form)
 4137 
 4138     Returns
 4139     -------
 4140     out : ndarray
 4141         View of `a`, with axes suitably permuted.
 4142 
 4143     See Also
 4144     --------
 4145     ndarray.T : Array property returning the array transposed.
 4146 
 4147     Examples
 4148     --------
 4149     >>> a = np.array([[1, 2], [3, 4]])
 4150     >>> a
 4151     array([[1, 2],
 4152            [3, 4]])
 4153     >>> a.transpose()
 4154     array([[1, 3],
 4155            [2, 4]])
 4156     >>> a.transpose((1, 0))
 4157     array([[1, 3],
 4158            [2, 4]])
 4159     >>> a.transpose(1, 0)
 4160     array([[1, 3],
 4161            [2, 4]])
 4162 
 4163     """))
 4164 
 4165 
 4166 add_newdoc('numpy.core.multiarray', 'ndarray', ('var',
 4167     """
 4168     a.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
 4169 
 4170     Returns the variance of the array elements, along given axis.
 4171 
 4172     Refer to `numpy.var` for full documentation.
 4173 
 4174     See Also
 4175     --------
 4176     numpy.var : equivalent function
 4177 
 4178     """))
 4179 
 4180 
 4181 add_newdoc('numpy.core.multiarray', 'ndarray', ('view',
 4182     """
 4183     a.view(dtype=None, type=None)
 4184 
 4185     New view of array with the same data.
 4186 
 4187     Parameters
 4188     ----------
 4189     dtype : data-type or ndarray sub-class, optional
 4190         Data-type descriptor of the returned view, e.g., float32 or int16. The
 4191         default, None, results in the view having the same data-type as `a`.
 4192         This argument can also be specified as an ndarray sub-class, which
 4193         then specifies the type of the returned object (this is equivalent to
 4194         setting the ``type`` parameter).
 4195     type : Python type, optional
 4196         Type of the returned view, e.g., ndarray or matrix.  Again, the
 4197         default None results in type preservation.
 4198 
 4199     Notes
 4200     -----
 4201     ``a.view()`` is used two different ways:
 4202 
 4203     ``a.view(some_dtype)`` or ``a.view(dtype=some_dtype)`` constructs a view
 4204     of the array's memory with a different data-type.  This can cause a
 4205     reinterpretation of the bytes of memory.
 4206 
 4207     ``a.view(ndarray_subclass)`` or ``a.view(type=ndarray_subclass)`` just
 4208     returns an instance of `ndarray_subclass` that looks at the same array
 4209     (same shape, dtype, etc.)  This does not cause a reinterpretation of the
 4210     memory.
 4211 
 4212     For ``a.view(some_dtype)``, if ``some_dtype`` has a different number of
 4213     bytes per entry than the previous dtype (for example, converting a
 4214     regular array to a structured array), then the behavior of the view
 4215     cannot be predicted just from the superficial appearance of ``a`` (shown
 4216     by ``print(a)``). It also depends on exactly how ``a`` is stored in
 4217     memory. Therefore if ``a`` is C-ordered versus fortran-ordered, versus
 4218     defined as a slice or transpose, etc., the view may give different
 4219     results.
 4220 
 4221 
 4222     Examples
 4223     --------
 4224     >>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])
 4225 
 4226     Viewing array data using a different type and dtype:
 4227 
 4228     >>> y = x.view(dtype=np.int16, type=np.matrix)
 4229     >>> y
 4230     matrix([[513]], dtype=int16)
 4231     >>> print(type(y))
 4232     <class 'numpy.matrixlib.defmatrix.matrix'>
 4233 
 4234     Creating a view on a structured array so it can be used in calculations
 4235 
 4236     >>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
 4237     >>> xv = x.view(dtype=np.int8).reshape(-1,2)
 4238     >>> xv
 4239     array([[1, 2],
 4240            [3, 4]], dtype=int8)
 4241     >>> xv.mean(0)
 4242     array([ 2.,  3.])
 4243 
 4244     Making changes to the view changes the underlying array
 4245 
 4246     >>> xv[0,1] = 20
 4247     >>> print(x)
 4248     [(1, 20) (3, 4)]
 4249 
 4250     Using a view to convert an array to a recarray:
 4251 
 4252     >>> z = x.view(np.recarray)
 4253     >>> z.a
 4254     array([1], dtype=int8)
 4255 
 4256     Views share data:
 4257 
 4258     >>> x[0] = (9, 10)
 4259     >>> z[0]
 4260     (9, 10)
 4261 
 4262     Views that change the dtype size (bytes per entry) should normally be
 4263     avoided on arrays defined by slices, transposes, fortran-ordering, etc.:
 4264 
 4265     >>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
 4266     >>> y = x[:, 0:2]
 4267     >>> y
 4268     array([[1, 2],
 4269            [4, 5]], dtype=int16)
 4270     >>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
 4271     Traceback (most recent call last):
 4272       File "<stdin>", line 1, in <module>
 4273     ValueError: new type not compatible with array.
 4274     >>> z = y.copy()
 4275     >>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
 4276     array([[(1, 2)],
 4277            [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])
 4278     """))
 4279 
 4280 
 4281 ##############################################################################
 4282 #
 4283 # umath functions
 4284 #
 4285 ##############################################################################
 4286 
 4287 add_newdoc('numpy.core.umath', 'frompyfunc',
 4288     """
 4289     frompyfunc(func, nin, nout)
 4290 
 4291     Takes an arbitrary Python function and returns a NumPy ufunc.
 4292 
 4293     Can be used, for example, to add broadcasting to a built-in Python
 4294     function (see Examples section).
 4295 
 4296     Parameters
 4297     ----------
 4298     func : Python function object
 4299         An arbitrary Python function.
 4300     nin : int
 4301         The number of input arguments.
 4302     nout : int
 4303         The number of objects returned by `func`.
 4304 
 4305     Returns
 4306     -------
 4307     out : ufunc
 4308         Returns a NumPy universal function (``ufunc``) object.
 4309 
 4310     See Also
 4311     --------
 4312     vectorize : evaluates pyfunc over input arrays using broadcasting rules of numpy
 4313 
 4314     Notes
 4315     -----
 4316     The returned ufunc always returns PyObject arrays.
 4317 
 4318     Examples
 4319     --------
 4320     Use frompyfunc to add broadcasting to the Python function ``oct``:
 4321 
 4322     >>> oct_array = np.frompyfunc(oct, 1, 1)
 4323     >>> oct_array(np.array((10, 30, 100)))
 4324     array([012, 036, 0144], dtype=object)
 4325     >>> np.array((oct(10), oct(30), oct(100))) # for comparison
 4326     array(['012', '036', '0144'],
 4327           dtype='|S4')
 4328 
 4329     """)
 4330 
 4331 add_newdoc('numpy.core.umath', 'geterrobj',
 4332     """
 4333     geterrobj()
 4334 
 4335     Return the current object that defines floating-point error handling.
 4336 
 4337     The error object contains all information that defines the error handling
 4338     behavior in NumPy. `geterrobj` is used internally by the other
 4339     functions that get and set error handling behavior (`geterr`, `seterr`,
 4340     `geterrcall`, `seterrcall`).
 4341 
 4342     Returns
 4343     -------
 4344     errobj : list
 4345         The error object, a list containing three elements:
 4346         [internal numpy buffer size, error mask, error callback function].
 4347 
 4348         The error mask is a single integer that holds the treatment information
 4349         on all four floating point errors. The information for each error type
 4350         is contained in three bits of the integer. If we print it in base 8, we
 4351         can see what treatment is set for "invalid", "under", "over", and
 4352         "divide" (in that order). The printed string can be interpreted with
 4353 
 4354         * 0 : 'ignore'
 4355         * 1 : 'warn'
 4356         * 2 : 'raise'
 4357         * 3 : 'call'
 4358         * 4 : 'print'
 4359         * 5 : 'log'
 4360 
 4361     See Also
 4362     --------
 4363     seterrobj, seterr, geterr, seterrcall, geterrcall
 4364     getbufsize, setbufsize
 4365 
 4366     Notes
 4367     -----
 4368     For complete documentation of the types of floating-point exceptions and
 4369     treatment options, see `seterr`.
 4370 
 4371     Examples
 4372     --------
 4373     >>> np.geterrobj()  # first get the defaults
 4374     [10000, 0, None]
 4375 
 4376     >>> def err_handler(type, flag):
 4377     ...     print("Floating point error (%s), with flag %s" % (type, flag))
 4378     ...
 4379     >>> old_bufsize = np.setbufsize(20000)
 4380     >>> old_err = np.seterr(divide='raise')
 4381     >>> old_handler = np.seterrcall(err_handler)
 4382     >>> np.geterrobj()
 4383     [20000, 2, <function err_handler at 0x91dcaac>]
 4384 
 4385     >>> old_err = np.seterr(all='ignore')
 4386     >>> np.base_repr(np.geterrobj()[1], 8)
 4387     '0'
 4388     >>> old_err = np.seterr(divide='warn', over='log', under='call',
 4389                             invalid='print')
 4390     >>> np.base_repr(np.geterrobj()[1], 8)
 4391     '4351'
 4392 
 4393     """)
 4394 
 4395 add_newdoc('numpy.core.umath', 'seterrobj',
 4396     """
 4397     seterrobj(errobj)
 4398 
 4399     Set the object that defines floating-point error handling.
 4400 
 4401     The error object contains all information that defines the error handling
 4402     behavior in NumPy. `seterrobj` is used internally by the other
 4403     functions that set error handling behavior (`seterr`, `seterrcall`).
 4404 
 4405     Parameters
 4406     ----------
 4407     errobj : list
 4408         The error object, a list containing three elements:
 4409         [internal numpy buffer size, error mask, error callback function].
 4410 
 4411         The error mask is a single integer that holds the treatment information
 4412         on all four floating point errors. The information for each error type
 4413         is contained in three bits of the integer. If we print it in base 8, we
 4414         can see what treatment is set for "invalid", "under", "over", and
 4415         "divide" (in that order). The printed string can be interpreted with
 4416 
 4417         * 0 : 'ignore'
 4418         * 1 : 'warn'
 4419         * 2 : 'raise'
 4420         * 3 : 'call'
 4421         * 4 : 'print'
 4422         * 5 : 'log'
 4423 
 4424     See Also
 4425     --------
 4426     geterrobj, seterr, geterr, seterrcall, geterrcall
 4427     getbufsize, setbufsize
 4428 
 4429     Notes
 4430     -----
 4431     For complete documentation of the types of floating-point exceptions and
 4432     treatment options, see `seterr`.
 4433 
 4434     Examples
 4435     --------
 4436     >>> old_errobj = np.geterrobj()  # first get the defaults
 4437     >>> old_errobj
 4438     [10000, 0, None]
 4439 
 4440     >>> def err_handler(type, flag):
 4441     ...     print("Floating point error (%s), with flag %s" % (type, flag))
 4442     ...
 4443     >>> new_errobj = [20000, 12, err_handler]
 4444     >>> np.seterrobj(new_errobj)
 4445     >>> np.base_repr(12, 8)  # int for divide=4 ('print') and over=1 ('warn')
 4446     '14'
 4447     >>> np.geterr()
 4448     {'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'}
 4449     >>> np.geterrcall() is err_handler
 4450     True
 4451 
 4452     """)
 4453 
 4454 
 4455 ##############################################################################
 4456 #
 4457 # compiled_base functions
 4458 #
 4459 ##############################################################################
 4460 
 4461 add_newdoc('numpy.core.multiarray', 'add_docstring',
 4462     """
 4463     add_docstring(obj, docstring)
 4464 
 4465     Add a docstring to a built-in obj if possible.
 4466     If the obj already has a docstring raise a RuntimeError
 4467     If this routine does not know how to add a docstring to the object
 4468     raise a TypeError
 4469     """)
 4470 
 4471 add_newdoc('numpy.core.umath', '_add_newdoc_ufunc',
 4472     """
 4473     add_ufunc_docstring(ufunc, new_docstring)
 4474 
 4475     Replace the docstring for a ufunc with new_docstring.
 4476     This method will only work if the current docstring for
 4477     the ufunc is NULL. (At the C level, i.e. when ufunc->doc is NULL.)
 4478 
 4479     Parameters
 4480     ----------
 4481     ufunc : numpy.ufunc
 4482         A ufunc whose current doc is NULL.
 4483     new_docstring : string
 4484         The new docstring for the ufunc.
 4485 
 4486     Notes
 4487     -----
 4488     This method allocates memory for new_docstring on
 4489     the heap. Technically this creates a mempory leak, since this
 4490     memory will not be reclaimed until the end of the program
 4491     even if the ufunc itself is removed. However this will only
 4492     be a problem if the user is repeatedly creating ufuncs with
 4493     no documentation, adding documentation via add_newdoc_ufunc,
 4494     and then throwing away the ufunc.
 4495     """)
 4496 
 4497 add_newdoc('numpy.core.multiarray', 'packbits',
 4498     """
 4499     packbits(myarray, axis=None)
 4500 
 4501     Packs the elements of a binary-valued array into bits in a uint8 array.
 4502 
 4503     The result is padded to full bytes by inserting zero bits at the end.
 4504 
 4505     Parameters
 4506     ----------
 4507     myarray : array_like
 4508         An array of integers or booleans whose elements should be packed to
 4509         bits.
 4510     axis : int, optional
 4511         The dimension over which bit-packing is done.
 4512         ``None`` implies packing the flattened array.
 4513 
 4514     Returns
 4515     -------
 4516     packed : ndarray
 4517         Array of type uint8 whose elements represent bits corresponding to the
 4518         logical (0 or nonzero) value of the input elements. The shape of
 4519         `packed` has the same number of dimensions as the input (unless `axis`
 4520         is None, in which case the output is 1-D).
 4521 
 4522     See Also
 4523     --------
 4524     unpackbits: Unpacks elements of a uint8 array into a binary-valued output
 4525                 array.
 4526 
 4527     Examples
 4528     --------
 4529     >>> a = np.array([[[1,0,1],
 4530     ...                [0,1,0]],
 4531     ...               [[1,1,0],
 4532     ...                [0,0,1]]])
 4533     >>> b = np.packbits(a, axis=-1)
 4534     >>> b
 4535     array([[[160],[64]],[[192],[32]]], dtype=uint8)
 4536 
 4537     Note that in binary 160 = 1010 0000, 64 = 0100 0000, 192 = 1100 0000,
 4538     and 32 = 0010 0000.
 4539 
 4540     """)
 4541 
 4542 add_newdoc('numpy.core.multiarray', 'unpackbits',
 4543     """
 4544     unpackbits(myarray, axis=None)
 4545 
 4546     Unpacks elements of a uint8 array into a binary-valued output array.
 4547 
 4548     Each element of `myarray` represents a bit-field that should be unpacked
 4549     into a binary-valued output array. The shape of the output array is either
 4550     1-D (if `axis` is None) or the same shape as the input array with unpacking
 4551     done along the axis specified.
 4552 
 4553     Parameters
 4554     ----------
 4555     myarray : ndarray, uint8 type
 4556        Input array.
 4557     axis : int, optional
 4558         The dimension over which bit-unpacking is done.
 4559         ``None`` implies unpacking the flattened array.
 4560 
 4561     Returns
 4562     -------
 4563     unpacked : ndarray, uint8 type
 4564        The elements are binary-valued (0 or 1).
 4565 
 4566     See Also
 4567     --------
 4568     packbits : Packs the elements of a binary-valued array into bits in a uint8
 4569                array.
 4570 
 4571     Examples
 4572     --------
 4573     >>> a = np.array([[2], [7], [23]], dtype=np.uint8)
 4574     >>> a
 4575     array([[ 2],
 4576            [ 7],
 4577            [23]], dtype=uint8)
 4578     >>> b = np.unpackbits(a, axis=1)
 4579     >>> b
 4580     array([[0, 0, 0, 0, 0, 0, 1, 0],
 4581            [0, 0, 0, 0, 0, 1, 1, 1],
 4582            [0, 0, 0, 1, 0, 1, 1, 1]], dtype=uint8)
 4583 
 4584     """)
 4585 
 4586 add_newdoc('numpy.core._multiarray_tests', 'format_float_OSprintf_g',
 4587     """
 4588     format_float_OSprintf_g(val, precision)
 4589 
 4590     Print a floating point scalar using the system's printf function,
 4591     equivalent to:
 4592 
 4593         printf("%.*g", precision, val);
 4594 
 4595     for half/float/double, or replacing 'g' by 'Lg' for longdouble. This
 4596     method is designed to help cross-validate the format_float_* methods.
 4597 
 4598     Parameters
 4599     ----------
 4600     val : python float or numpy floating scalar
 4601         Value to format.
 4602 
 4603     precision : non-negative integer, optional
 4604         Precision given to printf.
 4605 
 4606     Returns
 4607     -------
 4608     rep : string
 4609         The string representation of the floating point value
 4610 
 4611     See Also
 4612     --------
 4613     format_float_scientific
 4614     format_float_positional
 4615     """)
 4616 
 4617 
 4618 ##############################################################################
 4619 #
 4620 # Documentation for ufunc attributes and methods
 4621 #
 4622 ##############################################################################
 4623 
 4624 
 4625 ##############################################################################
 4626 #
 4627 # ufunc object
 4628 #
 4629 ##############################################################################
 4630 
 4631 add_newdoc('numpy.core', 'ufunc',
 4632     """
 4633     Functions that operate element by element on whole arrays.
 4634 
 4635     To see the documentation for a specific ufunc, use `info`.  For
 4636     example, ``np.info(np.sin)``.  Because ufuncs are written in C
 4637     (for speed) and linked into Python with NumPy's ufunc facility,
 4638     Python's help() function finds this page whenever help() is called
 4639     on a ufunc.
 4640 
 4641     A detailed explanation of ufuncs can be found in the docs for :ref:`ufuncs`.
 4642 
 4643     Calling ufuncs:
 4644     ===============
 4645 
 4646     op(*x[, out], where=True, **kwargs)
 4647     Apply `op` to the arguments `*x` elementwise, broadcasting the arguments.
 4648 
 4649     The broadcasting rules are:
 4650 
 4651     * Dimensions of length 1 may be prepended to either array.
 4652     * Arrays may be repeated along dimensions of length 1.
 4653 
 4654     Parameters
 4655     ----------
 4656     *x : array_like
 4657         Input arrays.
 4658     out : ndarray, None, or tuple of ndarray and None, optional
 4659         Alternate array object(s) in which to put the result; if provided, it
 4660         must have a shape that the inputs broadcast to. A tuple of arrays
 4661         (possible only as a keyword argument) must have length equal to the
 4662         number of outputs; use `None` for uninitialized outputs to be
 4663         allocated by the ufunc.
 4664     where : array_like, optional
 4665         Values of True indicate to calculate the ufunc at that position, values
 4666         of False indicate to leave the value in the output alone.  Note that if
 4667         an uninitialized return array is created via the default ``out=None``,
 4668         then the elements where the values are False will remain uninitialized.
 4669     **kwargs
 4670         For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.
 4671 
 4672     Returns
 4673     -------
 4674     r : ndarray or tuple of ndarray
 4675         `r` will have the shape that the arrays in `x` broadcast to; if `out` is
 4676         provided, it will be returned. If not, `r` will be allocated and
 4677         may contain uninitialized values. If the function has more than one
 4678         output, then the result will be a tuple of arrays.
 4679 
 4680     """)
 4681 
 4682 
 4683 ##############################################################################
 4684 #
 4685 # ufunc attributes
 4686 #
 4687 ##############################################################################
 4688 
 4689 add_newdoc('numpy.core', 'ufunc', ('identity',
 4690     """
 4691     The identity value.
 4692 
 4693     Data attribute containing the identity element for the ufunc, if it has one.
 4694     If it does not, the attribute value is None.
 4695 
 4696     Examples
 4697     --------
 4698     >>> np.add.identity
 4699     0
 4700     >>> np.multiply.identity
 4701     1
 4702     >>> np.power.identity
 4703     1
 4704     >>> print(np.exp.identity)
 4705     None
 4706     """))
 4707 
 4708 add_newdoc('numpy.core', 'ufunc', ('nargs',
 4709     """
 4710     The number of arguments.
 4711 
 4712     Data attribute containing the number of arguments the ufunc takes, including
 4713     optional ones.
 4714 
 4715     Notes
 4716     -----
 4717     Typically this value will be one more than what you might expect because all
 4718     ufuncs take  the optional "out" argument.
 4719 
 4720     Examples
 4721     --------
 4722     >>> np.add.nargs
 4723     3
 4724     >>> np.multiply.nargs
 4725     3
 4726     >>> np.power.nargs
 4727     3
 4728     >>> np.exp.nargs
 4729     2
 4730     """))
 4731 
 4732 add_newdoc('numpy.core', 'ufunc', ('nin',
 4733     """
 4734     The number of inputs.
 4735 
 4736     Data attribute containing the number of arguments the ufunc treats as input.
 4737 
 4738     Examples
 4739     --------
 4740     >>> np.add.nin
 4741     2
 4742     >>> np.multiply.nin
 4743     2
 4744     >>> np.power.nin
 4745     2
 4746     >>> np.exp.nin
 4747     1
 4748     """))
 4749 
 4750 add_newdoc('numpy.core', 'ufunc', ('nout',
 4751     """
 4752     The number of outputs.
 4753 
 4754     Data attribute containing the number of arguments the ufunc treats as output.
 4755 
 4756     Notes
 4757     -----
 4758     Since all ufuncs can take output arguments, this will always be (at least) 1.
 4759 
 4760     Examples
 4761     --------
 4762     >>> np.add.nout
 4763     1
 4764     >>> np.multiply.nout
 4765     1
 4766     >>> np.power.nout
 4767     1
 4768     >>> np.exp.nout
 4769     1
 4770 
 4771     """))
 4772 
 4773 add_newdoc('numpy.core', 'ufunc', ('ntypes',
 4774     """
 4775     The number of types.
 4776 
 4777     The number of numerical NumPy types - of which there are 18 total - on which
 4778     the ufunc can operate.
 4779 
 4780     See Also
 4781     --------
 4782     numpy.ufunc.types
 4783 
 4784     Examples
 4785     --------
 4786     >>> np.add.ntypes
 4787     18
 4788     >>> np.multiply.ntypes
 4789     18
 4790     >>> np.power.ntypes
 4791     17
 4792     >>> np.exp.ntypes
 4793     7
 4794     >>> np.remainder.ntypes
 4795     14
 4796 
 4797     """))
 4798 
 4799 add_newdoc('numpy.core', 'ufunc', ('types',
 4800     """
 4801     Returns a list with types grouped input->output.
 4802 
 4803     Data attribute listing the data-type "Domain-Range" groupings the ufunc can
 4804     deliver. The data-types are given using the character codes.
 4805 
 4806     See Also
 4807     --------
 4808     numpy.ufunc.ntypes
 4809 
 4810     Examples
 4811     --------
 4812     >>> np.add.types
 4813     ['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l',
 4814     'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D',
 4815     'GG->G', 'OO->O']
 4816 
 4817     >>> np.multiply.types
 4818     ['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l',
 4819     'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D',
 4820     'GG->G', 'OO->O']
 4821 
 4822     >>> np.power.types
 4823     ['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L',
 4824     'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D', 'GG->G',
 4825     'OO->O']
 4826 
 4827     >>> np.exp.types
 4828     ['f->f', 'd->d', 'g->g', 'F->F', 'D->D', 'G->G', 'O->O']
 4829 
 4830     >>> np.remainder.types
 4831     ['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L',
 4832     'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'OO->O']
 4833 
 4834     """))
 4835 
 4836 add_newdoc('numpy.core', 'ufunc', ('signature',
 4837     """
 4838     Definition of the core elements a generalized ufunc operates on.
 4839 
 4840     The signature determines how the dimensions of each input/output array
 4841     are split into core and loop dimensions:
 4842 
 4843     1. Each dimension in the signature is matched to a dimension of the
 4844        corresponding passed-in array, starting from the end of the shape tuple.
 4845     2. Core dimensions assigned to the same label in the signature must have
 4846        exactly matching sizes, no broadcasting is performed.
 4847     3. The core dimensions are removed from all inputs and the remaining
 4848        dimensions are broadcast together, defining the loop dimensions.
 4849 
 4850     Notes
 4851     -----
 4852     Generalized ufuncs are used internally in many linalg functions, and in
 4853     the testing suite; the examples below are taken from these.
 4854     For ufuncs that operate on scalars, the signature is `None`, which is
 4855     equivalent to '()' for every argument.
 4856 
 4857     Examples
 4858     --------
 4859     >>> np.core.umath_tests.matrix_multiply.signature
 4860     '(m,n),(n,p)->(m,p)'
 4861     >>> np.linalg._umath_linalg.det.signature
 4862     '(m,m)->()'
 4863     >>> np.add.signature is None
 4864     True  # equivalent to '(),()->()'
 4865     """))
 4866 
 4867 ##############################################################################
 4868 #
 4869 # ufunc methods
 4870 #
 4871 ##############################################################################
 4872 
 4873 add_newdoc('numpy.core', 'ufunc', ('reduce',
 4874     """
 4875     reduce(a, axis=0, dtype=None, out=None, keepdims=False, initial)
 4876 
 4877     Reduces `a`'s dimension by one, by applying ufunc along one axis.
 4878 
 4879     Let :math:`a.shape = (N_0, ..., N_i, ..., N_{M-1})`.  Then
 4880     :math:`ufunc.reduce(a, axis=i)[k_0, ..,k_{i-1}, k_{i+1}, .., k_{M-1}]` =
 4881     the result of iterating `j` over :math:`range(N_i)`, cumulatively applying
 4882     ufunc to each :math:`a[k_0, ..,k_{i-1}, j, k_{i+1}, .., k_{M-1}]`.
 4883     For a one-dimensional array, reduce produces results equivalent to:
 4884     ::
 4885 
 4886      r = op.identity # op = ufunc
 4887      for i in range(len(A)):
 4888        r = op(r, A[i])
 4889      return r
 4890 
 4891     For example, add.reduce() is equivalent to sum().
 4892 
 4893     Parameters
 4894     ----------
 4895     a : array_like
 4896         The array to act on.
 4897     axis : None or int or tuple of ints, optional
 4898         Axis or axes along which a reduction is performed.
 4899         The default (`axis` = 0) is perform a reduction over the first
 4900         dimension of the input array. `axis` may be negative, in
 4901         which case it counts from the last to the first axis.
 4902 
 4903         .. versionadded:: 1.7.0
 4904 
 4905         If this is `None`, a reduction is performed over all the axes.
 4906         If this is a tuple of ints, a reduction is performed on multiple
 4907         axes, instead of a single axis or all the axes as before.
 4908 
 4909         For operations which are either not commutative or not associative,
 4910         doing a reduction over multiple axes is not well-defined. The
 4911         ufuncs do not currently raise an exception in this case, but will
 4912         likely do so in the future.
 4913     dtype : data-type code, optional
 4914         The type used to represent the intermediate results. Defaults
 4915         to the data-type of the output array if this is provided, or
 4916         the data-type of the input array if no output array is provided.
 4917     out : ndarray, None, or tuple of ndarray and None, optional
 4918         A location into which the result is stored. If not provided or `None`,
 4919         a freshly-allocated array is returned. For consistency with
 4920         :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a
 4921         1-element tuple.
 4922 
 4923         .. versionchanged:: 1.13.0
 4924            Tuples are allowed for keyword argument.
 4925     keepdims : bool, optional
 4926         If this is set to True, the axes which are reduced are left
 4927         in the result as dimensions with size one. With this option,
 4928         the result will broadcast correctly against the original `arr`.
 4929 
 4930         .. versionadded:: 1.7.0
 4931     initial : scalar, optional
 4932         The value with which to start the reduction.
 4933         If the ufunc has no identity or the dtype is object, this defaults
 4934         to None - otherwise it defaults to ufunc.identity.
 4935         If ``None`` is given, the first element of the reduction is used,
 4936         and an error is thrown if the reduction is empty.
 4937 
 4938         .. versionadded:: 1.15.0
 4939 
 4940     Returns
 4941     -------
 4942     r : ndarray
 4943         The reduced array. If `out` was supplied, `r` is a reference to it.
 4944 
 4945     Examples
 4946     --------
 4947     >>> np.multiply.reduce([2,3,5])
 4948     30
 4949 
 4950     A multi-dimensional array example:
 4951 
 4952     >>> X = np.arange(8).reshape((2,2,2))
 4953     >>> X
 4954     array([[[0, 1],
 4955             [2, 3]],
 4956            [[4, 5],
 4957             [6, 7]]])
 4958     >>> np.add.reduce(X, 0)
 4959     array([[ 4,  6],
 4960            [ 8, 10]])
 4961     >>> np.add.reduce(X) # confirm: default axis value is 0
 4962     array([[ 4,  6],
 4963            [ 8, 10]])
 4964     >>> np.add.reduce(X, 1)
 4965     array([[ 2,  4],
 4966            [10, 12]])
 4967     >>> np.add.reduce(X, 2)
 4968     array([[ 1,  5],
 4969            [ 9, 13]])
 4970 
 4971     You can use the ``initial`` keyword argument to initialize the reduction with a
 4972     different value.
 4973 
 4974     >>> np.add.reduce([10], initial=5)
 4975     15
 4976     >>> np.add.reduce(np.ones((2, 2, 2)), axis=(0, 2), initializer=10)
 4977     array([14., 14.])
 4978 
 4979     Allows reductions of empty arrays where they would normally fail, i.e.
 4980     for ufuncs without an identity.
 4981 
 4982     >>> np.minimum.reduce([], initial=np.inf)
 4983     inf
 4984     >>> np.minimum.reduce([])
 4985     Traceback (most recent call last):
 4986         ...
 4987     ValueError: zero-size array to reduction operation minimum which has no identity
 4988     """))
 4989 
 4990 add_newdoc('numpy.core', 'ufunc', ('accumulate',
 4991     """
 4992     accumulate(array, axis=0, dtype=None, out=None)
 4993 
 4994     Accumulate the result of applying the operator to all elements.
 4995 
 4996     For a one-dimensional array, accumulate produces results equivalent to::
 4997 
 4998       r = np.empty(len(A))
 4999       t = op.identity        # op = the ufunc being applied to A's  elements
 5000       for i in range(len(A)):
 5001           t = op(t, A[i])
 5002           r[i] = t
 5003       return r
 5004 
 5005     For example, add.accumulate() is equivalent to np.cumsum().
 5006 
 5007     For a multi-dimensional array, accumulate is applied along only one
 5008     axis (axis zero by default; see Examples below) so repeated use is
 5009     necessary if one wants to accumulate over multiple axes.
 5010 
 5011     Parameters
 5012     ----------
 5013     array : array_like
 5014         The array to act on.
 5015     axis : int, optional
 5016         The axis along which to apply the accumulation; default is zero.
 5017     dtype : data-type code, optional
 5018         The data-type used to represent the intermediate results. Defaults
 5019         to the data-type of the output array if such is provided, or the
 5020         the data-type of the input array if no output array is provided.
 5021     out : ndarray, None, or tuple of ndarray and None, optional
 5022         A location into which the result is stored. If not provided or `None`,
 5023         a freshly-allocated array is returned. For consistency with
 5024         :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a
 5025         1-element tuple.
 5026 
 5027         .. versionchanged:: 1.13.0
 5028            Tuples are allowed for keyword argument.
 5029 
 5030     Returns
 5031     -------
 5032     r : ndarray
 5033         The accumulated values. If `out` was supplied, `r` is a reference to
 5034         `out`.
 5035 
 5036     Examples
 5037     --------
 5038     1-D array examples:
 5039 
 5040     >>> np.add.accumulate([2, 3, 5])
 5041     array([ 2,  5, 10])
 5042     >>> np.multiply.accumulate([2, 3, 5])
 5043     array([ 2,  6, 30])
 5044 
 5045     2-D array examples:
 5046 
 5047     >>> I = np.eye(2)
 5048     >>> I
 5049     array([[ 1.,  0.],
 5050            [ 0.,  1.]])
 5051 
 5052     Accumulate along axis 0 (rows), down columns:
 5053 
 5054     >>> np.add.accumulate(I, 0)
 5055     array([[ 1.,  0.],
 5056            [ 1.,  1.]])
 5057     >>> np.add.accumulate(I) # no axis specified = axis zero
 5058     array([[ 1.,  0.],
 5059            [ 1.,  1.]])
 5060 
 5061     Accumulate along axis 1 (columns), through rows:
 5062 
 5063     >>> np.add.accumulate(I, 1)
 5064     array([[ 1.,  1.],
 5065            [ 0.,  1.]])
 5066 
 5067     """))
 5068 
 5069 add_newdoc('numpy.core', 'ufunc', ('reduceat',
 5070     """
 5071     reduceat(a, indices, axis=0, dtype=None, out=None)
 5072 
 5073     Performs a (local) reduce with specified slices over a single axis.
 5074 
 5075     For i in ``range(len(indices))``, `reduceat` computes
 5076     ``ufunc.reduce(a[indices[i]:indices[i+1]])``, which becomes the i-th
 5077     generalized "row" parallel to `axis` in the final result (i.e., in a
 5078     2-D array, for example, if `axis = 0`, it becomes the i-th row, but if
 5079     `axis = 1`, it becomes the i-th column).  There are three exceptions to this:
 5080 
 5081     * when ``i = len(indices) - 1`` (so for the last index),
 5082       ``indices[i+1] = a.shape[axis]``.
 5083     * if ``indices[i] >= indices[i + 1]``, the i-th generalized "row" is
 5084       simply ``a[indices[i]]``.
 5085     * if ``indices[i] >= len(a)`` or ``indices[i] < 0``, an error is raised.
 5086 
 5087     The shape of the output depends on the size of `indices`, and may be
 5088     larger than `a` (this happens if ``len(indices) > a.shape[axis]``).
 5089 
 5090     Parameters
 5091     ----------
 5092     a : array_like
 5093         The array to act on.
 5094     indices : array_like
 5095         Paired indices, comma separated (not colon), specifying slices to
 5096         reduce.
 5097     axis : int, optional
 5098         The axis along which to apply the reduceat.
 5099     dtype : data-type code, optional
 5100         The type used to represent the intermediate results. Defaults
 5101         to the data type of the output array if this is provided, or
 5102         the data type of the input array if no output array is provided.
 5103     out : ndarray, None, or tuple of ndarray and None, optional
 5104         A location into which the result is stored. If not provided or `None`,
 5105         a freshly-allocated array is returned. For consistency with
 5106         :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a
 5107         1-element tuple.
 5108 
 5109         .. versionchanged:: 1.13.0
 5110            Tuples are allowed for keyword argument.
 5111 
 5112     Returns
 5113     -------
 5114     r : ndarray
 5115         The reduced values. If `out` was supplied, `r` is a reference to
 5116         `out`.
 5117 
 5118     Notes
 5119     -----
 5120     A descriptive example:
 5121 
 5122     If `a` is 1-D, the function `ufunc.accumulate(a)` is the same as
 5123     ``ufunc.reduceat(a, indices)[::2]`` where `indices` is
 5124     ``range(len(array) - 1)`` with a zero placed
 5125     in every other element:
 5126     ``indices = zeros(2 * len(a) - 1)``, ``indices[1::2] = range(1, len(a))``.
 5127 
 5128     Don't be fooled by this attribute's name: `reduceat(a)` is not
 5129     necessarily smaller than `a`.
 5130 
 5131     Examples
 5132     --------
 5133     To take the running sum of four successive values:
 5134 
 5135     >>> np.add.reduceat(np.arange(8),[0,4, 1,5, 2,6, 3,7])[::2]
 5136     array([ 6, 10, 14, 18])
 5137 
 5138     A 2-D example:
 5139 
 5140     >>> x = np.linspace(0, 15, 16).reshape(4,4)
 5141     >>> x
 5142     array([[  0.,   1.,   2.,   3.],
 5143            [  4.,   5.,   6.,   7.],
 5144            [  8.,   9.,  10.,  11.],
 5145            [ 12.,  13.,  14.,  15.]])
 5146 
 5147     ::
 5148 
 5149      # reduce such that the result has the following five rows:
 5150      # [row1 + row2 + row3]
 5151      # [row4]
 5152      # [row2]
 5153      # [row3]
 5154      # [row1 + row2 + row3 + row4]
 5155 
 5156     >>> np.add.reduceat(x, [0, 3, 1, 2, 0])
 5157     array([[ 12.,  15.,  18.,  21.],
 5158            [ 12.,  13.,  14.,  15.],
 5159            [  4.,   5.,   6.,   7.],
 5160            [  8.,   9.,  10.,  11.],
 5161            [ 24.,  28.,  32.,  36.]])
 5162 
 5163     ::
 5164 
 5165      # reduce such that result has the following two columns:
 5166      # [col1 * col2 * col3, col4]
 5167 
 5168     >>> np.multiply.reduceat(x, [0, 3], 1)
 5169     array([[    0.,     3.],
 5170            [  120.,     7.],
 5171            [  720.,    11.],
 5172            [ 2184.,    15.]])
 5173 
 5174     """))
 5175 
 5176 add_newdoc('numpy.core', 'ufunc', ('outer',
 5177     """
 5178     outer(A, B, **kwargs)
 5179 
 5180     Apply the ufunc `op` to all pairs (a, b) with a in `A` and b in `B`.
 5181 
 5182     Let ``M = A.ndim``, ``N = B.ndim``. Then the result, `C`, of
 5183     ``op.outer(A, B)`` is an array of dimension M + N such that:
 5184 
 5185     .. math:: C[i_0, ..., i_{M-1}, j_0, ..., j_{N-1}] =
 5186        op(A[i_0, ..., i_{M-1}], B[j_0, ..., j_{N-1}])
 5187 
 5188     For `A` and `B` one-dimensional, this is equivalent to::
 5189 
 5190       r = empty(len(A),len(B))
 5191       for i in range(len(A)):
 5192           for j in range(len(B)):
 5193               r[i,j] = op(A[i], B[j]) # op = ufunc in question
 5194 
 5195     Parameters
 5196     ----------
 5197     A : array_like
 5198         First array
 5199     B : array_like
 5200         Second array
 5201     kwargs : any
 5202         Arguments to pass on to the ufunc. Typically `dtype` or `out`.
 5203 
 5204     Returns
 5205     -------
 5206     r : ndarray
 5207         Output array
 5208 
 5209     See Also
 5210     --------
 5211     numpy.outer
 5212 
 5213     Examples
 5214     --------
 5215     >>> np.multiply.outer([1, 2, 3], [4, 5, 6])
 5216     array([[ 4,  5,  6],
 5217            [ 8, 10, 12],
 5218            [12, 15, 18]])
 5219 
 5220     A multi-dimensional example:
 5221 
 5222     >>> A = np.array([[1, 2, 3], [4, 5, 6]])
 5223     >>> A.shape
 5224     (2, 3)
 5225     >>> B = np.array([[1, 2, 3, 4]])
 5226     >>> B.shape
 5227     (1, 4)
 5228     >>> C = np.multiply.outer(A, B)
 5229     >>> C.shape; C
 5230     (2, 3, 1, 4)
 5231     array([[[[ 1,  2,  3,  4]],
 5232             [[ 2,  4,  6,  8]],
 5233             [[ 3,  6,  9, 12]]],
 5234            [[[ 4,  8, 12, 16]],
 5235             [[ 5, 10, 15, 20]],
 5236             [[ 6, 12, 18, 24]]]])
 5237 
 5238     """))
 5239 
 5240 add_newdoc('numpy.core', 'ufunc', ('at',
 5241     """
 5242     at(a, indices, b=None)
 5243 
 5244     Performs unbuffered in place operation on operand 'a' for elements
 5245     specified by 'indices'. For addition ufunc, this method is equivalent to
 5246     ``a[indices] += b``, except that results are accumulated for elements that
 5247     are indexed more than once. For example, ``a[[0,0]] += 1`` will only
 5248     increment the first element once because of buffering, whereas
 5249     ``add.at(a, [0,0], 1)`` will increment the first element twice.
 5250 
 5251     .. versionadded:: 1.8.0
 5252 
 5253     Parameters
 5254     ----------
 5255     a : array_like
 5256         The array to perform in place operation on.
 5257     indices : array_like or tuple
 5258         Array like index object or slice object for indexing into first
 5259         operand. If first operand has multiple dimensions, indices can be a
 5260         tuple of array like index objects or slice objects.
 5261     b : array_like
 5262         Second operand for ufuncs requiring two operands. Operand must be
 5263         broadcastable over first operand after indexing or slicing.
 5264 
 5265     Examples
 5266     --------
 5267     Set items 0 and 1 to their negative values:
 5268 
 5269     >>> a = np.array([1, 2, 3, 4])
 5270     >>> np.negative.at(a, [0, 1])
 5271     >>> print(a)
 5272     array([-1, -2, 3, 4])
 5273 
 5274     Increment items 0 and 1, and increment item 2 twice:
 5275 
 5276     >>> a = np.array([1, 2, 3, 4])
 5277     >>> np.add.at(a, [0, 1, 2, 2], 1)
 5278     >>> print(a)
 5279     array([2, 3, 5, 4])
 5280 
 5281     Add items 0 and 1 in first array to second array,
 5282     and store results in first array:
 5283 
 5284     >>> a = np.array([1, 2, 3, 4])
 5285     >>> b = np.array([1, 2])
 5286     >>> np.add.at(a, [0, 1], b)
 5287     >>> print(a)
 5288     array([2, 4, 3, 4])
 5289 
 5290     """))
 5291 
 5292 ##############################################################################
 5293 #
 5294 # Documentation for dtype attributes and methods
 5295 #
 5296 ##############################################################################
 5297 
 5298 ##############################################################################
 5299 #
 5300 # dtype object
 5301 #
 5302 ##############################################################################
 5303 
 5304 add_newdoc('numpy.core.multiarray', 'dtype',
 5305     """
 5306     dtype(obj, align=False, copy=False)
 5307 
 5308     Create a data type object.
 5309 
 5310     A numpy array is homogeneous, and contains elements described by a
 5311     dtype object. A dtype object can be constructed from different
 5312     combinations of fundamental numeric types.
 5313 
 5314     Parameters
 5315     ----------
 5316     obj
 5317         Object to be converted to a data type object.
 5318     align : bool, optional
 5319         Add padding to the fields to match what a C compiler would output
 5320         for a similar C-struct. Can be ``True`` only if `obj` is a dictionary
 5321         or a comma-separated string. If a struct dtype is being created,
 5322         this also sets a sticky alignment flag ``isalignedstruct``.
 5323     copy : bool, optional
 5324         Make a new copy of the data-type object. If ``False``, the result
 5325         may just be a reference to a built-in data-type object.
 5326 
 5327     See also
 5328     --------
 5329     result_type
 5330 
 5331     Examples
 5332     --------
 5333     Using array-scalar type:
 5334 
 5335     >>> np.dtype(np.int16)
 5336     dtype('int16')
 5337 
 5338     Structured type, one field name 'f1', containing int16:
 5339 
 5340     >>> np.dtype([('f1', np.int16)])
 5341     dtype([('f1', '<i2')])
 5342 
 5343     Structured type, one field named 'f1', in itself containing a structured
 5344     type with one field:
 5345 
 5346     >>> np.dtype([('f1', [('f1', np.int16)])])
 5347     dtype([('f1', [('f1', '<i2')])])
 5348 
 5349     Structured type, two fields: the first field contains an unsigned int, the
 5350     second an int32:
 5351 
 5352     >>> np.dtype([('f1', np.uint), ('f2', np.int32)])
 5353     dtype([('f1', '<u4'), ('f2', '<i4')])
 5354 
 5355     Using array-protocol type strings:
 5356 
 5357     >>> np.dtype([('a','f8'),('b','S10')])
 5358     dtype([('a', '<f8'), ('b', '|S10')])
 5359 
 5360     Using comma-separated field formats.  The shape is (2,3):
 5361 
 5362     >>> np.dtype("i4, (2,3)f8")
 5363     dtype([('f0', '<i4'), ('f1', '<f8', (2, 3))])
 5364 
 5365     Using tuples.  ``int`` is a fixed type, 3 the field's shape.  ``void``
 5366     is a flexible type, here of size 10:
 5367 
 5368     >>> np.dtype([('hello',(int,3)),('world',np.void,10)])
 5369     dtype([('hello', '<i4', 3), ('world', '|V10')])
 5370 
 5371     Subdivide ``int16`` into 2 ``int8``'s, called x and y.  0 and 1 are
 5372     the offsets in bytes:
 5373 
 5374     >>> np.dtype((np.int16, {'x':(np.int8,0), 'y':(np.int8,1)}))
 5375     dtype(('<i2', [('x', '|i1'), ('y', '|i1')]))
 5376 
 5377     Using dictionaries.  Two fields named 'gender' and 'age':
 5378 
 5379     >>> np.dtype({'names':['gender','age'], 'formats':['S1',np.uint8]})
 5380     dtype([('gender', '|S1'), ('age', '|u1')])
 5381 
 5382     Offsets in bytes, here 0 and 25:
 5383 
 5384     >>> np.dtype({'surname':('S25',0),'age':(np.uint8,25)})
 5385     dtype([('surname', '|S25'), ('age', '|u1')])
 5386 
 5387     """)
 5388 
 5389 ##############################################################################
 5390 #
 5391 # dtype attributes
 5392 #
 5393 ##############################################################################
 5394 
 5395 add_newdoc('numpy.core.multiarray', 'dtype', ('alignment',
 5396     """
 5397     The required alignment (bytes) of this data-type according to the compiler.
 5398 
 5399     More information is available in the C-API section of the manual.
 5400 
 5401     """))
 5402 
 5403 add_newdoc('numpy.core.multiarray', 'dtype', ('byteorder',
 5404     """
 5405     A character indicating the byte-order of this data-type object.
 5406 
 5407     One of:
 5408 
 5409     ===  ==============
 5410     '='  native
 5411     '<'  little-endian
 5412     '>'  big-endian
 5413     '|'  not applicable
 5414     ===  ==============
 5415 
 5416     All built-in data-type objects have byteorder either '=' or '|'.
 5417 
 5418     Examples
 5419     --------
 5420 
 5421     >>> dt = np.dtype('i2')
 5422     >>> dt.byteorder
 5423     '='
 5424     >>> # endian is not relevant for 8 bit numbers
 5425     >>> np.dtype('i1').byteorder
 5426     '|'
 5427     >>> # or ASCII strings
 5428     >>> np.dtype('S2').byteorder
 5429     '|'
 5430     >>> # Even if specific code is given, and it is native
 5431     >>> # '=' is the byteorder
 5432     >>> import sys
 5433     >>> sys_is_le = sys.byteorder == 'little'
 5434     >>> native_code = sys_is_le and '<' or '>'
 5435     >>> swapped_code = sys_is_le and '>' or '<'
 5436     >>> dt = np.dtype(native_code + 'i2')
 5437     >>> dt.byteorder
 5438     '='
 5439     >>> # Swapped code shows up as itself
 5440     >>> dt = np.dtype(swapped_code + 'i2')
 5441     >>> dt.byteorder == swapped_code
 5442     True
 5443 
 5444     """))
 5445 
 5446 add_newdoc('numpy.core.multiarray', 'dtype', ('char',
 5447     """A unique character code for each of the 21 different built-in types."""))
 5448 
 5449 add_newdoc('numpy.core.multiarray', 'dtype', ('descr',
 5450     """
 5451     `__array_interface__` description of the data-type.
 5452 
 5453     The format is that required by the 'descr' key in the
 5454     `__array_interface__` attribute.
 5455 
 5456     Warning: This attribute exists specifically for `__array_interface__`,
 5457     and is not a datatype description compatible with `np.dtype`.
 5458     """))
 5459 
 5460 add_newdoc('numpy.core.multiarray', 'dtype', ('fields',
 5461     """
 5462     Dictionary of named fields defined for this data type, or ``None``.
 5463 
 5464     The dictionary is indexed by keys that are the names of the fields.
 5465     Each entry in the dictionary is a tuple fully describing the field::
 5466 
 5467       (dtype, offset[, title])
 5468 
 5469     Offset is limited to C int, which is signed and usually 32 bits.
 5470     If present, the optional title can be any object (if it is a string
 5471     or unicode then it will also be a key in the fields dictionary,
 5472     otherwise it's meta-data). Notice also that the first two elements
 5473     of the tuple can be passed directly as arguments to the ``ndarray.getfield``
 5474     and ``ndarray.setfield`` methods.
 5475 
 5476     See Also
 5477     --------
 5478     ndarray.getfield, ndarray.setfield
 5479 
 5480     Examples
 5481     --------
 5482     >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
 5483     >>> print(dt.fields)
 5484     {'grades': (dtype(('float64',(2,))), 16), 'name': (dtype('|S16'), 0)}
 5485 
 5486     """))
 5487 
 5488 add_newdoc('numpy.core.multiarray', 'dtype', ('flags',
 5489     """
 5490     Bit-flags describing how this data type is to be interpreted.
 5491 
 5492     Bit-masks are in `numpy.core.multiarray` as the constants
 5493     `ITEM_HASOBJECT`, `LIST_PICKLE`, `ITEM_IS_POINTER`, `NEEDS_INIT`,
 5494     `NEEDS_PYAPI`, `USE_GETITEM`, `USE_SETITEM`. A full explanation
 5495     of these flags is in C-API documentation; they are largely useful
 5496     for user-defined data-types.
 5497 
 5498     """))
 5499 
 5500 add_newdoc('numpy.core.multiarray', 'dtype', ('hasobject',
 5501     """
 5502     Boolean indicating whether this dtype contains any reference-counted
 5503     objects in any fields or sub-dtypes.
 5504 
 5505     Recall that what is actually in the ndarray memory representing
 5506     the Python object is the memory address of that object (a pointer).
 5507     Special handling may be required, and this attribute is useful for
 5508     distinguishing data types that may contain arbitrary Python objects
 5509     and data-types that won't.
 5510 
 5511     """))
 5512 
 5513 add_newdoc('numpy.core.multiarray', 'dtype', ('isbuiltin',
 5514     """
 5515     Integer indicating how this dtype relates to the built-in dtypes.
 5516 
 5517     Read-only.
 5518 
 5519     =  ========================================================================
 5520     0  if this is a structured array type, with fields
 5521     1  if this is a dtype compiled into numpy (such as ints, floats etc)
 5522     2  if the dtype is for a user-defined numpy type
 5523        A user-defined type uses the numpy C-API machinery to extend
 5524        numpy to handle a new array type. See
 5525        :ref:`user.user-defined-data-types` in the NumPy manual.
 5526     =  ========================================================================
 5527 
 5528     Examples
 5529     --------
 5530     >>> dt = np.dtype('i2')
 5531     >>> dt.isbuiltin
 5532     1
 5533     >>> dt = np.dtype('f8')
 5534     >>> dt.isbuiltin
 5535     1
 5536     >>> dt = np.dtype([('field1', 'f8')])
 5537     >>> dt.isbuiltin
 5538     0
 5539 
 5540     """))
 5541 
 5542 add_newdoc('numpy.core.multiarray', 'dtype', ('isnative',
 5543     """
 5544     Boolean indicating whether the byte order of this dtype is native
 5545     to the platform.
 5546 
 5547     """))
 5548 
 5549 add_newdoc('numpy.core.multiarray', 'dtype', ('isalignedstruct',
 5550     """
 5551     Boolean indicating whether the dtype is a struct which maintains
 5552     field alignment. This flag is sticky, so when combining multiple
 5553     structs together, it is preserved and produces new dtypes which
 5554     are also aligned.
 5555     """))
 5556 
 5557 add_newdoc('numpy.core.multiarray', 'dtype', ('itemsize',
 5558     """
 5559     The element size of this data-type object.
 5560 
 5561     For 18 of the 21 types this number is fixed by the data-type.
 5562     For the flexible data-types, this number can be anything.
 5563 
 5564     """))
 5565 
 5566 add_newdoc('numpy.core.multiarray', 'dtype', ('kind',
 5567     """
 5568     A character code (one of 'biufcmMOSUV') identifying the general kind of data.
 5569 
 5570     =  ======================
 5571     b  boolean
 5572     i  signed integer
 5573     u  unsigned integer
 5574     f  floating-point
 5575     c  complex floating-point
 5576     m  timedelta
 5577     M  datetime
 5578     O  object
 5579     S  (byte-)string
 5580     U  Unicode
 5581     V  void
 5582     =  ======================
 5583 
 5584     """))
 5585 
 5586 add_newdoc('numpy.core.multiarray', 'dtype', ('name',
 5587     """
 5588     A bit-width name for this data-type.
 5589 
 5590     Un-sized flexible data-type objects do not have this attribute.
 5591 
 5592     """))
 5593 
 5594 add_newdoc('numpy.core.multiarray', 'dtype', ('names',
 5595     """
 5596     Ordered list of field names, or ``None`` if there are no fields.
 5597 
 5598     The names are ordered according to increasing byte offset. This can be
 5599     used, for example, to walk through all of the named fields in offset order.
 5600 
 5601     Examples
 5602     --------
 5603     >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
 5604     >>> dt.names
 5605     ('name', 'grades')
 5606 
 5607     """))
 5608 
 5609 add_newdoc('numpy.core.multiarray', 'dtype', ('num',
 5610     """
 5611     A unique number for each of the 21 different built-in types.
 5612 
 5613     These are roughly ordered from least-to-most precision.
 5614 
 5615     """))
 5616 
 5617 add_newdoc('numpy.core.multiarray', 'dtype', ('shape',
 5618     """
 5619     Shape tuple of the sub-array if this data type describes a sub-array,
 5620     and ``()`` otherwise.
 5621 
 5622     """))
 5623 
 5624 add_newdoc('numpy.core.multiarray', 'dtype', ('ndim',
 5625     """
 5626     Number of dimensions of the sub-array if this data type describes a
 5627     sub-array, and ``0`` otherwise.
 5628 
 5629     .. versionadded:: 1.13.0
 5630 
 5631     """))
 5632 
 5633 add_newdoc('numpy.core.multiarray', 'dtype', ('str',
 5634     """The array-protocol typestring of this data-type object."""))
 5635 
 5636 add_newdoc('numpy.core.multiarray', 'dtype', ('subdtype',
 5637     """
 5638     Tuple ``(item_dtype, shape)`` if this `dtype` describes a sub-array, and
 5639     None otherwise.
 5640 
 5641     The *shape* is the fixed shape of the sub-array described by this
 5642     data type, and *item_dtype* the data type of the array.
 5643 
 5644     If a field whose dtype object has this attribute is retrieved,
 5645     then the extra dimensions implied by *shape* are tacked on to
 5646     the end of the retrieved array.
 5647 
 5648     """))
 5649 
 5650 add_newdoc('numpy.core.multiarray', 'dtype', ('type',
 5651     """The type object used to instantiate a scalar of this data-type."""))
 5652 
 5653 ##############################################################################
 5654 #
 5655 # dtype methods
 5656 #
 5657 ##############################################################################
 5658 
 5659 add_newdoc('numpy.core.multiarray', 'dtype', ('newbyteorder',
 5660     """
 5661     newbyteorder(new_order='S')
 5662 
 5663     Return a new dtype with a different byte order.
 5664 
 5665     Changes are also made in all fields and sub-arrays of the data type.
 5666 
 5667     Parameters
 5668     ----------
 5669     new_order : string, optional
 5670         Byte order to force; a value from the byte order specifications
 5671         below.  The default value ('S') results in swapping the current
 5672         byte order.  `new_order` codes can be any of:
 5673 
 5674         * 'S' - swap dtype from current to opposite endian
 5675         * {'<', 'L'} - little endian
 5676         * {'>', 'B'} - big endian
 5677         * {'=', 'N'} - native order
 5678         * {'|', 'I'} - ignore (no change to byte order)
 5679 
 5680         The code does a case-insensitive check on the first letter of
 5681         `new_order` for these alternatives.  For example, any of '>'
 5682         or 'B' or 'b' or 'brian' are valid to specify big-endian.
 5683 
 5684     Returns
 5685     -------
 5686     new_dtype : dtype
 5687         New dtype object with the given change to the byte order.
 5688 
 5689     Notes
 5690     -----
 5691     Changes are also made in all fields and sub-arrays of the data type.
 5692 
 5693     Examples
 5694     --------
 5695     >>> import sys
 5696     >>> sys_is_le = sys.byteorder == 'little'
 5697     >>> native_code = sys_is_le and '<' or '>'
 5698     >>> swapped_code = sys_is_le and '>' or '<'
 5699     >>> native_dt = np.dtype(native_code+'i2')
 5700     >>> swapped_dt = np.dtype(swapped_code+'i2')
 5701     >>> native_dt.newbyteorder('S') == swapped_dt
 5702     True
 5703     >>> native_dt.newbyteorder() == swapped_dt
 5704     True
 5705     >>> native_dt == swapped_dt.newbyteorder('S')
 5706     True
 5707     >>> native_dt == swapped_dt.newbyteorder('=')
 5708     True
 5709     >>> native_dt == swapped_dt.newbyteorder('N')
 5710     True
 5711     >>> native_dt == native_dt.newbyteorder('|')
 5712     True
 5713     >>> np.dtype('<i2') == native_dt.newbyteorder('<')
 5714     True
 5715     >>> np.dtype('<i2') == native_dt.newbyteorder('L')
 5716     True
 5717     >>> np.dtype('>i2') == native_dt.newbyteorder('>')
 5718     True
 5719     >>> np.dtype('>i2') == native_dt.newbyteorder('B')
 5720     True
 5721 
 5722     """))
 5723 
 5724 
 5725 ##############################################################################
 5726 #
 5727 # Datetime-related Methods
 5728 #
 5729 ##############################################################################
 5730 
 5731 add_newdoc('numpy.core.multiarray', 'busdaycalendar',
 5732     """
 5733     busdaycalendar(weekmask='1111100', holidays=None)
 5734 
 5735     A business day calendar object that efficiently stores information
 5736     defining valid days for the busday family of functions.
 5737 
 5738     The default valid days are Monday through Friday ("business days").
 5739     A busdaycalendar object can be specified with any set of weekly
 5740     valid days, plus an optional "holiday" dates that always will be invalid.
 5741 
 5742     Once a busdaycalendar object is created, the weekmask and holidays
 5743     cannot be modified.
 5744 
 5745     .. versionadded:: 1.7.0
 5746 
 5747     Parameters
 5748     ----------
 5749     weekmask : str or array_like of bool, optional
 5750         A seven-element array indicating which of Monday through Sunday are
 5751         valid days. May be specified as a length-seven list or array, like
 5752         [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
 5753         like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
 5754         weekdays, optionally separated by white space. Valid abbreviations
 5755         are: Mon Tue Wed Thu Fri Sat Sun
 5756     holidays : array_like of datetime64[D], optional
 5757         An array of dates to consider as invalid dates, no matter which
 5758         weekday they fall upon.  Holiday dates may be specified in any
 5759         order, and NaT (not-a-time) dates are ignored.  This list is
 5760         saved in a normalized form that is suited for fast calculations
 5761         of valid days.
 5762 
 5763     Returns
 5764     -------
 5765     out : busdaycalendar
 5766         A business day calendar object containing the specified
 5767         weekmask and holidays values.
 5768 
 5769     See Also
 5770     --------
 5771     is_busday : Returns a boolean array indicating valid days.
 5772     busday_offset : Applies an offset counted in valid days.
 5773     busday_count : Counts how many valid days are in a half-open date range.
 5774 
 5775     Attributes
 5776     ----------
 5777     Note: once a busdaycalendar object is created, you cannot modify the
 5778     weekmask or holidays.  The attributes return copies of internal data.
 5779     weekmask : (copy) seven-element array of bool
 5780     holidays : (copy) sorted array of datetime64[D]
 5781 
 5782     Examples
 5783     --------
 5784     >>> # Some important days in July
 5785     ... bdd = np.busdaycalendar(
 5786     ...             holidays=['2011-07-01', '2011-07-04', '2011-07-17'])
 5787     >>> # Default is Monday to Friday weekdays
 5788     ... bdd.weekmask
 5789     array([ True,  True,  True,  True,  True, False, False], dtype='bool')
 5790     >>> # Any holidays already on the weekend are removed
 5791     ... bdd.holidays
 5792     array(['2011-07-01', '2011-07-04'], dtype='datetime64[D]')
 5793     """)
 5794 
 5795 add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('weekmask',
 5796     """A copy of the seven-element boolean mask indicating valid days."""))
 5797 
 5798 add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('holidays',
 5799     """A copy of the holiday array indicating additional invalid days."""))
 5800 
 5801 add_newdoc('numpy.core.multiarray', 'normalize_axis_index',
 5802     """
 5803     normalize_axis_index(axis, ndim, msg_prefix=None)
 5804 
 5805     Normalizes an axis index, `axis`, such that is a valid positive index into
 5806     the shape of array with `ndim` dimensions. Raises an AxisError with an
 5807     appropriate message if this is not possible.
 5808 
 5809     Used internally by all axis-checking logic.
 5810 
 5811     .. versionadded:: 1.13.0
 5812 
 5813     Parameters
 5814     ----------
 5815     axis : int
 5816         The un-normalized index of the axis. Can be negative
 5817     ndim : int
 5818         The number of dimensions of the array that `axis` should be normalized
 5819         against
 5820     msg_prefix : str
 5821         A prefix to put before the message, typically the name of the argument
 5822 
 5823     Returns
 5824     -------
 5825     normalized_axis : int
 5826         The normalized axis index, such that `0 <= normalized_axis < ndim`
 5827 
 5828     Raises
 5829     ------
 5830     AxisError
 5831         If the axis index is invalid, when `-ndim <= axis < ndim` is false.
 5832 
 5833     Examples
 5834     --------
 5835     >>> normalize_axis_index(0, ndim=3)
 5836     0
 5837     >>> normalize_axis_index(1, ndim=3)
 5838     1
 5839     >>> normalize_axis_index(-1, ndim=3)
 5840     2
 5841 
 5842     >>> normalize_axis_index(3, ndim=3)
 5843     Traceback (most recent call last):
 5844     ...
 5845     AxisError: axis 3 is out of bounds for array of dimension 3
 5846     >>> normalize_axis_index(-4, ndim=3, msg_prefix='axes_arg')
 5847     Traceback (most recent call last):
 5848     ...
 5849     AxisError: axes_arg: axis -4 is out of bounds for array of dimension 3
 5850     """)
 5851 
 5852 add_newdoc('numpy.core.multiarray', 'datetime_data',
 5853     """
 5854     datetime_data(dtype, /)
 5855 
 5856     Get information about the step size of a date or time type.
 5857 
 5858     The returned tuple can be passed as the second argument of `numpy.datetime64` and
 5859     `numpy.timedelta64`.
 5860 
 5861     Parameters
 5862     ----------
 5863     dtype : dtype
 5864         The dtype object, which must be a `datetime64` or `timedelta64` type.
 5865 
 5866     Returns
 5867     -------
 5868     unit : str
 5869         The :ref:`datetime unit <arrays.dtypes.dateunits>` on which this dtype
 5870         is based.
 5871     count : int
 5872         The number of base units in a step.
 5873 
 5874     Examples
 5875     --------
 5876     >>> dt_25s = np.dtype('timedelta64[25s]')
 5877     >>> np.datetime_data(dt_25s)
 5878     ('s', 25)
 5879     >>> np.array(10, dt_25s).astype('timedelta64[s]')
 5880     array(250, dtype='timedelta64[s]')
 5881 
 5882     The result can be used to construct a datetime that uses the same units
 5883     as a timedelta
 5884 
 5885     >>> np.datetime64('2010', np.datetime_data(dt_25s))
 5886     numpy.datetime64('2010-01-01T00:00:00', '25s')
 5887     """)
 5888 
 5889 
 5890 ##############################################################################
 5891 #
 5892 # Documentation for `generic` attributes and methods
 5893 #
 5894 ##############################################################################
 5895 
 5896 add_newdoc('numpy.core.numerictypes', 'generic',
 5897     """
 5898     Base class for numpy scalar types.
 5899 
 5900     Class from which most (all?) numpy scalar types are derived.  For
 5901     consistency, exposes the same API as `ndarray`, despite many
 5902     consequent attributes being either "get-only," or completely irrelevant.
 5903     This is the class from which it is strongly suggested users should derive
 5904     custom scalar types.
 5905 
 5906     """)
 5907 
 5908 # Attributes
 5909 
 5910 add_newdoc('numpy.core.numerictypes', 'generic', ('T',
 5911     """
 5912     Not implemented (virtual attribute)
 5913 
 5914     Class generic exists solely to derive numpy scalars from, and possesses,
 5915     albeit unimplemented, all the attributes of the ndarray class so as to
 5916     provide a uniform API.
 5917 
 5918     See Also
 5919     --------
 5920     The corresponding attribute of the derived class of interest.
 5921 
 5922     """))
 5923 
 5924 add_newdoc('numpy.core.numerictypes', 'generic', ('base',
 5925     """
 5926     Not implemented (virtual attribute)
 5927 
 5928     Class generic exists solely to derive numpy scalars from, and possesses,
 5929     albeit unimplemented, all the attributes of the ndarray class so as to
 5930     a uniform API.
 5931 
 5932     See Also
 5933     --------
 5934     The corresponding attribute of the derived class of interest.
 5935 
 5936     """))
 5937 
 5938 add_newdoc('numpy.core.numerictypes', 'generic', ('data',
 5939     """Pointer to start of data."""))
 5940 
 5941 add_newdoc('numpy.core.numerictypes', 'generic', ('dtype',
 5942     """Get array data-descriptor."""))
 5943 
 5944 add_newdoc('numpy.core.numerictypes', 'generic', ('flags',
 5945     """The integer value of flags."""))
 5946 
 5947 add_newdoc('numpy.core.numerictypes', 'generic', ('flat',
 5948     """A 1-D view of the scalar."""))
 5949 
 5950 add_newdoc('numpy.core.numerictypes', 'generic', ('imag',
 5951     """The imaginary part of the scalar."""))
 5952 
 5953 add_newdoc('numpy.core.numerictypes', 'generic', ('itemsize',
 5954     """The length of one element in bytes."""))
 5955 
 5956 add_newdoc('numpy.core.numerictypes', 'generic', ('nbytes',
 5957     """The length of the scalar in bytes."""))
 5958 
 5959 add_newdoc('numpy.core.numerictypes', 'generic', ('ndim',
 5960     """The number of array dimensions."""))
 5961 
 5962 add_newdoc('numpy.core.numerictypes', 'generic', ('real',
 5963     """The real part of the scalar."""))
 5964 
 5965 add_newdoc('numpy.core.numerictypes', 'generic', ('shape',
 5966     """Tuple of array dimensions."""))
 5967 
 5968 add_newdoc('numpy.core.numerictypes', 'generic', ('size',
 5969     """The number of elements in the gentype."""))
 5970 
 5971 add_newdoc('numpy.core.numerictypes', 'generic', ('strides',
 5972     """Tuple of bytes steps in each dimension."""))
 5973 
 5974 # Methods
 5975 
 5976 add_newdoc('numpy.core.numerictypes', 'generic', ('all',
 5977     """
 5978     Not implemented (virtual attribute)
 5979 
 5980     Class generic exists solely to derive numpy scalars from, and possesses,
 5981     albeit unimplemented, all the attributes of the ndarray class
 5982     so as to provide a uniform API.
 5983 
 5984     See Also
 5985     --------
 5986     The corresponding attribute of the derived class of interest.
 5987 
 5988     """))
 5989 
 5990 add_newdoc('numpy.core.numerictypes', 'generic', ('any',
 5991     """
 5992     Not implemented (virtual attribute)
 5993 
 5994     Class generic exists solely to derive numpy scalars from, and possesses,
 5995     albeit unimplemented, all the attributes of the ndarray class
 5996     so as to provide a uniform API.
 5997 
 5998     See Also
 5999     --------
 6000     The corresponding attribute of the derived class of interest.
 6001 
 6002     """))
 6003 
 6004 add_newdoc('numpy.core.numerictypes', 'generic', ('argmax',
 6005     """
 6006     Not implemented (virtual attribute)
 6007 
 6008     Class generic exists solely to derive numpy scalars from, and possesses,
 6009     albeit unimplemented, all the attributes of the ndarray class
 6010     so as to provide a uniform API.
 6011 
 6012     See Also
 6013     --------
 6014     The corresponding attribute of the derived class of interest.
 6015 
 6016     """))
 6017 
 6018 add_newdoc('numpy.core.numerictypes', 'generic', ('argmin',
 6019     """
 6020     Not implemented (virtual attribute)
 6021 
 6022     Class generic exists solely to derive numpy scalars from, and possesses,
 6023     albeit unimplemented, all the attributes of the ndarray class
 6024     so as to provide a uniform API.
 6025 
 6026     See Also
 6027     --------
 6028     The corresponding attribute of the derived class of interest.
 6029 
 6030     """))
 6031 
 6032 add_newdoc('numpy.core.numerictypes', 'generic', ('argsort',
 6033     """
 6034     Not implemented (virtual attribute)
 6035 
 6036     Class generic exists solely to derive numpy scalars from, and possesses,
 6037     albeit unimplemented, all the attributes of the ndarray class
 6038     so as to provide a uniform API.
 6039 
 6040     See Also
 6041     --------
 6042     The corresponding attribute of the derived class of interest.
 6043 
 6044     """))
 6045 
 6046 add_newdoc('numpy.core.numerictypes', 'generic', ('astype',
 6047     """
 6048     Not implemented (virtual attribute)
 6049 
 6050     Class generic exists solely to derive numpy scalars from, and possesses,
 6051     albeit unimplemented, all the attributes of the ndarray class
 6052     so as to provide a uniform API.
 6053 
 6054     See Also
 6055     --------
 6056     The corresponding attribute of the derived class of interest.
 6057 
 6058     """))
 6059 
 6060 add_newdoc('numpy.core.numerictypes', 'generic', ('byteswap',
 6061     """
 6062     Not implemented (virtual attribute)
 6063 
 6064     Class generic exists solely to derive numpy scalars from, and possesses,
 6065     albeit unimplemented, all the attributes of the ndarray class so as to
 6066     provide a uniform API.
 6067 
 6068     See Also
 6069     --------
 6070     The corresponding attribute of the derived class of interest.
 6071 
 6072     """))
 6073 
 6074 add_newdoc('numpy.core.numerictypes', 'generic', ('choose',
 6075     """
 6076     Not implemented (virtual attribute)
 6077 
 6078     Class generic exists solely to derive numpy scalars from, and possesses,
 6079     albeit unimplemented, all the attributes of the ndarray class
 6080     so as to provide a uniform API.
 6081 
 6082     See Also
 6083     --------
 6084     The corresponding attribute of the derived class of interest.
 6085 
 6086     """))
 6087 
 6088 add_newdoc('numpy.core.numerictypes', 'generic', ('clip',
 6089     """
 6090     Not implemented (virtual attribute)
 6091 
 6092     Class generic exists solely to derive numpy scalars from, and possesses,
 6093     albeit unimplemented, all the attributes of the ndarray class
 6094     so as to provide a uniform API.
 6095 
 6096     See Also
 6097     --------
 6098     The corresponding attribute of the derived class of interest.
 6099 
 6100     """))
 6101 
 6102 add_newdoc('numpy.core.numerictypes', 'generic', ('compress',
 6103     """
 6104     Not implemented (virtual attribute)
 6105 
 6106     Class generic exists solely to derive numpy scalars from, and possesses,
 6107     albeit unimplemented, all the attributes of the ndarray class
 6108     so as to provide a uniform API.
 6109 
 6110     See Also
 6111     --------
 6112     The corresponding attribute of the derived class of interest.
 6113 
 6114     """))
 6115 
 6116 add_newdoc('numpy.core.numerictypes', 'generic', ('conjugate',
 6117     """
 6118     Not implemented (virtual attribute)
 6119 
 6120     Class generic exists solely to derive numpy scalars from, and possesses,
 6121     albeit unimplemented, all the attributes of the ndarray class
 6122     so as to provide a uniform API.
 6123 
 6124     See Also
 6125     --------
 6126     The corresponding attribute of the derived class of interest.
 6127 
 6128     """))
 6129 
 6130 add_newdoc('numpy.core.numerictypes', 'generic', ('copy',
 6131     """
 6132     Not implemented (virtual attribute)
 6133 
 6134     Class generic exists solely to derive numpy scalars from, and possesses,
 6135     albeit unimplemented, all the attributes of the ndarray class
 6136     so as to provide a uniform API.
 6137 
 6138     See Also
 6139     --------
 6140     The corresponding attribute of the derived class of interest.
 6141 
 6142     """))
 6143 
 6144 add_newdoc('numpy.core.numerictypes', 'generic', ('cumprod',
 6145     """
 6146     Not implemented (virtual attribute)
 6147 
 6148     Class generic exists solely to derive numpy scalars from, and possesses,
 6149     albeit unimplemented, all the attributes of the ndarray class
 6150     so as to provide a uniform API.
 6151 
 6152     See Also
 6153     --------
 6154     The corresponding attribute of the derived class of interest.
 6155 
 6156     """))
 6157 
 6158 add_newdoc('numpy.core.numerictypes', 'generic', ('cumsum',
 6159     """
 6160     Not implemented (virtual attribute)
 6161 
 6162     Class generic exists solely to derive numpy scalars from, and possesses,
 6163     albeit unimplemented, all the attributes of the ndarray class
 6164     so as to provide a uniform API.
 6165 
 6166     See Also
 6167     --------
 6168     The corresponding attribute of the derived class of interest.
 6169 
 6170     """))
 6171 
 6172 add_newdoc('numpy.core.numerictypes', 'generic', ('diagonal',
 6173     """
 6174     Not implemented (virtual attribute)
 6175 
 6176     Class generic exists solely to derive numpy scalars from, and possesses,
 6177     albeit unimplemented, all the attributes of the ndarray class
 6178     so as to provide a uniform API.
 6179 
 6180     See Also
 6181     --------
 6182     The corresponding attribute of the derived class of interest.
 6183 
 6184     """))
 6185 
 6186 add_newdoc('numpy.core.numerictypes', 'generic', ('dump',
 6187     """
 6188     Not implemented (virtual attribute)
 6189 
 6190     Class generic exists solely to derive numpy scalars from, and possesses,
 6191     albeit unimplemented, all the attributes of the ndarray class
 6192     so as to provide a uniform API.
 6193 
 6194     See Also
 6195     --------
 6196     The corresponding attribute of the derived class of interest.
 6197 
 6198     """))
 6199 
 6200 add_newdoc('numpy.core.numerictypes', 'generic', ('dumps',
 6201     """
 6202     Not implemented (virtual attribute)
 6203 
 6204     Class generic exists solely to derive numpy scalars from, and possesses,
 6205     albeit unimplemented, all the attributes of the ndarray class
 6206     so as to provide a uniform API.
 6207 
 6208     See Also
 6209     --------
 6210     The corresponding attribute of the derived class of interest.
 6211 
 6212     """))
 6213 
 6214 add_newdoc('numpy.core.numerictypes', 'generic', ('fill',
 6215     """
 6216     Not implemented (virtual attribute)
 6217 
 6218     Class generic exists solely to derive numpy scalars from, and possesses,
 6219     albeit unimplemented, all the attributes of the ndarray class
 6220     so as to provide a uniform API.
 6221 
 6222     See Also
 6223     --------
 6224     The corresponding attribute of the derived class of interest.
 6225 
 6226     """))
 6227 
 6228 add_newdoc('numpy.core.numerictypes', 'generic', ('flatten',
 6229     """
 6230     Not implemented (virtual attribute)
 6231 
 6232     Class generic exists solely to derive numpy scalars from, and possesses,
 6233     albeit unimplemented, all the attributes of the ndarray class
 6234     so as to provide a uniform API.
 6235 
 6236     See Also
 6237     --------
 6238     The corresponding attribute of the derived class of interest.
 6239 
 6240     """))
 6241 
 6242 add_newdoc('numpy.core.numerictypes', 'generic', ('getfield',
 6243     """
 6244     Not implemented (virtual attribute)
 6245 
 6246     Class generic exists solely to derive numpy scalars from, and possesses,
 6247     albeit unimplemented, all the attributes of the ndarray class
 6248     so as to provide a uniform API.
 6249 
 6250     See Also
 6251     --------
 6252     The corresponding attribute of the derived class of interest.
 6253 
 6254     """))
 6255 
 6256 add_newdoc('numpy.core.numerictypes', 'generic', ('item',
 6257     """
 6258     Not implemented (virtual attribute)
 6259 
 6260     Class generic exists solely to derive numpy scalars from, and possesses,
 6261     albeit unimplemented, all the attributes of the ndarray class
 6262     so as to provide a uniform API.
 6263 
 6264     See Also
 6265     --------
 6266     The corresponding attribute of the derived class of interest.
 6267 
 6268     """))
 6269 
 6270 add_newdoc('numpy.core.numerictypes', 'generic', ('itemset',
 6271     """
 6272     Not implemented (virtual attribute)
 6273 
 6274     Class generic exists solely to derive numpy scalars from, and possesses,
 6275     albeit unimplemented, all the attributes of the ndarray class
 6276     so as to provide a uniform API.
 6277 
 6278     See Also
 6279     --------
 6280     The corresponding attribute of the derived class of interest.
 6281 
 6282     """))
 6283 
 6284 add_newdoc('numpy.core.numerictypes', 'generic', ('max',
 6285     """
 6286     Not implemented (virtual attribute)
 6287 
 6288     Class generic exists solely to derive numpy scalars from, and possesses,
 6289     albeit unimplemented, all the attributes of the ndarray class
 6290     so as to provide a uniform API.
 6291 
 6292     See Also
 6293     --------
 6294     The corresponding attribute of the derived class of interest.
 6295 
 6296     """))
 6297 
 6298 add_newdoc('numpy.core.numerictypes', 'generic', ('mean',
 6299     """
 6300     Not implemented (virtual attribute)
 6301 
 6302     Class generic exists solely to derive numpy scalars from, and possesses,
 6303     albeit unimplemented, all the attributes of the ndarray class
 6304     so as to provide a uniform API.
 6305 
 6306     See Also
 6307     --------
 6308     The corresponding attribute of the derived class of interest.
 6309 
 6310     """))
 6311 
 6312 add_newdoc('numpy.core.numerictypes', 'generic', ('min',
 6313     """
 6314     Not implemented (virtual attribute)
 6315 
 6316     Class generic exists solely to derive numpy scalars from, and possesses,
 6317     albeit unimplemented, all the attributes of the ndarray class
 6318     so as to provide a uniform API.
 6319 
 6320     See Also
 6321     --------
 6322     The corresponding attribute of the derived class of interest.
 6323 
 6324     """))
 6325 
 6326 add_newdoc('numpy.core.numerictypes', 'generic', ('newbyteorder',
 6327     """
 6328     newbyteorder(new_order='S')
 6329 
 6330     Return a new `dtype` with a different byte order.
 6331 
 6332     Changes are also made in all fields and sub-arrays of the data type.
 6333 
 6334     The `new_order` code can be any from the following:
 6335 
 6336     * 'S' - swap dtype from current to opposite endian
 6337     * {'<', 'L'} - little endian
 6338     * {'>', 'B'} - big endian
 6339     * {'=', 'N'} - native order
 6340     * {'|', 'I'} - ignore (no change to byte order)
 6341 
 6342     Parameters
 6343     ----------
 6344     new_order : str, optional
 6345         Byte order to force; a value from the byte order specifications
 6346         above.  The default value ('S') results in swapping the current
 6347         byte order. The code does a case-insensitive check on the first
 6348         letter of `new_order` for the alternatives above.  For example,
 6349         any of 'B' or 'b' or 'biggish' are valid to specify big-endian.
 6350 
 6351 
 6352     Returns
 6353     -------
 6354     new_dtype : dtype
 6355         New `dtype` object with the given change to the byte order.
 6356 
 6357     """))
 6358 
 6359 add_newdoc('numpy.core.numerictypes', 'generic', ('nonzero',
 6360     """
 6361     Not implemented (virtual attribute)
 6362 
 6363     Class generic exists solely to derive numpy scalars from, and possesses,
 6364     albeit unimplemented, all the attributes of the ndarray class
 6365     so as to provide a uniform API.
 6366 
 6367     See Also
 6368     --------
 6369     The corresponding attribute of the derived class of interest.
 6370 
 6371     """))
 6372 
 6373 add_newdoc('numpy.core.numerictypes', 'generic', ('prod',
 6374     """
 6375     Not implemented (virtual attribute)
 6376 
 6377     Class generic exists solely to derive numpy scalars from, and possesses,
 6378     albeit unimplemented, all the attributes of the ndarray class
 6379     so as to provide a uniform API.
 6380 
 6381     See Also
 6382     --------
 6383     The corresponding attribute of the derived class of interest.
 6384 
 6385     """))
 6386 
 6387 add_newdoc('numpy.core.numerictypes', 'generic', ('ptp',
 6388     """
 6389     Not implemented (virtual attribute)
 6390 
 6391     Class generic exists solely to derive numpy scalars from, and possesses,
 6392     albeit unimplemented, all the attributes of the ndarray class
 6393     so as to provide a uniform API.
 6394 
 6395     See Also
 6396     --------
 6397     The corresponding attribute of the derived class of interest.
 6398 
 6399     """))
 6400 
 6401 add_newdoc('numpy.core.numerictypes', 'generic', ('put',
 6402     """
 6403     Not implemented (virtual attribute)
 6404 
 6405     Class generic exists solely to derive numpy scalars from, and possesses,
 6406     albeit unimplemented, all the attributes of the ndarray class
 6407     so as to provide a uniform API.
 6408 
 6409     See Also
 6410     --------
 6411     The corresponding attribute of the derived class of interest.
 6412 
 6413     """))
 6414 
 6415 add_newdoc('numpy.core.numerictypes', 'generic', ('ravel',
 6416     """
 6417     Not implemented (virtual attribute)
 6418 
 6419     Class generic exists solely to derive numpy scalars from, and possesses,
 6420     albeit unimplemented, all the attributes of the ndarray class
 6421     so as to provide a uniform API.
 6422 
 6423     See Also
 6424     --------
 6425     The corresponding attribute of the derived class of interest.
 6426 
 6427     """))
 6428 
 6429 add_newdoc('numpy.core.numerictypes', 'generic', ('repeat',
 6430     """
 6431     Not implemented (virtual attribute)
 6432 
 6433     Class generic exists solely to derive numpy scalars from, and possesses,
 6434     albeit unimplemented, all the attributes of the ndarray class
 6435     so as to provide a uniform API.
 6436 
 6437     See Also
 6438     --------
 6439     The corresponding attribute of the derived class of interest.
 6440 
 6441     """))
 6442 
 6443 add_newdoc('numpy.core.numerictypes', 'generic', ('reshape',
 6444     """
 6445     Not implemented (virtual attribute)
 6446 
 6447     Class generic exists solely to derive numpy scalars from, and possesses,
 6448     albeit unimplemented, all the attributes of the ndarray class
 6449     so as to provide a uniform API.
 6450 
 6451     See Also
 6452     --------
 6453     The corresponding attribute of the derived class of interest.
 6454 
 6455     """))
 6456 
 6457 add_newdoc('numpy.core.numerictypes', 'generic', ('resize',
 6458     """
 6459     Not implemented (virtual attribute)
 6460 
 6461     Class generic exists solely to derive numpy scalars from, and possesses,
 6462     albeit unimplemented, all the attributes of the ndarray class
 6463     so as to provide a uniform API.
 6464 
 6465     See Also
 6466     --------
 6467     The corresponding attribute of the derived class of interest.
 6468 
 6469     """))
 6470 
 6471 add_newdoc('numpy.core.numerictypes', 'generic', ('round',
 6472     """
 6473     Not implemented (virtual attribute)
 6474 
 6475     Class generic exists solely to derive numpy scalars from, and possesses,
 6476     albeit unimplemented, all the attributes of the ndarray class
 6477     so as to provide a uniform API.
 6478 
 6479     See Also
 6480     --------
 6481     The corresponding attribute of the derived class of interest.
 6482 
 6483     """))
 6484 
 6485 add_newdoc('numpy.core.numerictypes', 'generic', ('searchsorted',
 6486     """
 6487     Not implemented (virtual attribute)
 6488 
 6489     Class generic exists solely to derive numpy scalars from, and possesses,
 6490     albeit unimplemented, all the attributes of the ndarray class
 6491     so as to provide a uniform API.
 6492 
 6493     See Also
 6494     --------
 6495     The corresponding attribute of the derived class of interest.
 6496 
 6497     """))
 6498 
 6499 add_newdoc('numpy.core.numerictypes', 'generic', ('setfield',
 6500     """
 6501     Not implemented (virtual attribute)
 6502 
 6503     Class generic exists solely to derive numpy scalars from, and possesses,
 6504     albeit unimplemented, all the attributes of the ndarray class
 6505     so as to provide a uniform API.
 6506 
 6507     See Also
 6508     --------
 6509     The corresponding attribute of the derived class of interest.
 6510 
 6511     """))
 6512 
 6513 add_newdoc('numpy.core.numerictypes', 'generic', ('setflags',
 6514     """
 6515     Not implemented (virtual attribute)
 6516 
 6517     Class generic exists solely to derive numpy scalars from, and possesses,
 6518     albeit unimplemented, all the attributes of the ndarray class so as to
 6519     provide a uniform API.
 6520 
 6521     See Also
 6522     --------
 6523     The corresponding attribute of the derived class of interest.
 6524 
 6525     """))
 6526 
 6527 add_newdoc('numpy.core.numerictypes', 'generic', ('sort',
 6528     """
 6529     Not implemented (virtual attribute)
 6530 
 6531     Class generic exists solely to derive numpy scalars from, and possesses,
 6532     albeit unimplemented, all the attributes of the ndarray class
 6533     so as to provide a uniform API.
 6534 
 6535     See Also
 6536     --------
 6537     The corresponding attribute of the derived class of interest.
 6538 
 6539     """))
 6540 
 6541 add_newdoc('numpy.core.numerictypes', 'generic', ('squeeze',
 6542     """
 6543     Not implemented (virtual attribute)
 6544 
 6545     Class generic exists solely to derive numpy scalars from, and possesses,
 6546     albeit unimplemented, all the attributes of the ndarray class
 6547     so as to provide a uniform API.
 6548 
 6549     See Also
 6550     --------
 6551     The corresponding attribute of the derived class of interest.
 6552 
 6553     """))
 6554 
 6555 add_newdoc('numpy.core.numerictypes', 'generic', ('std',
 6556     """
 6557     Not implemented (virtual attribute)
 6558 
 6559     Class generic exists solely to derive numpy scalars from, and possesses,
 6560     albeit unimplemented, all the attributes of the ndarray class
 6561     so as to provide a uniform API.
 6562 
 6563     See Also
 6564     --------
 6565     The corresponding attribute of the derived class of interest.
 6566 
 6567     """))
 6568 
 6569 add_newdoc('numpy.core.numerictypes', 'generic', ('sum',
 6570     """
 6571     Not implemented (virtual attribute)
 6572 
 6573     Class generic exists solely to derive numpy scalars from, and possesses,
 6574     albeit unimplemented, all the attributes of the ndarray class
 6575     so as to provide a uniform API.
 6576 
 6577     See Also
 6578     --------
 6579     The corresponding attribute of the derived class of interest.
 6580 
 6581     """))
 6582 
 6583 add_newdoc('numpy.core.numerictypes', 'generic', ('swapaxes',
 6584     """
 6585     Not implemented (virtual attribute)
 6586 
 6587     Class generic exists solely to derive numpy scalars from, and possesses,
 6588     albeit unimplemented, all the attributes of the ndarray class
 6589     so as to provide a uniform API.
 6590 
 6591     See Also
 6592     --------
 6593     The corresponding attribute of the derived class of interest.
 6594 
 6595     """))
 6596 
 6597 add_newdoc('numpy.core.numerictypes', 'generic', ('take',
 6598     """
 6599     Not implemented (virtual attribute)
 6600 
 6601     Class generic exists solely to derive numpy scalars from, and possesses,
 6602     albeit unimplemented, all the attributes of the ndarray class
 6603     so as to provide a uniform API.
 6604 
 6605     See Also
 6606     --------
 6607     The corresponding attribute of the derived class of interest.
 6608 
 6609     """))
 6610 
 6611 add_newdoc('numpy.core.numerictypes', 'generic', ('tofile',
 6612     """
 6613     Not implemented (virtual attribute)
 6614 
 6615     Class generic exists solely to derive numpy scalars from, and possesses,
 6616     albeit unimplemented, all the attributes of the ndarray class
 6617     so as to provide a uniform API.
 6618 
 6619     See Also
 6620     --------
 6621     The corresponding attribute of the derived class of interest.
 6622 
 6623     """))
 6624 
 6625 add_newdoc('numpy.core.numerictypes', 'generic', ('tolist',
 6626     """
 6627     Not implemented (virtual attribute)
 6628 
 6629     Class generic exists solely to derive numpy scalars from, and possesses,
 6630     albeit unimplemented, all the attributes of the ndarray class
 6631     so as to provide a uniform API.
 6632 
 6633     See Also
 6634     --------
 6635     The corresponding attribute of the derived class of interest.
 6636 
 6637     """))
 6638 
 6639 add_newdoc('numpy.core.numerictypes', 'generic', ('tostring',
 6640     """
 6641     Not implemented (virtual attribute)
 6642 
 6643     Class generic exists solely to derive numpy scalars from, and possesses,
 6644     albeit unimplemented, all the attributes of the ndarray class
 6645     so as to provide a uniform API.
 6646 
 6647     See Also
 6648     --------
 6649     The corresponding attribute of the derived class of interest.
 6650 
 6651     """))
 6652 
 6653 add_newdoc('numpy.core.numerictypes', 'generic', ('trace',
 6654     """
 6655     Not implemented (virtual attribute)
 6656 
 6657     Class generic exists solely to derive numpy scalars from, and possesses,
 6658     albeit unimplemented, all the attributes of the ndarray class
 6659     so as to provide a uniform API.
 6660 
 6661     See Also
 6662     --------
 6663     The corresponding attribute of the derived class of interest.
 6664 
 6665     """))
 6666 
 6667 add_newdoc('numpy.core.numerictypes', 'generic', ('transpose',
 6668     """
 6669     Not implemented (virtual attribute)
 6670 
 6671     Class generic exists solely to derive numpy scalars from, and possesses,
 6672     albeit unimplemented, all the attributes of the ndarray class
 6673     so as to provide a uniform API.
 6674 
 6675     See Also
 6676     --------
 6677     The corresponding attribute of the derived class of interest.
 6678 
 6679     """))
 6680 
 6681 add_newdoc('numpy.core.numerictypes', 'generic', ('var',
 6682     """
 6683     Not implemented (virtual attribute)
 6684 
 6685     Class generic exists solely to derive numpy scalars from, and possesses,
 6686     albeit unimplemented, all the attributes of the ndarray class
 6687     so as to provide a uniform API.
 6688 
 6689     See Also
 6690     --------
 6691     The corresponding attribute of the derived class of interest.
 6692 
 6693     """))
 6694 
 6695 add_newdoc('numpy.core.numerictypes', 'generic', ('view',
 6696     """
 6697     Not implemented (virtual attribute)
 6698 
 6699     Class generic exists solely to derive numpy scalars from, and possesses,
 6700     albeit unimplemented, all the attributes of the ndarray class
 6701     so as to provide a uniform API.
 6702 
 6703     See Also
 6704     --------
 6705     The corresponding attribute of the derived class of interest.
 6706 
 6707     """))
 6708 
 6709 
 6710 ##############################################################################
 6711 #
 6712 # Documentation for scalar type abstract base classes in type hierarchy
 6713 #
 6714 ##############################################################################
 6715 
 6716 
 6717 add_newdoc('numpy.core.numerictypes', 'number',
 6718     """
 6719     Abstract base class of all numeric scalar types.
 6720     
 6721     """)
 6722 
 6723 add_newdoc('numpy.core.numerictypes', 'integer',
 6724     """
 6725     Abstract base class of all integer scalar types.
 6726     
 6727     """)
 6728 
 6729 add_newdoc('numpy.core.numerictypes', 'signedinteger',
 6730     """
 6731     Abstract base class of all signed integer scalar types.
 6732     
 6733     """)
 6734 
 6735 add_newdoc('numpy.core.numerictypes', 'unsignedinteger',
 6736     """
 6737     Abstract base class of all unsigned integer scalar types.
 6738     
 6739     """)
 6740 
 6741 add_newdoc('numpy.core.numerictypes', 'inexact',
 6742     """
 6743     Abstract base class of all numeric scalar types with a (potentially)
 6744     inexact representation of the values in its range, such as
 6745     floating-point numbers.
 6746     
 6747     """)
 6748 
 6749 add_newdoc('numpy.core.numerictypes', 'floating',
 6750     """
 6751     Abstract base class of all floating-point scalar types.
 6752     
 6753     """)
 6754 
 6755 add_newdoc('numpy.core.numerictypes', 'complexfloating',
 6756     """
 6757     Abstract base class of all complex number scalar types that are made up of
 6758     floating-point numbers.
 6759     
 6760     """)
 6761 
 6762 add_newdoc('numpy.core.numerictypes', 'flexible',
 6763     """
 6764     Abstract base class of all scalar types without predefined length.
 6765     The actual size of these types depends on the specific `np.dtype`
 6766     instantiation.
 6767     
 6768     """)
 6769 
 6770 add_newdoc('numpy.core.numerictypes', 'character',
 6771     """
 6772     Abstract base class of all character string scalar types.
 6773     
 6774     """)
 6775 
 6776 
 6777 ##############################################################################
 6778 #
 6779 # Documentation for concrete scalar classes
 6780 #
 6781 ##############################################################################
 6782 
 6783 def numeric_type_aliases(aliases):
 6784     def type_aliases_gen():
 6785         for alias, doc in aliases:
 6786             try:
 6787                 alias_type = getattr(_numerictypes, alias)
 6788             except AttributeError:
 6789                 # The set of aliases that actually exist varies between platforms
 6790                 pass
 6791             else:
 6792                 yield (alias_type, alias, doc)
 6793     return list(type_aliases_gen())
 6794 
 6795 
 6796 possible_aliases = numeric_type_aliases([
 6797     ('int8', '8-bit signed integer (-128 to 127)'),
 6798     ('int16', '16-bit signed integer (-32768 to 32767)'),
 6799     ('int32', '32-bit signed integer (-2147483648 to 2147483647)'),
 6800     ('int64', '64-bit signed integer (-9223372036854775808 to 9223372036854775807)'),
 6801     ('intp', 'Signed integer large enough to fit pointer, compatible with C ``intptr_t``'),
 6802     ('uint8', '8-bit unsigned integer (0 to 255)'),
 6803     ('uint16', '16-bit unsigned integer (0 to 65535)'),
 6804     ('uint32', '32-bit unsigned integer (0 to 4294967295)'),
 6805     ('uint64', '64-bit unsigned integer (0 to 18446744073709551615)'),
 6806     ('uintp', 'Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``'),
 6807     ('float16', '16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa'),
 6808     ('float32', '32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits mantissa'),
 6809     ('float64', '64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa'),
 6810     ('float96', '96-bit extended-precision floating-point number type'),
 6811     ('float128', '128-bit extended-precision floating-point number type'),
 6812     ('complex64', 'Complex number type composed of 2 32-bit-precision floating-point numbers'),
 6813     ('complex128', 'Complex number type composed of 2 64-bit-precision floating-point numbers'),
 6814     ('complex192', 'Complex number type composed of 2 96-bit extended-precision floating-point numbers'),
 6815     ('complex256', 'Complex number type composed of 2 128-bit extended-precision floating-point numbers'),
 6816     ])
 6817 
 6818 
 6819 def add_newdoc_for_scalar_type(obj, fixed_aliases, doc):
 6820     o = getattr(_numerictypes, obj)
 6821 
 6822     character_code = dtype(o).char
 6823     canonical_name_doc = "" if obj == o.__name__ else "Canonical name: ``np.{}``.\n    ".format(obj)
 6824     alias_doc = ''.join("Alias: ``np.{}``.\n    ".format(alias) for alias in fixed_aliases)
 6825     alias_doc += ''.join("Alias *on this platform*: ``np.{}``: {}.\n    ".format(alias, doc)
 6826                          for (alias_type, alias, doc) in possible_aliases if alias_type is o)
 6827 
 6828     docstring = """
 6829     {doc}
 6830     Character code: ``'{character_code}'``.
 6831     {canonical_name_doc}{alias_doc}
 6832     """.format(doc=doc.strip(), character_code=character_code,
 6833                canonical_name_doc=canonical_name_doc, alias_doc=alias_doc)
 6834 
 6835     add_newdoc('numpy.core.numerictypes', obj, docstring)
 6836 
 6837 
 6838 add_newdoc_for_scalar_type('bool_', ['bool8'],
 6839     """
 6840     Boolean type (True or False), stored as a byte.
 6841     """)
 6842 
 6843 add_newdoc_for_scalar_type('byte', [],
 6844     """
 6845     Signed integer type, compatible with C ``char``.
 6846     """)
 6847 
 6848 add_newdoc_for_scalar_type('short', [],
 6849     """
 6850     Signed integer type, compatible with C ``short``.
 6851     """)
 6852 
 6853 add_newdoc_for_scalar_type('intc', [],
 6854     """
 6855     Signed integer type, compatible with C ``int``.
 6856     """)
 6857 
 6858 add_newdoc_for_scalar_type('int_', [],
 6859     """
 6860     Signed integer type, compatible with Python `int` anc C ``long``.
 6861     """)
 6862 
 6863 add_newdoc_for_scalar_type('longlong', [],
 6864     """
 6865     Signed integer type, compatible with C ``long long``.
 6866     """)
 6867 
 6868 add_newdoc_for_scalar_type('ubyte', [],
 6869     """
 6870     Unsigned integer type, compatible with C ``unsigned char``.
 6871     """)
 6872 
 6873 add_newdoc_for_scalar_type('ushort', [],
 6874     """
 6875     Unsigned integer type, compatible with C ``unsigned short``.
 6876     """)
 6877 
 6878 add_newdoc_for_scalar_type('uintc', [],
 6879     """
 6880     Unsigned integer type, compatible with C ``unsigned int``.
 6881     """)
 6882 
 6883 add_newdoc_for_scalar_type('uint', [],
 6884     """
 6885     Unsigned integer type, compatible with C ``unsigned long``.
 6886     """)
 6887 
 6888 add_newdoc_for_scalar_type('ulonglong', [],
 6889     """
 6890     Signed integer type, compatible with C ``unsigned long long``.
 6891     """)
 6892 
 6893 add_newdoc_for_scalar_type('half', [],
 6894     """
 6895     Half-precision floating-point number type.
 6896     """)
 6897 
 6898 add_newdoc_for_scalar_type('single', [],
 6899     """
 6900     Single-precision floating-point number type, compatible with C ``float``.
 6901     """)
 6902 
 6903 add_newdoc_for_scalar_type('double', ['float_'],
 6904     """
 6905     Double-precision floating-point number type, compatible with Python `float`
 6906     and C ``double``.
 6907     """)
 6908 
 6909 add_newdoc_for_scalar_type('longdouble', ['longfloat'],
 6910     """
 6911     Extended-precision floating-point number type, compatible with C
 6912     ``long double`` but not necessarily with IEEE 754 quadruple-precision.
 6913     """)
 6914 
 6915 add_newdoc_for_scalar_type('csingle', ['singlecomplex'],
 6916     """
 6917     Complex number type composed of two single-precision floating-point
 6918     numbers.
 6919     """)
 6920 
 6921 add_newdoc_for_scalar_type('cdouble', ['cfloat', 'complex_'],
 6922     """
 6923     Complex number type composed of two double-precision floating-point
 6924     numbers, compatible with Python `complex`.
 6925     """)
 6926 
 6927 add_newdoc_for_scalar_type('clongdouble', ['clongfloat', 'longcomplex'],
 6928     """
 6929     Complex number type composed of two extended-precision floating-point
 6930     numbers.
 6931     """)
 6932 
 6933 add_newdoc_for_scalar_type('object_', [],
 6934     """
 6935     Any Python object.
 6936     """)