import builtins

import functools

import itertools

import math

import numbers

import operator

import sys

import warnings

import numpy as np

from numpy.exceptions import AxisError

from . import multiarray, numerictypes, numerictypes as nt, overrides, shape_base, umath

from ._ufunc_config import errstate

from .multiarray import ( # noqa: F401

ALLOW_THREADS,

BUFSIZE,

CLIP,

MAXDIMS,

MAY_SHARE_BOUNDS,

MAY_SHARE_EXACT,

RAISE,

WRAP,

arange,

array,

asanyarray,

asarray,

ascontiguousarray,

asfortranarray,

broadcast,

can_cast,

concatenate,

copyto,

dot,

dtype,

empty,

empty_like,

flatiter,

from_dlpack,

frombuffer,

fromfile,

fromiter,

fromstring,

inner,

lexsort,

matmul,

may_share_memory,

min_scalar_type,

ndarray,

nditer,

nested_iters,

normalize_axis_index,

promote_types,

putmask,

result_type,

shares_memory,

vdot,

vecdot,

where,

zeros,

)

from .overrides import finalize_array_function_like, set_module

from .umath import NAN, PINF, invert, multiply, sin

bitwise_not = invert

ufunc = type(sin)

newaxis = None

array_function_dispatch = functools.partial(

overrides.array_function_dispatch, module='numpy')

__all__ = [

'newaxis', 'ndarray', 'flatiter', 'nditer', 'nested_iters', 'ufunc',

'arange', 'array', 'asarray', 'asanyarray', 'ascontiguousarray',

'asfortranarray', 'zeros', 'count_nonzero', 'empty', 'broadcast', 'dtype',

'fromstring', 'fromfile', 'frombuffer', 'from_dlpack', 'where',

'argwhere', 'copyto', 'concatenate', 'lexsort', 'astype',

'can_cast', 'promote_types', 'min_scalar_type',

'result_type', 'isfortran', 'empty_like', 'zeros_like', 'ones_like',

'correlate', 'convolve', 'inner', 'dot', 'outer', 'vdot', 'roll',

'rollaxis', 'moveaxis', 'cross', 'tensordot', 'little_endian',

'fromiter', 'array_equal', 'array_equiv', 'indices', 'fromfunction',

'isclose', 'isscalar', 'binary_repr', 'base_repr', 'ones',

'identity', 'allclose', 'putmask',

'flatnonzero', 'inf', 'nan', 'False_', 'True_', 'bitwise_not',

'full', 'full_like', 'matmul', 'vecdot', 'shares_memory',

'may_share_memory']

def _zeros_like_dispatcher(

a, dtype=None, order=None, subok=None, shape=None, *, device=None

):

return (a,)

@array_function_dispatch(_zeros_like_dispatcher)

def zeros_like(

a, dtype=None, order='K', subok=True, shape=None, *, device=None

):

"""

Return an array of zeros with the same shape and type as a given array.

Parameters

----------

a : array_like

The shape and data-type of `a` define these same attributes of

the returned array.

dtype : data-type, optional

Overrides the data type of the result.

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 `a` is Fortran contiguous,

'C' otherwise. 'K' means match the layout of `a` as closely

as possible.

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.

device : str, optional

The device on which to place the created array. Default: None.

For Array-API interoperability only, so must be ``"cpu"`` if passed.

.. versionadded:: 2.0.0

Returns

-------

out : ndarray

Array of zeros with the same shape and type as `a`.

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.

full_like : Return a new array with shape of input filled with value.

zeros : Return a new array setting values to zero.

Examples

--------

>>> import numpy as np

>>> x = np.arange(6)

>>> x = x.reshape((2, 3))

>>> x

array([[0, 1, 2],

[3, 4, 5]])

>>> np.zeros_like(x)

array([[0, 0, 0],

[0, 0, 0]])

>>> y = np.arange(3, dtype=np.float64)

>>> y

array([0., 1., 2.])

>>> np.zeros_like(y)

array([0., 0., 0.])

"""

res = empty_like(

a, dtype=dtype, order=order, subok=subok, shape=shape, device=device

)

# needed instead of a 0 to get same result as zeros for string dtypes

z = zeros(1, dtype=res.dtype)

multiarray.copyto(res, z, casting='unsafe')

return res

@finalize_array_function_like

@set_module('numpy')

def ones(shape, dtype=None, order='C', *, device=None, like=None):

"""

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

Parameters

----------

shape : int or sequence 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.

device : str, optional

The device on which to place the created array. Default: None.

For Array-API interoperability only, so must be ``"cpu"`` if passed.

.. versionadded:: 2.0.0

${ARRAY_FUNCTION_LIKE}

Returns

-------

out : ndarray

Array of ones with the given shape, dtype, and order.

See Also

--------

ones_like : Return an array of ones with shape and type of input.

empty : Return a new uninitialized array.

zeros : Return a new array setting values to zero.

full : Return a new array of given shape filled with value.

Examples

--------

>>> import numpy as np

>>> np.ones(5)

array([1., 1., 1., 1., 1.])

>>> np.ones((5,), dtype=np.int_)

array([1, 1, 1, 1, 1])

>>> np.ones((2, 1))

array([[1.],

[1.]])

>>> s = (2,2)

>>> np.ones(s)

array([[1., 1.],

[1., 1.]])

"""

if like is not None:

return _ones_with_like(

like, shape, dtype=dtype, order=order, device=device

)

a = empty(shape, dtype, order, device=device)

multiarray.copyto(a, 1, casting='unsafe')

return a

_ones_with_like = array_function_dispatch()(ones)

def _ones_like_dispatcher(

a, dtype=None, order=None, subok=None, shape=None, *, device=None

):

return (a,)

@array_function_dispatch(_ones_like_dispatcher)

def ones_like(

a, dtype=None, order='K', subok=True, shape=None, *, device=None

):

"""

Return an array of ones with the same shape and type as a given array.

Parameters

----------

a : array_like

The shape and data-type of `a` define these same attributes of

the returned array.

dtype : data-type, optional

Overrides the data type of the result.

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 `a` is Fortran contiguous,

'C' otherwise. 'K' means match the layout of `a` as closely

as possible.

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.

device : str, optional

The device on which to place the created array. Default: None.

For Array-API interoperability only, so must be ``"cpu"`` if passed.

.. versionadded:: 2.0.0

Returns

-------

out : ndarray

Array of ones with the same shape and type as `a`.

See Also

--------

empty_like : Return an empty array 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.

ones : Return a new array setting values to one.

Examples

--------

>>> import numpy as np

>>> x = np.arange(6)

>>> x = x.reshape((2, 3))

>>> x

array([[0, 1, 2],

[3, 4, 5]])

>>> np.ones_like(x)

array([[1, 1, 1],

[1, 1, 1]])

>>> y = np.arange(3, dtype=np.float64)

>>> y

array([0., 1., 2.])

>>> np.ones_like(y)

array([1., 1., 1.])

"""

res = empty_like(

a, dtype=dtype, order=order, subok=subok, shape=shape, device=device

)

multiarray.copyto(res, 1, casting='unsafe')

return res

def _full_dispatcher(

shape, fill_value, dtype=None, order=None, *, device=None, like=None

):

return (like,)

@finalize_array_function_like

@set_module('numpy')

def full(shape, fill_value, dtype=None, order='C', *, device=None, like=None):

"""

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

Parameters

----------

shape : int or sequence of ints

Shape of the new array, e.g., ``(2, 3)`` or ``2``.

fill_value : scalar or array_like

Fill value.

dtype : data-type, optional

The desired data-type for the array The default, None, means

``np.array(fill_value).dtype``.

order : {'C', 'F'}, optional

Whether to store multidimensional data in C- or Fortran-contiguous

(row- or column-wise) order in memory.

device : str, optional

The device on which to place the created array. Default: None.

For Array-API interoperability only, so must be ``"cpu"`` if passed.

.. versionadded:: 2.0.0

${ARRAY_FUNCTION_LIKE}

Returns

-------

out : ndarray

Array of `fill_value` with the given shape, dtype, and order.

See Also

--------

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.

Examples

--------

>>> import numpy as np

>>> np.full((2, 2), np.inf)

array([[inf, inf],

[inf, inf]])

>>> np.full((2, 2), 10)

array([[10, 10],

[10, 10]])

>>> np.full((2, 2), [1, 2])

array([[1, 2],

[1, 2]])

"""

if like is not None:

return _full_with_like(

like, shape, fill_value, dtype=dtype, order=order, device=device

)

if dtype is None:

fill_value = asarray(fill_value)

dtype = fill_value.dtype

a = empty(shape, dtype, order, device=device)

multiarray.copyto(a, fill_value, casting='unsafe')

return a

_full_with_like = array_function_dispatch()(full)

def _full_like_dispatcher(

a, fill_value, dtype=None, order=None, subok=None, shape=None,

*, device=None

):

return (a,)

@array_function_dispatch(_full_like_dispatcher)

def full_like(

a, fill_value, dtype=None, order='K', subok=True, shape=None,

*, device=None

):

"""

Return a full array with the same shape and type as a given array.

Parameters

----------

a : array_like

The shape and data-type of `a` define these same attributes of

the returned array.

fill_value : array_like

Fill value.

dtype : data-type, optional

Overrides the data type of the result.

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 `a` is Fortran contiguous,

'C' otherwise. 'K' means match the layout of `a` as closely

as possible.

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.

device : str, optional

The device on which to place the created array. Default: None.

For Array-API interoperability only, so must be ``"cpu"`` if passed.

.. versionadded:: 2.0.0

Returns

-------

out : ndarray

Array of `fill_value` with the same shape and type as `a`.

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 : Return a new array of given shape filled with value.

Examples

--------

>>> import numpy as np

>>> x = np.arange(6, dtype=np.int_)

>>> np.full_like(x, 1)

array([1, 1, 1, 1, 1, 1])

>>> np.full_like(x, 0.1)

array([0, 0, 0, 0, 0, 0])

>>> np.full_like(x, 0.1, dtype=np.float64)

array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1])

>>> np.full_like(x, np.nan, dtype=np.float64)

array([nan, nan, nan, nan, nan, nan])

>>> y = np.arange(6, dtype=np.float64)

>>> np.full_like(y, 0.1)

array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1])

>>> y = np.zeros([2, 2, 3], dtype=np.int_)

>>> np.full_like(y, [0, 0, 255])

array([[[ 0, 0, 255],

[ 0, 0, 255]],

[[ 0, 0, 255],

[ 0, 0, 255]]])

"""

res = empty_like(

a, dtype=dtype, order=order, subok=subok, shape=shape, device=device

)

multiarray.copyto(res, fill_value, casting='unsafe')

return res

def _count_nonzero_dispatcher(a, axis=None, *, keepdims=None):

return (a,)

@array_function_dispatch(_count_nonzero_dispatcher)

def count_nonzero(a, axis=None, *, keepdims=False):

"""

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

A non-zero value is one that evaluates to truthful in a boolean

context, including any non-zero number and any string that

is not empty. This function recursively counts how many elements

in ``a`` (and its sub-arrays) are non-zero values.

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``.

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.

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

--------

>>> import numpy as np

>>> np.count_nonzero(np.eye(4))

np.int64(4)

>>> a = np.array([[0, 1, 7, 0],

... [3, 0, 2, 19]])

>>> np.count_nonzero(a)

np.int64(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]])

"""

if axis is None and not keepdims:

return multiarray.count_nonzero(a)

a = asanyarray(a)

# This is a performance optimization for character dtypes

# TODO: this can be removed if the legacy fixed-width string dtypes are ever removed

if np.issubdtype(a.dtype, np.character):

a_bool = a != a.dtype.type()

else:

a_bool = a.astype(np.bool, copy=False)

return a_bool.sum(axis=axis, dtype=np.intp, keepdims=keepdims)

@set_module('numpy')

def isfortran(a):

"""

Check if the array is Fortran contiguous but *not* C contiguous.

.. deprecated:: 2.6

`numpy.isfortran` is deprecated. Use ``a.flags.fnc`` instead, or

``a.flags.f_contiguous`` if you only need to check for Fortran

contiguity.

Parameters

----------

a : ndarray

Input array.

Returns

-------

isfortran : bool

Returns True if the array is Fortran contiguous but *not* C contiguous.

Examples

--------

np.array allows to specify whether the array is written in C-contiguous

order (last index varies the fastest), or FORTRAN-contiguous order in

memory (first index varies the fastest).

>>> import numpy as np

>>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C')

>>> a

array([[1, 2, 3],

[4, 5, 6]])

>>> a.flags.fnc

False

>>> b = np.array([[1, 2, 3], [4, 5, 6]], order='F')

>>> b

array([[1, 2, 3],

[4, 5, 6]])

>>> b.flags.fnc

True

The transpose of a C-ordered array is a FORTRAN-ordered array.

>>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C')

>>> a

array([[1, 2, 3],

[4, 5, 6]])

>>> a.flags.fnc

False

>>> b = a.T

>>> b

array([[1, 4],

[2, 5],

[3, 6]])

>>> b.flags.fnc

True

C-ordered arrays evaluate as False even if they are also FORTRAN-ordered.

>>> np.array([1, 2], order='F').flags.fnc

False

"""

# Deprecated in NumPy 2.6, 2026-10-14

warnings.warn(

"numpy.isfortran is deprecated. Use a.flags.fnc instead.",

DeprecationWarning,

stacklevel=2,

)

return a.flags.fnc

def _argwhere_dispatcher(a):

return (a,)

@array_function_dispatch(_argwhere_dispatcher)

def argwhere(a):

"""

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

--------

>>> import numpy as np

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

"""

# nonzero does not behave well on 0d, so promote to 1d

if np.ndim(a) == 0:

a = shape_base.atleast_1d(a)

# then remove the added dimension

return argwhere(a)[:, :0]

return transpose(nonzero(a))

def _flatnonzero_dispatcher(a):

return (a,)

@array_function_dispatch(_flatnonzero_dispatcher)

def flatnonzero(a):

"""

Return indices that are non-zero in the flattened version of a.

This is equivalent to ``np.nonzero(np.ravel(a))[0]``.

Parameters

----------

a : array_like

Input data.

Returns

-------

res : ndarray

Output array, containing the indices of the elements of ``a.ravel()``

that are non-zero.

See Also

--------

nonzero : Return the indices of the non-zero elements of the input array.

ravel : Return a 1-D array containing the elements of the input array.

Examples

--------

>>> import numpy as np

>>> x = np.arange(-2, 3)

>>> x

array([-2, -1, 0, 1, 2])

>>> np.flatnonzero(x)

array([0, 1, 3, 4])

Use the indices of the non-zero elements as an index array to extract

these elements:

>>> x.ravel()[np.flatnonzero(x)]

array([-2, -1, 1, 2])

"""

return np.nonzero(np.ravel(a))[0]

def _correlate_dispatcher(a, v, mode=None):

return (a, v)

@array_function_dispatch(_correlate_dispatcher)

def correlate(a, v, mode='valid'):

r"""

Cross-correlation of two 1-dimensional sequences.

This function computes the correlation as generally defined in signal

processing texts [1]_:

.. math:: c_k = \sum_n a_{n+k} \cdot \overline{v}_n

with a and v sequences being zero-padded where necessary and

:math:`\overline v` denoting complex conjugation.

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'.

Returns

-------

out : ndarray

Discrete cross-correlation of `a` and `v`.

See Also

--------

convolve : Discrete, linear convolution of two one-dimensional sequences.

scipy.signal.correlate : uses FFT which has superior performance

on large arrays.

Notes

-----

The definition of correlation above is not unique and sometimes

correlation may be defined differently. Another common definition is [1]_:

.. math:: c'_k = \sum_n a_{n} \cdot \overline{v_{n+k}}

which is related to :math:`c_k` by :math:`c'_k = c_{-k}`.

For example:

>>> np.correlate([1, 1], [1, 2, 3, 4, 5, 6], "valid")

array([11, 9, 7, 5, 3])

Using NumPy's definition, the valid correlation values correspond to

the lags -4, -3, -2, -1, and 0, so the returned values correspond to

:math:`[c_{-4}, c_{-3}, c_{-2}, c_{-1}, c_0]`.

Under the alternative definition, :math:`c'_k = c_{-k}`, the same

correlation values are associated with the opposite lag sign.

`numpy.correlate` may perform slowly in large arrays (i.e. n = 1e5)

because it does not use the FFT to compute the convolution; in that case,

`scipy.signal.correlate` might be preferable.

References

----------

.. [1] Wikipedia, "Cross-correlation",

https://en.wikipedia.org/wiki/Cross-correlation

Examples

--------

>>> import numpy as np

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

(:math:`\overline{c_{-k}}`) when the two input sequences a and v change

places:

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

"""

return multiarray.correlate2(a, v, mode)

def _convolve_dispatcher(a, v, mode=None):

return (a, v)

@array_function_dispatch(_convolve_dispatcher)

def convolve(a, v, mode='full'):

"""

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_{m = -\\infty}^{\\infty} a_m v_{n - 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:

>>> import numpy as np

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

"""

a, v = array(a, copy=None, ndmin=1), array(v, copy=None, ndmin=1)

if len(a) == 0:

raise ValueError('a cannot be empty')

if len(v) == 0:

raise ValueError('v cannot be empty')

if len(v) > len(a):

a, v = v, a

return multiarray.correlate(a, v[::-1], mode)

def _outer_dispatcher(a, b, out=None):

return (a, b, out)

@array_function_dispatch(_outer_dispatcher)

def outer(a, b, out=None):

"""

Compute the outer product of two vectors.

Given two vectors `a` and `b` of length ``M`` and ``N``, respectively,

the outer product [1]_ is::

[[a_0*b_0 a_0*b_1 ... a_0*b_{N-1} ]

[a_1*b_0 .

[ ... .

[a_{M-1}*b_0 a_{M-1}*b_{N-1} ]]

Parameters

----------

a : (M,) array_like

First input vector. Input is flattened if

not already 1-dimensional.

b : (N,) array_like

Second input vector. Input is flattened if

not already 1-dimensional.

out : (M, N) ndarray, optional

A location where the result is stored

Returns

-------

out : (M, N) ndarray

``out[i, j] = a[i] * b[j]``

See also

--------

inner

einsum : ``einsum('i,j->ij', a.ravel(), b.ravel())`` is the equivalent.

ufunc.outer : A generalization to dimensions other than 1D and other

operations. ``np.multiply.outer(a.ravel(), b.ravel())``

is the equivalent.

linalg.outer : An Array API compatible variation of ``np.outer``,

which accepts 1-dimensional inputs only.

tensordot : ``np.tensordot(a.ravel(), b.ravel(), axes=((), ()))``

is the equivalent.

References

----------

.. [1] G. H. Golub and C. F. Van Loan, *Matrix Computations*, 3rd

ed., Baltimore, MD, Johns Hopkins University Press, 1996,

pg. 8.

Examples

--------

Make a (*very* coarse) grid for computing a Mandelbrot set:

>>> import numpy as np

>>> rl = np.outer(np.ones((5,)), np.linspace(-2, 2, 5))

>>> rl

array([[-2., -1., 0., 1., 2.],

[-2., -1., 0., 1., 2.],

[-2., -1., 0., 1., 2.],

[-2., -1., 0., 1., 2.],

[-2., -1., 0., 1., 2.]])

>>> im = np.outer(1j*np.linspace(2, -2, 5), np.ones((5,)))

>>> im

array([[0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j],

[0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j],

[0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j],

[0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j],

[0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j]])

>>> grid = rl + im

>>> grid

array([[-2.+2.j, -1.+2.j, 0.+2.j, 1.+2.j, 2.+2.j],

[-2.+1.j, -1.+1.j, 0.+1.j, 1.+1.j, 2.+1.j],

[-2.+0.j, -1.+0.j, 0.+0.j, 1.+0.j, 2.+0.j],

[-2.-1.j, -1.-1.j, 0.-1.j, 1.-1.j, 2.-1.j],

[-2.-2.j, -1.-2.j, 0.-2.j, 1.-2.j, 2.-2.j]])

An example using a "vector" of letters:

>>> x = np.array(['a', 'b', 'c'], dtype=np.object_)

>>> np.outer(x, [1, 2, 3])

array([['a', 'aa', 'aaa'],

['b', 'bb', 'bbb'],

['c', 'cc', 'ccc']], dtype=object)