package scipy

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

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()

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

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.maximum(a_min, np.minimum(a, a_max))``. 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)

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])

Construct the sigma matrix in SVD from singular values and size M, N.

Parameters ---------- s : (M,) or (N,) array_like Singular values M : int Size of the matrix whose singular values are `s`. N : int Size of the matrix whose singular values are `s`.

Returns ------- S : (M, N) ndarray The S-matrix in the singular value decomposition

See Also -------- svd : Singular value decomposition of a matrix svdvals : Compute singular values of a matrix.

Examples -------- >>> from scipy.linalg import diagsvd >>> vals = np.array(1, 2, 3) # The array representing the computed svd >>> diagsvd(vals, 3, 4) array([1, 0, 0, 0], [0, 2, 0, 0], [0, 0, 3, 0]) >>> diagsvd(vals, 4, 3) array([1, 0, 0], [0, 2, 0], [0, 0, 3], [0, 0, 0])

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

Return available LAPACK function objects from names.

Arrays are used to determine the optimal prefix of LAPACK routines.

Parameters ---------- names : str or sequence of str Name(s) of LAPACK functions without type prefix.

arrays : sequence of ndarrays, optional Arrays can be given to determine optimal prefix of LAPACK routines. If not given, double-precision routines will be used, otherwise the most generic type in arrays will be used.

dtype : str or dtype, optional Data-type specifier. Not used if `arrays` is non-empty.

Returns ------- funcs : list List containing the found function(s).

Notes ----- This routine automatically chooses between Fortran/C interfaces. Fortran code is used whenever possible for arrays with column major order. In all other cases, C code is preferred.

In LAPACK, the naming convention is that all functions start with a type prefix, which depends on the type of the principal matrix. These can be one of 's', 'd', 'c', 'z' for the numpy types float32, float64, complex64, complex128 respectively, and are stored in attribute ``typecode`` of the returned functions.

Examples -------- Suppose we would like to use '?lange' routine which computes the selected norm of an array. We pass our array in order to get the correct 'lange' flavor.

>>> import scipy.linalg as LA >>> a = np.random.rand(3,2) >>> x_lange = LA.get_lapack_funcs('lange', (a,)) >>> x_lange.typecode 'd' >>> x_lange = LA.get_lapack_funcs('lange',(a*1j,)) >>> x_lange.typecode 'z'

Several LAPACK routines work best when its internal WORK array has the optimal size (big enough for fast computation and small enough to avoid waste of memory). This size is determined also by a dedicated query to the function which is often wrapped as a standalone function and commonly denoted as ``###_lwork``. Below is an example for ``?sysv``

>>> import scipy.linalg as LA >>> a = np.random.rand(1000,1000) >>> b = np.random.rand(1000,1)*1j >>> # We pick up zsysv and zsysv_lwork due to b array ... xsysv, xlwork = LA.get_lapack_funcs(('sysv', 'sysv_lwork'), (a, b)) >>> opt_lwork, _ = xlwork(a.shape0) # returns a complex for 'z' prefix >>> udut, ipiv, x, info = xsysv(a, b, lwork=int(opt_lwork.real))

Construct an orthonormal basis for the null space of A using SVD

Parameters ---------- A : (M, N) array_like Input array rcond : float, optional Relative condition number. Singular values ``s`` smaller than ``rcond * max(s)`` are considered zero. Default: floating point eps * max(M,N).

Returns ------- Z : (N, K) ndarray Orthonormal basis for the null space of A. K = dimension of effective null space, as determined by rcond

See also -------- svd : Singular value decomposition of a matrix orth : Matrix range

Examples -------- One-dimensional null space:

>>> from scipy.linalg import null_space >>> A = np.array([1, 1], [1, 1]) >>> ns = null_space(A) >>> ns * np.sign(ns0,0) # Remove the sign ambiguity of the vector array([ 0.70710678], [-0.70710678])

Two-dimensional null space:

>>> B = np.random.rand(3, 5) >>> Z = null_space(B) >>> Z.shape (5, 2) >>> np.allclose(B.dot(Z), 0) True

The basis vectors are orthonormal (up to rounding error):

>>> Z.T.dot(Z) array([ 1.00000000e+00, 6.92087741e-17], [ 6.92087741e-17, 1.00000000e+00])

Construct an orthonormal basis for the range of A using SVD

Parameters ---------- A : (M, N) array_like Input array rcond : float, optional Relative condition number. Singular values ``s`` smaller than ``rcond * max(s)`` are considered zero. Default: floating point eps * max(M,N).

Returns ------- Q : (M, K) ndarray Orthonormal basis for the range of A. K = effective rank of A, as determined by rcond

See also -------- svd : Singular value decomposition of a matrix null_space : Matrix null space

Examples -------- >>> from scipy.linalg import orth >>> A = np.array([2, 0, 0], [0, 5, 0]) # rank 2 array >>> orth(A) array([0., 1.], [1., 0.]) >>> orth(A.T) array([0., 1.], [1., 0.], [0., 0.])

Compute the subspace angles between two matrices.

Parameters ---------- A : (M, N) array_like The first input array. B : (M, K) array_like The second input array.

Returns ------- angles : ndarray, shape (min(N, K),) The subspace angles between the column spaces of `A` and `B` in descending order.

See Also -------- orth svd

Notes ----- This computes the subspace angles according to the formula provided in 1_. For equivalence with MATLAB and Octave behavior, use ``angles0``.

.. versionadded:: 1.0

References ---------- .. 1 Knyazev A, Argentati M (2002) Principal Angles between Subspaces in an A-Based Scalar Product: Algorithms and Perturbation Estimates. SIAM J. Sci. Comput. 23:2008-2040.

Examples -------- A Hadamard matrix, which has orthogonal columns, so we expect that the suspace angle to be :math:`\frac\pi

`:

>>> from scipy.linalg import hadamard, subspace_angles >>> H = hadamard(4) >>> print(H) [ 1 1 1 1] [ 1 -1 1 -1] [ 1 1 -1 -1] [ 1 -1 -1 1] >>> np.rad2deg(subspace_angles(H:, :2, H:, 2:)) array( 90., 90.)

And the subspace angle of a matrix to itself should be zero:

>>> subspace_angles(H:, :2, H:, :2) <= 2 * np.finfo(float).eps array( True, True, dtype=bool)

The angles between non-orthogonal subspaces are in between these extremes:

>>> x = np.random.RandomState(0).randn(4, 3) >>> np.rad2deg(subspace_angles(x:, :2, x:, [2])) array( 55.832)

Singular Value Decomposition.

Factorizes the matrix `a` into two unitary matrices ``U`` and ``Vh``, and a 1-D array ``s`` of singular values (real, non-negative) such that ``a == U @ S @ Vh``, where ``S`` is a suitably shaped matrix of zeros with main diagonal ``s``.

Parameters ---------- a : (M, N) array_like Matrix to decompose. full_matrices : bool, optional If True (default), `U` and `Vh` are of shape ``(M, M)``, ``(N, N)``. If False, the shapes are ``(M, K)`` and ``(K, N)``, where ``K = min(M, N)``. compute_uv : bool, optional Whether to compute also ``U`` and ``Vh`` in addition to ``s``. Default is True. overwrite_a : bool, optional Whether to overwrite `a`; may improve performance. Default is False. check_finite : bool, optional Whether to check that the input matrix contains only finite numbers. Disabling may give a performance gain, but may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs. lapack_driver : 'gesdd', 'gesvd', optional Whether to use the more efficient divide-and-conquer approach (``'gesdd'``) or general rectangular approach (``'gesvd'``) to compute the SVD. MATLAB and Octave use the ``'gesvd'`` approach. Default is ``'gesdd'``.

.. versionadded:: 0.18

Returns ------- U : ndarray Unitary matrix having left singular vectors as columns. Of shape ``(M, M)`` or ``(M, K)``, depending on `full_matrices`. s : ndarray The singular values, sorted in non-increasing order. Of shape (K,), with ``K = min(M, N)``. Vh : ndarray Unitary matrix having right singular vectors as rows. Of shape ``(N, N)`` or ``(K, N)`` depending on `full_matrices`.

For ``compute_uv=False``, only ``s`` is returned.

Raises ------ LinAlgError If SVD computation does not converge.

See also -------- svdvals : Compute singular values of a matrix. diagsvd : Construct the Sigma matrix, given the vector s.

Examples -------- >>> from scipy import linalg >>> m, n = 9, 6 >>> a = np.random.randn(m, n) + 1.j*np.random.randn(m, n) >>> U, s, Vh = linalg.svd(a) >>> U.shape, s.shape, Vh.shape ((9, 9), (6,), (6, 6))

Reconstruct the original matrix from the decomposition:

>>> sigma = np.zeros((m, n)) >>> for i in range(min(m, n)): ... sigmai, i = si >>> a1 = np.dot(U, np.dot(sigma, Vh)) >>> np.allclose(a, a1) True

Alternatively, use ``full_matrices=False`` (notice that the shape of ``U`` is then ``(m, n)`` instead of ``(m, m)``):

>>> U, s, Vh = linalg.svd(a, full_matrices=False) >>> U.shape, s.shape, Vh.shape ((9, 6), (6,), (6, 6)) >>> S = np.diag(s) >>> np.allclose(a, np.dot(U, np.dot(S, Vh))) True

>>> s2 = linalg.svd(a, compute_uv=False) >>> np.allclose(s, s2) True

Compute singular values of a matrix.

Parameters ---------- a : (M, N) array_like Matrix to decompose. overwrite_a : bool, optional Whether to overwrite `a`; may improve performance. Default is False. check_finite : bool, optional Whether to check that the input matrix contains only finite numbers. Disabling may give a performance gain, but may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs.

Returns ------- s : (min(M, N),) ndarray The singular values, sorted in decreasing order.

Raises ------ LinAlgError If SVD computation does not converge.

Notes ----- ``svdvals(a)`` only differs from ``svd(a, compute_uv=False)`` by its handling of the edge case of empty ``a``, where it returns an empty sequence:

>>> a = np.empty((0, 2)) >>> from scipy.linalg import svdvals >>> svdvals(a) array(, dtype=float64)

See Also -------- svd : Compute the full singular value decomposition of a matrix. diagsvd : Construct the Sigma matrix, given the vector s.

Examples -------- >>> from scipy.linalg import svdvals >>> m = np.array([1.0, 0.0], ... [2.0, 3.0], ... [1.0, 1.0], ... [0.0, 2.0], ... [1.0, 0.0]) >>> svdvals(m) array( 4.28091555, 1.63516424)

We can verify the maximum singular value of `m` by computing the maximum length of `m.dot(u)` over all the unit vectors `u` in the (x,y) plane. We approximate 'all' the unit vectors with a large sample. Because of linearity, we only need the unit vectors with angles in 0, pi.

>>> t = np.linspace(0, np.pi, 2000) >>> u = np.array(np.cos(t), np.sin(t)) >>> np.linalg.norm(m.dot(u), axis=0).max() 4.2809152422538475

`p` is a projection matrix with rank 1. With exact arithmetic, its singular values would be 1, 0, 0, 0.

>>> v = np.array(0.1, 0.3, 0.9, 0.3) >>> p = np.outer(v, v) >>> svdvals(p) array( 1.00000000e+00, 2.02021698e-17, 1.56692500e-17, 8.15115104e-34)

The singular values of an orthogonal matrix are all 1. Here we create a random orthogonal matrix by using the `rvs()` method of `scipy.stats.ortho_group`.

>>> from scipy.stats import ortho_group >>> np.random.seed(123) >>> orth = ortho_group.rvs(4) >>> svdvals(orth) array( 1., 1., 1., 1.)

where(condition, x, y)

Return elements chosen from `x` or `y` depending on `condition`.

.. note:: When only `condition` is provided, this function is a shorthand for ``np.asarray(condition).nonzero()``. Using `nonzero` directly should be preferred, as it behaves correctly for subclasses. The rest of this documentation covers only the case where all three arguments are provided.

Parameters ---------- condition : array_like, bool Where True, yield `x`, otherwise yield `y`. x, y : array_like Values from which to choose. `x`, `y` and `condition` need to be broadcastable to some shape.

Returns ------- out : ndarray An array with elements from `x` where `condition` is True, and elements from `y` elsewhere.

See Also -------- choose nonzero : The function that is called when x and y are omitted

Notes ----- If all the arrays are 1-D, `where` is equivalent to::

xv if c else yv for c, xv, yv in zip(condition, x, y)

Examples -------- >>> a = np.arange(10) >>> a array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) >>> np.where(a < 5, a, 10*a) array( 0, 1, 2, 3, 4, 50, 60, 70, 80, 90)

This can be used on multidimensional arrays too:

>>> np.where([True, False], [True, True], ... [1, 2], [3, 4], ... [9, 8], [7, 6]) array([1, 8], [3, 4])

The shapes of x, y, and the condition are broadcast together:

>>> x, y = np.ogrid:3, :4 >>> np.where(x < y, x, 10 + y) # both x and 10+y are broadcast array([10, 0, 0, 0], [10, 11, 1, 1], [10, 11, 12, 2])

>>> a = np.array([0, 1, 2], ... [0, 2, 4], ... [0, 3, 6]) >>> np.where(a < 4, a, -1) # -1 is broadcast array([ 0, 1, 2], [ 0, 2, -1], [ 0, 3, -1])

zeros(shape, dtype=float, order='C')

Return a new array of given shape and type, filled with zeros.

Parameters ---------- shape : int or tuple of ints Shape of the new array, e.g., ``(2, 3)`` or ``2``. dtype : data-type, optional The desired 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 zeros with the given shape, dtype, and order.

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

Examples -------- >>> np.zeros(5) array( 0., 0., 0., 0., 0.)

>>> np.zeros((5,), dtype=int) array(0, 0, 0, 0, 0)

>>> np.zeros((2, 1)) array([ 0.], [ 0.])

>>> s = (2,2) >>> np.zeros(s) array([ 0., 0.], [ 0., 0.])

>>> np.zeros((2,), dtype=('x', 'i4'), ('y', 'i4')) # custom dtype array((0, 0), (0, 0), dtype=('x', '<i4'), ('y', '<i4'))