Ctrl+K

matmul#

ivy.matmul(x1, x2, /, *, transpose_a=False, transpose_b=False, adjoint_a=False, adjoint_b=False, out=None)[source]#

Compute the matrix product.

Parameters:

  • x1 (Union[Array, NativeArray]) – first input array. Should have a numeric data type. Must have at least one dimension.

  • x2 (Union[Array, NativeArray]) – second input array. Should have a numeric data type. Must have at least one dimension.

  • transpose_a (bool, default: False) – if True, x1 is transposed before multiplication.

  • transpose_b (bool, default: False) – if True, x2 is transposed before multiplication.

  • adjoint_a (bool, default: False) – If True, takes the conjugate of the matrix then the transpose of the matrix. adjoint_a and transpose_a can not be true at the same time.

  • adjoint_b (bool, default: False) – If True, takes the conjugate of the matrix then the transpose of the matrix. adjoint_b and transpose_b can not be true at the same time.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret –

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

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.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

With ivy.Array inputs:

>>> x = ivy.array([2., 0., 3.])
>>> y = ivy.array([4., 1., 8.])
>>> z = ivy.matmul(x, y)
>>> print(z)
ivy.array(32.)

>>> x = ivy.array([[1., 2.], [0., 1.]])
>>> y = ivy.array([[2., 0.], [0., 3.]])
>>> z = ivy.matmul(x, y, transpose_b=True)
>>> print(z)
ivy.array([[2., 6.],
       [0., 3.]])

With ivy.Container inputs:

>>> x = ivy.Container(a=ivy.array([5., 1.]), b=ivy.array([1., 0.]))
>>> y = ivy.Container(a=ivy.array([4., 7.]), b=ivy.array([3., 0.]))
>>> z = ivy.matmul(x,y)
>>> print(z)
{
    a: ivy.array(27.),
    b: ivy.array(3.)
}

With a combination of ivy.Array and ivy.Container inputs:

>>> x = ivy.array([9., 0.])
>>> y = ivy.Container(a=ivy.array([2., 1.]), b=ivy.array([1., 0.]))
>>> z = ivy.matmul(x, y)
>>> print(z)
{
    a: ivy.array(18.),
    b: ivy.array(9.)
}

>>> x = ivy.array([[1., 2.], [0., 3.]])
>>> y = ivy.array([[1.], [3.]])
>>> z = ivy.matmul(x, y, transpose_a=True)
>>> print(z)
ivy.array([[ 1.],
   [11.]])
Array.matmul(self, x2, /, *, transpose_a=False, transpose_b=False, adjoint_a=False, adjoint_b=False, out=None)[source]#

ivy.Array instance method variant of ivy.matmul. This method simply wraps the function, and so the docstring for ivy.matmul also applies to this method with minimal changes.

Parameters:

  • self (Array) – first input array. Should have a numeric data type. Must have at least one dimension.

  • x2 (Union[Array, NativeArray]) – second input array. Should have a numeric data type. Must have at least one dimension.

  • transpose_a (bool, default: False) – if True, x1 is transposed before multiplication.

  • transpose_b (bool, default: False) – if True, x2 is transposed before multiplication.

  • adjoint_a (bool, default: False) – If True, takes the conjugate of the matrix then the transpose of the matrix. adjoint_a and transpose_a can not be true at the same time.

  • adjoint_b (bool, default: False) – If True, takes the conjugate of the matrix then the transpose of the matrix. adjoint_b and transpose_b can not be true at the same time.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – An array containing the output of matrix multiplication. The returned array must have a data type determined by type-promotion. More details can be found in ivy.matmul.

Examples

With ivy.Array instance inputs:

>>> x = ivy.array([1., 4.])
>>> y = ivy.array([3., 2.])
>>> z = x.matmul(y)
>>> print(z)
ivy.array(11.)
Container.matmul(self, x2, /, *, transpose_a=False, transpose_b=False, adjoint_a=False, adjoint_b=False, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

ivy.Container instance method variant of ivy.matmul. This method simply wraps the function, and so the docstring for ivy.matmul also applies to this method with minimal changes.

Parameters:

  • self (Container) – first input array

  • x2 (Union[Container, Array, NativeArray]) – second input array

  • key_chains (Optional[Union[List[str], Dict[str, str], Container]], default: None) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (Union[bool, Container], default: True) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (Union[bool, Container], default: False) – Whether to prune key_chains for which the function was not applied. Default is False.

  • map_sequences (Union[bool, Container], default: False) – Whether to also map method to sequences (lists, tuples). Default is False.

  • out (Optional[Container], default: None) – optional output container, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Container

Returns:

ret – the matrix multiplication result of self and x2

Examples

>>> x = ivy.Container(a = ivy.array([[3., -1.], [-1., 3.]]) ,
...                   b = ivy.array([[2., 1.], [1., 1.]]))
>>> y = x.matmul(x)
>>> print(y)
{
    a: ivy.array([[10., -6.],
                  [-6., 10.]]),
    b: ivy.array([[5., 3.],
                  [3., 2.]])
}
On this page