`numpy:matmul`

source: /numpy/__init__.py

Summary

Matrix product of two arrays.

Parameters

x1, x2 : array_like: Input arrays, scalars not allowed.
out : ndarray, optional: A location into which the result is stored. If provided, it must have a shape that matches the signature (n,k),(k,m)->(n,m). If not provided or None, a freshly-allocated array is returned.
**kwargs: For other keyword-only arguments, see the ufunc docs <ufuncs.kwargs>.

Returns

y : ndarray: The matrix product of the inputs. This is a scalar only when both x1, x2 are 1-d vectors.

Raises

: ValueError

If the last dimension of x1 is not the same size as the second-to-last dimension of x2.

If a scalar value is passed in.

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 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 matvec.)

matmul differs from 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):

>>> 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

The matmul function implements the semantics of the @ operator defined in Pep 465.

It uses an optimized BLAS library when possible (see numpy.linalg).

Examples

For 2-D arrays it is the matrix product:

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

✓

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)
np.matmul(b, a)

✓

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

✓

np.matmul(a, b)[0, 1, 1]
sum(a[0, 1, :] * b[0 , :, 1])

✗

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

np.matmul([2j, 3j], [2j, 3j])

✗

Scalar multiplication raises an error.

np.matmul([1,2], 3)

✓

The ``@`` operator can be used as a shorthand for ``np.matmul`` on ndarrays.

x1 = np.array([2j, 3j])
x2 = np.array([2j, 3j])

✓

x1 @ x2

`numpy:matmul`

Summary

Parameters

Returns

Raises

Notes

Examples

See also

Aliases

Referenced by

This package