flopscope.numpy.matmul

fnp.matmul(a, b)[flopscope source][numpy source]

Matrix product of two arrays.

Adapted from NumPy docs np.matmul

Areacore

Typecustom

Cost

m \cdot k \cdot n

Flopscope Context

Matrix multiplication; cost = M*K*N (FMA=1).

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.

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

The matmul function implements the semantics of the @ operator introduced in Python 3.5 following 465.

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

Examples

For 2-D arrays it is the matrix product:

>>> import flopscope.numpy as fnp

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

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

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

Broadcasting is conventional for stacks of arrays

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

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

>>> flops.matmul([2j, 3j], [2j, 3j])
(-13+0j)

Scalar multiplication raises an error.

>>> flops.matmul([1,2], 3)
Traceback (most recent call last):
...
ValueError: matmul: Input operand 1 does not have enough dimensions ...

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

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