xal.tools.math

Class SquareMatrix<M extends SquareMatrix<M>>

java.lang.Object

xal.tools.math.BaseMatrix<M>

xal.tools.math.SquareMatrix<M>

All Implemented Interfaces:

IArchive

Direct Known Subclasses:

PhaseMatrix, R2x2, R3x3, R4x4, R6x6, TrnsPhaseMatrix

public abstract class SquareMatrix<M extends SquareMatrix<M>>
extends BaseMatrix<M>

Class SquareMatrix is the abstract base class for square matrix objects supported in the XAL tools packages.

Currently the internal matrix operations are supported by the Jama matrix package. However, the Jama matrix package has been deemed a "proof of principle" for the Java language and scientific computing and is, thus, no longer supported. The objective of this base class is to hide the internal implementation of matrix operations from the child classes and all developers using the matrix packages. If it is determined that the Jama matrix package is to be removed from XAL, the modification will be substantially simplified in the current architecture.

Since:

Sep 25, 2013

Field Summary

Fields inherited from class xal.tools.math.BaseMatrix

ATTR_DATA, matImpl

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SquareMatrix(int intSize) Constructor for SquareMatrix.
protected	SquareMatrix(int intSize, double[][] arrVals) Initializing constructor for bases class SquareMatrix.
protected	SquareMatrix(int intSize, java.lang.String strTokens) Parsing Constructor - creates an instance of the child class and initialize it according to a token string of element values.
protected	SquareMatrix(M matParent) Copy constructor for SquareMatrix.

Method Summary

Modifier and Type	Method and Description
void	assignIdentity() Assign this matrix to be the identity matrix.
M	conjugateInv(M matPhi) Function for inverse conjugation of this matrix by the argument matrix.
M	conjugateTrans(M matPhi) Function for transpose conjugation of this matrix by the argument matrix.
double	det() Matrix determinant function.
int	getSize() Returns the size of this square matrix, that is, the equal number of rows and columns.
M	inverse() Non-destructive inverse of this matrix.
boolean	isEquivalentTo(BaseMatrix<M> matTest) Checks if the given matrix is algebraically equivalent to this matrix.
boolean	isSymmetric() Check if matrix is symmetric.
void	setElem(IIndex iRow, IIndex iCol, double dblVal) Set the element specified by the given position indices to the given new value.
<V extends BaseVector<V>> V	solve(V vecObs) Solves the linear matrix-vector system without destroying the given data vector.
<V extends BaseVector<V>> void	solveInPlace(V vecObs) Solves the linear matrix-vector system and returns the solution in the given data vector.
M	times(double s) Non-destructive scalar multiplication.
M	times(M matRight) Non-destructive matrix multiplication.
<V extends BaseVector<V>> V	times(V vecFac) Non-destructive matrix-vector multiplication.
void	timesEquals(BaseMatrix<M> matMult) In-place matrix multiplication.
void	timesEquals(double s) In-place scalar multiplication.
M	transpose() Non-destructive transpose of this matrix.

Methods inherited from class xal.tools.math.BaseMatrix

assignMatrix, assignZero, clone, conditionNumber, copy, equals, getArrayCopy, getColCnt, getElem, getElem, getMatrix, getRowCnt, hashCode, load, max, minus, minusEquals, newInstance, newInstance, norm1, norm2, normF, normInf, plus, plusEquals, print, save, setElem, setMatrix, setMatrix, setSubMatrix, toString, toStringMatrix, toStringMatrix, toStringMatrix

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SquareMatrix

protected SquareMatrix(int intSize)
                throws java.lang.UnsupportedOperationException

Constructor for SquareMatrix. Creates a new, uninitialized instance of a square matrix with the given matrix dimensions. The matrix contains all zeros.

Parameters:

intSize - size of this square matrix

Throws:

java.lang.UnsupportedOperationException - child class has not defined a public, zero-argument constructor

Since:

Oct 14, 2013

SquareMatrix

protected SquareMatrix(M matParent)
                throws java.lang.UnsupportedOperationException

Copy constructor for SquareMatrix. Creates a deep copy of the given object. The dimensions are set and the internal array is cloned.

Parameters:

matParent - the matrix to be cloned

Throws:

java.lang.UnsupportedOperationException - base class has not defined a public, zero-argument constructor

Since:

Sep 25, 2013

SquareMatrix

protected SquareMatrix(int intSize,
                       java.lang.String strTokens)
                throws java.lang.IllegalArgumentException,
                       java.lang.NumberFormatException

Parsing Constructor - creates an instance of the child class and initialize it according to a token string of element values. The token string argument is assumed to be one-dimensional and packed by column (ala FORTRAN).

Parameters:

intSize - the matrix size of this object

strTokens - token vector of getSize()^2 numeric values

Throws:

java.lang.IllegalArgumentException - wrong number of token strings

java.lang.NumberFormatException - bad number format, unparseable

SquareMatrix

protected SquareMatrix(int intSize,
                       double[][] arrVals)
                throws java.lang.ArrayIndexOutOfBoundsException

Initializing constructor for bases class SquareMatrix. Sets the entire matrix to the values given in the Java primitive type double array. The argument itself remains unchanged.

The dimensions of the given Java double array must be consistent with the size of the matrix. Thus, if the arguments are inconsistent, an exception is thrown.

Parameters:

cntRows - the matrix row size of this object

cntCols - the matrix column size of this object

arrMatrix - Java primitive array containing new matrix values

Throws:

java.lang.ArrayIndexOutOfBoundsException - the argument must have the same dimensions as this matrix

Since:

Oct 4, 2013

Method Detail

setElem

public void setElem(IIndex iRow,
                    IIndex iCol,
                    double dblVal)

Set the element specified by the given position indices to the given new value.

Parameters:

iRow - matrix row location

iCol - matrix column index

dblVal - matrix element at given row and column will be set to this value

assignIdentity

public void assignIdentity()

Assign this matrix to be the identity matrix. The identity matrix is the square matrix with 1's on the diagonal and 0's everywhere else.

Since:

Oct 3, 2013

getSize

public int getSize()

Returns the size of this square matrix, that is, the equal number of rows and columns.

Returns:

matrix is square of this size on a side

Since:

Sep 25, 2013

isSymmetric

public boolean isSymmetric()

Check if matrix is symmetric.

Returns:

true if matrix is symmetric

isEquivalentTo

public boolean isEquivalentTo(BaseMatrix<M> matTest)

Checks if the given matrix is algebraically equivalent to this matrix. That is, it is equal in size and element values.

Parameters:

matTest - matrix under equivalency test

Returns:

true if the argument is equivalent to this matrix, false if otherwise

Since:

Oct 1, 2013

transpose

public M transpose()

Non-destructive transpose of this matrix.

Returns:

transposed copy of this matrix or null if error

det

public double det()

Matrix determinant function.

Returns:

the determinant of this square matrix

inverse

public M inverse()

Non-destructive inverse of this matrix.

Returns:

the algebraic inverse of this matrix or null if error

solve

public <V extends BaseVector<V>> V solve(V vecObs)
                                  throws java.lang.IllegalArgumentException

Solves the linear matrix-vector system without destroying the given data vector. Say the linear system can be represented algebraically as

Ax = y ,

where A is this matrix, x is the solution matrix to be determined, and y is the data vector provided as the argument. The returned value is equivalent to

x = A^-1y ,

that is, the value of vector x.

The vector y is left unchanged. However, this is somewhat expensive in that the solution vector must be created through reflection and exceptions may occur. For a safer implementation, but where the solution is returned within the existing data vector y see solveInPlace(BaseVector).

Note that the inverse matrix A^-1 is never computed, the system is solved in less than N² time. However, if this system is to be solved repeated for the same matrix A it may be preferable to invert this matrix and solve the multiple system with matrix multiplication.

Parameters:

vecObs - the data vector

Returns:

vector which, when multiplied by this matrix, will equal the data vector

Throws:

java.lang.IllegalArgumentException - the argument has the wrong size

Since:

Oct 11, 2013

solveInPlace

public <V extends BaseVector<V>> void solveInPlace(V vecObs)
                                            throws java.lang.IllegalArgumentException

Solves the linear matrix-vector system and returns the solution in the given data vector. Say the linear system can be represented algebraically as

Ax = y ,

where A is this matrix, x is the solution matrix to be determined, and y is the data vector provided as the argument. The returned value is equivalent to

x = A^-1y ,

that is, the value of vector y.

The value of x is returned within the argument vector. Thus, the argument cannot be immutable.

Note that the inverse matrix A^-1 is never computed, the system is solved in less than N² time. However, if this system is to be solved repeated for the same matrix A it may be preferable to invert this matrix and solve the multiple system with matrix multiplication.

Parameters:

vecObs - the data vector on call, the solution vector upon return

Throws:

java.lang.IllegalArgumentException - the argument has the wrong size

Since:

Oct 11, 2013

times

public M times(double s)

Non-destructive scalar multiplication. This matrix is unaffected.

Parameters:

s - multiplier

Returns:

new matrix equal to the element-wise product of s and this matrix, or null if an error occurred

timesEquals

public void timesEquals(double s)

In-place scalar multiplication. Each element of this matrix is replaced by its product with the argument.

Parameters:

s - multiplier

times

public <V extends BaseVector<V>> V times(V vecFac)
                                  throws java.lang.IllegalArgumentException

Non-destructive matrix-vector multiplication. The returned value is the usual product of the given vector pre-multiplied by this matrix. Specifically, denote by A this matrix and by x the argument vector, then the components {y_i} of the returned vector y are given by

y_i = Σ_j A_ijx_j

The returned vector must be created using Java reflection, so this operation is somewhat more risky and expensive than and in place multiplication.

Parameters:

vecFac - the vector factor

Returns:

the matrix-vector product of this matrix with the argument

Throws:

java.lang.IllegalArgumentException - the argument vector must be the same size

Since:

Oct 11, 2013

times

public M times(M matRight)

Non-destructive matrix multiplication. A new matrix is returned with the product while both multiplier and multiplicand are unchanged.

Parameters:

matRight - multiplicand - right operand of matrix multiplication operator

Returns:

new matrix which is the matrix product of this matrix and the argument, or null if an error occurred

timesEquals

public void timesEquals(BaseMatrix<M> matMult)

In-place matrix multiplication. The final value of this matrix is assigned to be the matrix product of the pre-method-call value time the given matrix.

Parameters:

matMult - multiplicand - right operand of matrix multiplication operator

conjugateTrans

public M conjugateTrans(M matPhi)

Function for transpose conjugation of this matrix by the argument matrix. This method is non-destructive, returning a new matrix.

Denote by σ₀ this matrix object, and denote the argument matrix as Φ. Then the returned matrix, σ₁ is given by

σ₁ = Φσ₀Φ^T

Parameters:

matPhi - conjugating matrix Φ (typically a transfer matrix)

Returns:

matPhi*this*matPhi^T, or null if an error occurred

conjugateInv

public M conjugateInv(M matPhi)

Function for inverse conjugation of this matrix by the argument matrix. This method is non-destructive, return a new matrix.

Denote by σ₀ this matrix object, and denote the argument matrix as Φ. Then the returned matrix, σ₁ is given by

σ₁ = Φσ₀Φ^-1

Parameters:

matPhi - conjugating matrix Φ (typically a transfer matrix)

Returns:

matPhi*this*matPhi^-1