matmul

matmul(x1: array, x2: array, /) → array

Computes the matrix product.

Parameters:

  • x1 (array) –

    first input array. Should have a numeric data type. Must have at least one dimension.

    • If x1 is a one-dimensional array 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 array 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.

Returns:

out (array) – output array.

  • If both x1 and x2 are one-dimensional arrays having shape (N,), the returned array must be a zero-dimensional array and must contain 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), the returned array must be a two-dimensional array and must contain 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), the returned array must be an array having shape (..., N) (i.e., prepended dimensions during vector-to-matrix promotion must be removed) and must contain the conventional matrix product.

  • If x1 is an array having shape (..., M, K) and x2 is a one-dimensional array having shape (K,), the returned array must be an array having shape (..., M) (i.e., appended dimensions during vector-to-matrix promotion must be removed) and must contain the conventional matrix product.

  • If x1 is a two-dimensional array having shape (M, K) and x2 is an array having shape (..., K, N), the returned array must be an array having shape (..., M, N) and must contain 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), the returned array must be an array having shape (..., M, N) and must contain the conventional matrix product for each stacked matrix.

  • If either x1 or x2 has more than two dimensions, the returned array must be an array having a shape determined by Broadcasting shape(x1)[:-2] against shape(x2)[:-2] and must contain the conventional matrix product for each stacked matrix.

The returned array must have a data type determined by Type Promotion Rules.

Raises:

Exception – an exception should be raised in the following circumstances: - 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.

Notes

  • The matmul function must implement the same semantics as the built-in @ operator (see PEP 465).

  • If either x1 or x2 has a complex floating-point data type, the function must not complex-conjugate or tranpose either argument. If conjugation and/or transposition is desired, a user can explicitly perform these operations prior to computing the matrix product.

Changed in version 2022.12: Added complex data type support.