# diagmatrix

Calculate eigenvectors and eigenvalues from given symmetric matrix.

`diagmatrix <name> [out <filename>] [thermo [outthermo <filename>]] [vecs <#>] [name <modesname>] [reduce] [nmwiz [nmwizvecs <#>] [nmwizfile <filename>]]`

`<name>` Name of symmetric matrix to diagonalize.
`[out <filename>]` Write results to <filename>.
`[thermo [outthermo <filename>]]` Mass-weighted covariance (mwcovar) matrix only. Calculate entropy, heat capacity, and internal energy from the structure of a molecule (average coordinates, see above) and its vibrational frequencies using standard statistical mechanical formulas for an ideal gas. Results are written to <filename> if specified, otherwise results are written to STDOUT. Note that this converts the units of the calculated eigenvalues to frequencies (cm-1).
`[vecs <#>]` Number of eigenvectors to calculate. Default is 0, which is only allowed when ’thermo’ is specified.
`[name <modesname>]` Store resulting modes data set with name <modesname>.
`[reduce]` Covariance (covar/mwcovar/distcovar) matrices only. For coordinate covariance (covar/mwcovar) matrices, each eigenvector element is reduced via $E_1 = E_{ix}^2 + E_{iy}^2 + E_{iz}^2$. For distance covariance (distcovar) the eigenvectors are reduced by taking the sum of the squares of each row. See Abseher & Nilges for further details. They may be used to compare results from PCA in distance space with those from PCA in cartesian-coordinate space.
`[nmwiz]` Generate output in .nmd format file for viewing with NMWiz[579]. See here for further details.
`[nmwizvecs <#>]` Number of vectors to write out for nmwiz output, starting with the lowest frequency mode (default 20).
`[nmwizfile <filename>]` Name of nmwiz file to write to (default ’out.nmd’).
[nmwizmask <mask>] Mask of atoms corresponding to eigenvectors – should be the same one used to generate the matrix.

Calculate eigenvectors and eigenvalues for the specified symmetric matrix. This is followed by Principal ComponentAnalysis (in cartesian coordinate space in the case of a covariance matrix or in distance space in the case of a distance-covariance matrix), or Quasiharmonic Analysis (in the case of a mass-weighted covariance matrix). Diagonalization of distance, correlation, idea, and ired matrices are also possible. Eigenvalues are given in $cm^{-1}$
in the case of a mass-weighted covariance matrix and in the units of the matrix elements in all other cases. In the case of a mass-weighted covariance matrix, the eigenvectors are mass-weighted.

For quasi-harmonic analysis the input must be a mass-weighted covariance matrix. Thermodynamic quantities are calculated based on statistical mechanical formulae that assume the input system is oscillating in a single energy well: see Statistical Thermodynamics by D. A. McQuarrie, particularly chapters 4, 5, and 6 for more details [reference]. For an in-depth discussion of the accuracy of thermodynamic parameters obtained via quasi-harmonic analysis see Chang et al.

Note that the maximum number of non-zero eigenvalues obtainable depends on the number of frames used to generate the input matrix; the number of frames should be equal to or greater than the number of columns in the matrix in order to obtain all eigenmodes. Results may include average coordinates (in the case of covar, mwcovar, correl), average distances (in the case of distcovar), main diagonal elements (in the case of idea and ired), eigenvalues, and eigenvectors.

For example, in the following a mass-weighted covariance matrix of all atoms is generated and stored internally with the name mwcvmat; the matrix itself is written to mwcvmat.dat. Subsequently, the first 20 eigenmodes of the matrix are calculated and written to evecs.dat, and quasiharmonic analysis is performed at 300.0 K, with the results written to thermo.dat.

```matrix mwcovar name mwcvmat out mwcvmat.dat
diagmatrix mwcvmat out evecs.dat vecs 20 \
thermo outthermo thermo.dat temp 300.0```

Output Format
The “modes” or “evecs” output file is a text file with the following format:

```[Reduced] Eigenvector file: <Type> nmodes <#> width <width>
<# Avg Coords> <Eigenvector Size>
<Average Coordinates>```

Where <Type> is a string identifying what kind of matrix the eigenvectors/eigenvalues were determined from, nmodes is how many eigenvectors are in the file, and <Average Coordinates> are in lines 7 columns wide, with each element having width specified by <width>. Then for each eigenvector:

```****
<Eigenvector#> <Eigenvalue>
<Eigenvector Coordinates>
...```

Where <Eigenvector Coordinates> are in lines 7 columns wide, with each element having width specified by <width>.