Main Content

pagemldivide

Page-wise left matrix divide

Since R2022a

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

example

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

example

[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.

example

Examples

collapse all

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

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

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

collapse all

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

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

ValueDescription
"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

collapse all

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

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

collapse all

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.

3-D array with several matrices stacked on top of each other as pages in the third dimension

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.

Flow chart displays checks performed by pagemldivide to decide which solver to use.

Extended Capabilities

Version History

Introduced in R2022a

expand all