pagemtimes

Page-wise matrix multiplication

Syntax

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

Description

example

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

example

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

collapse all

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 `i`th page of the output `Z(:,:,i)` is formed by multiplying `X(:,:,i)*Y(:,:,i)`.

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 `i`th page of the output `Z(:,:,i)` is formed by multiplying `A*Y(:,:,i)`.

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

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

collapse all

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

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

ValueDescription
`'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

collapse all

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.

collapse all

Array Pages

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

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 gets operated on, such as `X(:,:,i,j,k,l)`.

The `cat` function is useful to assemble a collection of matrices into a multidimensional array, and the `zeros` function is useful to preallocate a multidimensional array.

Tips

• For real N-D arrays, `pagemtimes(X,'transpose',X,'none')` returns a matrix with symmetric pages. Similarly, for complex N-D arrays, you can get symmetric pages with `pagemtimes(X,'ctranspose',X,'none')`.

Version History

Introduced in R2020b