Linear Algebra Functions ¶
Array API specification for linear algebra functions.
A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.

Positional parameters must be positionalonly parameters. Positionalonly parameters have no externallyusable name. When a function accepting positionalonly parameters is called, positional arguments are mapped to these parameters based solely on their order.

Optional parameters must be keywordonly arguments.

Broadcasting semantics must follow the semantics defined in Broadcasting .

Unless stated otherwise, functions must support the data types defined in Data Types .

Unless stated otherwise, functions must adhere to the type promotion rules defined in Type Promotion Rules .

Unless stated otherwise, floatingpoint operations must adhere to IEEE 7542019.
Objects in API ¶
matmul(x1, x2, /) ¶
Computes the matrix product.
Note
The
matmul
function must implement the same semantics as the builtin
@
operator (see
PEP 465
).
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type. Must have at least one dimension. If
x1
is onedimensional having shape(M,)
andx2
has more than one dimension,x1
must be promoted to a twodimensional array by prepending1
to its dimensions (i.e., must have shape(1, M)
). After matrix multiplication, the prepended dimensions in the returned array must be removed. Ifx1
has more than one dimension (including after vectortomatrix promotion),shape(x1)[:2]
must be compatible withshape(x2)[:2]
(after vectortomatrix promotion) (see Broadcasting ). Ifx1
has shape(..., M, K)
, the innermost two dimensions form matrices on which to perform matrix multiplication.


x2 : <array>

second input array. Should have a numeric data type. Must have at least one dimension. If
x2
is onedimensional having shape(N,)
andx1
has more than one dimension,x2
must be promoted to a twodimensional array by appending1
to its dimensions (i.e., must have shape(N, 1)
). After matrix multiplication, the appended dimensions in the returned array must be removed. Ifx2
has more than one dimension (including after vectortomatrix promotion),shape(x2)[:2]
must be compatible withshape(x1)[:2]
(after vectortomatrix promotion) (see Broadcasting ). Ifx2
has shape(..., K, N)
, the innermost two dimensions form matrices on which to perform matrix multiplication.

Returns ¶

out : <array>

if both
x1
andx2
are onedimensional arrays having shape(N,)
, a zerodimensional array containing the inner product as its only element. 
if
x1
is a twodimensional array having shape(M, K)
andx2
is a twodimensional array having shape(K, N)
, a twodimensional array containing the conventional matrix product and having shape(M, N)
. 
if
x1
is a onedimensional array having shape(K,)
andx2
is an array having shape(..., K, N)
, an array having shape(..., N)
(i.e., prepended dimensions during vectortomatrix promotion must be removed) and containing the conventional matrix product . 
if
x1
is an array having shape(..., M, K)
andx2
is a onedimensional array having shape(K,)
, an array having shape(..., M)
(i.e., appended dimensions during vectortomatrix promotion must be removed) and containing the conventional matrix product . 
if
x1
is a twodimensional array having shape(M, K)
andx2
is an array having shape(..., K, N)
, an array having shape(..., M, N)
and containing the conventional matrix product for each stacked matrix. 
if
x1
is an array having shape(..., M, K)
andx2
is a twodimensional array having shape(K, N)
, an array having shape(..., M, N)
and containing the conventional matrix product for each stacked matrix. 
if either
x1
orx2
has more than two dimensions, an array having a shape determined by Broadcastingshape(x1)[:2]
againstshape(x2)[:2]
and containing the conventional matrix product for each stacked matrix.
The returned array must have a data type determined by Type Promotion Rules .

Raises ¶

if either
x1
orx2
is a zerodimensional array. 
if
x1
is a onedimensional array having shape(K,)
,x2
is a onedimensional array having shape(L,)
, andK != L
. 
if
x1
is a onedimensional array having shape(K,)
,x2
is an array having shape(..., L, N)
, andK != L
. 
if
x1
is an array having shape(..., M, K)
,x2
is a onedimensional array having shape(L,)
, andK != L
. 
if
x1
is an array having shape(..., M, K)
,x2
is an array having shape(..., L, N)
, andK != L
.
matrix_transpose(x, /) ¶
Transposes a matrix (or a stack of matrices)
x
.
Parameters ¶

x : <array>

input array having shape
(..., M, N)
and whose innermost two dimensions formMxN
matrices.

Returns ¶

out : <array>

an array containing the transpose for each matrix and having shape
(..., N, M)
. The returned array must have the same data type asx
.

tensordot(x1, x2, /, *, axes=2) ¶
Returns a tensor contraction of
x1
and
x2
over specific axes.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
for all noncontracted axes (see Broadcasting ). Should have a numeric data type.Note
Contracted axes (dimensions) must not be broadcasted.


axes : Union[ int, Tuple[ Sequence[ int ], Sequence[ int ] ] ]

number of axes (dimensions) to contract or explicit sequences of axes (dimensions) for
x1
andx2
, respectively.If
axes
is anint
equal toN
, then contraction must be performed over the lastN
axes ofx1
and the firstN
axes ofx2
in order. The size of each corresponding axis (dimension) must match. Must be nonnegative.
If
N
equals0
, the result is the tensor (outer) product. 
If
N
equals1
, the result is the tensor dot product. 
If
N
equals2
, the result is the tensor double contraction (default).
If
axes
is a tuple of two sequences(x1_axes, x2_axes)
, the first sequence must apply tox
and the second sequence tox2
. Both sequences must have the same length. Each axis (dimension)x1_axes[i]
forx1
must have the same size as the respective axis (dimension)x2_axes[i]
forx2
. Each sequence must consist of unique (nonnegative) integers that specify valid axes for each respective array. 

Returns ¶

out : <array>

an array containing the tensor contraction whose shape consists of the noncontracted axes (dimensions) of the first array
x1
, followed by the noncontracted axes (dimensions) of the second arrayx2
. The returned array must have a data type determined by Type Promotion Rules .

vecdot(x1, x2, /, *, axis=1) ¶
Computes the (vector) dot product of two arrays.
Parameters ¶

x1 : <array>

first input array. Should have a numeric data type.


x2 : <array>

second input array. Must be compatible with
x1
(see Broadcasting ). Should have a numeric data type.


axis : int

axis over which to compute the dot product. Must be an integer on the interval
[N, N)
, whereN
is the rank (number of dimensions) of the shape determined according to Broadcasting . If specified as a negative integer, the function must determine the axis along which to compute the dot product by counting backward from the last dimension (where1
refers to the last dimension). By default, the function must compute the dot product over the last axis. Default:1
.

Returns ¶

out : <array>

if
x1
andx2
are both onedimensional arrays, a zerodimensional containing the dot product; otherwise, a nonzerodimensional array containing the dot products and having rankN1
, whereN
is the rank (number of dimensions) of the shape determined according to Broadcasting . The returned array must have a data type determined by Type Promotion Rules .

Raises ¶

if provided an invalid
axis
. 
if the size of the axis over which to compute the dot product is not the same for both
x1
andx2
.