pagemtimes

Page-wise matrix multiplication

Since R2020b

Syntax

Z = pagemtimes(X,Y)

Z = pagemtimes(X,transpX,Y,transpY)

Description

Z = pagemtimes(X,Y) computes the matrix product of corresponding pages of the N-D arrays X and Y. Each page of the output array Z is given by the product: Z(:,:,i) = X(:,:,i)*Y(:,:,i).

• If one of X or Y is a matrix, then pagemtimes multiplies it with each page of the other input. For example, if X is a matrix, then Z(:,:,i) = X*Y(:,:,i).

• If X and Y have more than three dimensions, then all dimensions beyond the first two must have Compatible Sizes. pagemtimes implicitly expands the extra dimensions to multiply all combinations of the paged matrices: Z(:,:,i,j,k) = Xx(:,:,i,j,k)*Yy(:,:,i,j,k). (The extra dimensions have been expanded in Xx and Yy.)

Z = pagemtimes(X,transpX,Y,transpY) optionally computes the matrix product with the specified transpositions of X and Y. For this syntax you must specify both transpose options. transpX and transpY must each be: 'transpose', 'ctranspose', or 'none'.

Examples

Multiply 3-D Arrays

Create two 3-D arrays and multiply corresponding pages.

rng default
X = randi([1 6],2,2,3)

X = 
X(:,:,1) =

     5     1
     6     6


X(:,:,2) =

     4     2
     1     4


X(:,:,3) =

     6     1
     6     6

Y = randi([1 6],2,2,3)

Y = 
Y(:,:,1) =

     6     5
     3     1


Y(:,:,2) =

     3     5
     6     6


Y(:,:,3) =

     4     6
     1     6

Z = pagemtimes(X,Y)

Z = 
Z(:,:,1) =

    33    26
    54    36


Z(:,:,2) =

    24    32
    27    29


Z(:,:,3) =

    25    42
    30    72

The ith page of the output Z(:,:,i) is formed by multiplying X(:,:,i)*Y(:,:,i).

Multiply Matrix and 3-D Array

Create a matrix A and a 3-D array Y, and then multiply each page of the 3-D array with the matrix.

A = magic(3)

A = 3×3

     8     1     6
     3     5     7
     4     9     2

rng default
Y = randi([1 10],3,3,3)

Y = 
Y(:,:,1) =

     9    10     3
    10     7     6
     2     1    10


Y(:,:,2) =

    10    10     2
     2     5     5
    10     9    10


Y(:,:,3) =

     8     1     7
    10     9     8
     7    10     8

Z = pagemtimes(A,Y)

Z = 
Z(:,:,1) =

    94    93    90
    91    72   109
   130   105    86


Z(:,:,2) =

   142   139    81
   110   118   101
    78   103    73


Z(:,:,3) =

   116    77   112
   123   118   117
   136   105   116

The ith page of the output Z(:,:,i) is formed by multiplying A*Y(:,:,i).

Multiply Transposed Array Pages

Create two 3-D arrays X and Y. Use pagemtimes to perform the operation X(:,:,i)'*Y(:,:,i) on each page of X and Y.

rng default
X = rand(3,3,3) + 1i;
Y = rand(3,3,3);
A = pagemtimes(X,'ctranspose',Y,'none')

A = 
A(:,:,1) =

   0.9350 - 1.2189i   0.6392 - 1.0148i   0.2302 - 0.9668i
   0.7894 - 1.2189i   0.6920 - 1.0148i   0.1839 - 0.9668i
   0.6316 - 1.2189i   0.4792 - 1.0148i   0.8544 - 0.9668i


A(:,:,2) =

   1.6427 - 1.9622i   0.4727 - 0.8547i   1.0453 - 1.7476i
   1.5794 - 1.9622i   0.5513 - 0.8547i   1.2682 - 1.7476i
   1.1025 - 1.9622i   0.5393 - 0.8547i   0.6151 - 1.7476i


A(:,:,3) =

   1.2393 - 1.5817i   1.4671 - 1.7401i   1.2737 - 1.4974i
   0.9995 - 1.5817i   0.9240 - 1.7401i   0.7324 - 1.4974i
   1.1504 - 1.5817i   1.2585 - 1.7401i   1.0786 - 1.4974i

Now, perform the operation X(:,:,i)*Y(:,:,i).' on each page of X and Y.

B = pagemtimes(X,'none',Y,'transpose')

B = 
B(:,:,1) =

   0.9773 + 1.1444i   0.5902 + 0.7844i   0.6217 + 1.2716i
   0.8270 + 1.1444i   0.6670 + 0.7844i   0.7805 + 1.2716i
   0.1629 + 1.1444i   0.1793 + 0.7844i   0.8372 + 1.2716i


B(:,:,2) =

   0.8120 + 1.4948i   0.8387 + 1.5510i   1.3086 + 1.5187i
   0.4491 + 1.4948i   0.5983 + 1.5510i   0.4138 + 1.5187i
   1.4030 + 1.4948i   1.3871 + 1.5510i   1.3988 + 1.5187i


B(:,:,3) =

   0.8747 + 1.8788i   0.8246 + 1.8554i   0.6322 + 1.0849i
   1.5873 + 1.8788i   1.5648 + 1.8554i   0.9777 + 1.0849i
   1.4888 + 1.8788i   1.4839 + 1.8554i   0.8025 + 1.0849i

Multiply N-D Arrays

Create a 3-by-3-by-2 array X and multiply it with a 3-by-3-by-1-by-4 array Y. The result has size 3-by-3-by-2-by-4.

X = ones(3,3,2);
A = eye(3);
Y = cat(4,A,2*A,3*A,4*A);
Z = pagemtimes(X,Y)

Z = 
Z(:,:,1,1) =

     1     1     1
     1     1     1
     1     1     1


Z(:,:,2,1) =

     1     1     1
     1     1     1
     1     1     1


Z(:,:,1,2) =

     2     2     2
     2     2     2
     2     2     2


Z(:,:,2,2) =

     2     2     2
     2     2     2
     2     2     2


Z(:,:,1,3) =

     3     3     3
     3     3     3
     3     3     3


Z(:,:,2,3) =

     3     3     3
     3     3     3
     3     3     3


Z(:,:,1,4) =

     4     4     4
     4     4     4
     4     4     4


Z(:,:,2,4) =

     4     4     4
     4     4     4
     4     4     4

Each dimension with size 1 (after the first two dimensions) is implicitly expanded to match the dimension size of the other input, and then each page of the output Z(:,:,i,j) is formed by multiplying X(:,:,i,j)*Y(:,:,i,j). An intuitive way to think about this operation is that X contains two matrices as pages in a 3-D array, and Y contains four matrices arranged along the fourth dimension; thus, multiplying all combinations of these matrices results in eight 3-by-3 matrices.

Input Arguments

X, Y — Input arrays

matrices | multidimensional arrays

Input arrays, specified as dense matrices or multidimensional arrays. The pages of X and Y must be valid inputs to a matrix product (mtimes, *).

• If one of X or Y is a matrix, then pagemtimes multiplies it with each page of the other input. For example, if X is a matrix, then Z(:,:,i) = X*Y(:,:,i).

• If X and Y have more than three dimensions, then all dimensions beyond the first two must have Compatible Sizes. pagemtimes implicitly expands the extra dimensions to multiply all combinations of the paged matrices: Z(:,:,i,j,k) = Xx(:,:,i,j,k)*Yy(:,:,i,j,k). (The extra dimensions have been expanded in Xx and Yy.)

Data Types: single | double
Complex Number Support: Yes

transpX, transpY — Transposition options

'none' (default) | 'transpose' | 'ctranspose'

Transposition options, each specified as one of the values in this table.

Value	Description
'none'	Do not apply transposition.
'transpose'	Apply transposition to each page of the corresponding input (transpose applied to each page).
'ctranspose'	Apply complex conjugate transposition to each page of the corresponding input (ctranspose applied to each page).

Use the transpose options to compute operations such as X'*Y in a page-wise manner. You must specify both transpose options even if only one input is being transposed.

Example: pagemtimes(X,'ctranspose',Y,'none') computes a page-wise version of X'*Y.

Data Types: char | string

Output Arguments

Z — Output array

multidimensional array

Output array, returned as a multidimensional array. The operation performed by pagemtimes depends on the sizes of the inputs X and Y:

Size of X	Size of Y	Operation
3-D	3-D	Z(:,:,i) = X(:,:,i)*Y(:,:,i)
2-D	3-D	Z(:,:,i) = X*Y(:,:,i)
3-D	2-D	Z(:,:,i) = X(:,:,i)*Y
N-D	N-D	Z(:,:,i,j,k) = X(:,:,i,j,k)*Y(:,:,i,j,k)

The size of Z follows these rules:

• In the first two dimensions, the rules of matrix multiplication apply. If either operand is a scalar, then the result has the size of the nonscalar operand. When both operands are matrices, multiplying an m-by-n matrix with an n-by-q matrix results in an m-by-q matrix.

• Compatible dimensions beyond the first two in X and Y are expanded to match the non-singleton dimension. So if X is 10-by-8-by-1-by-3 and Y is 8-by-10-by-4-by-1, then Z is 10-by-10-by-4-by-3.

More About

Array Pages

Page-wise functions like pagemtimes operate on 2-D matrices that have been arranged into a multidimensional array. For example, the elements in the third dimension of a 3-D array are commonly called pages because they stack on top of each other like pages in a book. Each page is a matrix that the function operates on.

You can also assemble a collection of 2-D matrices into a higher dimensional array, like a 4-D or 5-D array, and in these cases pagemtimes still treats the fundamental unit of the array as a 2-D matrix that the function operates on, such as X(:,:,i,j,k,l).

The cat function is useful for assembling a collection of matrices into a multidimensional array, and the zeros function is useful for preallocating a multidimensional array.

Tips

• For both real and complex N-D arrays, pagemtimes(X,'transpose',X,'none') and pagemtimes(X,'none',X,'transpose') return an array with pages of symmetric matrices. For complex N-D arrays, pagemtimes(X,'ctranspose',X,'none') and pagemtimes(X,'none',X,'ctranspose') return an array with pages of Hermitian matrices.

• Results obtained using pagemtimes are numerically equivalent to multiplying each of the same matrices in a for-loop. However, the two results might differ slightly due to floating-point round-off error.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The transpose options transpX and transpY must be constant.

• Code generation does not support integer and half-precision data types for this function.

• Input arrays passed to pagemtimes must be non-sparse.

• Code generation supports the implicit expansion of array inputs along with non-page dimensions for pagemtimes function.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The transpose options transpX and transpY must be constant.

• Code generation does not support integer and half-precision data types for this function.

• Input arrays passed to pagemtimes must be non-sparse.

• Code generation supports the implicit expansion of array inputs along with non-page dimensions for pagemtimes function.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

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

The pagemtimes 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 R2020b