pageeig

Page-wise eigenvalues and eigenvectors

Since R2023a

Syntax

D = pageeig(X)

[V,D] = pageeig(X)

[V,D,W] = pageeig(X)

[___] = pageeig(X,balanceOption)

[___] = pageeig(___,outputForm)

Description

D = pageeig(X) returns the eigenvalues of each page of a multidimensional array. Each page of the output D(:,:,i) is a column vector containing the eigenvalues of X(:,:,i). Each page of X must be a square matrix.

[V,D] = pageeig(X) computes the eigenvalue decomposition of each page of a multidimensional array. The pages in the outputs satisfy the equation: X(:,:,i) * V(:,:,i) = V(:,:,i) * D(:,:,i).

If X has more than three dimensions, then pageeig returns arrays with the same number of dimensions such that the outputs satisfy the equation: X(:,:,i,j,k) * V(:,:,i,j,k) = V(:,:,i,j,k) * D(:,:,i,j,k).

[V,D,W] = pageeig(X) also computes the left eigenvectors of each page of a multidimensional array. The pages in W satisfy the equation: W(:,:,i)' * X(:,:,i) = D(:,:,i) * W(:,:,i)'.

[___] = pageeig(X,balanceOption), where balanceOption is "nobalance", disables the preliminary balancing step in the algorithm. The default for balanceOption is "balance", which enables balancing. The pageeig function can return any of the output arguments in previous syntaxes.

[___] = pageeig(___,outputForm) returns the eigenvalues in the form specified by outputForm using any of the input or output arguments in previous syntaxes. Specify outputForm as "vector" to return the eigenvalues as pages of column vectors or as "matrix" to return the eigenvalues as pages of diagonal matrices.

Examples

Eigenvalues of Array Pages

Create two 6-by-6 matrices. Use the cat function to concatenate them along the third dimension into a 6-by-6-by-2 array.

A = magic(6);
B = hilb(6);
X = cat(3,A,B);

Calculate the eigenvalues of each array page.

D = pageeig(X)

D = 
D(:,:,1) =

  111.0000
   27.0000
  -27.0000
    9.7980
   -0.0000
   -9.7980


D(:,:,2) =

    0.0000
    0.0000
    0.0006
    0.0163
    0.2424
    1.6189

Specify the "matrix" option to instead return the eigenvalues as pages of diagonal matrices.

D = pageeig(X,"matrix")

D = 
D(:,:,1) =

  111.0000         0         0         0         0         0
         0   27.0000         0         0         0         0
         0         0  -27.0000         0         0         0
         0         0         0    9.7980         0         0
         0         0         0         0   -0.0000         0
         0         0         0         0         0   -9.7980


D(:,:,2) =

    0.0000         0         0         0         0         0
         0    0.0000         0         0         0         0
         0         0    0.0006         0         0         0
         0         0         0    0.0163         0         0
         0         0         0         0    0.2424         0
         0         0         0         0         0    1.6189

Eigenvalue Decomposition of Array Pages

Create two 5-by-5 matrices. Use the cat function to concatenate them along the third dimension into a 5-by-5-by-2 array.

A = magic(5);
B = hilb(5);
X = cat(3,A,B);

Calculate the eigenvalue decomposition of each array page.

[V,D] = pageeig(X)

V = 
V(:,:,1) =

   -0.4472    0.0976   -0.6330    0.6780   -0.2619
   -0.4472    0.3525    0.5895    0.3223   -0.1732
   -0.4472    0.5501   -0.3915   -0.5501    0.3915
   -0.4472   -0.3223    0.1732   -0.3525   -0.5895
   -0.4472   -0.6780    0.2619   -0.0976    0.6330


V(:,:,2) =

   -0.0062    0.0472    0.2142   -0.6019    0.7679
    0.1167   -0.4327   -0.7241    0.2759    0.4458
   -0.5062    0.6674   -0.1205    0.4249    0.3216
    0.7672    0.2330    0.3096    0.4439    0.2534
   -0.3762   -0.5576    0.5652    0.4290    0.2098

D = 
D(:,:,1) =

   65.0000         0         0         0         0
         0  -21.2768         0         0         0
         0         0  -13.1263         0         0
         0         0         0   21.2768         0
         0         0         0         0   13.1263


D(:,:,2) =

    0.0000         0         0         0         0
         0    0.0003         0         0         0
         0         0    0.0114         0         0
         0         0         0    0.2085         0
         0         0         0         0    1.5671

Verify the relation $\mathit{X}\mathit{V}=\mathit{V}\mathit{D}$ for each array page, within machine precision.

err = pagenorm(pagemtimes(X,V) - pagemtimes(V,D),"fro")

err = 
err(:,:,1) =

   8.7328e-14


err(:,:,2) =

   4.2074e-16

Left Eigenvectors of Array Pages

Create two 6-by-6 matrices. Use the cat function to concatenate them along the third dimension into a 6-by-6-by-2 array.

A = magic(6);
B = hilb(6);
X = cat(3,A,B);

Calculate the eigenvalue decomposition of each array page, specifying three outputs to calculate the left eigenvectors W.

[V,D,W] = pageeig(X)

V = 
V(:,:,1) =

    0.4082   -0.2887    0.4082    0.1507    0.4714   -0.4769
    0.4082    0.5774    0.4082    0.4110    0.4714   -0.4937
    0.4082   -0.2887    0.4082   -0.2602   -0.2357    0.0864
    0.4082    0.2887   -0.4082    0.4279   -0.4714    0.1435
    0.4082   -0.5774   -0.4082   -0.7465   -0.4714    0.0338
    0.4082    0.2887   -0.4082    0.0171    0.2357    0.7068


V(:,:,2) =

   -0.0012   -0.0111    0.0622    0.2403   -0.6145    0.7487
    0.0356    0.1797   -0.4908   -0.6977    0.2111    0.4407
   -0.2407   -0.6042    0.5355   -0.2314    0.3659    0.3207
    0.6255    0.4436    0.4170    0.1329    0.3947    0.2543
   -0.6898    0.4415   -0.0470    0.3627    0.3882    0.2115
    0.2716   -0.4591   -0.5407    0.5028    0.3707    0.1814

D = 
D(:,:,1) =

  111.0000         0         0         0         0         0
         0   27.0000         0         0         0         0
         0         0  -27.0000         0         0         0
         0         0         0    9.7980         0         0
         0         0         0         0   -0.0000         0
         0         0         0         0         0   -9.7980


D(:,:,2) =

    0.0000         0         0         0         0         0
         0    0.0000         0         0         0         0
         0         0    0.0006         0         0         0
         0         0         0    0.0163         0         0
         0         0         0         0    0.2424         0
         0         0         0         0         0    1.6189

W = 
W(:,:,1) =

    0.4082   -0.7029   -0.1983    0.5244    0.5000   -0.0530
    0.4082    0.6797    0.0777   -0.4714   -0.0000   -0.4714
    0.4082    0.0233    0.8547   -0.0530   -0.5000    0.5244
    0.4082   -0.1576   -0.1983    0.5244   -0.5000   -0.0530
    0.4082    0.1344   -0.4117   -0.4714   -0.0000   -0.4714
    0.4082    0.0233   -0.1241   -0.0530    0.5000    0.5244


W(:,:,2) =

   -0.0012   -0.0111    0.0622    0.2403   -0.6145    0.7487
    0.0356    0.1797   -0.4908   -0.6977    0.2111    0.4407
   -0.2407   -0.6042    0.5355   -0.2314    0.3659    0.3207
    0.6255    0.4436    0.4170    0.1329    0.3947    0.2543
   -0.6898    0.4415   -0.0470    0.3627    0.3882    0.2115
    0.2716   -0.4591   -0.5407    0.5028    0.3707    0.1814

Verify the relation ${\mathit{W}}^{*}\mathit{X}=\mathit{D}{\mathit{W}}^{*}$ for each array page, within machine precision.

err = pagenorm(pagemtimes(W,"ctranspose",X,"none") - pagemtimes(D,"none",W,"ctranspose"))

err = 
err(:,:,1) =

   8.5480e-14


err(:,:,2) =

   4.0946e-16

Input Arguments

X — Input array

matrix | multidimensional array

Input array, specified as a matrix or multidimensional array. X must have the same number of rows and columns.

Data Types: single | double
Complex Number Support: Yes

balanceOption — Balance option

"balance" (default) | "nobalance"

Balance option, specified as "balance", which enables a preliminary balancing step, or "nobalance", which disables it.

In most cases, the balancing step improves the conditioning of the pages of X to produce more accurate results. However, there are cases in which balancing produces incorrect results. Specify "nobalance" when the pages of X contain values whose scale differs dramatically. For example, if X contains nonzero integers as well as very small (near zero) values, then the balancing step might scale the small values to make them as significant as the integers and produce inaccurate results.

For more information about balancing, see balance.

outputForm — Output format of eigenvalues

"vector" | "matrix"

Output format of eigenvalues, specified as "vector" or "matrix". Use this option to specify whether the pages of eigenvalues are returned as column vectors or as diagonal matrices. The default behavior varies according to the number of outputs specified:

• If you specify one output, such as D = pageeig(X), then the eigenvalues are returned as pages of column vectors by default.

• If you specify two or three outputs, such as [V,D] = pageeig(X), then the eigenvalues are returned as pages of diagonal matrices by default.

Example: D = pageeig(X,"matrix") returns the eigenvalues as pages of diagonal matrices using the one-output syntax.

Output Arguments

D — Eigenvalues

multidimensional array

Eigenvalues, returned as a multidimensional array. Each page of D is either a column vector or diagonal matrix, depending on the value of outputForm. Each eigenvalue D(k,k,i) corresponds with the right eigenvector V(:,k,i) and the left eigenvector W(:,k,i).

• When X(:,:,i) is real symmetric or complex Hermitian, the values of D(:,:,i) that satisfy Xv = λv are real.

• When X(:,:,i) is real skew-symmetric or complex skew-Hermitian, the values of D(:,:,i) that satisfy Xv = λv are imaginary.

V — Right eigenvectors

multidimensional array

Right eigenvectors, returned as a multidimensional array. Each page V(:,:,i) is a square matrix whose columns are the right eigenvectors of X(:,:,i). The form and normalization of V depends on the combination of input arguments:

• [V,D] = pageeig(X) returns eigenvectors in V that are normalized so that the 2-norm of each is 1.

  If X(:,:,i) is real symmetric, Hermitian, or skew-Hermitian, then the right eigenvectors in V(:,:,i) are orthonormal.

• [V,D] = pageeig(X,"nobalance") returns eigenvectors in V that are not normalized. The 2-norm of each eigenvector is not necessarily 1.

Different machines and releases of MATLAB^® can produce different eigenvectors that are still numerically accurate:

• For real eigenvectors, the sign of the eigenvectors can change.

• For complex eigenvectors, the eigenvectors can be multiplied by any complex number of magnitude 1.

• For a multiple eigenvalue, its eigenvectors can be recombined through linear combinations. For example, if Ax = λx and Ay = λy, then A(x+y) = λ(x+y), so x+y also is an eigenvector of A.

W — Left eigenvectors

multidimensional array

Left eigenvectors, returned as a multidimensional array. Each page W(:,:,i) is a square matrix whose columns are the left eigenvectors of X(:,:,i). The form and normalization of W depends on the combination of input arguments:

• [V,D,W] = pageeig(X) returns eigenvectors in W that are normalized so that the 2-norm of each is 1.

  If X(:,:,i) is symmetric, then W(:,:,i) is the same as V(:,:,i).

• [V,D,W] = pageeig(X,"nobalance") returns eigenvectors in W that are not normalized. The 2-norm of each eigenvector is not necessarily 1.

Different machines and releases of MATLAB can produce different eigenvectors that are still numerically accurate:

• For real eigenvectors, the sign of the eigenvectors can change.

• For complex eigenvectors, the eigenvectors can be multiplied by any complex number of magnitude 1.

• For a multiple eigenvalue, its eigenvectors can be recombined through linear combinations. For example, if Ax = λx and Ay = λy, then A(x+y) = λ(x+y), so x+y also is an eigenvector of A.

More About

Array Pages

Page-wise functions like pageeig 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 pageeig 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 pageeig are numerically equivalent to computing the eigenvalue decomposition of each of the same matrices in a for-loop. However, the two results might differ slightly due to floating-point round-off error.

Version History

Introduced in R2023a