pagemldivide

Page-wise left matrix divide

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 the reciprocal condition number of each page of A, using any of the input argument combinations in previous syntaxes. The value of rcondA(1,1,i) is the reciprocal condition number of A(:,:,i). 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) =

  Columns 1 through 6

           1           1           1           1           1           1
           1           2           3           4           5           6
           1           3           6          10          15          21
           1           4          10          20          35          56
           1           5          15          35          70         126
           1           6          21          56         126         252
           1           7          28          84         210         462
           1           8          36         120         330         792
           1           9          45         165         495        1287
           1          10          55         220         715        2002

  Columns 7 through 10

           1           1           1           1
           7           8           9          10
          28          36          45          55
          84         120         165         220
         210         330         495         715
         462         792        1287        2002
         924        1716        3003        5005
        1716        3432        6435       11440
        3003        6435       12870       24310
        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) =

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

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.

More About

Array Pages

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

Version History

Introduced in R2022a