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,) and x2 has more than one dimension, x1 must be promoted to a two-dimensional array by prepending 1 to its dimensions (i.e., must have shape (1, M)). After matrix multiplication, the prepended dimensions in the returned array must be removed. If x1 has more than one dimension (including after vector-to-matrix promotion), shape(x1)[:-2] must be compatible with shape(x2)[:-2] (after vector-to-matrix promotion) (see Broadcasting). If x1 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,) and x1 has more than one dimension, x2 must be promoted to a two-dimensional array by appending 1 to its dimensions (i.e., must have shape (N, 1)). After matrix multiplication, the appended dimensions in the returned array must be removed. If x2 has more than one dimension (including after vector-to-matrix promotion), shape(x2)[:-2] must be compatible with shape(x1)[:-2] (after vector-to-matrix promotion) (see Broadcasting). If x2 has shape (..., K, N), the innermost two dimensions form matrices on which to perform matrix multiplication.

Note

If either x1 or x2 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 and x2 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) and x2 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,) and x2 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) and x2 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) and x2 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) and x2 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 or x2 has more than two dimensions, an array having a shape determined by Broadcasting shape(x1)[:-2] against shape(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 or x2 is a zero-dimensional array.

  • if x1 is a one-dimensional array having shape (K,), x2 is a one-dimensional array having shape (L,), and K != L.

  • if x1 is a one-dimensional array having shape (K,), x2 is an array having shape (..., L, N), and K != L.

  • if x1 is an array having shape (..., M, K), x2 is a one-dimensional array having shape (L,), and K != L.

  • if x1 is an array having shape (..., M, K), x2 is an array having shape (..., L, N), and K != L.