o Yi::@sddlmZddlZddlmZerddlmZmZgdZd*ddZ d+ddZ ddd,ddZ dddd-ddZ dd d.d#d$Z d/d&d'Zd0d(d)ZdS)1) annotationsN) TYPE_CHECKING)Array ModuleType) atleast_ndcovcreate_diagonal expand_dimskronsincxrndimintxprreturncCs*|j|kr|j|dd}t|||d}|S)a_ Recursively expand the dimension of an array to at least `ndim`. Parameters ---------- x : array ndim : int The minimum number of dimensions for the result. xp : array_namespace The standard-compatible namespace for `x`. Returns ------- res : array An array with ``res.ndim`` >= `ndim`. If ``x.ndim`` >= `ndim`, `x` is returned. If ``x.ndim`` < `ndim`, `x` is expanded by prepending new axes until ``res.ndim`` equals `ndim`. Examples -------- >>> import array_api_strict as xp >>> import array_api_extra as xpx >>> x = xp.asarray([1]) >>> xpx.atleast_nd(x, ndim=3, xp=xp) Array([[[1]]], dtype=array_api_strict.int64) >>> x = xp.asarray([[[1, 2], ... [3, 4]]]) >>> xpx.atleast_nd(x, ndim=1, xp=xp) is x True raxisrr)rr r)r rrrH/tmp/pip-target-1s0edx8b/lib/python/scipy/_lib/array_api_extra/_funcs.pyr s "rmcCs|j|dd}||jdr|jn|||j}t|d|d}|||}t|d|d}|jdd}|dkrAt j d t dd d }||d d d f8}|j }||jd rZ| |}||}||}tddt|jD}|j||dS)a Estimate a covariance matrix. 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_{ij}` is the covariance of :math:`x_i` and :math:`x_j`. The element :math:`C_{ii}` is the variance of :math:`x_i`. This provides a subset of the functionality of ``numpy.cov``. Parameters ---------- m : array 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. xp : array_namespace The standard-compatible namespace for `m`. Returns ------- res : array The covariance matrix of the variables. Examples -------- >>> import array_api_strict as xp >>> import array_api_extra as xpx Consider two variables, :math:`x_0` and :math:`x_1`, which correlate perfectly, but in opposite directions: >>> x = xp.asarray([[0, 2], [1, 1], [2, 0]]).T >>> x Array([[0, 1, 2], [2, 1, 0]], dtype=array_api_strict.int64) Note how :math:`x_0` increases while :math:`x_1` decreases. The covariance matrix shows this clearly: >>> xpx.cov(x, xp=xp) Array([[ 1., -1.], [-1., 1.]], dtype=array_api_strict.float64) Note that element :math:`C_{0,1}`, which shows the correlation between :math:`x_0` and :math:`x_1`, is negative. Further, note how `x` and `y` are combined: >>> x = xp.asarray([-2.1, -1, 4.3]) >>> y = xp.asarray([3, 1.1, 0.12]) >>> X = xp.stack((x, y), axis=0) >>> xpx.cov(X, xp=xp) Array([[11.71 , -4.286 ], [-4.286 , 2.14413333]], dtype=array_api_strict.float64) >>> xpx.cov(x, xp=xp) Array(11.71, dtype=array_api_strict.float64) >>> xpx.cov(y, xp=xp) Array(2.14413333, dtype=array_api_strict.float64) T)copyintegralrrrrrz!Degrees of freedom <= 0 for slice) stacklevelgNcomplex floatingcss |] \}}|dkr|VqdS)rNr).0rlengthrrr szcov..r)asarrayisdtypedtypefloat64 result_typerastype_meanshapewarningswarnRuntimeWarningTconjtuple enumeratesqueeze)rrr#avgfact m_transposecaxesrrrr4s$B   r)offsetr6cCs|jdkr d}t||jdt|}|j|d|jd}|dkr$|nt||}|||t||||jd|d<||||fS)a Construct a diagonal array. Parameters ---------- x : array A 1-D array offset : int, optional Offset from the leading diagonal (default is ``0``). Use positive ints for diagonals above the leading diagonal, and negative ints for diagonals below the leading diagonal. xp : array_namespace The standard-compatible namespace for `x`. Returns ------- res : array A 2-D array with `x` on the diagonal (offset by `offset`). Examples -------- >>> import array_api_strict as xp >>> import array_api_extra as xpx >>> x = xp.asarray([2, 4, 8]) >>> xpx.create_diagonal(x, xp=xp) Array([[2, 0, 0], [0, 4, 0], [0, 0, 8]], dtype=array_api_strict.int64) >>> xpx.create_diagonal(x, offset=-2, xp=xp) Array([[0, 0, 0, 0, 0], [0, 0, 0, 0, 0], [2, 0, 0, 0, 0], [0, 4, 0, 0, 0], [0, 0, 8, 0, 0]], dtype=array_api_strict.int64) rz`x` must be 1-dimensional.rrr#)r ValueErrorr(abszerosr#minreshape)r r6rerr_msgndiagirrrr s '&r Frkeepdimsrint | tuple[int, ...] | NonerBboolcCsd||jdr*||}||}|j|||d}|j|||d}|||dS|j|||dS)zJ Complex mean, https://github.com/data-apis/array-api/issues/846. rrAy?)r"r#realimagmeanr!)r rrBrx_realx_imag mean_real mean_imagrrrr's  r')rraint | tuple[int, ...]cst|ts|f}|jt||dkr*t| ks t|kr*d|j}t|tfdd|D}tt|t|krEd}t|t |D] }|j ||d}qI|S)a Expand the shape of an array. Insert (a) new axis/axes that will appear at the position(s) specified by `axis` in the expanded array shape. This is ``xp.expand_dims`` for `axis` an int *or a tuple of ints*. Roughly equivalent to ``numpy.expand_dims`` for NumPy arrays. Parameters ---------- a : array axis : int or tuple of ints, optional Position(s) in the expanded axes where the new axis (or axes) is/are placed. If multiple positions are provided, they should be unique (note that a position given by a positive index could also be referred to by a negative index - that will also result in an error). Default: ``(0,)``. xp : array_namespace The standard-compatible namespace for `a`. Returns ------- res : array `a` with an expanded shape. Examples -------- >>> import array_api_strict as xp >>> import array_api_extra as xpx >>> x = xp.asarray([1, 2]) >>> x.shape (2,) The following is equivalent to ``x[xp.newaxis, :]`` or ``x[xp.newaxis]``: >>> y = xpx.expand_dims(x, axis=0, xp=xp) >>> y Array([[1, 2]], dtype=array_api_strict.int64) >>> y.shape (1, 2) The following is equivalent to ``x[:, xp.newaxis]``: >>> y = xpx.expand_dims(x, axis=1, xp=xp) >>> y Array([[1], [2]], dtype=array_api_strict.int64) >>> y.shape (2, 1) ``axis`` may also be a tuple: >>> y = xpx.expand_dims(x, axis=(0, 1), xp=xp) >>> y Array([[[1, 2]]], dtype=array_api_strict.int64) >>> y = xpx.expand_dims(x, axis=(2, 0), xp=xp) >>> y Array([[[1], [2]]], dtype=array_api_strict.int64) rzAa provided axis position is out of bounds for array of dimension c3s|]}|VqdS)Nr)rdimrrrr szexpand_dims..z)Duplicate dimensions specified in `axis`.r) isinstancer.rlenr;max IndexErrorsetr8sortedr )rLrrr=r@rrOrr s B"  r bc CsF||}d|j|j}|||||j}|j|j}}t||}|dks-|dkr3|||S|j}|j}dtd|||}dtd|||}t|tt|||d} t|tt|||d} t| ttd|dd|d} t| ttd|dd|d} || | } ||}||}| | t|||S)a Kronecker product of two arrays. Computes the Kronecker product, a composite array made of blocks of the second array scaled by the first. Equivalent to ``numpy.kron`` for NumPy arrays. Parameters ---------- a, b : array xp : array_namespace The standard-compatible namespace for `a` and `b`. Returns ------- res : array The Kronecker product of `a` and `b`. Notes ----- The function assumes that the number of dimensions of `a` and `b` are the same, if necessary prepending the smallest with ones. If ``a.shape = (r0,r1,..,rN)`` and ``b.shape = (s0,s1,...,sN)``, the Kronecker product has shape ``(r0*s0, r1*s1, ..., rN*SN)``. The elements are products of elements from `a` and `b`, organized explicitly by:: kron(a,b)[k0,k1,...,kN] = a[i0,i1,...,iN] * b[j0,j1,...,jN] where:: kt = it * st + jt, t = 0,...,N In the common 2-D case (N=1), the block structure can be visualized:: [[ a[0,0]*b, a[0,1]*b, ... , a[0,-1]*b ], [ ... ... ], [ a[-1,0]*b, a[-1,1]*b, ... , a[-1,-1]*b ]] Examples -------- >>> import array_api_strict as xp >>> import array_api_extra as xpx >>> xpx.kron(xp.asarray([1, 10, 100]), xp.asarray([5, 6, 7]), xp=xp) Array([ 5, 6, 7, 50, 60, 70, 500, 600, 700], dtype=array_api_strict.int64) >>> xpx.kron(xp.asarray([5, 6, 7]), xp.asarray([1, 10, 100]), xp=xp) Array([ 5, 50, 500, 6, 60, 600, 7, 70, 700], dtype=array_api_strict.int64) >>> xpx.kron(xp.eye(2), xp.ones((2, 2)), xp=xp) Array([[1., 1., 0., 0.], [1., 1., 0., 0.], [0., 0., 1., 1.], [0., 0., 1., 1.]], dtype=array_api_strict.float64) >>> a = xp.reshape(xp.arange(100), (2, 5, 2, 5)) >>> b = xp.reshape(xp.arange(24), (2, 3, 4)) >>> c = xpx.kron(a, b, xp=xp) >>> c.shape (2, 10, 6, 20) >>> I = (1, 3, 0, 2) >>> J = (0, 2, 1) >>> J1 = (0,) + J # extend to ndim=4 >>> S1 = (1,) + b.shape >>> K = tuple(xp.asarray(I) * xp.asarray(S1) + xp.asarray(J1)) >>> c[K] == a[I]*b[J] Array(True, dtype=array_api_strict.bool) )rrrrr) r!r broadcast_tor(rRmultiplyr r.ranger<) rLrVr singletonsnd_bnd_and_maxa_shapeb_shapea_arrb_arrresultrrrr 's& L     r c CsR||jds d}t||j||||j||jj|jd}|||S)a Return the normalized sinc function. The sinc function is equal to :math:`\sin(\pi x)/(\pi x)` for any argument :math:`x\ne 0`. ``sinc(0)`` takes the limit value 1, making ``sinc`` not only everywhere continuous but also infinitely differentiable. .. note:: Note the normalization factor of ``pi`` used in the definition. This is the most commonly used definition in signal processing. Use ``sinc(x / xp.pi)`` to obtain the unnormalized sinc function :math:`\sin(x)/x` that is more common in mathematics. Parameters ---------- x : array Array (possibly multi-dimensional) of values for which to calculate ``sinc(x)``. Must have a real floating point dtype. xp : array_namespace The standard-compatible namespace for `x`. Returns ------- res : array ``sinc(x)`` calculated elementwise, which has the same shape as the input. Notes ----- The name sinc is short for "sine cardinal" or "sinus cardinalis". The sinc function is used in various signal processing applications, including in anti-aliasing, in the construction of a Lanczos resampling filter, and in interpolation. For bandlimited interpolation of discrete-time signals, the ideal interpolation kernel is proportional to the sinc function. References ---------- .. [1] Weisstein, Eric W. "Sinc Function." From MathWorld--A Wolfram Web Resource. https://mathworld.wolfram.com/SincFunction.html .. [2] Wikipedia, "Sinc function", https://en.wikipedia.org/wiki/Sinc_function Examples -------- >>> import array_api_strict as xp >>> import array_api_extra as xpx >>> x = xp.linspace(-4, 4, 41) >>> xpx.sinc(x, xp=xp) Array([-3.89817183e-17, -4.92362781e-02, -8.40918587e-02, -8.90384387e-02, -5.84680802e-02, 3.89817183e-17, 6.68206631e-02, 1.16434881e-01, 1.26137788e-01, 8.50444803e-02, -3.89817183e-17, -1.03943254e-01, -1.89206682e-01, -2.16236208e-01, -1.55914881e-01, 3.89817183e-17, 2.33872321e-01, 5.04551152e-01, 7.56826729e-01, 9.35489284e-01, 1.00000000e+00, 9.35489284e-01, 7.56826729e-01, 5.04551152e-01, 2.33872321e-01, 3.89817183e-17, -1.55914881e-01, -2.16236208e-01, -1.89206682e-01, -1.03943254e-01, -3.89817183e-17, 8.50444803e-02, 1.26137788e-01, 1.16434881e-01, 6.68206631e-02, 3.89817183e-17, -5.84680802e-02, -8.90384387e-02, -8.40918587e-02, -4.92362781e-02, -3.89817183e-17], dtype=array_api_strict.float64) z real floatingz(`x` must have a real floating data type.r7) r"r#r8piwherer!finfosmallest_normalsin)r rr=yrrrr sKr )r rrrrrrr)rrrrrr)r rr6rrrrr) r rrrCrBrDrrrr)rLrrrMrrrr)rLrrVrrrrr)r rrrrr) __future__rr)typingr_typingrr__all__rrr r'r r r rrrrs    ([5 Sk