dpnp.matmul

dpnp.matmul(x1, x2, /, out=None, *, casting='same_kind', order='K', dtype=None, subok=True, signature=None, axes=None, axis=None)[source]

Matrix product of two arrays.

For full documentation refer to numpy.matmul.

Parameters:

  • x1 ({dpnp.ndarray, usm_ndarray}) -- First input array.

  • x2 ({dpnp.ndarray, usm_ndarray}) -- Second input array.

  • out ({None, dpnp.ndarray, usm_ndarray}, optional) --

    Alternative output array in which to place the result. It must have a shape that matches the signature (n,k),(k,m)->(n,m) but the type (of the calculated values) will be cast if necessary.

    Default: None.

  • dtype ({None, str, dtype object}, optional) --

    Type to use in computing the matrix product. By default, the returned array will have data type that is determined by considering Promotion Type Rule and device capabilities.

    Default: None.

  • casting ({"no", "equiv", "safe", "same_kind", "unsafe"}, optional) --

    Controls what kind of data casting may occur.

    Default: "same_kind".

  • order ({"C", "F", "A", "K", None}, optional) --

    Memory layout of the newly output array, if parameter out is None.

    Default: "K".

  • axes ({None, list of tuples}, optional) --

    A list of tuples with indices of axes the matrix product should operate on. For instance, for the signature of (i,j),(j,k)->(i,k), the base elements are 2d matrices and these are taken to be stored in the two last axes of each argument. The corresponding axes keyword would be [(-2, -1), (-2, -1), (-2, -1)].

    Default: None.

Returns:

out -- Returns the matrix product of the inputs. This is a 0-d array only when both x1, x2 are 1-d vectors.

Return type:

dpnp.ndarray

Limitations

Keyword arguments subok, and signature, are only supported with their default values. Otherwise NotImplementedError exception will be raised.

See also

dpnp.linalg.matmul

Array API compatible version.

dpnp.vecdot

Complex-conjugating dot product for stacks of vectors.

dpnp.matvec

Matrix-vector product for stacks of matrices and vectors.

dpnp.vecmat

Vector-matrix product for stacks of vectors and matrices.

dpnp.tensordot

Sum products over arbitrary axes.

dpnp.einsum

Einstein summation convention.

dpnp.dot

Alternative matrix product with different broadcasting rules.

Notes

The behavior depends on the arguments in the following way.

  • If both arguments are 2-D they are multiplied like conventional matrices.

  • If either argument is N-D, N > 2, it is treated as a stack of matrices residing in the last two indexes and broadcast accordingly.

  • If the first argument is 1-D, it is promoted to a matrix by prepending a 1 to its dimensions. After matrix multiplication the prepended 1 is removed. (For stacks of vectors, use dpnp.vecmat.)

  • If the second argument is 1-D, it is promoted to a matrix by appending a 1 to its dimensions. After matrix multiplication the appended 1 is removed. (For stacks of vectors, use dpnp.matvec.)

dpnp.matmul differs from dpnp.dot in two important ways:

  • Multiplication by scalars is not allowed, use * instead.

  • Stacks of matrices are broadcast together as if the matrices were elements, respecting the signature (n,k),(k,m)->(n,m):

>>> import dpnp as np
>>> a = np.ones([9, 5, 7, 4])
>>> c = np.ones([9, 5, 4, 3])
>>> np.dot(a, c).shape
(9, 5, 7, 9, 5, 3)
>>> np.matmul(a, c).shape
(9, 5, 7, 3) # n is 7, k is 4, m is 3

Examples

For 2-D arrays it is the matrix product:

>>> import dpnp as np
>>> a = np.array([[1, 0], [0, 1]])
>>> b = np.array([[4, 1], [2, 2]])
>>> np.matmul(a, b)
array([[4, 1],
       [2, 2]])

For 2-D mixed with 1-D, the result is the usual.

>>> a = np.array([[1, 0], [0, 1]])
>>> b = np.array([1, 2])
>>> np.matmul(a, b)
array([1, 2])
>>> np.matmul(b, a)
array([1, 2])

Broadcasting is conventional for stacks of arrays

>>> a = np.arange(2 * 2 * 4).reshape((2, 2, 4))
>>> b = np.arange(2 * 2 * 4).reshape((2, 4, 2))
>>> np.matmul(a,b).shape
(2, 2, 2)
>>> np.matmul(a, b)[0, 1, 1]
array(98)
>>> np.sum(a[0, 1, :] * b[0 , :, 1])
array(98)

Vector, vector returns the scalar inner product, but neither argument is complex-conjugated:

>>> x1 = np.array([2j, 3j])
>>> x2 = np.array([2j, 3j])
>>> np.matmul(x1, x2)
array(-13+0j)

The @ operator can be used as a shorthand for dpnp.matmul on dpnp.ndarray.

>>> x1 @ x2
array(-13+0j)