# 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

example

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

example

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

example

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

example

````[___] = 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

collapse all

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

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.5002e-14 err(:,:,2) = 5.9005e-16 ```

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) = 6.1573e-14 err(:,:,2) = 4.5820e-16 ```

## Input Arguments

collapse all

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

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

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

collapse all

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.

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.

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.

collapse all

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