pagemldivide

Page-wise left matrix divide

Since R2022a

Syntax

X = pagemldivide(A,B)

X = pagemldivide(A,transpA,B)

[X,rcondA] = pagemldivide(___)

Description

X = pagemldivide(A,B) computes the left 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) = A(:,:,i) \ B(:,:,i). The pages of A and B must be valid inputs to mldivide (\).

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

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

[X,rcondA] = pagemldivide(___) 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) = A(:,:,i) \ B(:,:,i) returns a warning because the matrix is ill conditioned. However, pagemldivide 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 3-by-1-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(3,1,2)

B = 
B(:,:,1) =

     1
     1
     1


B(:,:,2) =

     1
     1
     1

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

X = pagemldivide(A,B)

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 4-by-1-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(4,1,2)

B = 
B(:,:,1) =

     2
     2
     2
     2


B(:,:,2) =

     2
     2
     2
     2

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

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

X = 
X(:,:,1) =

     2
     0
     0
     0


X(:,:,2) =

    0.0263
   -0.0386
    0.1562
    0.0913

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 10-by-1-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(10,1,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 A(:,:,i)*X(:,:,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] = pagemldivide(A,B)

X = 
X(:,:,1) =

     3
     3
     3
     3
     3
     3
     3
     3
     3
   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 A(:,:,1)\B(:,:,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

A, B — Input arrays (as separate arguments)

multidimensional arrays

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

If A and B have more than three dimensions, then all dimensions beyond the first two must have compatible sizes. pagemldivide implicitly expands the extra dimensions to divide all page combinations: X(:,:,i,j,k) = A(:,:,i,j,k) \ B(:,:,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: pagemldivide(A,"transpose",B)

Output Arguments

X — Linear system solutions

multidimensional array

Linear system solutions, returned as a multidimensional array with the same number of pages as A and B. Each page of X is the solution to the linear system X(:,:,i,...) = A(:,:,i,...) \ B(:,:,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) = A(:,:,i) \ B(:,:,i) returns a warning because the matrix is ill conditioned. However, pagemldivide 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 pagemldivide 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 pagemldivide 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 pagemldivide 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.

Algorithms

Similar to mldivide, the pagemldivide function determines which algorithm to use in solving the linear systems in the input array by applying a series of checks to the array pages. Different algorithms can be used with different pages in the input array. pagemldivide chooses between QR, Triangular, LU, and Cholesky solvers for each array page in A depending on its properties, as shown in this diagram.

Extended Capabilities

GPU Arrays

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

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

• The two-output syntax [X,rcondA] = pagemldivide(___) 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

R2022b: Improved performance with small matrices

The pagemldivide function shows improved performance when solving linear systems A*x = b with a small coefficient matrix A. The performance improvement applies to real matrix pages that are 16-by-16 or smaller, and complex matrix pages that are 8-by-8 or smaller.

For example, this code solves three triangular linear systems specified by an 11-by-11-by-3 array. The code is about 2.2x faster than in the previous release.

function pagemldividePerf
a = triu(rand(11));
A = cat(3,a,a,a);
for k = 1:1e5
    x = pagemldivide(A,A);
end
end

The approximate execution times are:

R2022a: 0.65 s

R2022b: 0.30 s

The code was timed on a Windows^® 10, Intel^® Xeon^® CPU W-2133 @ 3.60 GHz test system using the timeit function:

timeit(@pagemldividePerf)