1. Home
2. FLRV directive

# FLRV directive

Forms the values of LRV structures.

### Options

`PRINT` = string tokens Printed output required (`roots, vectors`); default `*` i.e. no printing Number of roots or vectors to print; default `*` i.e. print them all Whether to print the smallest roots instead of the largest (`yes, no`); default `no` Tolerance for detecting zero roots

### Parameters

`INMATRIX` = matrices or symmetric matrices Matrices whose latent roots and vectors are to be calculated LRV to store the latent roots and vectors from each `INMATRIX` (Generalized) within-group sums of squares and products matrix used in forming the two-matrix decomposition; if any of these is omitted, it is taken to be the identity matrix, giving the usual spectral decomposition LRV to store the imaginary parts of the latent roots and vectors arising from the decomposition of a non-symmetric matrix

### Description

The `INMATRIX` parameter lists the matrices for which latent roots and vectors are to be calculated. If the `WMATRIX` parameter is not set, `FLRV` provides the solution of the one-matrix eigenvalue problem

AX = XL

A is usually an n-by-n symmetric matrix. XLXʹ is then the spectral decomposition of the symmetric matrix A. Here L is a diagonal matrix containing the n latent roots, or eigenvalues, of A ordered such that

l1l2 ≥ … ≥ ln

The columns of the n-by-n matrix X are the corresponding latent vectors, or eigenvectors. The matrix X is orthogonal:

XʹX = XXʹ = In

The three options of `FLRV` control the printing of the results. You use the `PRINT` option to specify whether you want the roots or vectors to be printed. If you request the roots to be printed, the trace will be printed as well. By default nothing is printed. The `NROOTS` option governs how many of the roots and vectors are printed, while the `SMALLEST` option determines whether the largest or smallest roots, and corresponding vectors, are printed.

You can use the `LRV` parameter to save the latent roots and vectors, and the trace. You must declare these structures in advance if you want to save less than the full number of roots; otherwise, they are defined automatically, as `LRVs` with n rows. You can save a subset of the latent roots and vectors by supplying an LRV structure with fewer columns than rows. However this saves only the largest roots and the corresponding vectors. You cannot save the smallest roots directly, as the `SMALLEST` option applies only to printing. If you want to save the smallest roots, then you must save the complete set of roots and vectors, and extract the last columns of the matrix, for example using qualified identifiers. These rules are the same as those applied in the directives for multivariate analysis.

Alternatively, A can be a square, unsymmetric, matrix. This again provides the solution of the eigenvalue problem

AX = XL

but now A is a square matrix of order n, L is a diagonal matrix of n latent roots, and X is a square matrix of order n containing the right latent vectors of A. The solution of this problem may produce some complex latent roots, occurring as complex conjugate pairs, in which case the corresponding latent vectors are also complex conjugate pairs. To accomodate this, `FLRV` has a parameter, `ILRV`, for specifying an LRV structure to store the imaginary parts of the latent roots and vectors (the real parts being stored by the `LRV` parameter). The `ILRV` parameter need not be set, but a warning message is then printed if any complex roots are produced. If all the latent roots are real, they are sorted into descending order, such that l1l2 ≥ … ln, as in the symmetric case, but if some roots are complex they are ordered such that |l1| ≥ |l2| ≥ … ≥ |ln|. To detect whether a latent root is real, Genstat checks whether imaginary part is close to zero; to allow for numerical imprecision the value is tested against |l1| multiplied by the valued supplied by the `TOLERANCE` option, by default 10-6. The values saved by the `LRV` and `ILRV` parameters, however, are those generated by the algorithm, so procedures using `FLRV` may also need to test explicitly for zero roots. The `TOLERANCE` option and `ILRV` parameter are ignored if `INMATRIX` is set to a symmetric matrix. Percentage variations are printed only if all roots are real. The latent vectors xi are normalized so that xiʹx= 1, but this is not sufficient to determine them uniquely since they can still be scaled by any (complex) scalar z such that |z|=1. The convention adopted in Genstat is to apply an additional scaling such that the largest element of each xi is real and positive. The latent vectors are guaranteed to be orthogonal only when the matrix A is symmetric.

`FLRV` can also solve the two-matrix eigenvalue problem

AX = WXL

The symmetric matrix W is specified using the `WMATRIX` parameter. A is a symmetric matrix again specified by the `INMATRIX` parameter; if this is set to a square matrix, the `WMATRIX` parameter is ignored. L is a again diagonal matrix, and X a square matrix. Both A and W must have the same number of rows, n, and W must be positive semi-definite. Now the latent roots are the n elements of the diagonal matrix L and are the successive maxima of

l = (xʹAx) / (xʹWx)

where x is the corresponding column of the n-by-n matrix X, normalized so that XʹWX=I. The two-matrix decomposition is particularly relevant for canonical variate analysis.

For either eigenvalue problem, the sum of the latent roots is stored in the element of the `LRV` labelled `'Trace'`. In the one-matrix problem, this is also the trace of the original matrix A; but for the two-matrix problem, it is the trace of W-1A. Latent roots are often expressed as percentages of the trace.

The method used for the spectral decomposition of a symmetric matrix first reduces the matrix to tri-diagonal form using Householder transformations (Martin, Reinsch & Wilkinson 1968); this is followed by a QL algorithm for finding the eigenvalues and eigenvectors (Bowdler, Martin, Reinsch & Wilkinson 1968). The algorithm used for the unsymmetric eigenvalue problem is based on NAG Library subroutine F02EBF. The documentation of this routine should be consulted for a full discussion of the method and accuracy of the results (NAG 1994). If `INMATRIX` is set to a matrix `A` of order n which happens to be symmetric the results should be identical, up to the sign of the latent vectors, apart from small numerical discrepancies of the order of machine precision and dependent on n and the condition number of `A`. The two-matrix problem is solved using two spectral decompositions, each computed as for the first problem.

Options: `PRINT`, `NROOTS`, `SMALLEST`, `TOLERANCE`.

Parameters: `INMATRIX`, `LRV`, `WMATRIX`, `ILRV`.

Bowdler, H., Martin, R.S., Reinsch, C. & Wilkinson, J.H. (1968). The QR and QL algorithms for symmetric matrices. Numerische Mathematik, 11, 293-306.

Martin, R.S., Reinsch, C. & Wilkinson, J.H. (1968). Householders tridiagonalisation of a symmetric matrix. Numerische Mathematik, 11, 181-195.

Numerical Algorithms Group. (1994). F02EBF. NAG Fortran Library Mark 15, Volume 5. Oxford: Numerical Algorithms Group.

Directives: `LRV`, `MATRIX`, `SYMMETRICMATRIX`, `NAG`, `QRD`, `SVD`.

Functions: `EVALUES`, `EVECTORS`.

### Example

```" Genstat example FLRV-1: Symmetric eigenvalue decompositions"

SYMMETRICMATRIX [ROWS=5] a; VALUES=!(1.22, 4.12,4.15, 4.12,7.02,7.12,\
5.68,8.12,4.23,5.25,\
8.12,4.65,8.36,7.25,9.12)
"
The & symbol indicates that the directive name or procedure name
from the previous statement is to be repeated, together with any option
settings that are not explicitly changed. In this case it is the
SYMMETRICMATRIX directive that is repeated.
"
&   [ROWS=4] b; VALUES=!(16, 4,9, 10,3,25, 4,6,5,16)
&   [ROWS=4] w; VALUES=!( 4, -1,9, 2,-3,16, 1,0,-1,1)

"
Print the three symmetric matrices, one after the other.
"
PRINT [SERIAL=y] a,b,w

"
Declare three LRV structures l, l5 and l5s which will hold the results
of the matrix decompositions.
"
LRV [ROWS=4; COLUMNS=4] l
LRV [ROWS=5; COLUMNS=5] l5
&   [ROWS=5; COLUMNS=3] l5s

"
Obtain and print the latent roots of the three symmetric matrices:

1. For matrix a, saving all five roots.
2. For matrix a, saving the largest three roots.
3. For matrix b, saving all roots and the within-group sums of squares
and product matrix used in forming the decomposition into the matrix w.
"

FLRV INMATRIX=a; LRV=l5
PRINT [SERIAL=y] l5[]

FLRV INMATRIX=a; l5s
PRINT [SERIAL=y] l5s[]

FLRV INMATRIX=b; LRV=l; WMATRIX=w
PRINT [SERIAL=y] l[]
```