package np

Get an attribute of this module as a Py.Object.t. This is useful to pass a Python function to another function.

absolute(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Calculate the absolute value element-wise.

``np.abs`` is a shorthand for this function.

Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- absolute : ndarray An ndarray containing the absolute value of each element in `x`. For complex input, ``a + ib``, the absolute value is :math:`\sqrt a^2 + b^2 `. This is a scalar if `x` is a scalar.

Examples -------- >>> x = np.array(-1.2, 1.2) >>> np.absolute(x) array( 1.2, 1.2) >>> np.absolute(1.2 + 1j) 1.5620499351813308

Plot the function over ``-10, 10``:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(start=-10, stop=10, num=101) >>> plt.plot(x, np.absolute(x)) >>> plt.show()

Plot the function over the complex plane:

>>> xx = x + 1j * x:, np.newaxis >>> plt.imshow(np.abs(xx), extent=-10, 10, -10, 10, cmap='gray') >>> plt.show()

absolute(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Calculate the absolute value element-wise.

``np.abs`` is a shorthand for this function.

Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- absolute : ndarray An ndarray containing the absolute value of each element in `x`. For complex input, ``a + ib``, the absolute value is :math:`\sqrt a^2 + b^2 `. This is a scalar if `x` is a scalar.

Examples -------- >>> x = np.array(-1.2, 1.2) >>> np.absolute(x) array( 1.2, 1.2) >>> np.absolute(1.2 + 1j) 1.5620499351813308

Plot the function over ``-10, 10``:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(start=-10, stop=10, num=101) >>> plt.plot(x, np.absolute(x)) >>> plt.show()

Plot the function over the complex plane:

>>> xx = x + 1j * x:, np.newaxis >>> plt.imshow(np.abs(xx), extent=-10, 10, -10, 10, cmap='gray') >>> plt.show()

add(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Add arguments element-wise.

Parameters ---------- x1, x2 : array_like The arrays to be added. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- add : ndarray or scalar The sum of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars.

Notes ----- Equivalent to `x1` + `x2` in terms of array broadcasting.

Examples -------- >>> np.add(1.0, 4.0) 5.0 >>> x1 = np.arange(9.0).reshape((3, 3)) >>> x2 = np.arange(3.0) >>> np.add(x1, x2) array([ 0., 2., 4.], [ 3., 5., 7.], [ 6., 8., 10.])

add_docstring(obj, docstring)

Add a docstring to a built-in obj if possible. If the obj already has a docstring raise a RuntimeError If this routine does not know how to add a docstring to the object raise a TypeError

Add documentation to an existing object, typically one defined in C

The purpose is to allow easier editing of the docstrings without requiring a re-compile. This exists primarily for internal use within numpy itself.

Parameters ---------- place : str The absolute name of the module to import from obj : str The name of the object to add documentation to, typically a class or function name doc : str, Tuple[str, str], List[Tuple[str, str]] If a string, the documentation to apply to `obj`

If a tuple, then the first element is interpreted as an attribute of `obj` and the second as the docstring to apply - ``(method, docstring)``

If a list, then each element of the list should be a tuple of length two - ``(method1, docstring1), (method2, docstring2), ...`` warn_on_python : bool If True, the default, emit `UserWarning` if this is used to attach documentation to a pure-python object.

Notes ----- This routine never raises an error if the docstring can't be written, but will raise an error if the object being documented does not exist.

This routine cannot modify read-only docstrings, as appear in new-style classes or built-in functions. Because this routine never raises an error the caller must check manually that the docstrings were changed.

Since this function grabs the ``char *`` from a c-level str object and puts it into the ``tp_doc`` slot of the type of `obj`, it violates a number of C-API best-practices, by:

• modifying a `PyTypeObject` after calling `PyType_Ready`
• calling `Py_INCREF` on the str and losing the reference, so the str will never be released

If possible it should be avoided.

add_ufunc_docstring(ufunc, new_docstring)

Replace the docstring for a ufunc with new_docstring. This method will only work if the current docstring for the ufunc is NULL. (At the C level, i.e. when ufunc->doc is NULL.)

Parameters ---------- ufunc : numpy.ufunc A ufunc whose current doc is NULL. new_docstring : string The new docstring for the ufunc.

Notes ----- This method allocates memory for new_docstring on the heap. Technically this creates a mempory leak, since this memory will not be reclaimed until the end of the program even if the ufunc itself is removed. However this will only be a problem if the user is repeatedly creating ufuncs with no documentation, adding documentation via add_newdoc_ufunc, and then throwing away the ufunc.

Return the length of the first dimension of the input array.

Parameters ---------- a : array_like Input array.

Returns ------- alen : int Length of the first dimension of `a`.

See Also -------- shape, size

Examples -------- >>> a = np.zeros((7,4,5)) >>> a.shape0 7 >>> np.alen(a) 7

Test whether all array elements along a given axis evaluate to True.

Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : None or int or tuple of ints, optional Axis or axes along which a logical AND reduction is performed. The default (``axis=None``) is to perform a logical AND over all the dimensions of the input array. `axis` may be negative, in which case it counts from the last to the first axis.

.. versionadded:: 1.7.0

If this is a tuple of ints, a reduction is performed on multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved (e.g., if ``dtype(out)`` is float, the result will consist of 0.0's and 1.0's). See `ufuncs-output-type` for more details.

keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

If the default value is passed, then `keepdims` will not be passed through to the `all` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised.

Returns ------- all : ndarray, bool A new boolean or array is returned unless `out` is specified, in which case a reference to `out` is returned.

See Also -------- ndarray.all : equivalent method

any : Test whether any element along a given axis evaluates to True.

Notes ----- Not a Number (NaN), positive infinity and negative infinity evaluate to `True` because these are not equal to zero.

Examples -------- >>> np.all([True,False],[True,True]) False

>>> np.all([True,False],[True,True], axis=0) array( True, False)

>>> np.all(-1, 4, 5) True

>>> np.all(1.0, np.nan) True

>>> o=np.array(False) >>> z=np.all(-1, 4, 5, out=o) >>> id(z), id(o), z (28293632, 28293632, array(True)) # may vary

Returns True if two arrays are element-wise equal within a tolerance.

The tolerance values are positive, typically very small numbers. The relative difference (`rtol` * abs(`b`)) and the absolute difference `atol` are added together to compare against the absolute difference between `a` and `b`.

NaNs are treated as equal if they are in the same place and if ``equal_nan=True``. Infs are treated as equal if they are in the same place and of the same sign in both arrays.

Parameters ---------- a, b : array_like Input arrays to compare. rtol : float The relative tolerance parameter (see Notes). atol : float The absolute tolerance parameter (see Notes). equal_nan : bool Whether to compare NaN's as equal. If True, NaN's in `a` will be considered equal to NaN's in `b` in the output array.

.. versionadded:: 1.10.0

Returns ------- allclose : bool Returns True if the two arrays are equal within the given tolerance; False otherwise.

See Also -------- isclose, all, any, equal

Notes ----- If the following equation is element-wise True, then allclose returns True.

absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`))

The above equation is not symmetric in `a` and `b`, so that ``allclose(a, b)`` might be different from ``allclose(b, a)`` in some rare cases.

The comparison of `a` and `b` uses standard broadcasting, which means that `a` and `b` need not have the same shape in order for ``allclose(a, b)`` to evaluate to True. The same is true for `equal` but not `array_equal`.

Examples -------- >>> np.allclose(1e10,1e-7, 1.00001e10,1e-8) False >>> np.allclose(1e10,1e-8, 1.00001e10,1e-9) True >>> np.allclose(1e10,1e-8, 1.0001e10,1e-9) False >>> np.allclose(1.0, np.nan, 1.0, np.nan) False >>> np.allclose(1.0, np.nan, 1.0, np.nan, equal_nan=True) True

Check if all elements of input array are true.

See Also -------- numpy.all : Equivalent function; see for details.

Return the maximum of an array or maximum along an axis.

Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional Axis or axes along which to operate. By default, flattened input is used.

.. versionadded:: 1.7.0

If this is a tuple of ints, the maximum is selected over multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See `ufuncs-output-type` for more details.

keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

If the default value is passed, then `keepdims` will not be passed through to the `amax` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised.

initial : scalar, optional The minimum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details.

.. versionadded:: 1.15.0

where : array_like of bool, optional Elements to compare for the maximum. See `~numpy.ufunc.reduce` for details.

.. versionadded:: 1.17.0

Returns ------- amax : ndarray or scalar Maximum of `a`. If `axis` is None, the result is a scalar value. If `axis` is given, the result is an array of dimension ``a.ndim - 1``.

See Also -------- amin : The minimum value of an array along a given axis, propagating any NaNs. nanmax : The maximum value of an array along a given axis, ignoring any NaNs. maximum : Element-wise maximum of two arrays, propagating any NaNs. fmax : Element-wise maximum of two arrays, ignoring any NaNs. argmax : Return the indices of the maximum values.

nanmin, minimum, fmin

Notes ----- NaN values are propagated, that is if at least one item is NaN, the corresponding max value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmax.

Don't use `amax` for element-wise comparison of 2 arrays; when ``a.shape0`` is 2, ``maximum(a0, a1)`` is faster than ``amax(a, axis=0)``.

Examples -------- >>> a = np.arange(4).reshape((2,2)) >>> a array([0, 1], [2, 3]) >>> np.amax(a) # Maximum of the flattened array 3 >>> np.amax(a, axis=0) # Maxima along the first axis array(2, 3) >>> np.amax(a, axis=1) # Maxima along the second axis array(1, 3) >>> np.amax(a, where=False, True, initial=-1, axis=0) array(-1, 3) >>> b = np.arange(5, dtype=float) >>> b2 = np.NaN >>> np.amax(b) nan >>> np.amax(b, where=~np.isnan(b), initial=-1) 4.0 >>> np.nanmax(b) 4.0

You can use an initial value to compute the maximum of an empty slice, or to initialize it to a different value:

>>> np.max([-50], [10], axis=-1, initial=0) array( 0, 10)

Notice that the initial value is used as one of the elements for which the maximum is determined, unlike for the default argument Python's max function, which is only used for empty iterables.

>>> np.max(5, initial=6) 6 >>> max(5, default=6) 5

Return the minimum of an array or minimum along an axis.

Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional Axis or axes along which to operate. By default, flattened input is used.

.. versionadded:: 1.7.0

If this is a tuple of ints, the minimum is selected over multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See `ufuncs-output-type` for more details.

keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

If the default value is passed, then `keepdims` will not be passed through to the `amin` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised.

initial : scalar, optional The maximum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details.

.. versionadded:: 1.15.0

where : array_like of bool, optional Elements to compare for the minimum. See `~numpy.ufunc.reduce` for details.

.. versionadded:: 1.17.0

Returns ------- amin : ndarray or scalar Minimum of `a`. If `axis` is None, the result is a scalar value. If `axis` is given, the result is an array of dimension ``a.ndim - 1``.

See Also -------- amax : The maximum value of an array along a given axis, propagating any NaNs. nanmin : The minimum value of an array along a given axis, ignoring any NaNs. minimum : Element-wise minimum of two arrays, propagating any NaNs. fmin : Element-wise minimum of two arrays, ignoring any NaNs. argmin : Return the indices of the minimum values.

nanmax, maximum, fmax

Notes ----- NaN values are propagated, that is if at least one item is NaN, the corresponding min value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmin.

Don't use `amin` for element-wise comparison of 2 arrays; when ``a.shape0`` is 2, ``minimum(a0, a1)`` is faster than ``amin(a, axis=0)``.

Examples -------- >>> a = np.arange(4).reshape((2,2)) >>> a array([0, 1], [2, 3]) >>> np.amin(a) # Minimum of the flattened array 0 >>> np.amin(a, axis=0) # Minima along the first axis array(0, 1) >>> np.amin(a, axis=1) # Minima along the second axis array(0, 2) >>> np.amin(a, where=False, True, initial=10, axis=0) array(10, 1)

>>> b = np.arange(5, dtype=float) >>> b2 = np.NaN >>> np.amin(b) nan >>> np.amin(b, where=~np.isnan(b), initial=10) 0.0 >>> np.nanmin(b) 0.0

>>> np.min([-50], [10], axis=-1, initial=0) array(-50, 0)

Notice that the initial value is used as one of the elements for which the minimum is determined, unlike for the default argument Python's max function, which is only used for empty iterables.

Notice that this isn't the same as Python's ``default`` argument.

>>> np.min(6, initial=5) 5 >>> min(6, default=5) 6

Return the angle of the complex argument.

Parameters ---------- z : array_like A complex number or sequence of complex numbers. deg : bool, optional Return angle in degrees if True, radians if False (default).

Returns ------- angle : ndarray or scalar The counterclockwise angle from the positive real axis on the complex plane in the range ``(-pi, pi]``, with dtype as numpy.float64.

..versionchanged:: 1.16.0 This function works on subclasses of ndarray like `ma.array`.

See Also -------- arctan2 absolute

Notes ----- Although the angle of the complex number 0 is undefined, ``numpy.angle(0)`` returns the value 0.

Examples -------- >>> np.angle(1.0, 1.0j, 1+1j) # in radians array( 0. , 1.57079633, 0.78539816) # may vary >>> np.angle(1+1j, deg=True) # in degrees 45.0

Test whether any array element along a given axis evaluates to True.

Returns single boolean unless `axis` is not ``None``

Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : None or int or tuple of ints, optional Axis or axes along which a logical OR reduction is performed. The default (``axis=None``) is to perform a logical OR over all the dimensions of the input array. `axis` may be negative, in which case it counts from the last to the first axis.

.. versionadded:: 1.7.0

If this is a tuple of ints, a reduction is performed on multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved (e.g., if it is of type float, then it will remain so, returning 1.0 for True and 0.0 for False, regardless of the type of `a`). See `ufuncs-output-type` for more details.

keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

If the default value is passed, then `keepdims` will not be passed through to the `any` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised.

Returns ------- any : bool or ndarray A new boolean or `ndarray` is returned unless `out` is specified, in which case a reference to `out` is returned.

See Also -------- ndarray.any : equivalent method

all : Test whether all elements along a given axis evaluate to True.

Notes ----- Not a Number (NaN), positive infinity and negative infinity evaluate to `True` because these are not equal to zero.

Examples -------- >>> np.any([True, False], [True, True]) True

>>> np.any([True, False], [False, False], axis=0) array( True, False)

>>> np.any(-1, 0, 5) True

>>> np.any(np.nan) True

>>> o=np.array(False) >>> z=np.any(-1, 4, 5, out=o) >>> z, o (array(True), array(True)) >>> # Check now that z is a reference to o >>> z is o True >>> id(z), id(o) # identity of z and o # doctest: +SKIP (191614240, 191614240)

Append values to the end of an array.

Parameters ---------- arr : array_like Values are appended to a copy of this array. values : array_like These values are appended to a copy of `arr`. It must be of the correct shape (the same shape as `arr`, excluding `axis`). If `axis` is not specified, `values` can be any shape and will be flattened before use. axis : int, optional The axis along which `values` are appended. If `axis` is not given, both `arr` and `values` are flattened before use.

Returns ------- append : ndarray A copy of `arr` with `values` appended to `axis`. Note that `append` does not occur in-place: a new array is allocated and filled. If `axis` is None, `out` is a flattened array.

See Also -------- insert : Insert elements into an array. delete : Delete elements from an array.

Examples -------- >>> np.append(1, 2, 3, [4, 5, 6], [7, 8, 9]) array(1, 2, 3, ..., 7, 8, 9)

When `axis` is specified, `values` must have the correct shape.

>>> np.append([1, 2, 3], [4, 5, 6], [7, 8, 9], axis=0) array([1, 2, 3], [4, 5, 6], [7, 8, 9]) >>> np.append([1, 2, 3], [4, 5, 6], 7, 8, 9, axis=0) Traceback (most recent call last): ... ValueError: all the input arrays must have same number of dimensions, but the array at index 0 has 2 dimension(s) and the array at index 1 has 1 dimension(s)

Apply a function to 1-D slices along the given axis.

Execute `func1d(a, *args, **kwargs)` where `func1d` operates on 1-D arrays and `a` is a 1-D slice of `arr` along `axis`.

This is equivalent to (but faster than) the following use of `ndindex` and `s_`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of indices::

Ni, Nk = a.shape:axis, a.shapeaxis+1: for ii in ndindex(Ni): for kk in ndindex(Nk): f = func1d(arrii + s_[:,] + kk) Nj = f.shape for jj in ndindex(Nj): outii + jj + kk = fjj

Equivalently, eliminating the inner loop, this can be expressed as::

Ni, Nk = a.shape:axis, a.shapeaxis+1: for ii in ndindex(Ni): for kk in ndindex(Nk): outii + s_[...,] + kk = func1d(arrii + s_[:,] + kk)

Parameters ---------- func1d : function (M,) -> (Nj...) This function should accept 1-D arrays. It is applied to 1-D slices of `arr` along the specified axis. axis : integer Axis along which `arr` is sliced. arr : ndarray (Ni..., M, Nk...) Input array. args : any Additional arguments to `func1d`. kwargs : any Additional named arguments to `func1d`.

.. versionadded:: 1.9.0

Returns ------- out : ndarray (Ni..., Nj..., Nk...) The output array. The shape of `out` is identical to the shape of `arr`, except along the `axis` dimension. This axis is removed, and replaced with new dimensions equal to the shape of the return value of `func1d`. So if `func1d` returns a scalar `out` will have one fewer dimensions than `arr`.

See Also -------- apply_over_axes : Apply a function repeatedly over multiple axes.

Examples -------- >>> def my_func(a): ... '''Average first and last element of a 1-D array''' ... return (a0 + a-1) * 0.5 >>> b = np.array([1,2,3], [4,5,6], [7,8,9]) >>> np.apply_along_axis(my_func, 0, b) array(4., 5., 6.) >>> np.apply_along_axis(my_func, 1, b) array(2., 5., 8.)

For a function that returns a 1D array, the number of dimensions in `outarr` is the same as `arr`.

>>> b = np.array([8,1,7], [4,3,9], [5,2,6]) >>> np.apply_along_axis(sorted, 1, b) array([1, 7, 8], [3, 4, 9], [2, 5, 6])

For a function that returns a higher dimensional array, those dimensions are inserted in place of the `axis` dimension.

>>> b = np.array([1,2,3], [4,5,6], [7,8,9]) >>> np.apply_along_axis(np.diag, -1, b) array([[1, 0, 0], [0, 2, 0], [0, 0, 3]], [[4, 0, 0], [0, 5, 0], [0, 0, 6]], [[7, 0, 0], [0, 8, 0], [0, 0, 9]])

Apply a function repeatedly over multiple axes.

`func` is called as `res = func(a, axis)`, where `axis` is the first element of `axes`. The result `res` of the function call must have either the same dimensions as `a` or one less dimension. If `res` has one less dimension than `a`, a dimension is inserted before `axis`. The call to `func` is then repeated for each axis in `axes`, with `res` as the first argument.

Parameters ---------- func : function This function must take two arguments, `func(a, axis)`. a : array_like Input array. axes : array_like Axes over which `func` is applied; the elements must be integers.

Returns ------- apply_over_axis : ndarray The output array. The number of dimensions is the same as `a`, but the shape can be different. This depends on whether `func` changes the shape of its output with respect to its input.

See Also -------- apply_along_axis : Apply a function to 1-D slices of an array along the given axis.

Notes ------ This function is equivalent to tuple axis arguments to reorderable ufuncs with keepdims=True. Tuple axis arguments to ufuncs have been available since version 1.7.0.

Examples -------- >>> a = np.arange(24).reshape(2,3,4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]], [[12, 13, 14, 15], [16, 17, 18, 19], [20, 21, 22, 23]])

Sum over axes 0 and 2. The result has same number of dimensions as the original array:

>>> np.apply_over_axes(np.sum, a, 0,2) array([[ 60], [ 92], [124]])

Tuple axis arguments to ufuncs are equivalent:

>>> np.sum(a, axis=(0,2), keepdims=True) array([[ 60], [ 92], [124]])

arange(start, stop, step,, dtype=None)

Return evenly spaced values within a given interval.

Values are generated within the half-open interval ``start, stop)`` (in other words, the interval including `start` but excluding `stop`). For integer arguments the function is equivalent to the Python built-in `range` function, but returns an ndarray rather than a list. When using a non-integer step, such as 0.1, the results will often not be consistent. It is better to use `numpy.linspace` for these cases. Parameters ---------- start : number, optional Start of interval. The interval includes this value. The default start value is 0. stop : number End of interval. The interval does not include this value, except in some cases where `step` is not an integer and floating point round-off affects the length of `out`. step : number, optional Spacing between values. For any output `out`, this is the distance between two adjacent values, ``out[i+1] - out[i]``. The default step size is 1. If `step` is specified as a position argument, `start` must also be given. dtype : dtype The type of the output array. If `dtype` is not given, infer the data type from the other input arguments. Returns ------- arange : ndarray Array of evenly spaced values. For floating point arguments, the length of the result is ``ceil((stop - start)/step)``. Because of floating point overflow, this rule may result in the last element of `out` being greater than `stop`. See Also -------- numpy.linspace : Evenly spaced numbers with careful handling of endpoints. numpy.ogrid: Arrays of evenly spaced numbers in N-dimensions. numpy.mgrid: Grid-shaped arrays of evenly spaced numbers in N-dimensions. Examples -------- >>> np.arange(3) array([0, 1, 2]) >>> np.arange(3.0) array([ 0., 1., 2.]) >>> np.arange(3,7) array([3, 4, 5, 6]) >>> np.arange(3,7,2) array([3, 5])

arccos(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Trigonometric inverse cosine, element-wise.

The inverse of `cos` so that, if ``y = cos(x)``, then ``x = arccos(y)``.

Parameters ---------- x : array_like `x`-coordinate on the unit circle. For real arguments, the domain is -1, 1. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- angle : ndarray The angle of the ray intersecting the unit circle at the given `x`-coordinate in radians 0, pi. This is a scalar if `x` is a scalar.

See Also -------- cos, arctan, arcsin, emath.arccos

Notes ----- `arccos` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `cos(z) = x`. The convention is to return the angle `z` whose real part lies in `0, pi`.

For real-valued input data types, `arccos` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag.

For complex-valued input, `arccos` is a complex analytic function that has branch cuts `-inf, -1` and `1, inf` and is continuous from above on the former and from below on the latter.

The inverse `cos` is also known as `acos` or cos^-1.

References ---------- M. Abramowitz and I.A. Stegun, 'Handbook of Mathematical Functions', 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/

Examples -------- We expect the arccos of 1 to be 0, and of -1 to be pi:

>>> np.arccos(1, -1) array( 0. , 3.14159265)

Plot arccos:

>>> import matplotlib.pyplot as plt >>> x = np.linspace(-1, 1, num=100) >>> plt.plot(x, np.arccos(x)) >>> plt.axis('tight') >>> plt.show()

arccosh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Inverse hyperbolic cosine, element-wise.

Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- arccosh : ndarray Array of the same shape as `x`. This is a scalar if `x` is a scalar.

See Also --------

cosh, arcsinh, sinh, arctanh, tanh

Notes ----- `arccosh` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `cosh(z) = x`. The convention is to return the `z` whose imaginary part lies in `-pi, pi` and the real part in ``0, inf``.

For real-valued input data types, `arccosh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag.

For complex-valued input, `arccosh` is a complex analytical function that has a branch cut `-inf, 1` and is continuous from above on it.

References ---------- .. 1 M. Abramowitz and I.A. Stegun, 'Handbook of Mathematical Functions', 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/ .. 2 Wikipedia, 'Inverse hyperbolic function', https://en.wikipedia.org/wiki/Arccosh

Examples -------- >>> np.arccosh(np.e, 10.0) array( 1.65745445, 2.99322285) >>> np.arccosh(1) 0.0

arcsin(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Inverse sine, element-wise.

Parameters ---------- x : array_like `y`-coordinate on the unit circle. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- angle : ndarray The inverse sine of each element in `x`, in radians and in the closed interval ``-pi/2, pi/2``. This is a scalar if `x` is a scalar.

See Also -------- sin, cos, arccos, tan, arctan, arctan2, emath.arcsin

Notes ----- `arcsin` is a multivalued function: for each `x` there are infinitely many numbers `z` such that :math:`sin(z) = x`. The convention is to return the angle `z` whose real part lies in -pi/2, pi/2.

For real-valued input data types, *arcsin* always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag.

For complex-valued input, `arcsin` is a complex analytic function that has, by convention, the branch cuts -inf, -1 and 1, inf and is continuous from above on the former and from below on the latter.

The inverse sine is also known as `asin` or sin^

1

}

.

References ---------- Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, 10th printing, New York: Dover, 1964, pp. 79ff. http://www.math.sfu.ca/~cbm/aands/

Examples -------- >>> np.arcsin(1) # pi/2 1.5707963267948966 >>> np.arcsin(-1) # -pi/2 -1.5707963267948966 >>> np.arcsin(0) 0.0

arcsinh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Inverse hyperbolic sine element-wise.

Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Array of the same shape as `x`. This is a scalar if `x` is a scalar.

Notes ----- `arcsinh` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `sinh(z) = x`. The convention is to return the `z` whose imaginary part lies in `-pi/2, pi/2`.

For real-valued input data types, `arcsinh` always returns real output. For each value that cannot be expressed as a real number or infinity, it returns ``nan`` and sets the `invalid` floating point error flag.

For complex-valued input, `arccos` is a complex analytical function that has branch cuts `1j, infj` and `-1j, -infj` and is continuous from the right on the former and from the left on the latter.

The inverse hyperbolic sine is also known as `asinh` or ``sinh^-1``.

References ---------- .. 1 M. Abramowitz and I.A. Stegun, 'Handbook of Mathematical Functions', 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/ .. 2 Wikipedia, 'Inverse hyperbolic function', https://en.wikipedia.org/wiki/Arcsinh

Examples -------- >>> np.arcsinh(np.array(np.e, 10.0)) array( 1.72538256, 2.99822295)

arctan(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Trigonometric inverse tangent, element-wise.

The inverse of tan, so that if ``y = tan(x)`` then ``x = arctan(y)``.

Parameters ---------- x : array_like out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Out has the same shape as `x`. Its real part is in ``-pi/2, pi/2`` (``arctan(+/-inf)`` returns ``+/-pi/2``). This is a scalar if `x` is a scalar.

See Also -------- arctan2 : The 'four quadrant' arctan of the angle formed by (`x`, `y`) and the positive `x`-axis. angle : Argument of complex values.

Notes ----- `arctan` is a multi-valued function: for each `x` there are infinitely many numbers `z` such that tan(`z`) = `x`. The convention is to return the angle `z` whose real part lies in -pi/2, pi/2.

For real-valued input data types, `arctan` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag.

For complex-valued input, `arctan` is a complex analytic function that has `1j, infj` and `-1j, -infj` as branch cuts, and is continuous from the left on the former and from the right on the latter.

The inverse tangent is also known as `atan` or tan^

1

}

.

References ---------- Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, 10th printing, New York: Dover, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/

Examples -------- We expect the arctan of 0 to be 0, and of 1 to be pi/4:

>>> np.arctan(0, 1) array( 0. , 0.78539816)

>>> np.pi/4 0.78539816339744828

Plot arctan:

>>> import matplotlib.pyplot as plt >>> x = np.linspace(-10, 10) >>> plt.plot(x, np.arctan(x)) >>> plt.axis('tight') >>> plt.show()

arctan2(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Element-wise arc tangent of ``x1/x2`` choosing the quadrant correctly.

The quadrant (i.e., branch) is chosen so that ``arctan2(x1, x2)`` is the signed angle in radians between the ray ending at the origin and passing through the point (1,0), and the ray ending at the origin and passing through the point (`x2`, `x1`). (Note the role reversal: the '`y`-coordinate' is the first function parameter, the '`x`-coordinate' is the second.) By IEEE convention, this function is defined for `x2` = +/-0 and for either or both of `x1` and `x2` = +/-inf (see Notes for specific values).

This function is not defined for complex-valued arguments; for the so-called argument of complex values, use `angle`.

Parameters ---------- x1 : array_like, real-valued `y`-coordinates. x2 : array_like, real-valued `x`-coordinates. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- angle : ndarray Array of angles in radians, in the range ``-pi, pi``. This is a scalar if both `x1` and `x2` are scalars.

See Also -------- arctan, tan, angle

Notes ----- *arctan2* is identical to the `atan2` function of the underlying C library. The following special values are defined in the C standard: 1_

====== ====== ================ `x1` `x2` `arctan2(x1,x2)` ====== ====== ================ +/- 0 +0 +/- 0 +/- 0 -0 +/- pi > 0 +/-inf +0 / +pi < 0 +/-inf -0 / -pi +/-inf +inf +/- (pi/4) +/-inf -inf +/- (3*pi/4) ====== ====== ================

Note that +0 and -0 are distinct floating point numbers, as are +inf and -inf.

References ---------- .. 1 ISO/IEC standard 9899:1999, 'Programming language C.'

Examples -------- Consider four points in different quadrants:

>>> x = np.array(-1, +1, +1, -1) >>> y = np.array(-1, -1, +1, +1) >>> np.arctan2(y, x) * 180 / np.pi array(-135., -45., 45., 135.)

Note the order of the parameters. `arctan2` is defined also when `x2` = 0 and at several other special points, obtaining values in the range ``-pi, pi``:

>>> np.arctan2(1., -1., 0., 0.) array( 1.57079633, -1.57079633) >>> np.arctan2(0., 0., np.inf, +0., -0., np.inf) array( 0. , 3.14159265, 0.78539816)

arctanh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Inverse hyperbolic tangent element-wise.

Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Array of the same shape as `x`. This is a scalar if `x` is a scalar.

See Also -------- emath.arctanh

Notes ----- `arctanh` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `tanh(z) = x`. The convention is to return the `z` whose imaginary part lies in `-pi/2, pi/2`.

For real-valued input data types, `arctanh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag.

For complex-valued input, `arctanh` is a complex analytical function that has branch cuts `-1, -inf` and `1, inf` and is continuous from above on the former and from below on the latter.

The inverse hyperbolic tangent is also known as `atanh` or ``tanh^-1``.

References ---------- .. 1 M. Abramowitz and I.A. Stegun, 'Handbook of Mathematical Functions', 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/ .. 2 Wikipedia, 'Inverse hyperbolic function', https://en.wikipedia.org/wiki/Arctanh

Examples -------- >>> np.arctanh(0, -0.5) array( 0. , -0.54930614)

Returns the indices of the maximum values along an axis.

Parameters ---------- a : array_like Input array. axis : int, optional By default, the index is into the flattened array, otherwise along the specified axis. out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.

Returns ------- index_array : ndarray of ints Array of indices into the array. It has the same shape as `a.shape` with the dimension along `axis` removed.

See Also -------- ndarray.argmax, argmin amax : The maximum value along a given axis. unravel_index : Convert a flat index into an index tuple. take_along_axis : Apply ``np.expand_dims(index_array, axis)`` from argmax to an array as if by calling max.

Notes ----- In case of multiple occurrences of the maximum values, the indices corresponding to the first occurrence are returned.

Examples -------- >>> a = np.arange(6).reshape(2,3) + 10 >>> a array([10, 11, 12], [13, 14, 15]) >>> np.argmax(a) 5 >>> np.argmax(a, axis=0) array(1, 1, 1) >>> np.argmax(a, axis=1) array(2, 2)

Indexes of the maximal elements of a N-dimensional array:

>>> ind = np.unravel_index(np.argmax(a, axis=None), a.shape) >>> ind (1, 2) >>> aind 15

>>> b = np.arange(6) >>> b1 = 5 >>> b array(0, 5, 2, 3, 4, 5) >>> np.argmax(b) # Only the first occurrence is returned. 1

>>> x = np.array([4,2,3], [1,0,3]) >>> index_array = np.argmax(x, axis=-1) >>> # Same as np.max(x, axis=-1, keepdims=True) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1) array([4], [3]) >>> # Same as np.max(x, axis=-1) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1) array(4, 3)

Returns the indices of the minimum values along an axis.

Parameters ---------- a : array_like Input array. axis : int, optional By default, the index is into the flattened array, otherwise along the specified axis. out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.

Returns ------- index_array : ndarray of ints Array of indices into the array. It has the same shape as `a.shape` with the dimension along `axis` removed.

See Also -------- ndarray.argmin, argmax amin : The minimum value along a given axis. unravel_index : Convert a flat index into an index tuple. take_along_axis : Apply ``np.expand_dims(index_array, axis)`` from argmin to an array as if by calling min.

Notes ----- In case of multiple occurrences of the minimum values, the indices corresponding to the first occurrence are returned.

Examples -------- >>> a = np.arange(6).reshape(2,3) + 10 >>> a array([10, 11, 12], [13, 14, 15]) >>> np.argmin(a) 0 >>> np.argmin(a, axis=0) array(0, 0, 0) >>> np.argmin(a, axis=1) array(0, 0)

Indices of the minimum elements of a N-dimensional array:

>>> ind = np.unravel_index(np.argmin(a, axis=None), a.shape) >>> ind (0, 0) >>> aind 10

>>> b = np.arange(6) + 10 >>> b4 = 10 >>> b array(10, 11, 12, 13, 10, 15) >>> np.argmin(b) # Only the first occurrence is returned. 0

>>> x = np.array([4,2,3], [1,0,3]) >>> index_array = np.argmin(x, axis=-1) >>> # Same as np.min(x, axis=-1, keepdims=True) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1) array([2], [0]) >>> # Same as np.max(x, axis=-1) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1) array(2, 0)

Perform an indirect partition along the given axis using the algorithm specified by the `kind` keyword. It returns an array of indices of the same shape as `a` that index data along the given axis in partitioned order.

.. versionadded:: 1.8.0

Parameters ---------- a : array_like Array to sort. kth : int or sequence of ints Element index to partition by. The k-th element will be in its final sorted position and all smaller elements will be moved before it and all larger elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of k-th it will partition all of them into their sorted position at once. axis : int or None, optional Axis along which to sort. The default is -1 (the last axis). If None, the flattened array is used. kind : 'introselect', optional Selection algorithm. Default is 'introselect' order : str or list of str, optional When `a` is an array with fields defined, this argument specifies which fields to compare first, second, etc. A single field can be specified as a string, and not all fields need be specified, but unspecified fields will still be used, in the order in which they come up in the dtype, to break ties.

Returns ------- index_array : ndarray, int Array of indices that partition `a` along the specified axis. If `a` is one-dimensional, ``aindex_array`` yields a partitioned `a`. More generally, ``np.take_along_axis(a, index_array, axis=a)`` always yields the partitioned `a`, irrespective of dimensionality.

See Also -------- partition : Describes partition algorithms used. ndarray.partition : Inplace partition. argsort : Full indirect sort. take_along_axis : Apply ``index_array`` from argpartition to an array as if by calling partition.

Notes ----- See `partition` for notes on the different selection algorithms.

Examples -------- One dimensional array:

>>> x = np.array(3, 4, 2, 1) >>> xnp.argpartition(x, 3) array(2, 1, 3, 4) >>> xnp.argpartition(x, (1, 3)) array(1, 2, 3, 4)

>>> x = 3, 4, 2, 1 >>> np.array(x)np.argpartition(x, 3) array(2, 1, 3, 4)

Multi-dimensional array:

>>> x = np.array([3, 4, 2], [1, 3, 1]) >>> index_array = np.argpartition(x, kth=1, axis=-1) >>> np.take_along_axis(x, index_array, axis=-1) # same as np.partition(x, kth=1) array([2, 3, 4], [1, 1, 3])

Returns the indices that would sort an array.

Perform an indirect sort along the given axis using the algorithm specified by the `kind` keyword. It returns an array of indices of the same shape as `a` that index data along the given axis in sorted order.

Parameters ---------- a : array_like Array to sort. axis : int or None, optional Axis along which to sort. The default is -1 (the last axis). If None, the flattened array is used. kind : 'quicksort', 'mergesort', 'heapsort', 'stable', optional Sorting algorithm. The default is 'quicksort'. Note that both 'stable' and 'mergesort' use timsort under the covers and, in general, the actual implementation will vary with data type. The 'mergesort' option is retained for backwards compatibility.

.. versionchanged:: 1.15.0. The 'stable' option was added. order : str or list of str, optional When `a` is an array with fields defined, this argument specifies which fields to compare first, second, etc. A single field can be specified as a string, and not all fields need be specified, but unspecified fields will still be used, in the order in which they come up in the dtype, to break ties.

Returns ------- index_array : ndarray, int Array of indices that sort `a` along the specified `axis`. If `a` is one-dimensional, ``aindex_array`` yields a sorted `a`. More generally, ``np.take_along_axis(a, index_array, axis=axis)`` always yields the sorted `a`, irrespective of dimensionality.

See Also -------- sort : Describes sorting algorithms used. lexsort : Indirect stable sort with multiple keys. ndarray.sort : Inplace sort. argpartition : Indirect partial sort. take_along_axis : Apply ``index_array`` from argsort to an array as if by calling sort.

Notes ----- See `sort` for notes on the different sorting algorithms.

As of NumPy 1.4.0 `argsort` works with real/complex arrays containing nan values. The enhanced sort order is documented in `sort`.

Examples -------- One dimensional array:

>>> x = np.array(3, 1, 2) >>> np.argsort(x) array(1, 2, 0)

Two-dimensional array:

>>> x = np.array([0, 3], [2, 2]) >>> x array([0, 3], [2, 2])

>>> ind = np.argsort(x, axis=0) # sorts along first axis (down) >>> ind array([0, 1], [1, 0]) >>> np.take_along_axis(x, ind, axis=0) # same as np.sort(x, axis=0) array([0, 2], [2, 3])

>>> ind = np.argsort(x, axis=1) # sorts along last axis (across) >>> ind array([0, 1], [0, 1]) >>> np.take_along_axis(x, ind, axis=1) # same as np.sort(x, axis=1) array([0, 3], [2, 2])

Indices of the sorted elements of a N-dimensional array:

>>> ind = np.unravel_index(np.argsort(x, axis=None), x.shape) >>> ind (array(0, 1, 1, 0), array(0, 0, 1, 1)) >>> xind # same as np.sort(x, axis=None) array(0, 2, 2, 3)

Sorting with keys:

>>> x = np.array((1, 0), (0, 1), dtype=('x', '<i4'), ('y', '<i4')) >>> x array((1, 0), (0, 1), dtype=('x', '<i4'), ('y', '<i4'))

>>> np.argsort(x, order=('x','y')) array(1, 0)

>>> np.argsort(x, order=('y','x')) array(0, 1)

Find the indices of array elements that are non-zero, grouped by element.

Parameters ---------- a : array_like Input data.

Returns ------- index_array : (N, a.ndim) ndarray Indices of elements that are non-zero. Indices are grouped by element. This array will have shape ``(N, a.ndim)`` where ``N`` is the number of non-zero items.

See Also -------- where, nonzero

Notes ----- ``np.argwhere(a)`` is almost the same as ``np.transpose(np.nonzero(a))``, but produces a result of the correct shape for a 0D array.

The output of ``argwhere`` is not suitable for indexing arrays. For this purpose use ``nonzero(a)`` instead.

Examples -------- >>> x = np.arange(6).reshape(2,3) >>> x array([0, 1, 2], [3, 4, 5]) >>> np.argwhere(x>1) array([0, 2], [1, 0], [1, 1], [1, 2])

Evenly round to the given number of decimals.

Parameters ---------- a : array_like Input data. decimals : int, optional Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left of the decimal point. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output, but the type of the output values will be cast if necessary. See `ufuncs-output-type` for more details.

Returns ------- rounded_array : ndarray An array of the same type as `a`, containing the rounded values. Unless `out` was specified, a new array is created. A reference to the result is returned.

The real and imaginary parts of complex numbers are rounded separately. The result of rounding a float is a float.

See Also -------- ndarray.round : equivalent method

ceil, fix, floor, rint, trunc

Notes ----- For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0, -0.5 and 0.5 round to 0.0, etc.

``np.around`` uses a fast but sometimes inexact algorithm to round floating-point datatypes. For positive `decimals` it is equivalent to ``np.true_divide(np.rint(a * 10**decimals), 10**decimals)``, which has error due to the inexact representation of decimal fractions in the IEEE floating point standard 1_ and errors introduced when scaling by powers of ten. For instance, note the extra '1' in the following:

>>> np.round(56294995342131.5, 3) 56294995342131.51

If your goal is to print such values with a fixed number of decimals, it is preferable to use numpy's float printing routines to limit the number of printed decimals:

>>> np.format_float_positional(56294995342131.5, precision=3) '56294995342131.5'

The float printing routines use an accurate but much more computationally demanding algorithm to compute the number of digits after the decimal point.

Alternatively, Python's builtin `round` function uses a more accurate but slower algorithm for 64-bit floating point values:

>>> round(56294995342131.5, 3) 56294995342131.5 >>> np.round(16.055, 2), round(16.055, 2) # equals 16.0549999999999997 (16.06, 16.05)

References ---------- .. 1 'Lecture Notes on the Status of IEEE 754', William Kahan, https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF .. 2 'How Futile are Mindless Assessments of Roundoff in Floating-Point Computation?', William Kahan, https://people.eecs.berkeley.edu/~wkahan/Mindless.pdf

Examples -------- >>> np.around(0.37, 1.64) array(0., 2.) >>> np.around(0.37, 1.64, decimals=1) array(0.4, 1.6) >>> np.around(.5, 1.5, 2.5, 3.5, 4.5) # rounds to nearest even value array(0., 2., 2., 4., 4.) >>> np.around(1,2,3,11, decimals=1) # ndarray of ints is returned array( 1, 2, 3, 11) >>> np.around(1,2,3,11, decimals=-1) array( 0, 0, 0, 10)

array(object, dtype=None, *, copy=True, order='K', subok=False, ndmin=0)

Create an array.

Parameters ---------- object : array_like An array, any object exposing the array interface, an object whose __array__ method returns an array, or any (nested) sequence. dtype : data-type, optional The desired data-type for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence. copy : bool, optional If true (default), then the object is copied. Otherwise, a copy will only be made if __array__ returns a copy, if obj is a nested sequence, or if a copy is needed to satisfy any of the other requirements (`dtype`, `order`, etc.). order : 'K', 'A', 'C', 'F', optional Specify the memory layout of the array. If object is not an array, the newly created array will be in C order (row major) unless 'F' is specified, in which case it will be in Fortran order (column major). If object is an array the following holds.

===== ========= =================================================== order no copy copy=True ===== ========= =================================================== 'K' unchanged F & C order preserved, otherwise most similar order 'A' unchanged F order if input is F and not C, otherwise C order 'C' C order C order 'F' F order F order ===== ========= ===================================================

When ``copy=False`` and a copy is made for other reasons, the result is the same as if ``copy=True``, with some exceptions for `A`, see the Notes section. The default order is 'K'. subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (default). ndmin : int, optional Specifies the minimum number of dimensions that the resulting array should have. Ones will be pre-pended to the shape as needed to meet this requirement.

Returns ------- out : ndarray An array object satisfying the specified requirements.

See Also -------- empty_like : Return an empty array with shape and type of input. ones_like : Return an array of ones with shape and type of input. zeros_like : Return an array of zeros with shape and type of input. full_like : Return a new array with shape of input filled with value. empty : Return a new uninitialized array. ones : Return a new array setting values to one. zeros : Return a new array setting values to zero. full : Return a new array of given shape filled with value.

Notes ----- When order is 'A' and `object` is an array in neither 'C' nor 'F' order, and a copy is forced by a change in dtype, then the order of the result is not necessarily 'C' as expected. This is likely a bug.

Examples -------- >>> np.array(1, 2, 3) array(1, 2, 3)

Upcasting:

>>> np.array(1, 2, 3.0) array( 1., 2., 3.)

More than one dimension:

>>> np.array([1, 2], [3, 4]) array([1, 2], [3, 4])

Minimum dimensions 2:

>>> np.array(1, 2, 3, ndmin=2) array([1, 2, 3])

Type provided:

>>> np.array(1, 2, 3, dtype=complex) array( 1.+0.j, 2.+0.j, 3.+0.j)

Data-type consisting of more than one element:

>>> x = np.array((1,2),(3,4),dtype=('a','<i4'),('b','<i4')) >>> x'a' array(1, 3)

Creating an array from sub-classes:

>>> np.array(np.mat('1 2; 3 4')) array([1, 2], [3, 4])

>>> np.array(np.mat('1 2; 3 4'), subok=True) matrix([1, 2], [3, 4])

Return a string representation of an array.

Parameters ---------- a : array_like Input array. max_line_width : int, optional Inserts newlines if text is longer than `max_line_width`. Defaults to ``numpy.get_printoptions()'linewidth'``. precision : int or None, optional Floating point precision. Defaults to ``numpy.get_printoptions()'precision'``. suppress_small : bool, optional Represent numbers 'very close' to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to ``numpy.get_printoptions()'suppress'``. separator : str, optional Inserted between elements. prefix : str, optional suffix: str, optional The length of the prefix and suffix strings are used to respectively align and wrap the output. An array is typically printed as::

prefix + array2string(a) + suffix

The output is left-padded by the length of the prefix string, and wrapping is forced at the column ``max_line_width - len(suffix)``. It should be noted that the content of prefix and suffix strings are not included in the output. style : _NoValue, optional Has no effect, do not use.

.. deprecated:: 1.14.0 formatter : dict of callables, optional If not None, the keys should indicate the type(s) that the respective formatting function applies to. Callables should return a string. Types that are not specified (by their corresponding keys) are handled by the default formatters. Individual types for which a formatter can be set are:

• 'bool'
• 'int'
• 'timedelta' : a `numpy.timedelta64`
• 'datetime' : a `numpy.datetime64`
• 'float'
• 'longfloat' : 128-bit floats
• 'complexfloat'
• 'longcomplexfloat' : composed of two 128-bit floats
• 'void' : type `numpy.void`
• 'numpystr' : types `numpy.string_` and `numpy.unicode_`
• 'str' : all other strings

Other keys that can be used to set a group of types at once are:

• 'all' : sets all types
• 'int_kind' : sets 'int'
• 'float_kind' : sets 'float' and 'longfloat'
• 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat'
• 'str_kind' : sets 'str' and 'numpystr' threshold : int, optional Total number of array elements which trigger summarization rather than full repr. Defaults to ``numpy.get_printoptions()'threshold'``. edgeitems : int, optional Number of array items in summary at beginning and end of each dimension. Defaults to ``numpy.get_printoptions()'edgeitems'``. sign : string, either '-', '+', or ' ', optional Controls printing of the sign of floating-point types. If '+', always print the sign of positive values. If ' ', always prints a space (whitespace character) in the sign position of positive values. If '-', omit the sign character of positive values. Defaults to ``numpy.get_printoptions()'sign'``. floatmode : str, optional Controls the interpretation of the `precision` option for floating-point types. Defaults to ``numpy.get_printoptions()'floatmode'``. Can take the following values:

• 'fixed': Always print exactly `precision` fractional digits, even if this would print more or fewer digits than necessary to specify the value uniquely.
• 'unique': Print the minimum number of fractional digits necessary to represent each value uniquely. Different elements may have a different number of digits. The value of the `precision` option is ignored.
• 'maxprec': Print at most `precision` fractional digits, but if an element can be uniquely represented with fewer digits only print it with that many.
• 'maxprec_equal': Print at most `precision` fractional digits, but if every element in the array can be uniquely represented with an equal number of fewer digits, use that many digits for all elements. legacy : string or `False`, optional If set to the string `'1.13'` enables 1.13 legacy printing mode. This approximates numpy 1.13 print output by including a space in the sign position of floats and different behavior for 0d arrays. If set to `False`, disables legacy mode. Unrecognized strings will be ignored with a warning for forward compatibility.

.. versionadded:: 1.14.0

Returns ------- array_str : str String representation of the array.

Raises ------ TypeError if a callable in `formatter` does not return a string.

See Also -------- array_str, array_repr, set_printoptions, get_printoptions

Notes ----- If a formatter is specified for a certain type, the `precision` keyword is ignored for that type.

This is a very flexible function; `array_repr` and `array_str` are using `array2string` internally so keywords with the same name should work identically in all three functions.

Examples -------- >>> x = np.array(1e-16,1,2,3) >>> np.array2string(x, precision=2, separator=',', ... suppress_small=True) '0.,1.,2.,3.'

>>> x = np.arange(3.) >>> np.array2string(x, formatter='float_kind':lambda x: '%.2f' % x) '0.00 1.00 2.00'

>>> x = np.arange(3) >>> np.array2string(x, formatter='int':lambda x: hex(x)) '0x0 0x1 0x2'

True if two arrays have the same shape and elements, False otherwise.

Parameters ---------- a1, a2 : array_like Input arrays. equal_nan : bool Whether to compare NaN's as equal. If the dtype of a1 and a2 is complex, values will be considered equal if either the real or the imaginary component of a given value is ``nan``.

.. versionadded:: 1.19.0

Returns ------- b : bool Returns True if the arrays are equal.

See Also -------- allclose: Returns True if two arrays are element-wise equal within a tolerance. array_equiv: Returns True if input arrays are shape consistent and all elements equal.

Examples -------- >>> np.array_equal(1, 2, 1, 2) True >>> np.array_equal(np.array(1, 2), np.array(1, 2)) True >>> np.array_equal(1, 2, 1, 2, 3) False >>> np.array_equal(1, 2, 1, 4) False >>> a = np.array(1, np.nan) >>> np.array_equal(a, a) False >>> np.array_equal(a, a, equal_nan=True) True

When ``equal_nan`` is True, complex values with nan components are considered equal if either the real *or* the imaginary components are nan.

>>> a = np.array(1 + 1j) >>> b = a.copy() >>> a.real = np.nan >>> b.imag = np.nan >>> np.array_equal(a, b, equal_nan=True) True

Returns True if input arrays are shape consistent and all elements equal.

Shape consistent means they are either the same shape, or one input array can be broadcasted to create the same shape as the other one.

Parameters ---------- a1, a2 : array_like Input arrays.

Returns ------- out : bool True if equivalent, False otherwise.

Examples -------- >>> np.array_equiv(1, 2, 1, 2) True >>> np.array_equiv(1, 2, 1, 3) False

Showing the shape equivalence:

>>> np.array_equiv(1, 2, [1, 2], [1, 2]) True >>> np.array_equiv(1, 2, [1, 2, 1, 2], [1, 2, 1, 2]) False

>>> np.array_equiv(1, 2, [1, 2], [1, 3]) False

Return the string representation of an array.

Parameters ---------- arr : ndarray Input array. max_line_width : int, optional Inserts newlines if text is longer than `max_line_width`. Defaults to ``numpy.get_printoptions()'linewidth'``. precision : int, optional Floating point precision. Defaults to ``numpy.get_printoptions()'precision'``. suppress_small : bool, optional Represent numbers 'very close' to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to ``numpy.get_printoptions()'suppress'``.

Returns ------- string : str The string representation of an array.

See Also -------- array_str, array2string, set_printoptions

Examples -------- >>> np.array_repr(np.array(1,2)) 'array(1, 2)' >>> np.array_repr(np.ma.array(0.)) 'MaskedArray(0.)' >>> np.array_repr(np.array(, np.int32)) 'array(, dtype=int32)'

>>> x = np.array(1e-6, 4e-7, 2, 3) >>> np.array_repr(x, precision=6, suppress_small=True) 'array(0.000001, 0. , 2. , 3. )'

Split an array into multiple sub-arrays.

Please refer to the ``split`` documentation. The only difference between these functions is that ``array_split`` allows `indices_or_sections` to be an integer that does *not* equally divide the axis. For an array of length l that should be split into n sections, it returns l % n sub-arrays of size l//n + 1 and the rest of size l//n.

See Also -------- split : Split array into multiple sub-arrays of equal size.

Examples -------- >>> x = np.arange(8.0) >>> np.array_split(x, 3) array([0., 1., 2.]), array([3., 4., 5.]), array([6., 7.])

>>> x = np.arange(7.0) >>> np.array_split(x, 3) array([0., 1., 2.]), array([3., 4.]), array([5., 6.])

Return a string representation of the data in an array.

The data in the array is returned as a single string. This function is similar to `array_repr`, the difference being that `array_repr` also returns information on the kind of array and its data type.

Parameters ---------- a : ndarray Input array. max_line_width : int, optional Inserts newlines if text is longer than `max_line_width`. Defaults to ``numpy.get_printoptions()'linewidth'``. precision : int, optional Floating point precision. Defaults to ``numpy.get_printoptions()'precision'``. suppress_small : bool, optional Represent numbers 'very close' to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to ``numpy.get_printoptions()'suppress'``.

See Also -------- array2string, array_repr, set_printoptions

Examples -------- >>> np.array_str(np.arange(3)) '0 1 2'

Convert the input to an ndarray, but pass ndarray subclasses through.

Parameters ---------- a : array_like Input data, in any form that can be converted to an array. This includes scalars, lists, lists of tuples, tuples, tuples of tuples, tuples of lists, and ndarrays. dtype : data-type, optional By default, the data-type is inferred from the input data. order : 'C', 'F', optional Whether to use row-major (C-style) or column-major (Fortran-style) memory representation. Defaults to 'C'.

Returns ------- out : ndarray or an ndarray subclass Array interpretation of `a`. If `a` is an ndarray or a subclass of ndarray, it is returned as-is and no copy is performed.

See Also -------- asarray : Similar function which always returns ndarrays. ascontiguousarray : Convert input to a contiguous array. asfarray : Convert input to a floating point ndarray. asfortranarray : Convert input to an ndarray with column-major memory order. asarray_chkfinite : Similar function which checks input for NaNs and Infs. fromiter : Create an array from an iterator. fromfunction : Construct an array by executing a function on grid positions.

Examples -------- Convert a list into an array:

>>> a = 1, 2 >>> np.asanyarray(a) array(1, 2)

Instances of `ndarray` subclasses are passed through as-is:

>>> a = np.array((1.0, 2), (3.0, 4), dtype='f4,i4').view(np.recarray) >>> np.asanyarray(a) is a True

Convert the input to an array.

Parameters ---------- a : array_like Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays. dtype : data-type, optional By default, the data-type is inferred from the input data. order : 'C', 'F', optional Whether to use row-major (C-style) or column-major (Fortran-style) memory representation. Defaults to 'C'.

Returns ------- out : ndarray Array interpretation of `a`. No copy is performed if the input is already an ndarray with matching dtype and order. If `a` is a subclass of ndarray, a base class ndarray is returned.

See Also -------- asanyarray : Similar function which passes through subclasses. ascontiguousarray : Convert input to a contiguous array. asfarray : Convert input to a floating point ndarray. asfortranarray : Convert input to an ndarray with column-major memory order. asarray_chkfinite : Similar function which checks input for NaNs and Infs. fromiter : Create an array from an iterator. fromfunction : Construct an array by executing a function on grid positions.

Examples -------- Convert a list into an array:

>>> a = 1, 2 >>> np.asarray(a) array(1, 2)

Existing arrays are not copied:

>>> a = np.array(1, 2) >>> np.asarray(a) is a True

If `dtype` is set, array is copied only if dtype does not match:

>>> a = np.array(1, 2, dtype=np.float32) >>> np.asarray(a, dtype=np.float32) is a True >>> np.asarray(a, dtype=np.float64) is a False

Contrary to `asanyarray`, ndarray subclasses are not passed through:

>>> issubclass(np.recarray, np.ndarray) True >>> a = np.array((1.0, 2), (3.0, 4), dtype='f4,i4').view(np.recarray) >>> np.asarray(a) is a False >>> np.asanyarray(a) is a True

Convert the input to an array, checking for NaNs or Infs.

Parameters ---------- a : array_like Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays. Success requires no NaNs or Infs. dtype : data-type, optional By default, the data-type is inferred from the input data. order : 'C', 'F', optional Whether to use row-major (C-style) or column-major (Fortran-style) memory representation. Defaults to 'C'.

Returns ------- out : ndarray Array interpretation of `a`. No copy is performed if the input is already an ndarray. If `a` is a subclass of ndarray, a base class ndarray is returned.

Raises ------ ValueError Raises ValueError if `a` contains NaN (Not a Number) or Inf (Infinity).

See Also -------- asarray : Create and array. asanyarray : Similar function which passes through subclasses. ascontiguousarray : Convert input to a contiguous array. asfarray : Convert input to a floating point ndarray. asfortranarray : Convert input to an ndarray with column-major memory order. fromiter : Create an array from an iterator. fromfunction : Construct an array by executing a function on grid positions.

Examples -------- Convert a list into an array. If all elements are finite ``asarray_chkfinite`` is identical to ``asarray``.

>>> a = 1, 2 >>> np.asarray_chkfinite(a, dtype=float) array(1., 2.)

Raises ValueError if array_like contains Nans or Infs.

>>> a = 1, 2, np.inf >>> try: ... np.asarray_chkfinite(a) ... except ValueError: ... print('ValueError') ... ValueError

Return a contiguous array (ndim >= 1) in memory (C order).

Parameters ---------- a : array_like Input array. dtype : str or dtype object, optional Data-type of returned array.

Returns ------- out : ndarray Contiguous array of same shape and content as `a`, with type `dtype` if specified.

See Also -------- asfortranarray : Convert input to an ndarray with column-major memory order. require : Return an ndarray that satisfies requirements. ndarray.flags : Information about the memory layout of the array.

Examples -------- >>> x = np.arange(6).reshape(2,3) >>> np.ascontiguousarray(x, dtype=np.float32) array([0., 1., 2.], [3., 4., 5.], dtype=float32) >>> x.flags'C_CONTIGUOUS' True

Note: This function returns an array with at least one-dimension (1-d) so it will not preserve 0-d arrays.

Return an array converted to a float type.

Parameters ---------- a : array_like The input array. dtype : str or dtype object, optional Float type code to coerce input array `a`. If `dtype` is one of the 'int' dtypes, it is replaced with float64.

Returns ------- out : ndarray The input `a` as a float ndarray.

Examples -------- >>> np.asfarray(2, 3) array(2., 3.) >>> np.asfarray(2, 3, dtype='float') array(2., 3.) >>> np.asfarray(2, 3, dtype='int8') array(2., 3.)

Return an array (ndim >= 1) laid out in Fortran order in memory.

Parameters ---------- a : array_like Input array. dtype : str or dtype object, optional By default, the data-type is inferred from the input data.

Returns ------- out : ndarray The input `a` in Fortran, or column-major, order.

See Also -------- ascontiguousarray : Convert input to a contiguous (C order) array. asanyarray : Convert input to an ndarray with either row or column-major memory order. require : Return an ndarray that satisfies requirements. ndarray.flags : Information about the memory layout of the array.

Examples -------- >>> x = np.arange(6).reshape(2,3) >>> y = np.asfortranarray(x) >>> x.flags'F_CONTIGUOUS' False >>> y.flags'F_CONTIGUOUS' True

Note: This function returns an array with at least one-dimension (1-d) so it will not preserve 0-d arrays.

Interpret the input as a matrix.

Unlike `matrix`, `asmatrix` does not make a copy if the input is already a matrix or an ndarray. Equivalent to ``matrix(data, copy=False)``.

Parameters ---------- data : array_like Input data. dtype : data-type Data-type of the output matrix.

Returns ------- mat : matrix `data` interpreted as a matrix.

Examples -------- >>> x = np.array([1, 2], [3, 4])

>>> m = np.asmatrix(x)

>>> x0,0 = 5

>>> m matrix([5, 2], [3, 4])

Convert an array of size 1 to its scalar equivalent.

.. deprecated:: 1.16

Deprecated, use `numpy.ndarray.item()` instead.

Parameters ---------- a : ndarray Input array of size 1.

Returns ------- out : scalar Scalar representation of `a`. The output data type is the same type returned by the input's `item` method.

Examples -------- >>> np.asscalar(np.array(24)) 24

Convert inputs to arrays with at least one dimension.

Scalar inputs are converted to 1-dimensional arrays, whilst higher-dimensional inputs are preserved.

Parameters ---------- arys1, arys2, ... : array_like One or more input arrays.

Returns ------- ret : ndarray An array, or list of arrays, each with ``a.ndim >= 1``. Copies are made only if necessary.

See Also -------- atleast_2d, atleast_3d

Examples -------- >>> np.atleast_1d(1.0) array(1.)

>>> x = np.arange(9.0).reshape(3,3) >>> np.atleast_1d(x) array([0., 1., 2.], [3., 4., 5.], [6., 7., 8.]) >>> np.atleast_1d(x) is x True

>>> np.atleast_1d(1, 3, 4) array([1]), array([3, 4])

View inputs as arrays with at least two dimensions.

Parameters ---------- arys1, arys2, ... : array_like One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have two or more dimensions are preserved.

Returns ------- res, res2, ... : ndarray An array, or list of arrays, each with ``a.ndim >= 2``. Copies are avoided where possible, and views with two or more dimensions are returned.

See Also -------- atleast_1d, atleast_3d

Examples -------- >>> np.atleast_2d(3.0) array([3.])

>>> x = np.arange(3.0) >>> np.atleast_2d(x) array([0., 1., 2.]) >>> np.atleast_2d(x).base is x True

>>> np.atleast_2d(1, 1, 2, [1, 2]) array([[1]]), array([[1, 2]]), array([[1, 2]])

View inputs as arrays with at least three dimensions.

Parameters ---------- arys1, arys2, ... : array_like One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have three or more dimensions are preserved.

Returns ------- res1, res2, ... : ndarray An array, or list of arrays, each with ``a.ndim >= 3``. Copies are avoided where possible, and views with three or more dimensions are returned. For example, a 1-D array of shape ``(N,)`` becomes a view of shape ``(1, N, 1)``, and a 2-D array of shape ``(M, N)`` becomes a view of shape ``(M, N, 1)``.

See Also -------- atleast_1d, atleast_2d

Examples -------- >>> np.atleast_3d(3.0) array([[3.]])

>>> x = np.arange(3.0) >>> np.atleast_3d(x).shape (1, 3, 1)

>>> x = np.arange(12.0).reshape(4,3) >>> np.atleast_3d(x).shape (4, 3, 1) >>> np.atleast_3d(x).base is x.base # x is a reshape, so not base itself True

>>> for arr in np.atleast_3d(1, 2, [1, 2], [[1, 2]]): ... print(arr, arr.shape) # doctest: +SKIP ... [[1] [2]] (1, 2, 1) [[1] [2]] (1, 2, 1) [[1 2]] (1, 1, 2)

Compute the weighted average along the specified axis.

Parameters ---------- a : array_like Array containing data to be averaged. If `a` is not an array, a conversion is attempted. axis : None or int or tuple of ints, optional Axis or axes along which to average `a`. The default, axis=None, will average over all of the elements of the input array. If axis is negative it counts from the last to the first axis.

.. versionadded:: 1.7.0

If axis is a tuple of ints, averaging is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. weights : array_like, optional An array of weights associated with the values in `a`. Each value in `a` contributes to the average according to its associated weight. The weights array can either be 1-D (in which case its length must be the size of `a` along the given axis) or of the same shape as `a`. If `weights=None`, then all data in `a` are assumed to have a weight equal to one. The 1-D calculation is::

avg = sum(a * weights) / sum(weights)

The only constraint on `weights` is that `sum(weights)` must not be 0. returned : bool, optional Default is `False`. If `True`, the tuple (`average`, `sum_of_weights`) is returned, otherwise only the average is returned. If `weights=None`, `sum_of_weights` is equivalent to the number of elements over which the average is taken.

Returns ------- retval, sum_of_weights : array_type or double Return the average along the specified axis. When `returned` is `True`, return a tuple with the average as the first element and the sum of the weights as the second element. `sum_of_weights` is of the same type as `retval`. The result dtype follows a genereal pattern. If `weights` is None, the result dtype will be that of `a` , or ``float64`` if `a` is integral. Otherwise, if `weights` is not None and `a` is non- integral, the result type will be the type of lowest precision capable of representing values of both `a` and `weights`. If `a` happens to be integral, the previous rules still applies but the result dtype will at least be ``float64``.

Raises ------ ZeroDivisionError When all weights along axis are zero. See `numpy.ma.average` for a version robust to this type of error. TypeError When the length of 1D `weights` is not the same as the shape of `a` along axis.

See Also -------- mean

ma.average : average for masked arrays -- useful if your data contains 'missing' values numpy.result_type : Returns the type that results from applying the numpy type promotion rules to the arguments.

Examples -------- >>> data = np.arange(1, 5) >>> data array(1, 2, 3, 4) >>> np.average(data) 2.5 >>> np.average(np.arange(1, 11), weights=np.arange(10, 0, -1)) 4.0

>>> data = np.arange(6).reshape((3,2)) >>> data array([0, 1], [2, 3], [4, 5]) >>> np.average(data, axis=1, weights=1./4, 3./4) array(0.75, 2.75, 4.75) >>> np.average(data, weights=1./4, 3./4) Traceback (most recent call last): ... TypeError: Axis must be specified when shapes of a and weights differ.

>>> a = np.ones(5, dtype=np.float128) >>> w = np.ones(5, dtype=np.complex64) >>> avg = np.average(a, weights=w) >>> print(avg.dtype) complex256

Return the Bartlett window.

The Bartlett window is very similar to a triangular window, except that the end points are at zero. It is often used in signal processing for tapering a signal, without generating too much ripple in the frequency domain.

Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned.

Returns ------- out : array The triangular window, with the maximum value normalized to one (the value one appears only if the number of samples is odd), with the first and last samples equal to zero.

See Also -------- blackman, hamming, hanning, kaiser

Notes ----- The Bartlett window is defined as

.. math:: w(n) = \frac

M-1 \left( \fracM-1

• \left|n - \fracM-1

  \right| \right)

Most references to the Bartlett window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. Note that convolution with this window produces linear interpolation. It is also known as an apodization (which means'removing the foot', i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. The fourier transform of the Bartlett is the product of two sinc functions. Note the excellent discussion in Kanasewich.

References ---------- .. 1 M.S. Bartlett, 'Periodogram Analysis and Continuous Spectra', Biometrika 37, 1-16, 1950. .. 2 E.R. Kanasewich, 'Time Sequence Analysis in Geophysics', The University of Alberta Press, 1975, pp. 109-110. .. 3 A.V. Oppenheim and R.W. Schafer, 'Discrete-Time Signal Processing', Prentice-Hall, 1999, pp. 468-471. .. 4 Wikipedia, 'Window function', https://en.wikipedia.org/wiki/Window_function .. 5 W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, 'Numerical Recipes', Cambridge University Press, 1986, page 429.

Examples -------- >>> import matplotlib.pyplot as plt >>> np.bartlett(12) array( 0. , 0.18181818, 0.36363636, 0.54545455, 0.72727273, # may vary 0.90909091, 0.90909091, 0.72727273, 0.54545455, 0.36363636, 0.18181818, 0. )

Plot the window and its frequency response (requires SciPy and matplotlib):

>>> from numpy.fft import fft, fftshift >>> window = np.bartlett(51) >>> plt.plot(window) <matplotlib.lines.Line2D object at 0x...> >>> plt.title('Bartlett window') Text(0.5, 1.0, 'Bartlett window') >>> plt.ylabel('Amplitude') Text(0, 0.5, 'Amplitude') >>> plt.xlabel('Sample') Text(0.5, 0, 'Sample') >>> plt.show()

>>> plt.figure() <Figure size 640x480 with 0 Axes> >>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 * np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) <matplotlib.lines.Line2D object at 0x...> >>> plt.title('Frequency response of Bartlett window') Text(0.5, 1.0, 'Frequency response of Bartlett window') >>> plt.ylabel('Magnitude dB') Text(0, 0.5, 'Magnitude dB') >>> plt.xlabel('Normalized frequency cycles per sample') Text(0.5, 0, 'Normalized frequency cycles per sample') >>> _ = plt.axis('tight') >>> plt.show()

Return a string representation of a number in the given base system.

Parameters ---------- number : int The value to convert. Positive and negative values are handled. base : int, optional Convert `number` to the `base` number system. The valid range is 2-36, the default value is 2. padding : int, optional Number of zeros padded on the left. Default is 0 (no padding).

Returns ------- out : str String representation of `number` in `base` system.

See Also -------- binary_repr : Faster version of `base_repr` for base 2.

Examples -------- >>> np.base_repr(5) '101' >>> np.base_repr(6, 5) '11' >>> np.base_repr(7, base=5, padding=3) '00012'

>>> np.base_repr(10, base=16) 'A' >>> np.base_repr(32, base=16) '20'

Return the binary representation of the input number as a string.

For negative numbers, if width is not given, a minus sign is added to the front. If width is given, the two's complement of the number is returned, with respect to that width.

In a two's-complement system negative numbers are represented by the two's complement of the absolute value. This is the most common method of representing signed integers on computers 1_. A N-bit two's-complement system can represent every integer in the range :math:`-2^N-1` to :math:`+2^N-1-1`.

Parameters ---------- num : int Only an integer decimal number can be used. width : int, optional The length of the returned string if `num` is positive, or the length of the two's complement if `num` is negative, provided that `width` is at least a sufficient number of bits for `num` to be represented in the designated form.

If the `width` value is insufficient, it will be ignored, and `num` will be returned in binary (`num` > 0) or two's complement (`num` < 0) form with its width equal to the minimum number of bits needed to represent the number in the designated form. This behavior is deprecated and will later raise an error.

.. deprecated:: 1.12.0

Returns ------- bin : str Binary representation of `num` or two's complement of `num`.

See Also -------- base_repr: Return a string representation of a number in the given base system. bin: Python's built-in binary representation generator of an integer.

Notes ----- `binary_repr` is equivalent to using `base_repr` with base 2, but about 25x faster.

References ---------- .. 1 Wikipedia, 'Two's complement', https://en.wikipedia.org/wiki/Two's_complement

Examples -------- >>> np.binary_repr(3) '11' >>> np.binary_repr(-3) '-11' >>> np.binary_repr(3, width=4) '0011'

The two's complement is returned when the input number is negative and width is specified:

>>> np.binary_repr(-3, width=3) '101' >>> np.binary_repr(-3, width=5) '11101'

bincount(x, weights=None, minlength=0)

Count number of occurrences of each value in array of non-negative ints.

The number of bins (of size 1) is one larger than the largest value in `x`. If `minlength` is specified, there will be at least this number of bins in the output array (though it will be longer if necessary, depending on the contents of `x`). Each bin gives the number of occurrences of its index value in `x`. If `weights` is specified the input array is weighted by it, i.e. if a value ``n`` is found at position ``i``, ``outn += weighti`` instead of ``outn += 1``.

Parameters ---------- x : array_like, 1 dimension, nonnegative ints Input array. weights : array_like, optional Weights, array of the same shape as `x`. minlength : int, optional A minimum number of bins for the output array.

.. versionadded:: 1.6.0

Returns ------- out : ndarray of ints The result of binning the input array. The length of `out` is equal to ``np.amax(x)+1``.

Raises ------ ValueError If the input is not 1-dimensional, or contains elements with negative values, or if `minlength` is negative. TypeError If the type of the input is float or complex.

See Also -------- histogram, digitize, unique

Examples -------- >>> np.bincount(np.arange(5)) array(1, 1, 1, 1, 1) >>> np.bincount(np.array(0, 1, 1, 3, 2, 1, 7)) array(1, 3, 1, 1, 0, 0, 0, 1)

>>> x = np.array(0, 1, 1, 3, 2, 1, 7, 23) >>> np.bincount(x).size == np.amax(x)+1 True

The input array needs to be of integer dtype, otherwise a TypeError is raised:

>>> np.bincount(np.arange(5, dtype=float)) Traceback (most recent call last): ... TypeError: Cannot cast array data from dtype('float64') to dtype('int64') according to the rule 'safe'

A possible use of ``bincount`` is to perform sums over variable-size chunks of an array, using the ``weights`` keyword.

>>> w = np.array(0.3, 0.5, 0.2, 0.7, 1., -0.6) # weights >>> x = np.array(0, 1, 1, 2, 2, 2) >>> np.bincount(x, weights=w) array( 0.3, 0.7, 1.1)

bitwise_and(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Compute the bit-wise AND of two arrays element-wise.

Computes the bit-wise AND of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``&``.

Parameters ---------- x1, x2 : array_like Only integer and boolean types are handled. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Result. This is a scalar if both `x1` and `x2` are scalars.

See Also -------- logical_and bitwise_or bitwise_xor binary_repr : Return the binary representation of the input number as a string.

Examples -------- The number 13 is represented by ``00001101``. Likewise, 17 is represented by ``00010001``. The bit-wise AND of 13 and 17 is therefore ``000000001``, or 1:

>>> np.bitwise_and(13, 17) 1

>>> np.bitwise_and(14, 13) 12 >>> np.binary_repr(12) '1100' >>> np.bitwise_and(14,3, 13) array(12, 1)

>>> np.bitwise_and(11,7, 4,25) array(0, 1) >>> np.bitwise_and(np.array(2,5,255), np.array(3,14,16)) array( 2, 4, 16) >>> np.bitwise_and(True, True, False, True) array(False, True)

invert(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Compute bit-wise inversion, or bit-wise NOT, element-wise.

Computes the bit-wise NOT of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``~``.

For signed integer inputs, the two's complement is returned. In a two's-complement system negative numbers are represented by the two's complement of the absolute value. This is the most common method of representing signed integers on computers 1_. A N-bit two's-complement system can represent every integer in the range :math:`-2^N-1` to :math:`+2^N-1-1`.

Parameters ---------- x : array_like Only integer and boolean types are handled. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Result. This is a scalar if `x` is a scalar.

See Also -------- bitwise_and, bitwise_or, bitwise_xor logical_not binary_repr : Return the binary representation of the input number as a string.

Notes ----- `bitwise_not` is an alias for `invert`:

>>> np.bitwise_not is np.invert True

References ---------- .. 1 Wikipedia, 'Two's complement', https://en.wikipedia.org/wiki/Two's_complement

Examples -------- We've seen that 13 is represented by ``00001101``. The invert or bit-wise NOT of 13 is then:

>>> x = np.invert(np.array(13, dtype=np.uint8)) >>> x 242 >>> np.binary_repr(x, width=8) '11110010'

The result depends on the bit-width:

>>> x = np.invert(np.array(13, dtype=np.uint16)) >>> x 65522 >>> np.binary_repr(x, width=16) '1111111111110010'

When using signed integer types the result is the two's complement of the result for the unsigned type:

>>> np.invert(np.array(13, dtype=np.int8)) array(-14, dtype=int8) >>> np.binary_repr(-14, width=8) '11110010'

Booleans are accepted as well:

>>> np.invert(np.array(True, False)) array(False, True)

bitwise_or(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Compute the bit-wise OR of two arrays element-wise.

Computes the bit-wise OR of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``|``.

Parameters ---------- x1, x2 : array_like Only integer and boolean types are handled. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Result. This is a scalar if both `x1` and `x2` are scalars.

See Also -------- logical_or bitwise_and bitwise_xor binary_repr : Return the binary representation of the input number as a string.

Examples -------- The number 13 has the binaray representation ``00001101``. Likewise, 16 is represented by ``00010000``. The bit-wise OR of 13 and 16 is then ``000111011``, or 29:

>>> np.bitwise_or(13, 16) 29 >>> np.binary_repr(29) '11101'

>>> np.bitwise_or(32, 2) 34 >>> np.bitwise_or(33, 4, 1) array(33, 5) >>> np.bitwise_or(33, 4, 1, 2) array(33, 6)

>>> np.bitwise_or(np.array(2, 5, 255), np.array(4, 4, 4)) array( 6, 5, 255) >>> np.array(2, 5, 255) | np.array(4, 4, 4) array( 6, 5, 255) >>> np.bitwise_or(np.array(2, 5, 255, 2147483647, dtype=np.int32), ... np.array(4, 4, 4, 2147483647, dtype=np.int32)) array( 6, 5, 255, 2147483647) >>> np.bitwise_or(True, True, False, True) array( True, True)

bitwise_xor(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Compute the bit-wise XOR of two arrays element-wise.

Computes the bit-wise XOR of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``^``.

Parameters ---------- x1, x2 : array_like Only integer and boolean types are handled. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Result. This is a scalar if both `x1` and `x2` are scalars.

See Also -------- logical_xor bitwise_and bitwise_or binary_repr : Return the binary representation of the input number as a string.

Examples -------- The number 13 is represented by ``00001101``. Likewise, 17 is represented by ``00010001``. The bit-wise XOR of 13 and 17 is therefore ``00011100``, or 28:

>>> np.bitwise_xor(13, 17) 28 >>> np.binary_repr(28) '11100'

>>> np.bitwise_xor(31, 5) 26 >>> np.bitwise_xor(31,3, 5) array(26, 6)

>>> np.bitwise_xor(31,3, 5,6) array(26, 5) >>> np.bitwise_xor(True, True, False, True) array( True, False)

Return the Blackman window.

The Blackman window is a taper formed by using the first three terms of a summation of cosines. It was designed to have close to the minimal leakage possible. It is close to optimal, only slightly worse than a Kaiser window.

Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned.

Returns ------- out : ndarray The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd).

See Also -------- bartlett, hamming, hanning, kaiser

Notes ----- The Blackman window is defined as

.. math:: w(n) = 0.42 - 0.5 \cos(2\pi n/M) + 0.08 \cos(4\pi n/M)

Most references to the Blackman window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means 'removing the foot', i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. It is known as a 'near optimal' tapering function, almost as good (by some measures) as the kaiser window.

References ---------- Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York.

Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing. Upper Saddle River, NJ: Prentice-Hall, 1999, pp. 468-471.

Examples -------- >>> import matplotlib.pyplot as plt >>> np.blackman(12) array(-1.38777878e-17, 3.26064346e-02, 1.59903635e-01, # may vary 4.14397981e-01, 7.36045180e-01, 9.67046769e-01, 9.67046769e-01, 7.36045180e-01, 4.14397981e-01, 1.59903635e-01, 3.26064346e-02, -1.38777878e-17)

Plot the window and the frequency response:

>>> from numpy.fft import fft, fftshift >>> window = np.blackman(51) >>> plt.plot(window) <matplotlib.lines.Line2D object at 0x...> >>> plt.title('Blackman window') Text(0.5, 1.0, 'Blackman window') >>> plt.ylabel('Amplitude') Text(0, 0.5, 'Amplitude') >>> plt.xlabel('Sample') Text(0.5, 0, 'Sample') >>> plt.show()

>>> plt.figure() <Figure size 640x480 with 0 Axes> >>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 * np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) <matplotlib.lines.Line2D object at 0x...> >>> plt.title('Frequency response of Blackman window') Text(0.5, 1.0, 'Frequency response of Blackman window') >>> plt.ylabel('Magnitude dB') Text(0, 0.5, 'Magnitude dB') >>> plt.xlabel('Normalized frequency cycles per sample') Text(0.5, 0, 'Normalized frequency cycles per sample') >>> _ = plt.axis('tight') >>> plt.show()

Assemble an nd-array from nested lists of blocks.

Blocks in the innermost lists are concatenated (see `concatenate`) along the last dimension (-1), then these are concatenated along the second-last dimension (-2), and so on until the outermost list is reached.

Blocks can be of any dimension, but will not be broadcasted using the normal rules. Instead, leading axes of size 1 are inserted, to make ``block.ndim`` the same for all blocks. This is primarily useful for working with scalars, and means that code like ``np.block(v, 1)`` is valid, where ``v.ndim == 1``.

When the nested list is two levels deep, this allows block matrices to be constructed from their components.

.. versionadded:: 1.13.0

Parameters ---------- arrays : nested list of array_like or scalars (but not tuples) If passed a single ndarray or scalar (a nested list of depth 0), this is returned unmodified (and not copied).

Elements shapes must match along the appropriate axes (without broadcasting), but leading 1s will be prepended to the shape as necessary to make the dimensions match.

Returns ------- block_array : ndarray The array assembled from the given blocks.

The dimensionality of the output is equal to the greatest of: * the dimensionality of all the inputs * the depth to which the input list is nested

Raises ------ ValueError * If list depths are mismatched - for instance, ``[a, b], c`` is illegal, and should be spelt ``[a, b], [c]`` * If lists are empty - for instance, ``[a, b], []``

See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. vstack : Stack arrays in sequence vertically (row wise). hstack : Stack arrays in sequence horizontally (column wise). dstack : Stack arrays in sequence depth wise (along third axis). column_stack : Stack 1-D arrays as columns into a 2-D array. vsplit : Split an array into multiple sub-arrays vertically (row-wise).

Notes -----

When called with only scalars, ``np.block`` is equivalent to an ndarray call. So ``np.block([1, 2], [3, 4])`` is equivalent to ``np.array([1, 2], [3, 4])``.

This function does not enforce that the blocks lie on a fixed grid. ``np.block([a, b], [c, d])`` is not restricted to arrays of the form::

AAAbb AAAbb cccDD

But is also allowed to produce, for some ``a, b, c, d``::

AAAbb AAAbb cDDDD

Since concatenation happens along the last axis first, `block` is _not_ capable of producing the following directly::

AAAbb cccbb cccDD

Matlab's 'square bracket stacking', ``A, B, ...; p, q, ...``, is equivalent to ``np.block([A, B, ...], [p, q, ...])``.

Examples -------- The most common use of this function is to build a block matrix

>>> A = np.eye(2) * 2 >>> B = np.eye(3) * 3 >>> np.block( ... [A, np.zeros((2, 3))], ... [np.ones((3, 2)), B ] ... ) array([2., 0., 0., 0., 0.], [0., 2., 0., 0., 0.], [1., 1., 3., 0., 0.], [1., 1., 0., 3., 0.], [1., 1., 0., 0., 3.])

With a list of depth 1, `block` can be used as `hstack`

>>> np.block(1, 2, 3) # hstack(1, 2, 3) array(1, 2, 3)

>>> a = np.array(1, 2, 3) >>> b = np.array(2, 3, 4) >>> np.block(a, b, 10) # hstack(a, b, 10) array( 1, 2, 3, 2, 3, 4, 10)

>>> A = np.ones((2, 2), int) >>> B = 2 * A >>> np.block(A, B) # hstack(A, B) array([1, 1, 2, 2], [1, 1, 2, 2])

With a list of depth 2, `block` can be used in place of `vstack`:

>>> a = np.array(1, 2, 3) >>> b = np.array(2, 3, 4) >>> np.block([a], [b]) # vstack(a, b) array([1, 2, 3], [2, 3, 4])

>>> A = np.ones((2, 2), int) >>> B = 2 * A >>> np.block([A], [B]) # vstack(A, B) array([1, 1], [1, 1], [2, 2], [2, 2])

It can also be used in places of `atleast_1d` and `atleast_2d`

>>> a = np.array(0) >>> b = np.array(1) >>> np.block(a) # atleast_1d(a) array(0) >>> np.block(b) # atleast_1d(b) array(1)

>>> np.block([a]) # atleast_2d(a) array([0]) >>> np.block([b]) # atleast_2d(b) array([1])

Build a matrix object from a string, nested sequence, or array.

Parameters ---------- obj : str or array_like Input data. If a string, variables in the current scope may be referenced by name. ldict : dict, optional A dictionary that replaces local operands in current frame. Ignored if `obj` is not a string or `gdict` is None. gdict : dict, optional A dictionary that replaces global operands in current frame. Ignored if `obj` is not a string.

Returns ------- out : matrix Returns a matrix object, which is a specialized 2-D array.

See Also -------- block : A generalization of this function for N-d arrays, that returns normal ndarrays.

Examples -------- >>> A = np.mat('1 1; 1 1') >>> B = np.mat('2 2; 2 2') >>> C = np.mat('3 4; 5 6') >>> D = np.mat('7 8; 9 0')

All the following expressions construct the same block matrix:

>>> np.bmat([A, B], [C, D]) matrix([1, 1, 2, 2], [1, 1, 2, 2], [3, 4, 7, 8], [5, 6, 9, 0]) >>> np.bmat(np.r_np.c_[A, B], np.c_[C, D]) matrix([1, 1, 2, 2], [1, 1, 2, 2], [3, 4, 7, 8], [5, 6, 9, 0]) >>> np.bmat('A,B; C,D') matrix([1, 1, 2, 2], [1, 1, 2, 2], [3, 4, 7, 8], [5, 6, 9, 0])

Broadcast any number of arrays against each other.

Parameters ---------- `*args` : array_likes The arrays to broadcast.

subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned arrays will be forced to be a base-class array (default).

Returns ------- broadcasted : list of arrays These arrays are views on the original arrays. They are typically not contiguous. Furthermore, more than one element of a broadcasted array may refer to a single memory location. If you need to write to the arrays, make copies first. While you can set the ``writable`` flag True, writing to a single output value may end up changing more than one location in the output array.

.. deprecated:: 1.17 The output is currently marked so that if written to, a deprecation warning will be emitted. A future version will set the ``writable`` flag False so writing to it will raise an error.

Examples -------- >>> x = np.array([1,2,3]) >>> y = np.array([4],[5]) >>> np.broadcast_arrays(x, y) array([[1, 2, 3], [1, 2, 3]]), array([[4, 4, 4], [5, 5, 5]])

Here is a useful idiom for getting contiguous copies instead of non-contiguous views.

>>> np.array(a) for a in np.broadcast_arrays(x, y) array([[1, 2, 3], [1, 2, 3]]), array([[4, 4, 4], [5, 5, 5]])

Broadcast an array to a new shape.

Parameters ---------- array : array_like The array to broadcast. shape : tuple The shape of the desired array. subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (default).

Returns ------- broadcast : array A readonly view on the original array with the given shape. It is typically not contiguous. Furthermore, more than one element of a broadcasted array may refer to a single memory location.

Raises ------ ValueError If the array is not compatible with the new shape according to NumPy's broadcasting rules.

Notes ----- .. versionadded:: 1.10.0

Examples -------- >>> x = np.array(1, 2, 3) >>> np.broadcast_to(x, (3, 3)) array([1, 2, 3], [1, 2, 3], [1, 2, 3])

busday_count(begindates, enddates, weekmask='1111100', holidays=, busdaycal=None, out=None)

Counts the number of valid days between `begindates` and `enddates`, not including the day of `enddates`.

If ``enddates`` specifies a date value that is earlier than the corresponding ``begindates`` date value, the count will be negative.

.. versionadded:: 1.7.0

Parameters ---------- begindates : array_like of datetime64D The array of the first dates for counting. enddates : array_like of datetime64D The array of the end dates for counting, which are excluded from the count themselves. weekmask : str or array_like of bool, optional A seven-element array indicating which of Monday through Sunday are valid days. May be specified as a length-seven list or array, like 1,1,1,1,1,0,0; a length-seven string, like '1111100'; or a string like 'Mon Tue Wed Thu Fri', made up of 3-character abbreviations for weekdays, optionally separated by white space. Valid abbreviations are: Mon Tue Wed Thu Fri Sat Sun holidays : array_like of datetime64D, optional An array of dates to consider as invalid dates. They may be specified in any order, and NaT (not-a-time) dates are ignored. This list is saved in a normalized form that is suited for fast calculations of valid days. busdaycal : busdaycalendar, optional A `busdaycalendar` object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided. out : array of int, optional If provided, this array is filled with the result.

Returns ------- out : array of int An array with a shape from broadcasting ``begindates`` and ``enddates`` together, containing the number of valid days between the begin and end dates.

See Also -------- busdaycalendar: An object that specifies a custom set of valid days. is_busday : Returns a boolean array indicating valid days. busday_offset : Applies an offset counted in valid days.

Examples -------- >>> # Number of weekdays in January 2011 ... np.busday_count('2011-01', '2011-02') 21 >>> # Number of weekdays in 2011 >>> np.busday_count('2011', '2012') 260 >>> # Number of Saturdays in 2011 ... np.busday_count('2011', '2012', weekmask='Sat') 53

busday_offset(dates, offsets, roll='raise', weekmask='1111100', holidays=None, busdaycal=None, out=None)

First adjusts the date to fall on a valid day according to the ``roll`` rule, then applies offsets to the given dates counted in valid days.

.. versionadded:: 1.7.0

Parameters ---------- dates : array_like of datetime64D The array of dates to process. offsets : array_like of int The array of offsets, which is broadcast with ``dates``. roll : 'raise', 'nat', 'forward', 'following', 'backward', 'preceding', 'modifiedfollowing', 'modifiedpreceding', optional How to treat dates that do not fall on a valid day. The default is 'raise'.

* 'raise' means to raise an exception for an invalid day. * 'nat' means to return a NaT (not-a-time) for an invalid day. * 'forward' and 'following' mean to take the first valid day later in time. * 'backward' and 'preceding' mean to take the first valid day earlier in time. * 'modifiedfollowing' means to take the first valid day later in time unless it is across a Month boundary, in which case to take the first valid day earlier in time. * 'modifiedpreceding' means to take the first valid day earlier in time unless it is across a Month boundary, in which case to take the first valid day later in time. weekmask : str or array_like of bool, optional A seven-element array indicating which of Monday through Sunday are valid days. May be specified as a length-seven list or array, like 1,1,1,1,1,0,0; a length-seven string, like '1111100'; or a string like 'Mon Tue Wed Thu Fri', made up of 3-character abbreviations for weekdays, optionally separated by white space. Valid abbreviations are: Mon Tue Wed Thu Fri Sat Sun holidays : array_like of datetime64D, optional An array of dates to consider as invalid dates. They may be specified in any order, and NaT (not-a-time) dates are ignored. This list is saved in a normalized form that is suited for fast calculations of valid days. busdaycal : busdaycalendar, optional A `busdaycalendar` object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided. out : array of datetime64D, optional If provided, this array is filled with the result.

Returns ------- out : array of datetime64D An array with a shape from broadcasting ``dates`` and ``offsets`` together, containing the dates with offsets applied.

See Also -------- busdaycalendar: An object that specifies a custom set of valid days. is_busday : Returns a boolean array indicating valid days. busday_count : Counts how many valid days are in a half-open date range.

Examples -------- >>> # First business day in October 2011 (not accounting for holidays) ... np.busday_offset('2011-10', 0, roll='forward') numpy.datetime64('2011-10-03') >>> # Last business day in February 2012 (not accounting for holidays) ... np.busday_offset('2012-03', -1, roll='forward') numpy.datetime64('2012-02-29') >>> # Third Wednesday in January 2011 ... np.busday_offset('2011-01', 2, roll='forward', weekmask='Wed') numpy.datetime64('2011-01-19') >>> # 2012 Mother's Day in Canada and the U.S. ... np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun') numpy.datetime64('2012-05-13')

>>> # First business day on or after a date ... np.busday_offset('2011-03-20', 0, roll='forward') numpy.datetime64('2011-03-21') >>> np.busday_offset('2011-03-22', 0, roll='forward') numpy.datetime64('2011-03-22') >>> # First business day after a date ... np.busday_offset('2011-03-20', 1, roll='backward') numpy.datetime64('2011-03-21') >>> np.busday_offset('2011-03-22', 1, roll='backward') numpy.datetime64('2011-03-23')

Returns pointers to the end-points of an array.

Parameters ---------- a : ndarray Input array. It must conform to the Python-side of the array interface.

Returns ------- (low, high) : tuple of 2 integers The first integer is the first byte of the array, the second integer is just past the last byte of the array. If `a` is not contiguous it will not use every byte between the (`low`, `high`) values.

Examples -------- >>> I = np.eye(2, dtype='f'); I.dtype dtype('float32') >>> low, high = np.byte_bounds(I) >>> high - low == I.size*I.itemsize True >>> I = np.eye(2); I.dtype dtype('float64') >>> low, high = np.byte_bounds(I) >>> high - low == I.size*I.itemsize True

can_cast(from_, to, casting='safe')

Returns True if cast between data types can occur according to the casting rule. If from is a scalar or array scalar, also returns True if the scalar value can be cast without overflow or truncation to an integer.

Parameters ---------- from_ : dtype, dtype specifier, scalar, or array Data type, scalar, or array to cast from. to : dtype or dtype specifier Data type to cast to. casting : 'no', 'equiv', 'safe', 'same_kind', 'unsafe', optional Controls what kind of data casting may occur.

* 'no' means the data types should not be cast at all. * 'equiv' means only byte-order changes are allowed. * 'safe' means only casts which can preserve values are allowed. * 'same_kind' means only safe casts or casts within a kind, like float64 to float32, are allowed. * 'unsafe' means any data conversions may be done.

Returns ------- out : bool True if cast can occur according to the casting rule.

Notes ----- .. versionchanged:: 1.17.0 Casting between a simple data type and a structured one is possible only for 'unsafe' casting. Casting to multiple fields is allowed, but casting from multiple fields is not.

.. versionchanged:: 1.9.0 Casting from numeric to string types in 'safe' casting mode requires that the string dtype length is long enough to store the maximum integer/float value converted.

See also -------- dtype, result_type

Examples -------- Basic examples

>>> np.can_cast(np.int32, np.int64) True >>> np.can_cast(np.float64, complex) True >>> np.can_cast(complex, float) False

>>> np.can_cast('i8', 'f8') True >>> np.can_cast('i8', 'f4') False >>> np.can_cast('i4', 'S4') False

Casting scalars

>>> np.can_cast(100, 'i1') True >>> np.can_cast(150, 'i1') False >>> np.can_cast(150, 'u1') True

>>> np.can_cast(3.5e100, np.float32) False >>> np.can_cast(1000.0, np.float32) True

Array scalar checks the value, array does not

>>> np.can_cast(np.array(1000.0), np.float32) True >>> np.can_cast(np.array(1000.0), np.float32) False

Using the casting rules

>>> np.can_cast('i8', 'i8', 'no') True >>> np.can_cast('<i8', '>i8', 'no') False

>>> np.can_cast('<i8', '>i8', 'equiv') True >>> np.can_cast('<i4', '>i8', 'equiv') False

>>> np.can_cast('<i4', '>i8', 'safe') True >>> np.can_cast('<i8', '>i4', 'safe') False

>>> np.can_cast('<i8', '>i4', 'same_kind') True >>> np.can_cast('<i8', '>u4', 'same_kind') False

>>> np.can_cast('<i8', '>u4', 'unsafe') True

cbrt(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Return the cube-root of an array, element-wise.

.. versionadded:: 1.10.0

Parameters ---------- x : array_like The values whose cube-roots are required. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray An array of the same shape as `x`, containing the cube cube-root of each element in `x`. If `out` was provided, `y` is a reference to it. This is a scalar if `x` is a scalar.

Examples -------- >>> np.cbrt(1,8,27) array( 1., 2., 3.)

ceil(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Return the ceiling of the input, element-wise.

The ceil of the scalar `x` is the smallest integer `i`, such that `i >= x`. It is often denoted as :math:`\lceil x \rceil`.

Parameters ---------- x : array_like Input data. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray or scalar The ceiling of each element in `x`, with `float` dtype. This is a scalar if `x` is a scalar.

See Also -------- floor, trunc, rint

Examples -------- >>> a = np.array(-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0) >>> np.ceil(a) array(-1., -1., -0., 1., 2., 2., 2.)

Construct an array from an index array and a set of arrays to choose from.

First of all, if confused or uncertain, definitely look at the Examples - in its full generality, this function is less simple than it might seem from the following code description (below ndi = `numpy.lib.index_tricks`):

``np.choose(a,c) == np.array(c[a[I]][I] for I in ndi.ndindex(a.shape))``.

But this omits some subtleties. Here is a fully general summary:

Given an 'index' array (`a`) of integers and a sequence of `n` arrays (`choices`), `a` and each choice array are first broadcast, as necessary, to arrays of a common shape; calling these *Ba* and *Bchoicesi, i = 0,...,n-1* we have that, necessarily, ``Ba.shape == Bchoicesi.shape`` for each `i`. Then, a new array with shape ``Ba.shape`` is created as follows:

* if ``mode=raise`` (the default), then, first of all, each element of `a` (and thus `Ba`) must be in the range `0, n-1`; now, suppose that `i` (in that range) is the value at the `(j0, j1, ..., jm)` position in `Ba` - then the value at the same position in the new array is the value in `Bchoicesi` at that same position;

* if ``mode=wrap``, values in `a` (and thus `Ba`) may be any (signed) integer; modular arithmetic is used to map integers outside the range `0, n-1` back into that range; and then the new array is constructed as above;

* if ``mode=clip``, values in `a` (and thus `Ba`) may be any (signed) integer; negative integers are mapped to 0; values greater than `n-1` are mapped to `n-1`; and then the new array is constructed as above.

Parameters ---------- a : int array This array must contain integers in `0, n-1`, where `n` is the number of choices, unless ``mode=wrap`` or ``mode=clip``, in which cases any integers are permissible. choices : sequence of arrays Choice arrays. `a` and all of the choices must be broadcastable to the same shape. If `choices` is itself an array (not recommended), then its outermost dimension (i.e., the one corresponding to ``choices.shape0``) is taken as defining the 'sequence'. out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. Note that `out` is always buffered if `mode='raise'`; use other modes for better performance. mode : 'raise' (default), 'wrap', 'clip', optional Specifies how indices outside `0, n-1` will be treated:

* 'raise' : an exception is raised * 'wrap' : value becomes value mod `n` * 'clip' : values < 0 are mapped to 0, values > n-1 are mapped to n-1

Returns ------- merged_array : array The merged result.

Raises ------ ValueError: shape mismatch If `a` and each choice array are not all broadcastable to the same shape.

See Also -------- ndarray.choose : equivalent method numpy.take_along_axis : Preferable if `choices` is an array

Notes ----- To reduce the chance of misinterpretation, even though the following 'abuse' is nominally supported, `choices` should neither be, nor be thought of as, a single array, i.e., the outermost sequence-like container should be either a list or a tuple.

Examples --------

>>> choices = [0, 1, 2, 3], [10, 11, 12, 13], ... [20, 21, 22, 23], [30, 31, 32, 33] >>> np.choose(2, 3, 1, 0, choices ... # the first element of the result will be the first element of the ... # third (2+1) 'array' in choices, namely, 20; the second element ... # will be the second element of the fourth (3+1) choice array, i.e., ... # 31, etc. ... ) array(20, 31, 12, 3) >>> np.choose(2, 4, 1, 0, choices, mode='clip') # 4 goes to 3 (4-1) array(20, 31, 12, 3) >>> # because there are 4 choice arrays >>> np.choose(2, 4, 1, 0, choices, mode='wrap') # 4 goes to (4 mod 4) array(20, 1, 12, 3) >>> # i.e., 0

A couple examples illustrating how choose broadcasts:

>>> a = [1, 0, 1], [0, 1, 0], [1, 0, 1] >>> choices = -10, 10 >>> np.choose(a, choices) array([ 10, -10, 10], [-10, 10, -10], [ 10, -10, 10])

>>> # With thanks to Anne Archibald >>> a = np.array(0, 1).reshape((2,1,1)) >>> c1 = np.array(1, 2, 3).reshape((1,3,1)) >>> c2 = np.array(-1, -2, -3, -4, -5).reshape((1,1,5)) >>> np.choose(a, (c1, c2)) # result is 2x3x5, res0,:,:=c1, res1,:,:=c2 array([[ 1, 1, 1, 1, 1], [ 2, 2, 2, 2, 2], [ 3, 3, 3, 3, 3]], [[-1, -2, -3, -4, -5], [-1, -2, -3, -4, -5], [-1, -2, -3, -4, -5]])

Clip (limit) the values in an array.

Given an interval, values outside the interval are clipped to the interval edges. For example, if an interval of ``0, 1`` is specified, values smaller than 0 become 0, and values larger than 1 become 1.

Equivalent to but faster than ``np.minimum(a_max, np.maximum(a, a_min))``.

No check is performed to ensure ``a_min < a_max``.

Parameters ---------- a : array_like Array containing elements to clip. a_min : scalar or array_like or None Minimum value. If None, clipping is not performed on lower interval edge. Not more than one of `a_min` and `a_max` may be None. a_max : scalar or array_like or None Maximum value. If None, clipping is not performed on upper interval edge. Not more than one of `a_min` and `a_max` may be None. If `a_min` or `a_max` are array_like, then the three arrays will be broadcasted to match their shapes. out : ndarray, optional The results will be placed in this array. It may be the input array for in-place clipping. `out` must be of the right shape to hold the output. Its type is preserved. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

.. versionadded:: 1.17.0

Returns ------- clipped_array : ndarray An array with the elements of `a`, but where values < `a_min` are replaced with `a_min`, and those > `a_max` with `a_max`.

See Also -------- ufuncs-output-type

Examples -------- >>> a = np.arange(10) >>> np.clip(a, 1, 8) array(1, 1, 2, 3, 4, 5, 6, 7, 8, 8) >>> a array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) >>> np.clip(a, 3, 6, out=a) array(3, 3, 3, 3, 4, 5, 6, 6, 6, 6) >>> a = np.arange(10) >>> a array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) >>> np.clip(a, 3, 4, 1, 1, 1, 4, 4, 4, 4, 4, 8) array(3, 4, 2, 3, 4, 5, 6, 7, 8, 8)

Stack 1-D arrays as columns into a 2-D array.

Take a sequence of 1-D arrays and stack them as columns to make a single 2-D array. 2-D arrays are stacked as-is, just like with `hstack`. 1-D arrays are turned into 2-D columns first.

Parameters ---------- tup : sequence of 1-D or 2-D arrays. Arrays to stack. All of them must have the same first dimension.

Returns ------- stacked : 2-D array The array formed by stacking the given arrays.

See Also -------- stack, hstack, vstack, concatenate

Examples -------- >>> a = np.array((1,2,3)) >>> b = np.array((2,3,4)) >>> np.column_stack((a,b)) array([1, 2], [2, 3], [3, 4])

Return a scalar type which is common to the input arrays.

The return type will always be an inexact (i.e. floating point) scalar type, even if all the arrays are integer arrays. If one of the inputs is an integer array, the minimum precision type that is returned is a 64-bit floating point dtype.

All input arrays except int64 and uint64 can be safely cast to the returned dtype without loss of information.

Parameters ---------- array1, array2, ... : ndarrays Input arrays.

Returns ------- out : data type code Data type code.

See Also -------- dtype, mintypecode

Examples -------- >>> np.common_type(np.arange(2, dtype=np.float32)) <class 'numpy.float32'> >>> np.common_type(np.arange(2, dtype=np.float32), np.arange(2)) <class 'numpy.float64'> >>> np.common_type(np.arange(4), np.array(45, 6.j), np.array(45.0)) <class 'numpy.complex128'>

compare_chararrays(a, b, cmp_op, rstrip)

Performs element-wise comparison of two string arrays using the comparison operator specified by `cmp_op`.

Parameters ---------- a, b : array_like Arrays to be compared. cmp_op : '<', '<=', '==', '>=', '>', '!=' Type of comparison. rstrip : Boolean If True, the spaces at the end of Strings are removed before the comparison.

Returns ------- out : ndarray The output array of type Boolean with the same shape as a and b.

Raises ------ ValueError If `cmp_op` is not valid. TypeError If at least one of `a` or `b` is a non-string array

Examples -------- >>> a = np.array('a', 'b', 'cde') >>> b = np.array('a', 'a', 'dec') >>> np.compare_chararrays(a, b, '>', True) array(False, True, False)

Return selected slices of an array along given axis.

When working along a given axis, a slice along that axis is returned in `output` for each index where `condition` evaluates to True. When working on a 1-D array, `compress` is equivalent to `extract`.

Parameters ---------- condition : 1-D array of bools Array that selects which entries to return. If len(condition) is less than the size of `a` along the given axis, then output is truncated to the length of the condition array. a : array_like Array from which to extract a part. axis : int, optional Axis along which to take slices. If None (default), work on the flattened array. out : ndarray, optional Output array. Its type is preserved and it must be of the right shape to hold the output.

Returns ------- compressed_array : ndarray A copy of `a` without the slices along axis for which `condition` is false.

See Also -------- take, choose, diag, diagonal, select ndarray.compress : Equivalent method in ndarray np.extract: Equivalent method when working on 1-D arrays ufuncs-output-type

Examples -------- >>> a = np.array([1, 2], [3, 4], [5, 6]) >>> a array([1, 2], [3, 4], [5, 6]) >>> np.compress(0, 1, a, axis=0) array([3, 4]) >>> np.compress(False, True, True, a, axis=0) array([3, 4], [5, 6]) >>> np.compress(False, True, a, axis=1) array([2], [4], [6])

Working on the flattened array does not return slices along an axis but selects elements.

>>> np.compress(False, True, a) array(2)

concatenate((a1, a2, ...), axis=0, out=None)

Join a sequence of arrays along an existing axis.

Parameters ---------- a1, a2, ... : sequence of array_like The arrays must have the same shape, except in the dimension corresponding to `axis` (the first, by default). axis : int, optional The axis along which the arrays will be joined. If axis is None, arrays are flattened before use. Default is 0. out : ndarray, optional If provided, the destination to place the result. The shape must be correct, matching that of what concatenate would have returned if no out argument were specified.

Returns ------- res : ndarray The concatenated array.

See Also -------- ma.concatenate : Concatenate function that preserves input masks. array_split : Split an array into multiple sub-arrays of equal or near-equal size. split : Split array into a list of multiple sub-arrays of equal size. hsplit : Split array into multiple sub-arrays horizontally (column wise). vsplit : Split array into multiple sub-arrays vertically (row wise). dsplit : Split array into multiple sub-arrays along the 3rd axis (depth). stack : Stack a sequence of arrays along a new axis. block : Assemble arrays from blocks. hstack : Stack arrays in sequence horizontally (column wise). vstack : Stack arrays in sequence vertically (row wise). dstack : Stack arrays in sequence depth wise (along third dimension). column_stack : Stack 1-D arrays as columns into a 2-D array.

Notes ----- When one or more of the arrays to be concatenated is a MaskedArray, this function will return a MaskedArray object instead of an ndarray, but the input masks are *not* preserved. In cases where a MaskedArray is expected as input, use the ma.concatenate function from the masked array module instead.

Examples -------- >>> a = np.array([1, 2], [3, 4]) >>> b = np.array([5, 6]) >>> np.concatenate((a, b), axis=0) array([1, 2], [3, 4], [5, 6]) >>> np.concatenate((a, b.T), axis=1) array([1, 2, 5], [3, 4, 6]) >>> np.concatenate((a, b), axis=None) array(1, 2, 3, 4, 5, 6)

This function will not preserve masking of MaskedArray inputs.

>>> a = np.ma.arange(3) >>> a1 = np.ma.masked >>> b = np.arange(2, 5) >>> a masked_array(data=0, --, 2, mask=False, True, False, fill_value=999999) >>> b array(2, 3, 4) >>> np.concatenate(a, b) masked_array(data=0, 1, 2, 2, 3, 4, mask=False, fill_value=999999) >>> np.ma.concatenate(a, b) masked_array(data=0, --, 2, 2, 3, 4, mask=False, True, False, False, False, False, fill_value=999999)

conjugate(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Return the complex conjugate, element-wise.

The complex conjugate of a complex number is obtained by changing the sign of its imaginary part.

Parameters ---------- x : array_like Input value. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray The complex conjugate of `x`, with same dtype as `y`. This is a scalar if `x` is a scalar.

Notes ----- `conj` is an alias for `conjugate`:

>>> np.conj is np.conjugate True

Examples -------- >>> np.conjugate(1+2j) (1-2j)

>>> x = np.eye(2) + 1j * np.eye(2) >>> np.conjugate(x) array([ 1.-1.j, 0.-0.j], [ 0.-0.j, 1.-1.j])

conjugate(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Return the complex conjugate, element-wise.

The complex conjugate of a complex number is obtained by changing the sign of its imaginary part.

Parameters ---------- x : array_like Input value. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray The complex conjugate of `x`, with same dtype as `y`. This is a scalar if `x` is a scalar.

Notes ----- `conj` is an alias for `conjugate`:

>>> np.conj is np.conjugate True

Examples -------- >>> np.conjugate(1+2j) (1-2j)

>>> x = np.eye(2) + 1j * np.eye(2) >>> np.conjugate(x) array([ 1.-1.j, 0.-0.j], [ 0.-0.j, 1.-1.j])

Returns the discrete, linear convolution of two one-dimensional sequences.

The convolution operator is often seen in signal processing, where it models the effect of a linear time-invariant system on a signal 1_. In probability theory, the sum of two independent random variables is distributed according to the convolution of their individual distributions.

If `v` is longer than `a`, the arrays are swapped before computation.

Parameters ---------- a : (N,) array_like First one-dimensional input array. v : (M,) array_like Second one-dimensional input array. mode : 'full', 'valid', 'same', optional 'full': By default, mode is 'full'. This returns the convolution at each point of overlap, with an output shape of (N+M-1,). At the end-points of the convolution, the signals do not overlap completely, and boundary effects may be seen.

'same': Mode 'same' returns output of length ``max(M, N)``. Boundary effects are still visible.

'valid': Mode 'valid' returns output of length ``max(M, N) - min(M, N) + 1``. The convolution product is only given for points where the signals overlap completely. Values outside the signal boundary have no effect.

Returns ------- out : ndarray Discrete, linear convolution of `a` and `v`.

See Also -------- scipy.signal.fftconvolve : Convolve two arrays using the Fast Fourier Transform. scipy.linalg.toeplitz : Used to construct the convolution operator. polymul : Polynomial multiplication. Same output as convolve, but also accepts poly1d objects as input.

Notes ----- The discrete convolution operation is defined as

.. math:: (a * v)n = \sum_= -\infty^\infty am vn - m

It can be shown that a convolution :math:`x(t) * y(t)` in time/space is equivalent to the multiplication :math:`X(f) Y(f)` in the Fourier domain, after appropriate padding (padding is necessary to prevent circular convolution). Since multiplication is more efficient (faster) than convolution, the function `scipy.signal.fftconvolve` exploits the FFT to calculate the convolution of large data-sets.

References ---------- .. 1 Wikipedia, 'Convolution', https://en.wikipedia.org/wiki/Convolution

Examples -------- Note how the convolution operator flips the second array before 'sliding' the two across one another:

>>> np.convolve(1, 2, 3, 0, 1, 0.5) array(0. , 1. , 2.5, 4. , 1.5)

Only return the middle values of the convolution. Contains boundary effects, where zeros are taken into account:

>>> np.convolve(1,2,3,0,1,0.5, 'same') array(1. , 2.5, 4. )

The two arrays are of the same length, so there is only one position where they completely overlap:

>>> np.convolve(1,2,3,0,1,0.5, 'valid') array(2.5)

Return an array copy of the given object.

Parameters ---------- a : array_like Input data. order : 'C', 'F', 'A', 'K', optional Controls the memory layout of the copy. 'C' means C-order, 'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous, 'C' otherwise. 'K' means match the layout of `a` as closely as possible. (Note that this function and :meth:`ndarray.copy` are very similar, but have different default values for their order= arguments.) subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (defaults to False).

.. versionadded:: 1.19.0

Returns ------- arr : ndarray Array interpretation of `a`.

See Also -------- ndarray.copy : Preferred method for creating an array copy

Notes ----- This is equivalent to:

>>> np.array(a, copy=True) #doctest: +SKIP

Examples -------- Create an array x, with a reference y and a copy z:

>>> x = np.array(1, 2, 3) >>> y = x >>> z = np.copy(x)

Note that, when we modify x, y changes, but not z:

>>> x0 = 10 >>> x0 == y0 True >>> x0 == z0 False

Note that np.copy is a shallow copy and will not copy object elements within arrays. This is mainly important for arrays containing Python objects. The new array will contain the same object which may lead to surprises if that object can be modified (is mutable):

>>> a = np.array(1, 'm', [2, 3, 4], dtype=object) >>> b = np.copy(a) >>> b20 = 10 >>> a array(1, 'm', list([10, 3, 4]), dtype=object)

To ensure all elements within an ``object`` array are copied, use `copy.deepcopy`:

>>> import copy >>> a = np.array(1, 'm', [2, 3, 4], dtype=object) >>> c = copy.deepcopy(a) >>> c20 = 10 >>> c array(1, 'm', list([10, 3, 4]), dtype=object) >>> a array(1, 'm', list([2, 3, 4]), dtype=object)

copysign(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Change the sign of x1 to that of x2, element-wise.

If `x2` is a scalar, its sign will be copied to all elements of `x1`.

Parameters ---------- x1 : array_like Values to change the sign of. x2 : array_like The sign of `x2` is copied to `x1`. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar The values of `x1` with the sign of `x2`. This is a scalar if both `x1` and `x2` are scalars.

Examples -------- >>> np.copysign(1.3, -1) -1.3 >>> 1/np.copysign(0, 1) inf >>> 1/np.copysign(0, -1) -inf

>>> np.copysign(-1, 0, 1, -1.1) array(-1., -0., -1.) >>> np.copysign(-1, 0, 1, np.arange(3)-1) array(-1., 0., 1.)

copyto(dst, src, casting='same_kind', where=True)

Copies values from one array to another, broadcasting as necessary.

Raises a TypeError if the `casting` rule is violated, and if `where` is provided, it selects which elements to copy.

.. versionadded:: 1.7.0

Parameters ---------- dst : ndarray The array into which values are copied. src : array_like The array from which values are copied. casting : 'no', 'equiv', 'safe', 'same_kind', 'unsafe', optional Controls what kind of data casting may occur when copying.

* 'no' means the data types should not be cast at all. * 'equiv' means only byte-order changes are allowed. * 'safe' means only casts which can preserve values are allowed. * 'same_kind' means only safe casts or casts within a kind, like float64 to float32, are allowed. * 'unsafe' means any data conversions may be done. where : array_like of bool, optional A boolean array which is broadcasted to match the dimensions of `dst`, and selects elements to copy from `src` to `dst` wherever it contains the value True.

Return Pearson product-moment correlation coefficients.

Please refer to the documentation for `cov` for more detail. The relationship between the correlation coefficient matrix, `R`, and the covariance matrix, `C`, is

.. math:: R_j = \frac C_{ij

}

\sqrt{ C_{ii * C_jj

}

}

The values of `R` are between -1 and 1, inclusive.

Parameters ---------- x : array_like A 1-D or 2-D array containing multiple variables and observations. Each row of `x` represents a variable, and each column a single observation of all those variables. Also see `rowvar` below. y : array_like, optional An additional set of variables and observations. `y` has the same shape as `x`. rowvar : bool, optional If `rowvar` is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations. bias : _NoValue, optional Has no effect, do not use.

.. deprecated:: 1.10.0 ddof : _NoValue, optional Has no effect, do not use.

.. deprecated:: 1.10.0

Returns ------- R : ndarray The correlation coefficient matrix of the variables.

See Also -------- cov : Covariance matrix

Notes ----- Due to floating point rounding the resulting array may not be Hermitian, the diagonal elements may not be 1, and the elements may not satisfy the inequality abs(a) <= 1. The real and imaginary parts are clipped to the interval -1, 1 in an attempt to improve on that situation but is not much help in the complex case.

This function accepts but discards arguments `bias` and `ddof`. This is for backwards compatibility with previous versions of this function. These arguments had no effect on the return values of the function and can be safely ignored in this and previous versions of numpy.

Cross-correlation of two 1-dimensional sequences.

This function computes the correlation as generally defined in signal processing texts::

c_avk = sum_n an+k * conj(vn)

with a and v sequences being zero-padded where necessary and conj being the conjugate.

Parameters ---------- a, v : array_like Input sequences. mode : 'valid', 'same', 'full', optional Refer to the `convolve` docstring. Note that the default is 'valid', unlike `convolve`, which uses 'full'. old_behavior : bool `old_behavior` was removed in NumPy 1.10. If you need the old behavior, use `multiarray.correlate`.

Returns ------- out : ndarray Discrete cross-correlation of `a` and `v`.

See Also -------- convolve : Discrete, linear convolution of two one-dimensional sequences. multiarray.correlate : Old, no conjugate, version of correlate.

Notes ----- The definition of correlation above is not unique and sometimes correlation may be defined differently. Another common definition is::

c'_avk = sum_n an conj(vn+k)

which is related to ``c_avk`` by ``c'_avk = c_av-k``.

Examples -------- >>> np.correlate(1, 2, 3, 0, 1, 0.5) array(3.5) >>> np.correlate(1, 2, 3, 0, 1, 0.5, 'same') array(2. , 3.5, 3. ) >>> np.correlate(1, 2, 3, 0, 1, 0.5, 'full') array(0.5, 2. , 3.5, 3. , 0. )

Using complex sequences:

>>> np.correlate(1+1j, 2, 3-1j, 0, 1, 0.5j, 'full') array( 0.5-0.5j, 1.0+0.j , 1.5-1.5j, 3.0-1.j , 0.0+0.j )

Note that you get the time reversed, complex conjugated result when the two input sequences change places, i.e., ``c_

a}[k] = c^{*}_{av}[-k]``:

>>> np.correlate([0, 1, 0.5j], [1+1j, 2, 3-1j], 'full')
array([ 0.0+0.j ,  3.0+1.j ,  1.5+1.5j,  1.0+0.j ,  0.5+0.5j])

cos(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Cosine element-wise.

Parameters ---------- x : array_like Input array in radians. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray The corresponding cosine values. This is a scalar if `x` is a scalar.

Notes ----- If `out` is provided, the function writes the result into it, and returns a reference to `out`. (See Examples)

References ---------- M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972.

Examples -------- >>> np.cos(np.array(0, np.pi/2, np.pi)) array( 1.00000000e+00, 6.12303177e-17, -1.00000000e+00) >>> >>> # Example of providing the optional output parameter >>> out1 = np.array(0, dtype='d') >>> out2 = np.cos(0.1, out1) >>> out2 is out1 True >>> >>> # Example of ValueError due to provision of shape mis-matched `out` >>> np.cos(np.zeros((3,3)),np.zeros((2,2))) Traceback (most recent call last): File '<stdin>', line 1, in <module> ValueError: operands could not be broadcast together with shapes (3,3) (2,2)

cosh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Hyperbolic cosine, element-wise.

Equivalent to ``1/2 * (np.exp(x) + np.exp(-x))`` and ``np.cos(1j*x)``.

Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Output array of same shape as `x`. This is a scalar if `x` is a scalar.

Examples -------- >>> np.cosh(0) 1.0

The hyperbolic cosine describes the shape of a hanging cable:

>>> import matplotlib.pyplot as plt >>> x = np.linspace(-4, 4, 1000) >>> plt.plot(x, np.cosh(x)) >>> plt.show()

Counts the number of non-zero values in the array ``a``.

The word 'non-zero' is in reference to the Python 2.x built-in method ``__nonzero__()`` (renamed ``__bool__()`` in Python 3.x) of Python objects that tests an object's 'truthfulness'. For example, any number is considered truthful if it is nonzero, whereas any string is considered truthful if it is not the empty string. Thus, this function (recursively) counts how many elements in ``a`` (and in sub-arrays thereof) have their ``__nonzero__()`` or ``__bool__()`` method evaluated to ``True``.

Parameters ---------- a : array_like The array for which to count non-zeros. axis : int or tuple, optional Axis or tuple of axes along which to count non-zeros. Default is None, meaning that non-zeros will be counted along a flattened version of ``a``.

.. versionadded:: 1.12.0

keepdims : bool, optional If this is set to True, the axes that are counted are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

.. versionadded:: 1.19.0

Returns ------- count : int or array of int Number of non-zero values in the array along a given axis. Otherwise, the total number of non-zero values in the array is returned.

See Also -------- nonzero : Return the coordinates of all the non-zero values.

Examples -------- >>> np.count_nonzero(np.eye(4)) 4 >>> a = np.array([0, 1, 7, 0], ... [3, 0, 2, 19]) >>> np.count_nonzero(a) 5 >>> np.count_nonzero(a, axis=0) array(1, 1, 2, 1) >>> np.count_nonzero(a, axis=1) array(2, 3) >>> np.count_nonzero(a, axis=1, keepdims=True) array([2], [3])

Estimate a covariance matrix, given data and weights.

Covariance indicates the level to which two variables vary together. If we examine N-dimensional samples, :math:`X = x_1, x_2, ... x_N^T`, then the covariance matrix element :math:`C_j` is the covariance of :math:`x_i` and :math:`x_j`. The element :math:`C_i` is the variance of :math:`x_i`.

See the notes for an outline of the algorithm.

Parameters ---------- m : array_like A 1-D or 2-D array containing multiple variables and observations. Each row of `m` represents a variable, and each column a single observation of all those variables. Also see `rowvar` below. y : array_like, optional An additional set of variables and observations. `y` has the same form as that of `m`. rowvar : bool, optional If `rowvar` is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations. bias : bool, optional Default normalization (False) is by ``(N - 1)``, where ``N`` is the number of observations given (unbiased estimate). If `bias` is True, then normalization is by ``N``. These values can be overridden by using the keyword ``ddof`` in numpy versions >= 1.5. ddof : int, optional If not ``None`` the default value implied by `bias` is overridden. Note that ``ddof=1`` will return the unbiased estimate, even if both `fweights` and `aweights` are specified, and ``ddof=0`` will return the simple average. See the notes for the details. The default value is ``None``.

.. versionadded:: 1.5 fweights : array_like, int, optional 1-D array of integer frequency weights; the number of times each observation vector should be repeated.

.. versionadded:: 1.10 aweights : array_like, optional 1-D array of observation vector weights. These relative weights are typically large for observations considered 'important' and smaller for observations considered less 'important'. If ``ddof=0`` the array of weights can be used to assign probabilities to observation vectors.

.. versionadded:: 1.10

Returns ------- out : ndarray The covariance matrix of the variables.

See Also -------- corrcoef : Normalized covariance matrix

Notes ----- Assume that the observations are in the columns of the observation array `m` and let ``f = fweights`` and ``a = aweights`` for brevity. The steps to compute the weighted covariance are as follows::

>>> m = np.arange(10, dtype=np.float64) >>> f = np.arange(10) * 2 >>> a = np.arange(10) ** 2. >>> ddof = 1 >>> w = f * a >>> v1 = np.sum(w) >>> v2 = np.sum(w * a) >>> m -= np.sum(m * w, axis=None, keepdims=True) / v1 >>> cov = np.dot(m * w, m.T) * v1 / (v1**2 - ddof * v2)

Note that when ``a == 1``, the normalization factor ``v1 / (v1**2 - ddof * v2)`` goes over to ``1 / (np.sum(f) - ddof)`` as it should.

Examples -------- Consider two variables, :math:`x_0` and :math:`x_1`, which correlate perfectly, but in opposite directions:

>>> x = np.array([0, 2], [1, 1], [2, 0]).T >>> x array([0, 1, 2], [2, 1, 0])

Note how :math:`x_0` increases while :math:`x_1` decreases. The covariance matrix shows this clearly:

>>> np.cov(x) array([ 1., -1.], [-1., 1.])

Note that element :math:`C_

,1

`, which shows the correlation between :math:`x_0` and :math:`x_1`, is negative.

Further, note how `x` and `y` are combined:

>>> x = -2.1, -1, 4.3 >>> y = 3, 1.1, 0.12 >>> X = np.stack((x, y), axis=0) >>> np.cov(X) array([11.71 , -4.286 ], # may vary [-4.286 , 2.144133]) >>> np.cov(x, y) array([11.71 , -4.286 ], # may vary [-4.286 , 2.144133]) >>> np.cov(x) array(11.71)

Return the cross product of two (arrays of) vectors.

The cross product of `a` and `b` in :math:`R^3` is a vector perpendicular to both `a` and `b`. If `a` and `b` are arrays of vectors, the vectors are defined by the last axis of `a` and `b` by default, and these axes can have dimensions 2 or 3. Where the dimension of either `a` or `b` is 2, the third component of the input vector is assumed to be zero and the cross product calculated accordingly. In cases where both input vectors have dimension 2, the z-component of the cross product is returned.

Parameters ---------- a : array_like Components of the first vector(s). b : array_like Components of the second vector(s). axisa : int, optional Axis of `a` that defines the vector(s). By default, the last axis. axisb : int, optional Axis of `b` that defines the vector(s). By default, the last axis. axisc : int, optional Axis of `c` containing the cross product vector(s). Ignored if both input vectors have dimension 2, as the return is scalar. By default, the last axis. axis : int, optional If defined, the axis of `a`, `b` and `c` that defines the vector(s) and cross product(s). Overrides `axisa`, `axisb` and `axisc`.

Returns ------- c : ndarray Vector cross product(s).

Raises ------ ValueError When the dimension of the vector(s) in `a` and/or `b` does not equal 2 or 3.

See Also -------- inner : Inner product outer : Outer product. ix_ : Construct index arrays.

Notes ----- .. versionadded:: 1.9.0

Supports full broadcasting of the inputs.

Examples -------- Vector cross-product.

>>> x = 1, 2, 3 >>> y = 4, 5, 6 >>> np.cross(x, y) array(-3, 6, -3)

One vector with dimension 2.

>>> x = 1, 2 >>> y = 4, 5, 6 >>> np.cross(x, y) array(12, -6, -3)

Equivalently:

>>> x = 1, 2, 0 >>> y = 4, 5, 6 >>> np.cross(x, y) array(12, -6, -3)

Both vectors with dimension 2.

>>> x = 1,2 >>> y = 4,5 >>> np.cross(x, y) array(-3)

Multiple vector cross-products. Note that the direction of the cross product vector is defined by the `right-hand rule`.

>>> x = np.array([1,2,3], [4,5,6]) >>> y = np.array([4,5,6], [1,2,3]) >>> np.cross(x, y) array([-3, 6, -3], [ 3, -6, 3])

The orientation of `c` can be changed using the `axisc` keyword.

>>> np.cross(x, y, axisc=0) array([-3, 3], [ 6, -6], [-3, 3])

Change the vector definition of `x` and `y` using `axisa` and `axisb`.

>>> x = np.array([1,2,3], [4,5,6], [7, 8, 9]) >>> y = np.array([7, 8, 9], [4,5,6], [1,2,3]) >>> np.cross(x, y) array([ -6, 12, -6], [ 0, 0, 0], [ 6, -12, 6]) >>> np.cross(x, y, axisa=0, axisb=0) array([-24, 48, -24], [-30, 60, -30], [-36, 72, -36])

Return the cumulative product of elements along a given axis.

Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative product is computed. By default the input is flattened. dtype : dtype, optional Type of the returned array, as well as of the accumulator in which the elements are multiplied. If *dtype* is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used instead. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type of the resulting values will be cast if necessary.

Returns ------- cumprod : ndarray A new array holding the result is returned unless `out` is specified, in which case a reference to out is returned.

See Also -------- ufuncs-output-type

Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples -------- >>> a = np.array(1,2,3) >>> np.cumprod(a) # intermediate results 1, 1*2 ... # total product 1*2*3 = 6 array(1, 2, 6) >>> a = np.array([1, 2, 3], [4, 5, 6]) >>> np.cumprod(a, dtype=float) # specify type of output array( 1., 2., 6., 24., 120., 720.)

The cumulative product for each column (i.e., over the rows) of `a`:

>>> np.cumprod(a, axis=0) array([ 1, 2, 3], [ 4, 10, 18])

The cumulative product for each row (i.e. over the columns) of `a`:

>>> np.cumprod(a,axis=1) array([ 1, 2, 6], [ 4, 20, 120])

Return the cumulative product over the given axis.

See Also -------- cumprod : equivalent function; see for details.

Return the cumulative sum of the elements along a given axis.

Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative sum is computed. The default (None) is to compute the cumsum over the flattened array. dtype : dtype, optional Type of the returned array and of the accumulator in which the elements are summed. If `dtype` is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary. See `ufuncs-output-type` for more details.

Returns ------- cumsum_along_axis : ndarray. A new array holding the result is returned unless `out` is specified, in which case a reference to `out` is returned. The result has the same size as `a`, and the same shape as `a` if `axis` is not None or `a` is a 1-d array.

See Also -------- sum : Sum array elements.

trapz : Integration of array values using the composite trapezoidal rule.

diff : Calculate the n-th discrete difference along given axis.

Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples -------- >>> a = np.array([1,2,3], [4,5,6]) >>> a array([1, 2, 3], [4, 5, 6]) >>> np.cumsum(a) array( 1, 3, 6, 10, 15, 21) >>> np.cumsum(a, dtype=float) # specifies type of output value(s) array( 1., 3., 6., 10., 15., 21.)

>>> np.cumsum(a,axis=0) # sum over rows for each of the 3 columns array([1, 2, 3], [5, 7, 9]) >>> np.cumsum(a,axis=1) # sum over columns for each of the 2 rows array([ 1, 3, 6], [ 4, 9, 15])

datetime_as_string(arr, unit=None, timezone='naive', casting='same_kind')

Convert an array of datetimes into an array of strings.

Parameters ---------- arr : array_like of datetime64 The array of UTC timestamps to format. unit : str One of None, 'auto', or a :ref:`datetime unit <arrays.dtypes.dateunits>`. timezone : 'naive', 'UTC', 'local' or tzinfo Timezone information to use when displaying the datetime. If 'UTC', end with a Z to indicate UTC time. If 'local', convert to the local timezone first, and suffix with a +-#### timezone offset. If a tzinfo object, then do as with 'local', but use the specified timezone. casting : 'no', 'equiv', 'safe', 'same_kind', 'unsafe' Casting to allow when changing between datetime units.

Returns ------- str_arr : ndarray An array of strings the same shape as `arr`.

Examples -------- >>> import pytz >>> d = np.arange('2002-10-27T04:30', 4*60, 60, dtype='M8m') >>> d array('2002-10-27T04:30', '2002-10-27T05:30', '2002-10-27T06:30', '2002-10-27T07:30', dtype='datetime64m')

Setting the timezone to UTC shows the same information, but with a Z suffix

>>> np.datetime_as_string(d, timezone='UTC') array('2002-10-27T04:30Z', '2002-10-27T05:30Z', '2002-10-27T06:30Z', '2002-10-27T07:30Z', dtype='<U35')

Note that we picked datetimes that cross a DST boundary. Passing in a ``pytz`` timezone object will print the appropriate offset

>>> np.datetime_as_string(d, timezone=pytz.timezone('US/Eastern')) array('2002-10-27T00:30-0400', '2002-10-27T01:30-0400', '2002-10-27T01:30-0500', '2002-10-27T02:30-0500', dtype='<U39')

Passing in a unit will change the precision

>>> np.datetime_as_string(d, unit='h') array('2002-10-27T04', '2002-10-27T05', '2002-10-27T06', '2002-10-27T07', dtype='<U32') >>> np.datetime_as_string(d, unit='s') array('2002-10-27T04:30:00', '2002-10-27T05:30:00', '2002-10-27T06:30:00', '2002-10-27T07:30:00', dtype='<U38')

'casting' can be used to specify whether precision can be changed

>>> np.datetime_as_string(d, unit='h', casting='safe') Traceback (most recent call last): ... TypeError: Cannot create a datetime string as units 'h' from a NumPy datetime with units 'm' according to the rule 'safe'

datetime_data(dtype, /)

Get information about the step size of a date or time type.

The returned tuple can be passed as the second argument of `numpy.datetime64` and `numpy.timedelta64`.

Parameters ---------- dtype : dtype The dtype object, which must be a `datetime64` or `timedelta64` type.

Returns ------- unit : str The :ref:`datetime unit <arrays.dtypes.dateunits>` on which this dtype is based. count : int The number of base units in a step.

Examples -------- >>> dt_25s = np.dtype('timedelta6425s') >>> np.datetime_data(dt_25s) ('s', 25) >>> np.array(10, dt_25s).astype('timedelta64s') array(250, dtype='timedelta64s')

The result can be used to construct a datetime that uses the same units as a timedelta

>>> np.datetime64('2010', np.datetime_data(dt_25s)) numpy.datetime64('2010-01-01T00:00:00','25s')

deg2rad(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Convert angles from degrees to radians.

Parameters ---------- x : array_like Angles in degrees. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray The corresponding angle in radians. This is a scalar if `x` is a scalar.

See Also -------- rad2deg : Convert angles from radians to degrees. unwrap : Remove large jumps in angle by wrapping.

Notes ----- .. versionadded:: 1.3.0

``deg2rad(x)`` is ``x * pi / 180``.

Examples -------- >>> np.deg2rad(180) 3.1415926535897931

degrees(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Convert angles from radians to degrees.

Parameters ---------- x : array_like Input array in radians. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray of floats The corresponding degree values; if `out` was supplied this is a reference to it. This is a scalar if `x` is a scalar.

See Also -------- rad2deg : equivalent function

Examples -------- Convert a radian array to degrees

>>> rad = np.arange(12.)*np.pi/6 >>> np.degrees(rad) array( 0., 30., 60., 90., 120., 150., 180., 210., 240., 270., 300., 330.)

>>> out = np.zeros((rad.shape)) >>> r = np.degrees(rad, out) >>> np.all(r == out) True

Return a new array with sub-arrays along an axis deleted. For a one dimensional array, this returns those entries not returned by `arrobj`.

Parameters ---------- arr : array_like Input array. obj : slice, int or array of ints Indicate indices of sub-arrays to remove along the specified axis.

.. versionchanged:: 1.19.0 Boolean indices are now treated as a mask of elements to remove, rather than being cast to the integers 0 and 1.

axis : int, optional The axis along which to delete the subarray defined by `obj`. If `axis` is None, `obj` is applied to the flattened array.

Returns ------- out : ndarray A copy of `arr` with the elements specified by `obj` removed. Note that `delete` does not occur in-place. If `axis` is None, `out` is a flattened array.

See Also -------- insert : Insert elements into an array. append : Append elements at the end of an array.

Notes ----- Often it is preferable to use a boolean mask. For example:

>>> arr = np.arange(12) + 1 >>> mask = np.ones(len(arr), dtype=bool) >>> mask[0,2,4] = False >>> result = arrmask,...

Is equivalent to `np.delete(arr, 0,2,4, axis=0)`, but allows further use of `mask`.

Examples -------- >>> arr = np.array([1,2,3,4], [5,6,7,8], [9,10,11,12]) >>> arr array([ 1, 2, 3, 4], [ 5, 6, 7, 8], [ 9, 10, 11, 12]) >>> np.delete(arr, 1, 0) array([ 1, 2, 3, 4], [ 9, 10, 11, 12])

>>> np.delete(arr, np.s_::2, 1) array([ 2, 4], [ 6, 8], [10, 12]) >>> np.delete(arr, 1,3,5, None) array( 1, 3, 5, 7, 8, 9, 10, 11, 12)

Issues a DeprecationWarning, adds warning to `old_name`'s docstring, rebinds ``old_name.__name__`` and returns the new function object.

This function may also be used as a decorator.

Parameters ---------- func : function The function to be deprecated. old_name : str, optional The name of the function to be deprecated. Default is None, in which case the name of `func` is used. new_name : str, optional The new name for the function. Default is None, in which case the deprecation message is that `old_name` is deprecated. If given, the deprecation message is that `old_name` is deprecated and `new_name` should be used instead. message : str, optional Additional explanation of the deprecation. Displayed in the docstring after the warning.

Returns ------- old_func : function The deprecated function.

Examples -------- Note that ``olduint`` returns a value after printing Deprecation Warning:

>>> olduint = np.deprecate(np.uint) DeprecationWarning: `uint64` is deprecated! # may vary >>> olduint(6) 6

None

Extract a diagonal or construct a diagonal array.

See the more detailed documentation for ``numpy.diagonal`` if you use this function to extract a diagonal and wish to write to the resulting array; whether it returns a copy or a view depends on what version of numpy you are using.

Parameters ---------- v : array_like If `v` is a 2-D array, return a copy of its `k`-th diagonal. If `v` is a 1-D array, return a 2-D array with `v` on the `k`-th diagonal. k : int, optional Diagonal in question. The default is 0. Use `k>0` for diagonals above the main diagonal, and `k<0` for diagonals below the main diagonal.

Returns ------- out : ndarray The extracted diagonal or constructed diagonal array.

See Also -------- diagonal : Return specified diagonals. diagflat : Create a 2-D array with the flattened input as a diagonal. trace : Sum along diagonals. triu : Upper triangle of an array. tril : Lower triangle of an array.

Examples -------- >>> x = np.arange(9).reshape((3,3)) >>> x array([0, 1, 2], [3, 4, 5], [6, 7, 8])

>>> np.diag(x) array(0, 4, 8) >>> np.diag(x, k=1) array(1, 5) >>> np.diag(x, k=-1) array(3, 7)

>>> np.diag(np.diag(x)) array([0, 0, 0], [0, 4, 0], [0, 0, 8])

Return the indices to access the main diagonal of an array.

This returns a tuple of indices that can be used to access the main diagonal of an array `a` with ``a.ndim >= 2`` dimensions and shape (n, n, ..., n). For ``a.ndim = 2`` this is the usual diagonal, for ``a.ndim > 2`` this is the set of indices to access ``ai, i, ..., i`` for ``i = 0..n-1``.

Parameters ---------- n : int The size, along each dimension, of the arrays for which the returned indices can be used.

ndim : int, optional The number of dimensions.

See also -------- diag_indices_from

Notes ----- .. versionadded:: 1.4.0

Examples -------- Create a set of indices to access the diagonal of a (4, 4) array:

>>> di = np.diag_indices(4) >>> di (array(0, 1, 2, 3), array(0, 1, 2, 3)) >>> a = np.arange(16).reshape(4, 4) >>> a array([ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]) >>> adi = 100 >>> a array([100, 1, 2, 3], [ 4, 100, 6, 7], [ 8, 9, 100, 11], [ 12, 13, 14, 100])

Now, we create indices to manipulate a 3-D array:

>>> d3 = np.diag_indices(2, 3) >>> d3 (array(0, 1), array(0, 1), array(0, 1))

And use it to set the diagonal of an array of zeros to 1:

>>> a = np.zeros((2, 2, 2), dtype=int) >>> ad3 = 1 >>> a array([[1, 0], [0, 0]], [[0, 0], [0, 1]])

Return the indices to access the main diagonal of an n-dimensional array.

See `diag_indices` for full details.

Parameters ---------- arr : array, at least 2-D

See Also -------- diag_indices

Notes ----- .. versionadded:: 1.4.0

Create a two-dimensional array with the flattened input as a diagonal.

Parameters ---------- v : array_like Input data, which is flattened and set as the `k`-th diagonal of the output. k : int, optional Diagonal to set; 0, the default, corresponds to the 'main' diagonal, a positive (negative) `k` giving the number of the diagonal above (below) the main.

Returns ------- out : ndarray The 2-D output array.

See Also -------- diag : MATLAB work-alike for 1-D and 2-D arrays. diagonal : Return specified diagonals. trace : Sum along diagonals.

Examples -------- >>> np.diagflat([1,2], [3,4]) array([1, 0, 0, 0], [0, 2, 0, 0], [0, 0, 3, 0], [0, 0, 0, 4])

>>> np.diagflat(1,2, 1) array([0, 1, 0], [0, 0, 2], [0, 0, 0])

Return specified diagonals.

If `a` is 2-D, returns the diagonal of `a` with the given offset, i.e., the collection of elements of the form ``ai, i+offset``. If `a` has more than two dimensions, then the axes specified by `axis1` and `axis2` are used to determine the 2-D sub-array whose diagonal is returned. The shape of the resulting array can be determined by removing `axis1` and `axis2` and appending an index to the right equal to the size of the resulting diagonals.

In versions of NumPy prior to 1.7, this function always returned a new, independent array containing a copy of the values in the diagonal.

In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal, but depending on this fact is deprecated. Writing to the resulting array continues to work as it used to, but a FutureWarning is issued.

Starting in NumPy 1.9 it returns a read-only view on the original array. Attempting to write to the resulting array will produce an error.

In some future release, it will return a read/write view and writing to the returned array will alter your original array. The returned array will have the same type as the input array.

If you don't write to the array returned by this function, then you can just ignore all of the above.

If you depend on the current behavior, then we suggest copying the returned array explicitly, i.e., use ``np.diagonal(a).copy()`` instead of just ``np.diagonal(a)``. This will work with both past and future versions of NumPy.

Parameters ---------- a : array_like Array from which the diagonals are taken. offset : int, optional Offset of the diagonal from the main diagonal. Can be positive or negative. Defaults to main diagonal (0). axis1 : int, optional Axis to be used as the first axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to first axis (0). axis2 : int, optional Axis to be used as the second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to second axis (1).

Returns ------- array_of_diagonals : ndarray If `a` is 2-D, then a 1-D array containing the diagonal and of the same type as `a` is returned unless `a` is a `matrix`, in which case a 1-D array rather than a (2-D) `matrix` is returned in order to maintain backward compatibility.

If ``a.ndim > 2``, then the dimensions specified by `axis1` and `axis2` are removed, and a new axis inserted at the end corresponding to the diagonal.

Raises ------ ValueError If the dimension of `a` is less than 2.

See Also -------- diag : MATLAB work-a-like for 1-D and 2-D arrays. diagflat : Create diagonal arrays. trace : Sum along diagonals.

Examples -------- >>> a = np.arange(4).reshape(2,2) >>> a array([0, 1], [2, 3]) >>> a.diagonal() array(0, 3) >>> a.diagonal(1) array(1)

A 3-D example:

>>> a = np.arange(8).reshape(2,2,2); a array([[0, 1], [2, 3]], [[4, 5], [6, 7]]) >>> a.diagonal(0, # Main diagonals of two arrays created by skipping ... 0, # across the outer(left)-most axis last and ... 1) # the 'middle' (row) axis first. array([0, 6], [1, 7])

The sub-arrays whose main diagonals we just obtained; note that each corresponds to fixing the right-most (column) axis, and that the diagonals are 'packed' in rows.

>>> a:,:,0 # main diagonal is 0 6 array([0, 2], [4, 6]) >>> a:,:,1 # main diagonal is 1 7 array([1, 3], [5, 7])

The anti-diagonal can be obtained by reversing the order of elements using either `numpy.flipud` or `numpy.fliplr`.

>>> a = np.arange(9).reshape(3, 3) >>> a array([0, 1, 2], [3, 4, 5], [6, 7, 8]) >>> np.fliplr(a).diagonal() # Horizontal flip array(2, 4, 6) >>> np.flipud(a).diagonal() # Vertical flip array(6, 4, 2)

Note that the order in which the diagonal is retrieved varies depending on the flip function.

Calculate the n-th discrete difference along the given axis.

The first difference is given by ``outi = ai+1 - ai`` along the given axis, higher differences are calculated by using `diff` recursively.

Parameters ---------- a : array_like Input array n : int, optional The number of times values are differenced. If zero, the input is returned as-is. axis : int, optional The axis along which the difference is taken, default is the last axis. prepend, append : array_like, optional Values to prepend or append to `a` along axis prior to performing the difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match `a` except along axis.

.. versionadded:: 1.16.0

Returns ------- diff : ndarray The n-th differences. The shape of the output is the same as `a` except along `axis` where the dimension is smaller by `n`. The type of the output is the same as the type of the difference between any two elements of `a`. This is the same as the type of `a` in most cases. A notable exception is `datetime64`, which results in a `timedelta64` output array.

See Also -------- gradient, ediff1d, cumsum

Notes ----- Type is preserved for boolean arrays, so the result will contain `False` when consecutive elements are the same and `True` when they differ.

For unsigned integer arrays, the results will also be unsigned. This should not be surprising, as the result is consistent with calculating the difference directly:

>>> u8_arr = np.array(1, 0, dtype=np.uint8) >>> np.diff(u8_arr) array(255, dtype=uint8) >>> u8_arr1,... - u8_arr0,... 255

If this is not desirable, then the array should be cast to a larger integer type first:

>>> i16_arr = u8_arr.astype(np.int16) >>> np.diff(i16_arr) array(-1, dtype=int16)

Examples -------- >>> x = np.array(1, 2, 4, 7, 0) >>> np.diff(x) array( 1, 2, 3, -7) >>> np.diff(x, n=2) array( 1, 1, -10)

>>> x = np.array([1, 3, 6, 10], [0, 5, 6, 8]) >>> np.diff(x) array([2, 3, 4], [5, 1, 2]) >>> np.diff(x, axis=0) array([-1, 2, 0, -2])

>>> x = np.arange('1066-10-13', '1066-10-16', dtype=np.datetime64) >>> np.diff(x) array(1, 1, dtype='timedelta64D')

Return the indices of the bins to which each value in input array belongs.

========= ============= ============================ `right` order of bins returned index `i` satisfies ========= ============= ============================ ``False`` increasing ``binsi-1 <= x < binsi`` ``True`` increasing ``binsi-1 < x <= binsi`` ``False`` decreasing ``binsi-1 > x >= binsi`` ``True`` decreasing ``binsi-1 >= x > binsi`` ========= ============= ============================

If values in `x` are beyond the bounds of `bins`, 0 or ``len(bins)`` is returned as appropriate.

Parameters ---------- x : array_like Input array to be binned. Prior to NumPy 1.10.0, this array had to be 1-dimensional, but can now have any shape. bins : array_like Array of bins. It has to be 1-dimensional and monotonic. right : bool, optional Indicating whether the intervals include the right or the left bin edge. Default behavior is (right==False) indicating that the interval does not include the right edge. The left bin end is open in this case, i.e., binsi-1 <= x < binsi is the default behavior for monotonically increasing bins.

Returns ------- indices : ndarray of ints Output array of indices, of same shape as `x`.

Raises ------ ValueError If `bins` is not monotonic. TypeError If the type of the input is complex.

See Also -------- bincount, histogram, unique, searchsorted

Notes ----- If values in `x` are such that they fall outside the bin range, attempting to index `bins` with the indices that `digitize` returns will result in an IndexError.

.. versionadded:: 1.10.0

`np.digitize` is implemented in terms of `np.searchsorted`. This means that a binary search is used to bin the values, which scales much better for larger number of bins than the previous linear search. It also removes the requirement for the input array to be 1-dimensional.

For monotonically _increasing_ `bins`, the following are equivalent::

np.digitize(x, bins, right=True) np.searchsorted(bins, x, side='left')

Note that as the order of the arguments are reversed, the side must be too. The `searchsorted` call is marginally faster, as it does not do any monotonicity checks. Perhaps more importantly, it supports all dtypes.

Examples -------- >>> x = np.array(0.2, 6.4, 3.0, 1.6) >>> bins = np.array(0.0, 1.0, 2.5, 4.0, 10.0) >>> inds = np.digitize(x, bins) >>> inds array(1, 4, 3, 2) >>> for n in range(x.size): ... print(binsinds[n]-1, '<=', xn, '<', binsinds[n]) ... 0.0 <= 0.2 < 1.0 4.0 <= 6.4 < 10.0 2.5 <= 3.0 < 4.0 1.0 <= 1.6 < 2.5

>>> x = np.array(1.2, 10.0, 12.4, 15.5, 20.) >>> bins = np.array(0, 5, 10, 15, 20) >>> np.digitize(x,bins,right=True) array(1, 2, 3, 4, 4) >>> np.digitize(x,bins,right=False) array(1, 3, 3, 4, 5)

Display a message on a device.

Parameters ---------- mesg : str Message to display. device : object Device to write message. If None, defaults to ``sys.stdout`` which is very similar to ``print``. `device` needs to have ``write()`` and ``flush()`` methods. linefeed : bool, optional Option whether to print a line feed or not. Defaults to True.

Raises ------ AttributeError If `device` does not have a ``write()`` or ``flush()`` method.

Examples -------- Besides ``sys.stdout``, a file-like object can also be used as it has both required methods:

>>> from io import StringIO >>> buf = StringIO() >>> np.disp(u''Display' in a file', device=buf) >>> buf.getvalue() ''Display' in a file\n'

true_divide(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Returns a true division of the inputs, element-wise.

Instead of the Python traditional 'floor division', this returns a true division. True division adjusts the output type to present the best answer, regardless of input types.

Parameters ---------- x1 : array_like Dividend array. x2 : array_like Divisor array. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar This is a scalar if both `x1` and `x2` are scalars.

Notes ----- In Python, ``//`` is the floor division operator and ``/`` the true division operator. The ``true_divide(x1, x2)`` function is equivalent to true division in Python.

Examples -------- >>> x = np.arange(5) >>> np.true_divide(x, 4) array( 0. , 0.25, 0.5 , 0.75, 1. )

>>> x/4 array( 0. , 0.25, 0.5 , 0.75, 1. )

>>> x//4 array(0, 0, 0, 0, 1)

divmod(x1, x2, out1, out2, / , out=(None, None), *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Return element-wise quotient and remainder simultaneously.

.. versionadded:: 1.13.0

``np.divmod(x, y)`` is equivalent to ``(x // y, x % y)``, but faster because it avoids redundant work. It is used to implement the Python built-in function ``divmod`` on NumPy arrays.

Parameters ---------- x1 : array_like Dividend array. x2 : array_like Divisor array. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out1 : ndarray Element-wise quotient resulting from floor division. This is a scalar if both `x1` and `x2` are scalars. out2 : ndarray Element-wise remainder from floor division. This is a scalar if both `x1` and `x2` are scalars.

See Also -------- floor_divide : Equivalent to Python's ``//`` operator. remainder : Equivalent to Python's ``%`` operator. modf : Equivalent to ``divmod(x, 1)`` for positive ``x`` with the return values switched.

Examples -------- >>> np.divmod(np.arange(5), 3) (array(0, 0, 0, 1, 1), array(0, 1, 2, 0, 1))

dot(a, b, out=None)

Dot product of two arrays. Specifically,

• If both `a` and `b` are 1-D arrays, it is inner product of vectors (without complex conjugation).

• If both `a` and `b` are 2-D arrays, it is matrix multiplication, but using :func:`matmul` or ``a @ b`` is preferred.

• If either `a` or `b` is 0-D (scalar), it is equivalent to :func:`multiply` and using ``numpy.multiply(a, b)`` or ``a * b`` is preferred.

• If `a` is an N-D array and `b` is a 1-D array, it is a sum product over the last axis of `a` and `b`.

• If `a` is an N-D array and `b` is an M-D array (where ``M>=2``), it is a sum product over the last axis of `a` and the second-to-last axis of `b`::

dot(a, b)i,j,k,m = sum(ai,j,: * bk,:,m)

Parameters ---------- a : array_like First argument. b : array_like Second argument. out : ndarray, optional Output argument. This must have the exact kind that would be returned if it was not used. In particular, it must have the right type, must be C-contiguous, and its dtype must be the dtype that would be returned for `dot(a,b)`. This is a performance feature. Therefore, if these conditions are not met, an exception is raised, instead of attempting to be flexible.

Returns ------- output : ndarray Returns the dot product of `a` and `b`. If `a` and `b` are both scalars or both 1-D arrays then a scalar is returned; otherwise an array is returned. If `out` is given, then it is returned.

Raises ------ ValueError If the last dimension of `a` is not the same size as the second-to-last dimension of `b`.

See Also -------- vdot : Complex-conjugating dot product. tensordot : Sum products over arbitrary axes. einsum : Einstein summation convention. matmul : '@' operator as method with out parameter.

Examples -------- >>> np.dot(3, 4) 12

Neither argument is complex-conjugated:

>>> np.dot(2j, 3j, 2j, 3j) (-13+0j)

For 2-D arrays it is the matrix product:

>>> a = [1, 0], [0, 1] >>> b = [4, 1], [2, 2] >>> np.dot(a, b) array([4, 1], [2, 2])

>>> a = np.arange(3*4*5*6).reshape((3,4,5,6)) >>> b = np.arange(3*4*5*6)::-1.reshape((5,4,6,3)) >>> np.dot(a, b)2,3,2,1,2,2 499128 >>> sum(a2,3,2,: * b1,2,:,2) 499128

Split array into multiple sub-arrays along the 3rd axis (depth).

Please refer to the `split` documentation. `dsplit` is equivalent to `split` with ``axis=2``, the array is always split along the third axis provided the array dimension is greater than or equal to 3.

See Also -------- split : Split an array into multiple sub-arrays of equal size.

Examples -------- >>> x = np.arange(16.0).reshape(2, 2, 4) >>> x array([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.]], [[ 8., 9., 10., 11.], [12., 13., 14., 15.]]) >>> np.dsplit(x, 2) array([[[ 0., 1.], [ 4., 5.]], [[ 8., 9.], [12., 13.]]]), array([[[ 2., 3.], [ 6., 7.]], [[10., 11.], [14., 15.]]]) >>> np.dsplit(x, np.array(3, 6)) array([[[ 0., 1., 2.], [ 4., 5., 6.]], [[ 8., 9., 10.], [12., 13., 14.]]]), array([[[ 3.], [ 7.]], [[11.], [15.]]]), array([], shape=(2, 2, 0), dtype=float64)

Stack arrays in sequence depth wise (along third axis).

This is equivalent to concatenation along the third axis after 2-D arrays of shape `(M,N)` have been reshaped to `(M,N,1)` and 1-D arrays of shape `(N,)` have been reshaped to `(1,N,1)`. Rebuilds arrays divided by `dsplit`.

This function makes most sense for arrays with up to 3 dimensions. For instance, for pixel-data with a height (first axis), width (second axis), and r/g/b channels (third axis). The functions `concatenate`, `stack` and `block` provide more general stacking and concatenation operations.

Parameters ---------- tup : sequence of arrays The arrays must have the same shape along all but the third axis. 1-D or 2-D arrays must have the same shape.

Returns ------- stacked : ndarray The array formed by stacking the given arrays, will be at least 3-D.

See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. block : Assemble an nd-array from nested lists of blocks. vstack : Stack arrays in sequence vertically (row wise). hstack : Stack arrays in sequence horizontally (column wise). column_stack : Stack 1-D arrays as columns into a 2-D array. dsplit : Split array along third axis.

Examples -------- >>> a = np.array((1,2,3)) >>> b = np.array((2,3,4)) >>> np.dstack((a,b)) array([[1, 2], [2, 3], [3, 4]])

>>> a = np.array([1],[2],[3]) >>> b = np.array([2],[3],[4]) >>> np.dstack((a,b)) array([[1, 2]], [[2, 3]], [[3, 4]])

The differences between consecutive elements of an array.

Parameters ---------- ary : array_like If necessary, will be flattened before the differences are taken. to_end : array_like, optional Number(s) to append at the end of the returned differences. to_begin : array_like, optional Number(s) to prepend at the beginning of the returned differences.

Returns ------- ediff1d : ndarray The differences. Loosely, this is ``ary.flat1: - ary.flat:-1``.

See Also -------- diff, gradient

Notes ----- When applied to masked arrays, this function drops the mask information if the `to_begin` and/or `to_end` parameters are used.

Examples -------- >>> x = np.array(1, 2, 4, 7, 0) >>> np.ediff1d(x) array( 1, 2, 3, -7)

>>> np.ediff1d(x, to_begin=-99, to_end=np.array(88, 99)) array(-99, 1, 2, ..., -7, 88, 99)

The returned array is always 1D.

>>> y = [1, 2, 4], [1, 6, 24] >>> np.ediff1d(y) array( 1, 2, -3, 5, 18)

einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe', optimize=False)

Evaluates the Einstein summation convention on the operands.

Using the Einstein summation convention, many common multi-dimensional, linear algebraic array operations can be represented in a simple fashion. In *implicit* mode `einsum` computes these values.

In *explicit* mode, `einsum` provides further flexibility to compute other array operations that might not be considered classical Einstein summation operations, by disabling, or forcing summation over specified subscript labels.

See the notes and examples for clarification.

Parameters ---------- subscripts : str Specifies the subscripts for summation as comma separated list of subscript labels. An implicit (classical Einstein summation) calculation is performed unless the explicit indicator '->' is included as well as subscript labels of the precise output form. operands : list of array_like These are the arrays for the operation. out : ndarray, optional If provided, the calculation is done into this array. dtype : data-type, None, optional If provided, forces the calculation to use the data type specified. Note that you may have to also give a more liberal `casting` parameter to allow the conversions. Default is None. order : 'C', 'F', 'A', 'K', optional Controls the memory layout of the output. 'C' means it should be C contiguous. 'F' means it should be Fortran contiguous, 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise. 'K' means it should be as close to the layout as the inputs as is possible, including arbitrarily permuted axes. Default is 'K'. casting : 'no', 'equiv', 'safe', 'same_kind', 'unsafe', optional Controls what kind of data casting may occur. Setting this to 'unsafe' is not recommended, as it can adversely affect accumulations.

* 'no' means the data types should not be cast at all. * 'equiv' means only byte-order changes are allowed. * 'safe' means only casts which can preserve values are allowed. * 'same_kind' means only safe casts or casts within a kind, like float64 to float32, are allowed. * 'unsafe' means any data conversions may be done.

Default is 'safe'. optimize : False, True, 'greedy', 'optimal', optional Controls if intermediate optimization should occur. No optimization will occur if False and True will default to the 'greedy' algorithm. Also accepts an explicit contraction list from the ``np.einsum_path`` function. See ``np.einsum_path`` for more details. Defaults to False.

Returns ------- output : ndarray The calculation based on the Einstein summation convention.

See Also -------- einsum_path, dot, inner, outer, tensordot, linalg.multi_dot

Notes ----- .. versionadded:: 1.6.0

The Einstein summation convention can be used to compute many multi-dimensional, linear algebraic array operations. `einsum` provides a succinct way of representing these.

A non-exhaustive list of these operations, which can be computed by `einsum`, is shown below along with examples:

* Trace of an array, :py:func:`numpy.trace`. * Return a diagonal, :py:func:`numpy.diag`. * Array axis summations, :py:func:`numpy.sum`. * Transpositions and permutations, :py:func:`numpy.transpose`. * Matrix multiplication and dot product, :py:func:`numpy.matmul` :py:func:`numpy.dot`. * Vector inner and outer products, :py:func:`numpy.inner` :py:func:`numpy.outer`. * Broadcasting, element-wise and scalar multiplication, :py:func:`numpy.multiply`. * Tensor contractions, :py:func:`numpy.tensordot`. * Chained array operations, in efficient calculation order, :py:func:`numpy.einsum_path`.

The subscripts string is a comma-separated list of subscript labels, where each label refers to a dimension of the corresponding operand. Whenever a label is repeated it is summed, so ``np.einsum('i,i', a, b)`` is equivalent to :py:func:`np.inner(a,b) <numpy.inner>`. If a label appears only once, it is not summed, so ``np.einsum('i', a)`` produces a view of ``a`` with no changes. A further example ``np.einsum('ij,jk', a, b)`` describes traditional matrix multiplication and is equivalent to :py:func:`np.matmul(a,b) <numpy.matmul>`. Repeated subscript labels in one operand take the diagonal. For example, ``np.einsum('ii', a)`` is equivalent to :py:func:`np.trace(a) <numpy.trace>`.

In *implicit mode*, the chosen subscripts are important since the axes of the output are reordered alphabetically. This means that ``np.einsum('ij', a)`` doesn't affect a 2D array, while ``np.einsum('ji', a)`` takes its transpose. Additionally, ``np.einsum('ij,jk', a, b)`` returns a matrix multiplication, while, ``np.einsum('ij,jh', a, b)`` returns the transpose of the multiplication since subscript 'h' precedes subscript 'i'.

In *explicit mode* the output can be directly controlled by specifying output subscript labels. This requires the identifier '->' as well as the list of output subscript labels. This feature increases the flexibility of the function since summing can be disabled or forced when required. The call ``np.einsum('i->', a)`` is like :py:func:`np.sum(a, axis=-1) <numpy.sum>`, and ``np.einsum('ii->i', a)`` is like :py:func:`np.diag(a) <numpy.diag>`. The difference is that `einsum` does not allow broadcasting by default. Additionally ``np.einsum('ij,jh->ih', a, b)`` directly specifies the order of the output subscript labels and therefore returns matrix multiplication, unlike the example above in implicit mode.

To enable and control broadcasting, use an ellipsis. Default NumPy-style broadcasting is done by adding an ellipsis to the left of each term, like ``np.einsum('...ii->...i', a)``. To take the trace along the first and last axes, you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix product with the left-most indices instead of rightmost, one can do ``np.einsum('ij...,jk...->ik...', a, b)``.

When there is only one operand, no axes are summed, and no output parameter is provided, a view into the operand is returned instead of a new array. Thus, taking the diagonal as ``np.einsum('ii->i', a)`` produces a view (changed in version 1.10.0).

`einsum` also provides an alternative way to provide the subscripts and operands as ``einsum(op0, sublist0, op1, sublist1, ..., sublistout)``. If the output shape is not provided in this format `einsum` will be calculated in implicit mode, otherwise it will be performed explicitly. The examples below have corresponding `einsum` calls with the two parameter methods.

.. versionadded:: 1.10.0

Views returned from einsum are now writeable whenever the input array is writeable. For example, ``np.einsum('ijk...->kji...', a)`` will now have the same effect as :py:func:`np.swapaxes(a, 0, 2) <numpy.swapaxes>` and ``np.einsum('ii->i', a)`` will return a writeable view of the diagonal of a 2D array.

.. versionadded:: 1.12.0

Added the ``optimize`` argument which will optimize the contraction order of an einsum expression. For a contraction with three or more operands this can greatly increase the computational efficiency at the cost of a larger memory footprint during computation.

Typically a 'greedy' algorithm is applied which empirical tests have shown returns the optimal path in the majority of cases. In some cases 'optimal' will return the superlative path through a more expensive, exhaustive search. For iterative calculations it may be advisable to calculate the optimal path once and reuse that path by supplying it as an argument. An example is given below.

See :py:func:`numpy.einsum_path` for more details.

Examples -------- >>> a = np.arange(25).reshape(5,5) >>> b = np.arange(5) >>> c = np.arange(6).reshape(2,3)

Trace of a matrix:

>>> np.einsum('ii', a) 60 >>> np.einsum(a, 0,0) 60 >>> np.trace(a) 60

Extract the diagonal (requires explicit form):

>>> np.einsum('ii->i', a) array( 0, 6, 12, 18, 24) >>> np.einsum(a, 0,0, 0) array( 0, 6, 12, 18, 24) >>> np.diag(a) array( 0, 6, 12, 18, 24)

Sum over an axis (requires explicit form):

>>> np.einsum('ij->i', a) array( 10, 35, 60, 85, 110) >>> np.einsum(a, 0,1, 0) array( 10, 35, 60, 85, 110) >>> np.sum(a, axis=1) array( 10, 35, 60, 85, 110)

For higher dimensional arrays summing a single axis can be done with ellipsis:

>>> np.einsum('...j->...', a) array( 10, 35, 60, 85, 110) >>> np.einsum(a, Ellipsis,1, Ellipsis) array( 10, 35, 60, 85, 110)

Compute a matrix transpose, or reorder any number of axes:

>>> np.einsum('ji', c) array([0, 3], [1, 4], [2, 5]) >>> np.einsum('ij->ji', c) array([0, 3], [1, 4], [2, 5]) >>> np.einsum(c, 1,0) array([0, 3], [1, 4], [2, 5]) >>> np.transpose(c) array([0, 3], [1, 4], [2, 5])

Vector inner products:

>>> np.einsum('i,i', b, b) 30 >>> np.einsum(b, 0, b, 0) 30 >>> np.inner(b,b) 30

Matrix vector multiplication:

>>> np.einsum('ij,j', a, b) array( 30, 80, 130, 180, 230) >>> np.einsum(a, 0,1, b, 1) array( 30, 80, 130, 180, 230) >>> np.dot(a, b) array( 30, 80, 130, 180, 230) >>> np.einsum('...j,j', a, b) array( 30, 80, 130, 180, 230)

Broadcasting and scalar multiplication:

>>> np.einsum('..., ...', 3, c) array([ 0, 3, 6], [ 9, 12, 15]) >>> np.einsum(',ij', 3, c) array([ 0, 3, 6], [ 9, 12, 15]) >>> np.einsum(3, Ellipsis, c, Ellipsis) array([ 0, 3, 6], [ 9, 12, 15]) >>> np.multiply(3, c) array([ 0, 3, 6], [ 9, 12, 15])

Vector outer product:

>>> np.einsum('i,j', np.arange(2)+1, b) array([0, 1, 2, 3, 4], [0, 2, 4, 6, 8]) >>> np.einsum(np.arange(2)+1, 0, b, 1) array([0, 1, 2, 3, 4], [0, 2, 4, 6, 8]) >>> np.outer(np.arange(2)+1, b) array([0, 1, 2, 3, 4], [0, 2, 4, 6, 8])

Tensor contraction:

>>> a = np.arange(60.).reshape(3,4,5) >>> b = np.arange(24.).reshape(4,3,2) >>> np.einsum('ijk,jil->kl', a, b) array([4400., 4730.], [4532., 4874.], [4664., 5018.], [4796., 5162.], [4928., 5306.]) >>> np.einsum(a, 0,1,2, b, 1,0,3, 2,3) array([4400., 4730.], [4532., 4874.], [4664., 5018.], [4796., 5162.], [4928., 5306.]) >>> np.tensordot(a,b, axes=(1,0,0,1)) array([4400., 4730.], [4532., 4874.], [4664., 5018.], [4796., 5162.], [4928., 5306.])

Writeable returned arrays (since version 1.10.0):

>>> a = np.zeros((3, 3)) >>> np.einsum('ii->i', a): = 1 >>> a array([1., 0., 0.], [0., 1., 0.], [0., 0., 1.])

Example of ellipsis use:

>>> a = np.arange(6).reshape((3,2)) >>> b = np.arange(12).reshape((4,3)) >>> np.einsum('ki,jk->ij', a, b) array([10, 28, 46, 64], [13, 40, 67, 94]) >>> np.einsum('ki,...k->i...', a, b) array([10, 28, 46, 64], [13, 40, 67, 94]) >>> np.einsum('k...,jk', a, b) array([10, 28, 46, 64], [13, 40, 67, 94])

Chained array operations. For more complicated contractions, speed ups might be achieved by repeatedly computing a 'greedy' path or pre-computing the 'optimal' path and repeatedly applying it, using an `einsum_path` insertion (since version 1.12.0). Performance improvements can be particularly significant with larger arrays:

>>> a = np.ones(64).reshape(2,4,8)

Basic `einsum`: ~1520ms (benchmarked on 3.1GHz Intel i5.)

>>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a)

Sub-optimal `einsum` (due to repeated path calculation time): ~330ms

>>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='optimal')

Greedy `einsum` (faster optimal path approximation): ~160ms

>>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='greedy')

Optimal `einsum` (best usage pattern in some use cases): ~110ms

>>> path = np.einsum_path('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='optimal')0 >>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize=path)

einsum_path(subscripts, *operands, optimize='greedy')

Evaluates the lowest cost contraction order for an einsum expression by considering the creation of intermediate arrays.

Parameters ---------- subscripts : str Specifies the subscripts for summation. *operands : list of array_like These are the arrays for the operation. optimize : ool, list, tuple, 'greedy', 'optimal' Choose the type of path. If a tuple is provided, the second argument is assumed to be the maximum intermediate size created. If only a single argument is provided the largest input or output array size is used as a maximum intermediate size.

* if a list is given that starts with ``einsum_path``, uses this as the contraction path * if False no optimization is taken * if True defaults to the 'greedy' algorithm * 'optimal' An algorithm that combinatorially explores all possible ways of contracting the listed tensors and choosest the least costly path. Scales exponentially with the number of terms in the contraction. * 'greedy' An algorithm that chooses the best pair contraction at each step. Effectively, this algorithm searches the largest inner, Hadamard, and then outer products at each step. Scales cubically with the number of terms in the contraction. Equivalent to the 'optimal' path for most contractions.

Default is 'greedy'.

Returns ------- path : list of tuples A list representation of the einsum path. string_repr : str A printable representation of the einsum path.

Notes ----- The resulting path indicates which terms of the input contraction should be contracted first, the result of this contraction is then appended to the end of the contraction list. This list can then be iterated over until all intermediate contractions are complete.

See Also -------- einsum, linalg.multi_dot

Examples --------

We can begin with a chain dot example. In this case, it is optimal to contract the ``b`` and ``c`` tensors first as represented by the first element of the path ``(1, 2)``. The resulting tensor is added to the end of the contraction and the remaining contraction ``(0, 1)`` is then completed.

>>> np.random.seed(123) >>> a = np.random.rand(2, 2) >>> b = np.random.rand(2, 5) >>> c = np.random.rand(5, 2) >>> path_info = np.einsum_path('ij,jk,kl->il', a, b, c, optimize='greedy') >>> print(path_info0) 'einsum_path', (1, 2), (0, 1) >>> print(path_info1) Complete contraction: ij,jk,kl->il # may vary Naive scaling: 4 Optimized scaling: 3 Naive FLOP count: 1.600e+02 Optimized FLOP count: 5.600e+01 Theoretical speedup: 2.857 Largest intermediate: 4.000e+00 elements ------------------------------------------------------------------------- scaling current remaining ------------------------------------------------------------------------- 3 kl,jk->jl ij,jl->il 3 jl,ij->il il->il

A more complex index transformation example.

>>> I = np.random.rand(10, 10, 10, 10) >>> C = np.random.rand(10, 10) >>> path_info = np.einsum_path('ea,fb,abcd,gc,hd->efgh', C, C, I, C, C, ... optimize='greedy')

>>> print(path_info0) 'einsum_path', (0, 2), (0, 3), (0, 2), (0, 1) >>> print(path_info1) Complete contraction: ea,fb,abcd,gc,hd->efgh # may vary Naive scaling: 8 Optimized scaling: 5 Naive FLOP count: 8.000e+08 Optimized FLOP count: 8.000e+05 Theoretical speedup: 1000.000 Largest intermediate: 1.000e+04 elements -------------------------------------------------------------------------- scaling current remaining -------------------------------------------------------------------------- 5 abcd,ea->bcde fb,gc,hd,bcde->efgh 5 bcde,fb->cdef gc,hd,cdef->efgh 5 cdef,gc->defg hd,defg->efgh 5 defg,hd->efgh efgh->efgh

empty(shape, dtype=float, order='C')

Return a new array of given shape and type, without initializing entries.

Parameters ---------- shape : int or tuple of int Shape of the empty array, e.g., ``(2, 3)`` or ``2``. dtype : data-type, optional Desired output data-type for the array, e.g, `numpy.int8`. Default is `numpy.float64`. order : 'C', 'F', optional, default: 'C' Whether to store multi-dimensional data in row-major (C-style) or column-major (Fortran-style) order in memory.

Returns ------- out : ndarray Array of uninitialized (arbitrary) data of the given shape, dtype, and order. Object arrays will be initialized to None.

See Also -------- empty_like : Return an empty array with shape and type of input. ones : Return a new array setting values to one. zeros : Return a new array setting values to zero. full : Return a new array of given shape filled with value.

Notes ----- `empty`, unlike `zeros`, does not set the array values to zero, and may therefore be marginally faster. On the other hand, it requires the user to manually set all the values in the array, and should be used with caution.

Examples -------- >>> np.empty(2, 2) array([ -9.74499359e+001, 6.69583040e-309], [ 2.13182611e-314, 3.06959433e-309]) #uninitialized

>>> np.empty(2, 2, dtype=int) array([-1073741821, -1067949133], [ 496041986, 19249760]) #uninitialized

empty_like(prototype, dtype=None, order='K', subok=True, shape=None)

Return a new array with the same shape and type as a given array.

Parameters ---------- prototype : array_like The shape and data-type of `prototype` define these same attributes of the returned array. dtype : data-type, optional Overrides the data type of the result.

.. versionadded:: 1.6.0 order : 'C', 'F', 'A', or 'K', optional Overrides the memory layout of the result. 'C' means C-order, 'F' means F-order, 'A' means 'F' if ``prototype`` is Fortran contiguous, 'C' otherwise. 'K' means match the layout of ``prototype`` as closely as possible.

.. versionadded:: 1.6.0 subok : bool, optional. If True, then the newly created array will use the sub-class type of 'a', otherwise it will be a base-class array. Defaults to True. shape : int or sequence of ints, optional. Overrides the shape of the result. If order='K' and the number of dimensions is unchanged, will try to keep order, otherwise, order='C' is implied.

.. versionadded:: 1.17.0

Returns ------- out : ndarray Array of uninitialized (arbitrary) data with the same shape and type as `prototype`.

See Also -------- ones_like : Return an array of ones with shape and type of input. zeros_like : Return an array of zeros with shape and type of input. full_like : Return a new array with shape of input filled with value. empty : Return a new uninitialized array.

Notes ----- This function does *not* initialize the returned array; to do that use `zeros_like` or `ones_like` instead. It may be marginally faster than the functions that do set the array values.

Examples -------- >>> a = (1,2,3, 4,5,6) # a is array-like >>> np.empty_like(a) array([-1073741821, -1073741821, 3], # uninitialized [ 0, 0, -1073741821]) >>> a = np.array([1., 2., 3.],[4.,5.,6.]) >>> np.empty_like(a) array([ -2.00000715e+000, 1.48219694e-323, -2.00000572e+000], # uninitialized [ 4.38791518e-305, -2.00000715e+000, 4.17269252e-309])

equal(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Return (x1 == x2) element-wise.

Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Output array, element-wise comparison of `x1` and `x2`. Typically of type bool, unless ``dtype=object`` is passed. This is a scalar if both `x1` and `x2` are scalars.

See Also -------- not_equal, greater_equal, less_equal, greater, less

Examples -------- >>> np.equal(0, 1, 3, np.arange(3)) array( True, True, False)

What is compared are values, not types. So an int (1) and an array of length one can evaluate as True:

>>> np.equal(1, np.ones(1)) array( True)

exp(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Calculate the exponential of all elements in the input array.

Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Output array, element-wise exponential of `x`. This is a scalar if `x` is a scalar.

See Also -------- expm1 : Calculate ``exp(x) - 1`` for all elements in the array. exp2 : Calculate ``2**x`` for all elements in the array.

Notes ----- The irrational number ``e`` is also known as Euler's number. It is approximately 2.718281, and is the base of the natural logarithm, ``ln`` (this means that, if :math:`x = \ln y = \log_e y`, then :math:`e^x = y`. For real input, ``exp(x)`` is always positive.

For complex arguments, ``x = a + ib``, we can write :math:`e^x = e^a e^b`. The first term, :math:`e^a`, is already known (it is the real argument, described above). The second term, :math:`e^b`, is :math:`\cos b + i \sin b`, a function with magnitude 1 and a periodic phase.

References ---------- .. 1 Wikipedia, 'Exponential function', https://en.wikipedia.org/wiki/Exponential_function .. 2 M. Abramovitz and I. A. Stegun, 'Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables,' Dover, 1964, p. 69, http://www.math.sfu.ca/~cbm/aands/page_69.htm

Examples -------- Plot the magnitude and phase of ``exp(x)`` in the complex plane:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(-2*np.pi, 2*np.pi, 100) >>> xx = x + 1j * x:, np.newaxis # a + ib over complex plane >>> out = np.exp(xx)

>>> plt.subplot(121) >>> plt.imshow(np.abs(out), ... extent=-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi, cmap='gray') >>> plt.title('Magnitude of exp(x)')

>>> plt.subplot(122) >>> plt.imshow(np.angle(out), ... extent=-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi, cmap='hsv') >>> plt.title('Phase (angle) of exp(x)') >>> plt.show()

exp2(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Calculate `2**p` for all `p` in the input array.

Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Element-wise 2 to the power `x`. This is a scalar if `x` is a scalar.

See Also -------- power

Notes ----- .. versionadded:: 1.3.0

Examples -------- >>> np.exp2(2, 3) array( 4., 8.)

Expand the shape of an array.

Insert a new axis that will appear at the `axis` position in the expanded array shape.

Parameters ---------- a : array_like Input array. axis : int or tuple of ints Position in the expanded axes where the new axis (or axes) is placed.

.. deprecated:: 1.13.0 Passing an axis where ``axis > a.ndim`` will be treated as ``axis == a.ndim``, and passing ``axis < -a.ndim - 1`` will be treated as ``axis == 0``. This behavior is deprecated.

.. versionchanged:: 1.18.0 A tuple of axes is now supported. Out of range axes as described above are now forbidden and raise an `AxisError`.

Returns ------- result : ndarray View of `a` with the number of dimensions increased.

See Also -------- squeeze : The inverse operation, removing singleton dimensions reshape : Insert, remove, and combine dimensions, and resize existing ones doc.indexing, atleast_1d, atleast_2d, atleast_3d

Examples -------- >>> x = np.array(1, 2) >>> x.shape (2,)

The following is equivalent to ``xnp.newaxis, :`` or ``xnp.newaxis``:

>>> y = np.expand_dims(x, axis=0) >>> y array([1, 2]) >>> y.shape (1, 2)

The following is equivalent to ``x:, np.newaxis``:

>>> y = np.expand_dims(x, axis=1) >>> y array([1], [2]) >>> y.shape (2, 1)

``axis`` may also be a tuple:

>>> y = np.expand_dims(x, axis=(0, 1)) >>> y array([[1, 2]])

>>> y = np.expand_dims(x, axis=(2, 0)) >>> y array([[1], [2]])

Note that some examples may use ``None`` instead of ``np.newaxis``. These are the same objects:

>>> np.newaxis is None True

expm1(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Calculate ``exp(x) - 1`` for all elements in the array.

Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- out : ndarray or scalar Element-wise exponential minus one: ``out = exp(x) - 1``. This is a scalar if `x` is a scalar.

See Also -------- log1p : ``log(1 + x)``, the inverse of expm1.

Notes ----- This function provides greater precision than ``exp(x) - 1`` for small values of ``x``.

Examples -------- The true value of ``exp(1e-10) - 1`` is ``1.00000000005e-10`` to about 32 significant digits. This example shows the superiority of expm1 in this case.

>>> np.expm1(1e-10) 1.00000000005e-10 >>> np.exp(1e-10) - 1 1.000000082740371e-10

Return the elements of an array that satisfy some condition.

This is equivalent to ``np.compress(ravel(condition), ravel(arr))``. If `condition` is boolean ``np.extract`` is equivalent to ``arrcondition``.

Note that `place` does the exact opposite of `extract`.

Parameters ---------- condition : array_like An array whose nonzero or True entries indicate the elements of `arr` to extract. arr : array_like Input array of the same size as `condition`.

Returns ------- extract : ndarray Rank 1 array of values from `arr` where `condition` is True.

See Also -------- take, put, copyto, compress, place

Examples -------- >>> arr = np.arange(12).reshape((3, 4)) >>> arr array([ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]) >>> condition = np.mod(arr, 3)==0 >>> condition array([ True, False, False, True], [False, False, True, False], [False, True, False, False]) >>> np.extract(condition, arr) array(0, 3, 6, 9)

If `condition` is boolean:

>>> arrcondition array(0, 3, 6, 9)

Return a 2-D array with ones on the diagonal and zeros elsewhere.

Parameters ---------- N : int Number of rows in the output. M : int, optional Number of columns in the output. If None, defaults to `N`. k : int, optional Index of the diagonal: 0 (the default) refers to the main diagonal, a positive value refers to an upper diagonal, and a negative value to a lower diagonal. dtype : data-type, optional Data-type of the returned array. order : 'C', 'F', optional Whether the output should be stored in row-major (C-style) or column-major (Fortran-style) order in memory.

.. versionadded:: 1.14.0

Returns ------- I : ndarray of shape (N,M) An array where all elements are equal to zero, except for the `k`-th diagonal, whose values are equal to one.

See Also -------- identity : (almost) equivalent function diag : diagonal 2-D array from a 1-D array specified by the user.

Examples -------- >>> np.eye(2, dtype=int) array([1, 0], [0, 1]) >>> np.eye(3, k=1) array([0., 1., 0.], [0., 0., 1.], [0., 0., 0.])

fabs(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True, signature, extobj)

Compute the absolute values element-wise.

This function returns the absolute values (positive magnitude) of the data in `x`. Complex values are not handled, use `absolute` to find the absolute values of complex data.

Parameters ---------- x : array_like The array of numbers for which the absolute values are required. If `x` is a scalar, the result `y` will also be a scalar. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. where : array_like, optional This condition is broadcast over the input. At locations where the condition is True, the `out` array will be set to the ufunc result. Elsewhere, the `out` array will retain its original value. Note that if an uninitialized `out` array is created via the default ``out=None``, locations within it where the condition is False will remain uninitialized. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.

Returns ------- y : ndarray or scalar The absolute values of `x`, the returned values are always floats. This is a scalar if `x` is a scalar.

See Also -------- absolute : Absolute values including `complex` types.

Examples -------- >>> np.fabs(-1) 1.0 >>> np.fabs(-1.2, 1.2) array( 1.2, 1.2)

_fastCopyAndTranspose(a)