RealSquareMatrix (CML Euclid 2.9 API)

java.lang.Object
- org.xmlcml.euclid.RealMatrix
- - org.xmlcml.euclid.RealSquareMatrix

All Implemented Interfaces:

EuclidConstants

Direct Known Subclasses:

Transform2, Transform3
```
public class RealSquareMatrix
extends RealMatrix
```
square matrix class RealSquareMatrix represents a square m-x-m matrix. The basic matrix algebra for square matrices is represented here Check out the exciting member functions, which are supported by Exceptions where appropriate. (NB. No attempt has been made to provide numerical robustness and inversion, diagonalisation, etc are as you find them.)

Author:

(C) P. Murray-Rust, 1996

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class RealSquareMatrix.Type
type

Nested Classes
Modifier and Type	Class and Description
`static class`	`RealSquareMatrix.Type` type

Field Summary
- Fields inherited from class org.xmlcml.euclid.RealMatrix
  cols, flmat, rows
- Fields inherited from interface org.xmlcml.euclid.EuclidConstants
  C_AMP, C_APOS, C_ATSIGN, C_BACKSLASH, C_BACKSPACE, C_CARET, C_COLON, C_COMMA, C_DEL, C_DOLLAR, C_EQUALS, C_FORMFEED, C_HASH, C_LANGLE, C_LBRAK, C_LCURLY, C_LSQUARE, C_MINUS, C_NBSP, C_NEWLINE, C_NL, C_PERCENT, C_PERIOD, C_PIPE, C_PLUS, C_POUND, C_QUERY, C_QUOT, C_RANGLE, C_RBRAK, C_RCURLY, C_RETURN, C_RSQUARE, C_SEMICOLON, C_SHRIEK, C_SLASH, C_SPACE, C_STAR, C_TAB, C_TILDE, C_UNDER, EPS, F_S, NONWHITEPUNC, NONWHITEPUNC0, NONWHITEPUNC0REGEX, ONE_THIRD, PUNC, S_AMP, S_APOS, S_ATSIGN, S_BACKSLASH, S_CARET, S_COLON, S_COMMA, S_DOLLAR, S_EMPTY, S_EQUALS, S_FORMFEED, S_HASH, S_LANGLE, S_LBRAK, S_LCURLY, S_LSQUARE, S_MINUS, S_NEWLINE, S_NL, S_PERCENT, S_PERIOD, S_PIPE, S_PLUS, S_POUND, S_QUERY, S_QUOT, S_RANGLE, S_RBRAK, S_RCURLY, S_RETURN, S_RSQUARE, S_SEMICOLON, S_SHRIEK, S_SLASH, S_SPACE, S_STAR, S_TAB, S_TILDE, S_UNDER, S_WHITEREGEX, TWO_THIRDS, U_S, WHITESPACE

Constructor Summary

Constructors
Constructor and Description
`RealSquareMatrix()` Constructor.
`RealSquareMatrix(double[][] matrix)` constructor from array.
`RealSquareMatrix(int rows)` Constructor.
`RealSquareMatrix(int rows, double f)` Creates real square matrix with all elements initialized to double value.
`RealSquareMatrix(int rows, double[] array)` Creates real square matrix from array THE COLUMN IS THE FASTEST MOVING INDEX, that is the matrix is filled as mat(0,0), mat(0,1) ...
`RealSquareMatrix(RealMatrix m)` shallow copy from RealMatrix the array values are not copied (only the reference)
`RealSquareMatrix(RealMatrix m, int lowrow, int lowcol, int rows)` Constructor for submatrix of another matrix.
`RealSquareMatrix(RealSquareMatrix m)` copy constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`RealArray`	`calculateEigenvalues()`
`RealSquareMatrix`	`calculateEigenvectors()` V is an orthogonal matrix, i.e.
`RealSquareMatrix`	`calculateInverse()`
`RealSquareMatrix`	`copyLowerToUpper()` copy lower triangle into upper triangle.
`RealSquareMatrix`	`copyUpperToLower()` copy upper triangle into lower triangle.
`double`	`determinant()` determinant.
`static RealSquareMatrix`	`diagonal(RealArray f)` create diagonal matrix from real matrix.
`int`	`diagonaliseAndReturnRank(RealArray eigenvalues, RealSquareMatrix eigenvectors, EuclidRuntimeException illCond)` diagonalisation returns eigenvalues and vectors as MODIFIED arguments; 'this' is NOT affected USE JAMA INSTEAD Note that IllCondMatrixException is RETURNED and not thrown
`static RealSquareMatrix`	`fromLowerTriangle(RealArray f)` create square matrix from lower triangle values upper triangle is filled with zeros
`static RealSquareMatrix`	`fromUpperTriangle(RealArray f)` create square matrix from lower triangle lower triangle is filled with zeros
`static RealSquareMatrix`	`getCrystallographicOrthogonalisation(double[] celleng, double[] angle)` create orthogonlisation matrix from cell lengths and angles.
`RealSquareMatrix`	`getInverse()` inversion of matrix.
`boolean`	`isEqualTo(RealSquareMatrix r)` are two matrices identical
`boolean`	`isImproperRotation()` is matrix an improper rotation.
`boolean`	`isLowerTriangular()` is matrix LowerTriangular.
`boolean`	`isOrthogonal()` is matrix orthogonal.
`boolean`	`isOrthonormal()` is matrix unitary.
`boolean`	`isSymmetric()` is matrix symmetric.
`boolean`	`isUnit()` is it a unit matrix.
`boolean`	`isUnitary()` is matrix unitary.
`boolean`	`isUpperTriangular()` is matrix UpperTriangular.
`RealArray`	`lowerTriangle()` copy lower triangle into linear array; order: 0,0; 1,0; 1,1; 2,0
`RealSquareMatrix`	`multiply(RealSquareMatrix m)` matrix multiplication.
`void`	`orthogonalise()` orthogonalise matrix.
`RealSquareMatrix`	`orthonormalize()` orthonormalise matrix.
`static RealSquareMatrix`	`outerProduct(RealArray f)` Creates square matrix from real matrix.
`RealSquareMatrix`	`plus(RealSquareMatrix m)` matrix addition.
`void`	`resetEigenDecomposition()`
`void`	`shallowCopy(RealSquareMatrix m)` shallowCopy an existing square matrix.
`RealSquareMatrix`	`subtract(RealSquareMatrix m)` matrix subtraction.
`double`	`trace()` trace.
`void`	`transpose()` transpose.

Methods inherited from class org.xmlcml.euclid.RealMatrix
appendColumnData, appendColumnData, appendRowData, appendRowData, checkNonEmptyMatrix, clearMatrix, columnwiseDivide, createMatrixWithOriginShifted, deleteColumn, deleteColumns, deleteRow, deleteRows, elementAt, elementAt, elementsInRange, euclideanColumnLength, euclideanColumnLengths, euclideanRowLength, euclideanRowLengths, extractColumnData, extractColumns, extractRowData, extractRows, extractSubMatrixData, format, getCols, getFormat, getIntMatrix, getMatrix, getMatrixAsArray, getRows, getTranspose, indexOfLargestElement, indexOfLargestElementInColumn, indexOfLargestElementInRow, indexOfSmallestElement, indexOfSmallestElementInColumn, indexOfSmallestElementInRow, insertColumnData, insertColumnData, insertRowData, insertRowData, insertRows, isEqualTo, isSquare, isZero, largestElement, largestElementInColumn, largestElementInRow, makeSpaceForNewColumns, multiply, multiply, multiplyBy, multiplyEquals, negative, normaliseByColumns, normaliseByRows, plus, reorderColumnsBy, reorderRowsBy, replaceColumnData, replaceColumnData, replaceColumnData, replaceRowData, replaceRowData, replaceRowData, replaceSubMatrixData, scaleAndInterpolate, setAllElements, setElementAt, setFormat, shallowCopy, smallestElement, smallestElementInColumn, smallestElementInRow, subtract, toString, translateByColumn, writeXML

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - RealSquareMatrix
```
public RealSquareMatrix()
```
    Constructor. This gives a default matrix with cols = rows = 0.
  - RealSquareMatrix
```
public RealSquareMatrix(int rows)
```
    Constructor.
    
    Parameters:
    
    rows - number of rows and columns values are set to zero
  - RealSquareMatrix
```
public RealSquareMatrix(int rows,
                        double[] array)
                 throws EuclidRuntimeException
```
    Creates real square matrix from array THE COLUMN IS THE FASTEST MOVING INDEX, that is the matrix is filled as mat(0,0), mat(0,1) ... C-LIKE
    
    Parameters:
    
    rows - the final rows and cols of real square matrix
    
    array - of size (rows * rows)
    
    Throws:
    
    EuclidRuntimeException - array size must be multiple of rows
  - RealSquareMatrix
```
public RealSquareMatrix(int rows,
                        double f)
```
    Creates real square matrix with all elements initialized to double value.
    
    Parameters:
    
    rows - size of square matrix
    
    f - value of all elements
  - RealSquareMatrix
```
public RealSquareMatrix(RealMatrix m,
                        int lowrow,
                        int lowcol,
                        int rows)
                 throws EuclidRuntimeException
```
    Constructor for submatrix of another matrix.
    
    Parameters:
    
    m - matrix to slice (need not be square)
    
    lowrow - the start row inclusive (count from 0)
    
    lowcol - the start column inclusive (count from 0)
    
    rows - size of final matrix
    
    Throws:
    
    EuclidRuntimeException - lowrow, lowcol or rows are not consistent with size of m
  - RealSquareMatrix
```
public RealSquareMatrix(RealSquareMatrix m)
```
    copy constructor.
    
    Parameters:
    
    m - matrix to copy
  - RealSquareMatrix
```
public RealSquareMatrix(RealMatrix m)
                 throws EuclidRuntimeException
```
    shallow copy from RealMatrix the array values are not copied (only the reference)
    
    Parameters:
    
    m - matrix to copy reference from
    
    Throws:
    
    EuclidRuntimeException - m must be square (that is cols = rows)
  - RealSquareMatrix
```
public RealSquareMatrix(double[][] matrix)
                 throws EuclidRuntimeException
```
    constructor from array. form from a Java 2-D array (it holds row and column count)
    
    Parameters:
    
    matrix - to copy
    
    Throws:
    
    EuclidRuntimeException - matrix is not square (might even not be rectangular!)
- Method Detail
  - outerProduct
```
public static RealSquareMatrix outerProduct(RealArray f)
```
    Creates square matrix from real matrix.
    
    Parameters:
    
    f - real array (length rows) multiplied to give outer product
    
    Returns:
    
    square matrix of size rows * rows
  - diagonal
```
public static RealSquareMatrix diagonal(RealArray f)
```
    create diagonal matrix from real matrix.
    
    Parameters:
    
    f - real array (length rows)
    
    Returns:
    
    square matrix with elem (i, i) = f(i), else 0.0
  - shallowCopy
```
public void shallowCopy(RealSquareMatrix m)
                 throws EuclidRuntimeException
```
    shallowCopy an existing square matrix.
    
    Parameters:
    
    m - matrix to shallow copy
    
    Throws:
    
    EuclidRuntimeException - m must have the same number of rows and cols as this
  - fromLowerTriangle
```
public static RealSquareMatrix fromLowerTriangle(RealArray f)
```
    create square matrix from lower triangle values upper triangle is filled with zeros
    
    Parameters:
    
    f - real array (length rows * (rows+1) / 2)
    
    Returns:
    
    square matrix with elem (i, j) = f(k++), else 0.0
  - fromUpperTriangle
```
public static RealSquareMatrix fromUpperTriangle(RealArray f)
```
    create square matrix from lower triangle lower triangle is filled with zeros
    
    Parameters:
    
    f - real array (length rows * (rows+1) / 2)
    
    Returns:
    
    square matrix with elem (i, j) = f(k++), else 0.0
  - isEqualTo
```
public boolean isEqualTo(RealSquareMatrix r)
```
    are two matrices identical
    
    Parameters:
    
    r - matrix to compare
    
    Returns:
    
    true if equal (see RealMatrix.equals for details)
  - plus
```
public RealSquareMatrix plus(RealSquareMatrix m)
                      throws EuclidRuntimeException
```
    matrix addition. adds conformable matrices. Does NOT alter this.
    
    Parameters:
    
    m - matrix to add
    
    Returns:
    
    resultant matrix
    
    Throws:
    
    EuclidRuntimeException - m must have the same number of rows and cols as this
  - subtract
```
public RealSquareMatrix subtract(RealSquareMatrix m)
                          throws EuclidRuntimeException
```
    matrix subtraction. subtracts conformable matrices. Does NOT alter this.
    
    Parameters:
    
    m - matrix to subtract from this
    
    Returns:
    
    resultant matrix
    
    Throws:
    
    EuclidRuntimeException - m must have the same number of rows and cols as this
  - multiply
```
public RealSquareMatrix multiply(RealSquareMatrix m)
                          throws EuclidRuntimeException
```
    matrix multiplication. multiplies conformable matrices; result is this*m
    
    Parameters:
    
    m - matrix to multiply by
    
    Returns:
    
    new matrix
    
    Throws:
    
    EuclidRuntimeException - m must have the same number of rows as this has cols
  - determinant
```
public double determinant()
```
    determinant. hardcoded up to order 3 at present; rest is VERY slow :-( calls determinant recursively for order > 3
    
    Returns:
    
    the determinant
  - trace
```
public double trace()
```
    trace.
    
    Returns:
    
    the trace
  - isUnit
```
public boolean isUnit()
```
    is it a unit matrix.
    
    Returns:
    
    are all diagonals 1 and off-diagonal zero (within Real.isEqual())
  - isSymmetric
```
public boolean isSymmetric()
```
    is matrix symmetric.
    
    Returns:
    
    is Real.isEqual(elem(i,j), elem(j,i))
  - orthonormalize
```
public RealSquareMatrix orthonormalize()
```
    orthonormalise matrix. crude (only works for 1, 2x2, 3x3 at present) - use jama?
    
    Returns:
    
    the orthonormalized matrix
    
    Throws:
    
    EuclidRuntimeException - I have only written this for this.rows up to 3. If anyone can find a routine, this will disappear ... -(
  - isOrthonormal
```
public boolean isOrthonormal()
```
    is matrix unitary. i.e is it orthonormal? (synonym for isUnitary())
    
    Returns:
    
    true if is Unitary
  - isUpperTriangular
```
public boolean isUpperTriangular()
```
    is matrix UpperTriangular.
    
    Returns:
    
    true if all bottom triangle excluding diagona Real.isZero()
  - isLowerTriangular
```
public boolean isLowerTriangular()
```
    is matrix LowerTriangular. diagonal must also be zero
    
    Returns:
    
    true if all bottom triangle Real.isZero()
  - isOrthogonal
```
public boolean isOrthogonal()
```
    is matrix orthogonal. checks if Real.isZero(dotProduct) (rowwise calculation)
    
    Overrides:
    
    isOrthogonal in class RealMatrix
    
    Returns:
    
    true if orthogonal
  - isImproperRotation
```
public boolean isImproperRotation()
```
    is matrix an improper rotation.
    
    Returns:
    
    true if determinant is -1.0 and isOrthogonal
  - isUnitary
```
public boolean isUnitary()
```
    is matrix unitary. i.e is it orthonormal? (synonym for isUnitary())
    
    Returns:
    
    true if is Unitary
  - copyUpperToLower
```
public RealSquareMatrix copyUpperToLower()
```
    copy upper triangle into lower triangle. alters this to make it symmetric
    
    Returns:
    
    this as new square matrix
  - copyLowerToUpper
```
public RealSquareMatrix copyLowerToUpper()
```
    copy lower triangle into upper triangle. alters this to make it symmetric
    
    Returns:
    
    this as new square matrix
  - lowerTriangle
```
public RealArray lowerTriangle()
```
    copy lower triangle into linear array; order: 0,0; 1,0; 1,1; 2,0
    
    Returns:
    
    linear array of size rows * (rows+1) / 2
  - transpose
```
public void transpose()
```
    transpose. MODIFIES this
  - diagonaliseAndReturnRank
```
public int diagonaliseAndReturnRank(RealArray eigenvalues,
                                    RealSquareMatrix eigenvectors,
                                    EuclidRuntimeException illCond)
                             throws EuclidRuntimeException
```
    diagonalisation returns eigenvalues and vectors as MODIFIED arguments; 'this' is NOT affected USE JAMA INSTEAD Note that IllCondMatrixException is RETURNED and not thrown
    
    Parameters:
    
    eigenvalues -
    
    eigenvectors -
    
    illCond -
    
    Returns:
    
    flag
    
    Throws:
    
    EuclidRuntimeException - must have at least order 2
  - orthogonalise
```
public void orthogonalise()
                   throws EuclidRuntimeException
```
    orthogonalise matrix. (only works for 3x3 at present); MODIFIES this
    
    Throws:
    
    EuclidRuntimeException - I have only written this for this.rows up to 3. If anyone can find a routine, this will disappear ... -(
  - calculateEigenvalues
```
public RealArray calculateEigenvalues()
```
  - calculateInverse
```
public RealSquareMatrix calculateInverse()
```
  - calculateEigenvectors
```
public RealSquareMatrix calculateEigenvectors()
```
    V is an orthogonal matrix, i.e. its transpose is also its inverse. The columns of V are the eigenvectors of the original matrix. uses apachae.commons.math
    
    Returns:
  - resetEigenDecomposition
```
public void resetEigenDecomposition()
```
  - getCrystallographicOrthogonalisation
```
public static RealSquareMatrix getCrystallographicOrthogonalisation(double[] celleng,
                                                                    double[] angle)
```
    create orthogonlisation matrix from cell lengths and angles. Rollett "Computing Methods in Crystallography" Pergamon 1965 p.23
    
    Parameters:
    
    celleng - 3 lengths
    
    angle - 3 angles in degrees
    
    Returns:
    
    matrix
  - getInverse
```
public RealSquareMatrix getInverse()
                            throws EuclidRuntimeException
```
    inversion of matrix. creates NEW matrix Hard-coded up to 3x3, if matrix is larger uses JAMA
    
    Returns:
    
    inverse matrix
    
    Throws:
    
    EuclidRuntimeException - singular matrix (or worse!)

Class RealSquareMatrix

Nested Class Summary

Field Summary

Fields inherited from class org.xmlcml.euclid.RealMatrix

Fields inherited from interface org.xmlcml.euclid.EuclidConstants

Constructor Summary

Method Summary

Methods inherited from class org.xmlcml.euclid.RealMatrix

Methods inherited from class java.lang.Object

Constructor Detail

RealSquareMatrix

RealSquareMatrix

RealSquareMatrix

RealSquareMatrix

RealSquareMatrix

RealSquareMatrix

RealSquareMatrix

RealSquareMatrix

Method Detail

outerProduct

diagonal

shallowCopy

fromLowerTriangle

fromUpperTriangle

isEqualTo

plus

subtract

multiply

determinant

trace

isUnit

isSymmetric

orthonormalize

isOrthonormal

isUpperTriangular

isLowerTriangular

isOrthogonal

isImproperRotation

isUnitary

copyUpperToLower

copyLowerToUpper

lowerTriangle

transpose

diagonaliseAndReturnRank

orthogonalise

calculateEigenvalues

calculateInverse

calculateEigenvectors

resetEigenDecomposition

getCrystallographicOrthogonalisation

getInverse