# pageeig

## Syntax

## Description

`[`

computes the eigenvalue decomposition of each page of a multidimensional array. The pages in
the outputs satisfy the equation: `V`

,`D`

] = pageeig(`X`

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

.

`[___] = pageeig(`

,
where `X`

,`balanceOption`

)`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(___,`

returns the eigenvalues in the form specified by `outputForm`

)`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}\text{\hspace{0.17em}}\mathit{V}=\mathit{V}\text{\hspace{0.17em}}\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}\text{\hspace{0.17em}}{\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*X**v*=*λ**v*are real.When

`X(:,:,i)`

is real skew-symmetric or complex skew-Hermitian, the values of`D(:,:,i)`

that satisfy*X**v*=*λ**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

*A**x*=*λ**x*and*A**y*=*λ**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

*A**x*=*λ**x*and*A**y*=*λ**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, 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 `pageeig`

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

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)