tensorprod

Tensor products between two tensors

Since R2022a

Syntax

C = tensorprod(A,B,dimA,dimB)

C = tensorprod(A,B,dim)

C = tensorprod(A,B)

C = tensorprod(A,B,"all")

C = tensorprod(___,NumDimensionsA=ndimsA)

Description

C = tensorprod(A,B,dimA,dimB) returns the tensor product of tensors A and B. The arguments dimA and dimB are vectors that specify which dimensions to contract in A and B. The size of the output tensor is the size of the uncontracted dimensions of A followed by the size of the uncontracted dimensions of B.

C = tensorprod(A,B,dim) specifies the same dimensions to contract in both A and B.

C = tensorprod(A,B) returns the outer product between tensors A and B. This syntax is equivalent to using one of the previous syntaxes with dimA = dimB = [] or dim = []. The size of the output tensor is [size(A) size(B)].

C = tensorprod(A,B,"all") returns the inner product between tensors A and B, which must be the same size. The output is a scalar.

C = tensorprod(___,NumDimensionsA=ndimsA) optionally specifies the number of dimensions in tensor A in addition to any of the input argument combinations in previous syntaxes. Use this option when A has trailing singleton dimensions that are expected to be passed on to the output. For example, tensorprod(A,B,NumDimensionsA=4) calculates the outer product between tensors A and B where A has a total of four dimensions.

Examples

Tensor Products with Contracted Dimensions

Create two 3-D tensors with random elements.

A = rand(3,2,5);
B = rand(2,4,5);

Calculate the tensor product of A and B, contracting the second dimension of A with the first dimension of B. The resulting tensor contains the uncontracted dimensions of A followed by the uncontracted dimensions of B.

C = tensorprod(A,B,2,1);
size(C)

ans = 1×4

     3     5     4     5

To contract multiple dimensions in a tensor product, specify the dimensions to contract as vectors. Calculate another tensor product between A and B, but this time contract two dimensions:

• Contract the second dimension of A with the first dimension of B.

• Contract the third dimension of A with the third dimension of B.

D = tensorprod(A,B,[2 3],[1 3]);
size(D)

ans = 1×2

     3     4

Contract Same Dimensions in Both Tensors

Create two 4-D tensors with random elements.

A = rand(7,3,6,5);
B = rand(9,3,4,5);

Calculate the tensor product of A and B, contracting the second and fourth dimensions of each tensor. Check the size of the result.

C = tensorprod(A,B,[2 4]);
size(C)

ans = 1×4

     7     6     9     4

Outer Product of Two Tensors

Create two tensors with random elements.

A = rand(3,2,3);
B = rand(4,4,3,3);

Calculate the outer product of the two tensors. Check the size of the result.

C = tensorprod(A,B);
size(C)

ans = 1×7

     3     2     3     4     4     3     3

tensorprod multiplies all combinations of the elements in the two tensors, so the resulting tensor has a size equal to [size(A) size(B)].

Inner Product of Two Tensors

Create two 4-D tensors of the same size with random elements.

A = rand(4,4,3,2);
B = rand(4,4,3,2);

Calculate the inner product of the tensors, specifying the "all" option to contract all dimensions.

C = tensorprod(A,B,"all")

C = 
23.6148

Preserve Singleton Dimensions

Create two 4-D tensors with random elements. A has a trailing dimension of size 1, which MATLAB® ignores by convention.

A = rand(3,4,5,1);
B = rand(4,5,6,7);

Calculate the tensor product of A and B, contracting the second and third dimensions of A with the first and second dimensions of B. Because MATLAB ignores the trailing singleton dimension of A, the result has only three dimensions.

C = tensorprod(A,B,[2 3],[1 2]);
size(C)

ans = 1×3

     3     6     7

To preserve the singleton dimension in A, use the NumDimensionsA option to specify the number of dimensions in A. The result now has four dimensions.

D = tensorprod(A,B,[2 3],[1 2],NumDimensionsA=4);
size(D)

ans = 1×4

     3     1     6     7

Input Arguments

A, B — Input tensors

arrays

Input tensors, specified as arrays. tensorprod does not conjugate complex inputs during its calculations. If conjugation is required, use conj(A) or conj(B) to conjugate complex inputs before passing them to tensorprod.

Data Types: single | double
Complex Number Support: Yes

dimA, dimB — Dimensions to contract in A and B

vectors

Dimensions to contract in A and B, specified as vectors. dimA and dimB must have the same length and are matched pairwise. The sizes of the contracted dimensions must also match, so size(A,dimA) must equal size(B,dimB).

Example: tensorprod(A,B,[1 3],[2 4]) contracts the first dimension of A with the second dimension of B, and the third dimension of A with the fourth dimension of B.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

dim — Dimensions to contract in both A and B

vector

Dimensions to contract in both A and B, specified as a vector. The sizes of the contracted dimensions must match, so size(A,dim) must equal size(B,dim).

Example: tensorprod(A,B,[1 3]) contracts the first dimension of A with the first dimension of B, and the third dimension of A with the third dimension of B.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

ndimsA — Number of dimensions in A

scalar

Number of dimensions in A, specified as a scalar. Use this option when A has trailing singleton dimensions that are expected to be passed on to the output.

Example: tensorprod(A,B,NumDimensionsA=4) calculates the outer product between tensors A and B where A has a total of four dimensions.

More About

Inner Product

The inner product of two tensors is a generalization of the dot product operation for vectors as calculated by dot. A dot product operation (multiply and sum) is performed on all corresponding dimensions in the tensors, so the operation returns a scalar value. For this operation, the tensors must have the same size.

For example, if tensors U and V have the same n dimensions (i, j, k, ..., n), then the inner product tensorprod(U,V,"all") is given by the summation:

$${\displaystyle \sum _n\cdots {\displaystyle \sum _k{\displaystyle \sum _j{\displaystyle \sum _i{U}_{i,j,k,\dots ,n}\ast V_{i,j,k,\dots ,n}}}}}=w$$

Outer Product

The outer product for tensors is a generalization of the Kronecker product for 2-D matrices as calculated by kron. The outer product of two tensors multiplies all combinations of their elements. Because no dimensions in the tensors are contracted, the output is a large tensor.

For example, if tensor U has dimensions (i, j, k, ...) and tensor V has dimensions (l, m, n, ...), then the outer product tensorprod(U,V) is given by:

$$U_{i,j,k,\dots }\ast V_{l,m,n,\dots }=W_{i,j,k,\dots ,l,m,n,\dots }$$

Tensor Product

The tensor product combines the inner and outer product operations. You can specify pairs of dimensions with the same size in each tensor to be contracted with each other by means of an inner product, and these dimensions are multiplied and summed to reduce the dimension size to one. After all specified dimensions are contracted, the remaining dimensions have an outer product operation performed, multiplying all combinations of their elements.

For example, if tensor U has dimensions (i, j, k) and tensor V has dimensions (i, j, m), then the tensor product tensorprod(U,V,[1 2]) contracts the first two dimensions of each tensor with each other and the result has dimensions (k, m):

$${\displaystyle \sum _j{\displaystyle \sum _i{U}_{i,j,k}\ast V_{i,j,m}=W_{k,m}}}$$

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The tensorprod function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2022a