matmul¶
- matmul(x1: array, x2: array, /) array ¶
Computes the matrix product.
Note
The
matmul
function must implement the same semantics as the built-in@
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 one-dimensional having shape(M,)
andx2
has more than one dimension,x1
must be promoted to a two-dimensional 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 vector-to-matrix promotion),shape(x1)[:-2]
must be compatible withshape(x2)[:-2]
(after vector-to-matrix 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 one-dimensional having shape(N,)
andx1
has more than one dimension,x2
must be promoted to a two-dimensional 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 vector-to-matrix promotion),shape(x2)[:-2]
must be compatible withshape(x1)[:-2]
(after vector-to-matrix promotion) (see Broadcasting). Ifx2
has shape(..., K, N)
, the innermost two dimensions form matrices on which to perform matrix multiplication.
Note
If either
x1
orx2
has a complex floating-point data type, neither argument must be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations should be explicitly performed prior to computing the matrix product.- Returns:
out (array) –
if both
x1
andx2
are one-dimensional arrays having shape(N,)
, a zero-dimensional array containing the inner product as its only element.if
x1
is a two-dimensional array having shape(M, K)
andx2
is a two-dimensional array having shape(K, N)
, a two-dimensional array containing the conventional matrix product and having shape(M, N)
.if
x1
is a one-dimensional array having shape(K,)
andx2
is an array having shape(..., K, N)
, an array having shape(..., N)
(i.e., prepended dimensions during vector-to-matrix promotion must be removed) and containing the conventional matrix product.if
x1
is an array having shape(..., M, K)
andx2
is a one-dimensional array having shape(K,)
, an array having shape(..., M)
(i.e., appended dimensions during vector-to-matrix promotion must be removed) and containing the conventional matrix product.if
x1
is a two-dimensional 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 two-dimensional 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.
Notes
Changed in version 2022.12: Added complex data type support.
Raises
if either
x1
orx2
is a zero-dimensional array.if
x1
is a one-dimensional array having shape(K,)
,x2
is a one-dimensional array having shape(L,)
, andK != L
.if
x1
is a one-dimensional 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 one-dimensional 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
.