pagemrdivide

Page-wise right matrix divide

Since R2022a

Syntax

X = pagemrdivide(B,A)

X = pagemrdivide(B,A,transpA)

[X,rcondA] = pagemrdivide(___)

Description

X = pagemrdivide(B,A) computes the right matrix divide of each page of N-D array A into each page of N-D array B. Each page of the output array X is given by X(:,:,i) = B(:,:,i) / A(:,:,i). The pages of B and A must be valid inputs to mrdivide (/).

If B and A have more than three dimensions, then all dimensions beyond the first two must have compatible sizes. pagemrdivide implicitly expands the extra dimensions to divide all page combinations: X(:,:,i,j,k) = B(:,:,i,j,k) / A(:,:,i,j,k).

X = pagemrdivide(B,A,transpA) optionally applies a transposition to each page of A. The value of transpA can be "transpose", "ctranspose", or "none". For example, pagemrdivide(B,A,"transpose") computes X(:,:,i) = B(:,:,i) / A(:,:,i).'.

[X,rcondA] = pagemrdivide(___) also returns an estimate of the reciprocal condition number of each page of A, using any of the input argument combinations in previous syntaxes. If rcondA(1,1,i) < eps, then X(:,:,i) = B(:,:,i) / A(:,:,i) returns a warning because the matrix is ill conditioned. However, pagemrdivide does not issue a warning for ill-conditioned inputs.

Examples

Solve Systems of Equations

Create a 3-by-3-by-2 array A that has 3-by-3 matrices on each of two pages. Also create a 1-by-3-by-2 array B.

p1 = magic(3);
p2 = hilb(3);
A = cat(3,p1,p2)

A = 
A(:,:,1) =

     8     1     6
     3     5     7
     4     9     2


A(:,:,2) =

    1.0000    0.5000    0.3333
    0.5000    0.3333    0.2500
    0.3333    0.2500    0.2000

B = ones(1,3,2)

B = 
B(:,:,1) =

     1     1     1


B(:,:,2) =

     1     1     1

Solve the equation X(:,:,i)*A(:,:,i) = B(:,:,i) for each corresponding set of pages in A and B.

X = pagemrdivide(B,A)

X = 
X(:,:,1) =

    0.0667    0.0667    0.0667


X(:,:,2) =

    3.0000  -24.0000   30.0000

Solve Transposed Systems

Create a 4-by-4-by-2 array A that has 4-by-4 matrices on each of two pages. Also create a 1-by-4-by-2 array B.

p1 = pascal(4);
p2 = magic(4);
A = cat(3,p1,p2)

A = 
A(:,:,1) =

     1     1     1     1
     1     2     3     4
     1     3     6    10
     1     4    10    20


A(:,:,2) =

    16     2     3    13
     5    11    10     8
     9     7     6    12
     4    14    15     1

B = 2*ones(1,4,2)

B = 
B(:,:,1) =

     2     2     2     2


B(:,:,2) =

     2     2     2     2

Specify the "transpose" option to solve the system X(:,:,i)*A(:,:,i).' = B(:,:,i) for each corresponding set of pages in A and B.

X = pagemrdivide(B,A,"transpose")

X = 
X(:,:,1) =

     2     0     0     0


X(:,:,2) =

    0.1176    0.2353   -0.1176         0

Check Reciprocal Condition Number of Array Pages

Create a 10-by-10-by-2 array A that has 10-by-10 matrices on each of two pages. Also create a 1-by-10-by-2 array B.

p1 = diag([ones(9,1);0]);
p2 = pascal(10);
A = cat(3,p1,p2)

A = 
A(:,:,1) =

     1     0     0     0     0     0     0     0     0     0
     0     1     0     0     0     0     0     0     0     0
     0     0     1     0     0     0     0     0     0     0
     0     0     0     1     0     0     0     0     0     0
     0     0     0     0     1     0     0     0     0     0
     0     0     0     0     0     1     0     0     0     0
     0     0     0     0     0     0     1     0     0     0
     0     0     0     0     0     0     0     1     0     0
     0     0     0     0     0     0     0     0     1     0
     0     0     0     0     0     0     0     0     0     0


A(:,:,2) =

           1           1           1           1           1           1           1           1           1           1
           1           2           3           4           5           6           7           8           9          10
           1           3           6          10          15          21          28          36          45          55
           1           4          10          20          35          56          84         120         165         220
           1           5          15          35          70         126         210         330         495         715
           1           6          21          56         126         252         462         792        1287        2002
           1           7          28          84         210         462         924        1716        3003        5005
           1           8          36         120         330         792        1716        3432        6435       11440
           1           9          45         165         495        1287        3003        6435       12870       24310
           1          10          55         220         715        2002        5005       11440       24310       48620

B = 3*ones(1,10,2)

B = 
B(:,:,1) =

     3     3     3     3     3     3     3     3     3     3


B(:,:,2) =

     3     3     3     3     3     3     3     3     3     3

Solve the equation X(:,:,i)*A(:,:,i) = B(:,:,i) for each corresponding set of pages in A and B. Specify two outputs to also return the reciprocal condition number of each page in A.

[X,rcondA] = pagemrdivide(B,A)

X = 
X(:,:,1) =

   NaN   NaN   NaN   NaN   NaN   NaN   NaN   NaN   NaN   Inf


X(:,:,2) =

     3     0     0     0     0     0     0     0     0     0

rcondA = 
rcondA(:,:,1) =

     0


rcondA(:,:,2) =

   1.2295e-10

Compare the reciprocal condition numbers to eps. The results indicate that the matrix on the first page is ill conditioned, so the command B(:,:,1)/A(:,:,1) returns a warning and the results of the operation for that page are not reliable.

rcondA < eps

ans = 1x1x2 logical array
ans(:,:,1) =

   1


ans(:,:,2) =

   0

Input Arguments

B, A — Input arrays (as separate arguments)

multidimensional arrays

Input arrays. B and A are multidimensional arrays where each corresponding set of pages B(:,:,i,...) and A(:,:,i,...) are valid inputs to mrdivide.

If B and A have more than three dimensions, then all dimensions beyond the first two must have compatible sizes. pagemrdivide implicitly expands the extra dimensions to divide all page combinations: X(:,:,i,j,k) = B(:,:,i,j,k) / A(:,:,i,j,k).

Data Types: single | double
Complex Number Support: Yes

transpA — Transpose option for A

"none" (default) | "transpose" | "ctranspose"

Transpose option for A, specified as one of these values.

Value	Description
"none"	Do not transpose A. This is the default value.
"transpose"	Transpose each page of A without complex conjugation.
"ctranspose"	Transpose each page of A with complex conjugation.

Example: pagemrdivide(B,A,"transpose")

Output Arguments

X — Linear system solutions

multidimensional array

Linear system solutions, returned as a multidimensional array with the same number of pages as B and A. Each page of X is the solution to the linear system X(:,:,i,...) = B(:,:,i,...) / A(:,:,i,...).

rcondA — Reciprocal condition numbers of A

multidimensional array

Estimates of the reciprocal condition numbers of A returned as a multidimensional array. If the pages of A are m-by-n rectangular matrices with m~=n, then rcondA is estimated using the entries of R in the QR decomposition. If rcondA(1,1,i) < eps, then X(:,:,i) = B(:,:,i) / A(:,:,i) returns a warning because the matrix is ill conditioned. However, pagemrdivide does not issue a warning for ill-conditioned inputs.

rcondA may not be the same as the result of the rcond function.

More About

Array Pages

Page-wise functions like pagemrdivide 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 pagemrdivide 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

• Results obtained using pagemrdivide are numerically equivalent to computing the linear system solutions with 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

GPU Arrays

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

The pagemrdivide function supports GPU array input with these usage notes and limitations:

• The two-output syntax [X,rcondA] = pagemrdivide(___) is not supported.

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