BaseMatrix

java.lang.Object
- xal.tools.math.BaseMatrix<M>

All Implemented Interfaces:

IArchive

Direct Known Subclasses:

SquareMatrix
```
public abstract class BaseMatrix<M extends BaseMatrix<M>>
extends java.lang.Object
implements IArchive
```
Class BaseMatrix. This is a base class for objects representing real-number matrix objects. Thus it contains basic matrix operations where the interacting objects are all of type M, or vectors of the singular type V. (If matrix and vectors are not of compatible dimensions the operations fail.) The template parameter M is the type of the child class. This mechanism allows BaseMatrix<M extends BaseMatrix<M>> to recognize the type of it derived classes in order to create and process new objects as necessary.

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:

Oct 11, 2013

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ATTR_DATA` Attribute marker for data managed by IArchive interface
`protected Jama.Matrix`	`matImpl` internal matrix implementation

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`BaseMatrix(int cntRows, int cntCols)` Creates a new, uninitialized instance of a square matrix with the given matrix dimensions.
`protected`	`BaseMatrix(int cntRows, int cntCols, double[][] arrVals)` Initializing constructor for bases class `SquareMatrix`.
`protected`	`BaseMatrix(int cntRows, int cntCols, 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`	`BaseMatrix(M matParent)` Copy constructor for `BaseMatrix`.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`assignMatrix(Jama.Matrix matValue)` Sets the internal matrix value to that given in the argument.
`void`	`assignZero()` Assign this matrix to be the zero matrix, specifically the matrix containing all 0's.
`abstract M`	`clone()` Base classes must override the clone operation in order to make deep copies of the current object.
`double`	`conditionNumber()` Ratio of the largest singular value over the smallest singular value.
`M`	`copy()` Create a deep copy of the this matrix object.
`boolean`	`equals(java.lang.Object objTest)` Checks absolute equivalency.
`double[][]`	`getArrayCopy()` Returns a copy of the internal Java array containing the matrix elements.
`int`	`getColCnt()` Returns the number of columns in this matrix.
`double`	`getElem(IIndex indRow, IIndex indCol)` Returns the matrix element at the position indicated by the given row and column index sources.
`double`	`getElem(int i, int j)` Return matrix element value.
`protected Jama.Matrix`	`getMatrix()` Return the internal matrix representation.
`int`	`getRowCnt()` Returns the number of rows in this matrix.
`int`	`hashCode()` "Borrowed" implementation from AffineTransform, since it is based on double attribute values.
`void`	`load(DataAdaptor daptArchive)` Restore the value of the this `PhaseMatrix` from the contents of a data archive.
`double`	`max()` Return the maximum absolute value of all matrix elements.
`M`	`minus(M matSub)` Non-destructive matrix subtraction.
`void`	`minusEquals(M mat)` In-place matrix subtraction.
`protected abstract M`	`newInstance()` Creates a new, uninitialized instance of this matrix type.
`protected M`	`newInstance(Jama.Matrix impInit)` Creates a new instance of this matrix type initialized to the given implementation matrix.
`double`	`norm1()` The matrix norm \|\| · \|\|₁ induced from the l₁ vector norm on Rⁿ.
`double`	`norm2()` Returns the l₂ induced norm of this matrix, which is the maximum, which turns out to be the spectral radius of the matrix.
`double`	`normF()` Return the Frobenius norm \|\|A\|\|_F .
`double`	`normInf()` The matrix norm \|\| · \|\|_∞ induced from the l_∞ vector norm on Rⁿ.
`M`	`plus(M matAddend)` Non-destructive matrix addition.
`void`	`plusEquals(M mat)` In-place matrix addition.
`void`	`print(java.io.PrintWriter os)` Print out the contents of the R2x2 in text format.
`void`	`save(DataAdaptor daptArchive)` Save the value of this `PhaseMatrix` to a data sink represented by the `DataAdaptor` interface.
`void`	`setElem(int i, int j, double s)` Element assignment - assigns matrix element to the specified value
`void`	`setMatrix(double[][] arrMatrix)` Sets the entire matrix to the values given in the Java primitive type double array.
`void`	`setMatrix(java.lang.String strValues)` Parsing assignment - set the `PhaseMatrix` value according to a token string of element values.
`void`	`setSubMatrix(int i0, int i1, int j0, int j1, double[][] arrSub)` Set a block sub-matrix within the current matrix.
`java.lang.String`	`toString()` Convert the contents of the matrix to a string representation.
`java.lang.String`	`toStringMatrix()` Returns a string representation of this matrix.
`java.lang.String`	`toStringMatrix(java.text.NumberFormat fmt)` Returns a string representation of this matrix.
`java.lang.String`	`toStringMatrix(java.text.NumberFormat fmt, int intColWd)` Returns a string representation of this matrix.

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

- Field Detail
  - ATTR_DATA
```
public static final java.lang.String ATTR_DATA
```
    Attribute marker for data managed by IArchive interface
    
    See Also:
    
    Constant Field Values
  - matImpl
```
protected final Jama.Matrix matImpl
```
    internal matrix implementation
- Constructor Detail
  - BaseMatrix
```
protected BaseMatrix(int cntRows,
                     int cntCols)
```
    Creates a new, uninitialized instance of a square matrix with the given matrix dimensions. The matrix contains all zeros.
    
    Parameters:
    
    cntRows - the matrix row count of this object
    
    cntCols - the matrix column count
    
    Throws:
    
    java.lang.UnsupportedOperationException - child class has not defined a public, zero-argument constructor
  - BaseMatrix
```
protected BaseMatrix(M matParent)
```
    Copy constructor for BaseMatrix. 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
  - BaseMatrix
```
protected BaseMatrix(int cntRows,
                     int cntCols,
                     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:
    
    cntRows - the matrix row size of this object
    
    cntCols - the matrix column 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
  - BaseMatrix
```
protected BaseMatrix(int cntRows,
                     int cntCols,
                     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
  - clone
```
public abstract M clone()
```
    Base classes must override the clone operation in order to make deep copies of the current object. This operation cannot be done without the exact type.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Since:
    
    Jul 3, 2014
    
    See Also:
    
    Object.clone()
  - setElem
```
public void setElem(int i,
                    int j,
                    double s)
             throws java.lang.ArrayIndexOutOfBoundsException
```
    Element assignment - assigns matrix element to the specified value
    
    Parameters:
    
    i - row index
    
    j - column index
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - an index was equal to or larger than the matrix size
  - setSubMatrix
```
public void setSubMatrix(int i0,
                         int i1,
                         int j0,
                         int j1,
                         double[][] arrSub)
                  throws java.lang.ArrayIndexOutOfBoundsException
```
    Set a block sub-matrix within the current matrix. If the given two-dimensional array is larger than block described by the indices it is truncated. If the given indices describe a matrix larger than the given two-dimensional array then an exception is thrown.
    
    Parameters:
    
    i0 - row index of upper left block
    
    i1 - row index of lower right block
    
    j0 - column index of upper left block
    
    j1 - column index of lower right block
    
    arrSub - two-dimensional sub element array
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - sub-matrix does not fit into base matrix
  - setMatrix
```
public void setMatrix(double[][] arrMatrix)
               throws java.lang.ArrayIndexOutOfBoundsException
```
    Sets the entire matrix to the values given in the Java primitive type double array.
    
    Parameters:
    
    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
  - setMatrix
```
public void setMatrix(java.lang.String strValues)
               throws java.lang.NumberFormatException,
                      java.lang.IllegalArgumentException
```
    Parsing assignment - set the PhaseMatrix value according to a token string of element values. The token string argument is assumed to be one-dimensional and packed by column (aka FORTRAN).
    
    Parameters:
    
    strValues - token vector of SIZE² numeric values
    
    Throws:
    
    java.lang.IllegalArgumentException - wrong number of token strings
    
    java.lang.NumberFormatException - bad number format, unparseable
  - getRowCnt
```
public int getRowCnt()
```
    Returns the number of rows in this matrix. Specifically, if this matrix, denoted M, is in R^m×n, then the returned value is m.
    
    Returns:
    
    the first dimension in the shape of this matrix.
    
    Since:
    
    Oct 14, 2013
  - getColCnt
```
public int getColCnt()
```
    Returns the number of columns in this matrix. Specifically, if this matrix, denoted M, is in R^m×n, then the returned value is n.
    
    Returns:
    
    the second dimension in the shape of this matrix.
    
    Since:
    
    Oct 14, 2013
  - getElem
```
public double getElem(int i,
                      int j)
               throws java.lang.ArrayIndexOutOfBoundsException
```
    Return matrix element value. Get matrix element value at specified Diagonal position.
    
    Parameters:
    
    i - row index
    
    j - column index
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - an index was equal to or larger than the matrix size
  - getElem
```
public double getElem(IIndex indRow,
                      IIndex indCol)
```
    Returns the matrix element at the position indicated by the given row and column index sources.
    
    NOTES
    · It is expected that the object exposing the IIndex interface is an enumeration class restricting the number of possible index values.
    · Consequently we do not declare a thrown exception assuming that that enumeration class eliminates the possibility of an out of bounds error.
    
    Parameters:
    
    indRow - source of the row index
    
    indCol - source of the column index
    
    Returns:
    
    value of the matrix element at the given row and column
    
    Since:
    
    Sep 30, 2013
  - getArrayCopy
```
public double[][] getArrayCopy()
```
    Returns a copy of the internal Java array containing the matrix elements. The array dimensions are given by the size of this matrix, available from #getSize().
    
    Returns:
    
    copied array of matrix values
    
    Since:
    
    Sep 25, 2013
  - copy
```
public M copy()
```
    Create a deep copy of the this matrix object. The returned object is completely decoupled from the original.
    
    Returns:
    
    a deep copy object of this matrix
  - assignZero
```
public void assignZero()
```
    Assign this matrix to be the zero matrix, specifically the matrix containing all 0's.
    
    Since:
    
    Oct 3, 2013
  - conditionNumber
```
public double conditionNumber()
```
    Ratio of the largest singular value over the smallest singular value. Note that this method does a singular value decomposition just to get the number (done in the (wasteful) Jama.Matrix internal implementation). Thus, this computation is not cheap if the matrix is large.
    
    Returns:
    
    the ratio of extreme singular values
    
    Since:
    
    Oct 16, 2013
  - plus
```
public M plus(M matAddend)
```
    Non-destructive matrix addition. This matrix is unaffected.
    
    Parameters:
    
    matAddend - matrix to be added to this
    
    Returns:
    
    the result of this matrix plus the given matrix (element-wise), or null if error
  - plusEquals
```
public void plusEquals(M mat)
```
    In-place matrix addition. The given matrix is added to this matrix algebraically (element by element).
    
    Parameters:
    
    mat - matrix to be added to this (no new objects are created)
  - minus
```
public M minus(M matSub)
```
    Non-destructive matrix subtraction. This matrix is unaffected.
    
    Parameters:
    
    matSub - the subtrahend
    
    Returns:
    
    the value of this matrix minus the value of the given matrix, or null if an error occurred
  - minusEquals
```
public void minusEquals(M mat)
```
    In-place matrix subtraction. The given matrix is subtracted from the value of this matrix. No additional objects are created.
    
    Parameters:
    
    mat - subtrahend
  - max
```
public double max()
```
    Return the maximum absolute value of all matrix elements. This can be considered a norm on matrices, but it is not sub-multiplicative. That is,
    
    ||AB||_max is not necessarily bound by ||A||_max ||B||_max .
    
    Returns:
    
    max_i,j | A_i,j |
  - norm1
```
public double norm1()
```
    The matrix norm || · ||₁ induced from the l₁ vector norm on Rⁿ. That is,
    
    ||A||₁ ≡ max_x∈Rⁿ ||Ax||₁
    
    where, by context, the second occurrence of ||·||₁ is the Lesbeque 1-norm on R^{n^.}
    
    NOTES:
    · For square matrices induced norms are sub-multiplicative, that is ||AB|| ≤ ||A|| ||B||.
    
    · The ||·||₁ induced norm equates to the the maximum absolute column sum.
    
    Returns:
    
    ||M||₁ = max_i Σ_j |M_i,j|
  - norm2
```
public double norm2()
```
    Returns the l₂ induced norm of this matrix, which is the maximum, which turns out to be the spectral radius of the matrix. Specifically,
    
    ||A||₂ ≡ [ max λ(A^TA) ]^1/2 ,
    = max ρ(A) ,
    
    where λ(·) is the eigenvalue operator and ρ(·) is the singular value operator.
    
    Returns:
    
    the maximum singular value of this matrix
  - normInf
```
public double normInf()
```
    The matrix norm || · ||_∞ induced from the l_∞ vector norm on Rⁿ. That is,
    
    ||A||_∞ ≡ max_x∈Rⁿ ||Ax||_∞
    
    where, by context, the second occurrence of ||·||_∞ is the Lesbeque ∞-norm on R^{n^.}
    
    NOTES:
    · For square matrices induced norms are sub-multiplicative, that is ||AB|| ≤ ||A|| ||B||.
    
    · The ||·||_∞ induced norm equates to the the maximum absolute column sum.
    
    Returns:
    
    ||M||₁ = max_i Σ_j |M_i,j|
  - normF
```
public double normF()
```
    Return the Frobenius norm ||A||_F . The Frobenius norm has the property that it is both the element-wise Lebesgue 2-norm the Schatten 2-norm. Thus we have
    
    ||A||_F = [ Σ_i Σ_j A_i,j² ]^1/2 = [ Tr(A^TA) ]^1/2 = [ Σ_i σ_i² ]^1/2
    
    where Tr is the trace operator and σ_i are the singular values of matrix A.
    
    NOTES
    · Since the Schatten norms are sub-multiplicative, the Frobenius norm is sub-multiplicative.
    
    · The Frobenius norm is invariant under rotations by elements of O(2) ⊂ R^n×n .
    
    Returns:
    
    ||A||_F = [ Σ_i,j A_ij² ]^1/2
  - print
```
public void print(java.io.PrintWriter os)
```
    Print out the contents of the R2x2 in text format.
    
    Parameters:
    
    os - output stream to receive text dump
  - save
```
public void save(DataAdaptor daptArchive)
```
    Save the value of this PhaseMatrix to a data sink represented by the DataAdaptor interface.
    
    Specified by:
    
    save in interface IArchive
    
    Parameters:
    
    daptArchive - interface to data sink
    
    See Also:
    
    IArchive.save(xal.tools.data.DataAdaptor)
  - load
```
public void load(DataAdaptor daptArchive)
          throws DataFormatException
```
    Restore the value of the this PhaseMatrix from the contents of a data archive.
    
    Specified by:
    
    load in interface IArchive
    
    Parameters:
    
    daptArchive - interface to data source
    
    Throws:
    
    DataFormatException - malformed data
    
    java.lang.IllegalArgumentException - wrong number of string tokens
    
    See Also:
    
    IArchive.load(xal.tools.data.DataAdaptor)
  - equals
```
public boolean equals(java.lang.Object objTest)
```
    Checks absolute equivalency. That is, checks whether or not the argument is this object.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    objTest - object under equivalency test
    
    Returns:
    
    true if the argument is this object, false otherwise
  - toString
```
public java.lang.String toString()
```
    Convert the contents of the matrix to a string representation. The format is similar to that of Mathematica. Specifically,
    
    { {a b }{c d } }
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    string representation of the matrix
  - toStringMatrix
```
public java.lang.String toStringMatrix()
```
    Returns a string representation of this matrix. The string contains multiple lines, one for each row of the matrix. Within each line the matrix entries are formatted. Thus, the string should resemble the usual matrix format when printed out.
    
    Returns:
    
    multiple line formatted string containing matrix elements in matrix format
    
    Since:
    
    Feb 8, 2013
  - toStringMatrix
```
public java.lang.String toStringMatrix(java.text.NumberFormat fmt)
```
    Returns a string representation of this matrix. The string contains multiple lines, one for each row of the matrix. Within each line the matrix entries are formatted according to the given number format. The default column width is used. The string should resemble the usual matrix format when printed out.
    
    Parameters:
    
    fmt - NumberFormat object containing output format for matrix entries
    
    Returns:
    
    multiple line formatted string containing matrix elements in matrix format
    
    Since:
    
    Feb 8, 2013
  - toStringMatrix
```
public java.lang.String toStringMatrix(java.text.NumberFormat fmt,
                                       int intColWd)
```
    Returns a string representation of this matrix. The string contains multiple lines, one for each row of the matrix. Within each line the matrix entries are formatted according to the given number format. The string should resemble the usual matrix format when printed out.
    
    Parameters:
    
    fmt - NumberFormat object containing output format for matrix entries
    
    intColWd - number of characters used for each column (padding is with spaces)
    
    Returns:
    
    multiple line formatted string containing matrix elements in matrix format
    
    Since:
    
    Feb 8, 2013
  - hashCode
```
public int hashCode()
```
    "Borrowed" implementation from AffineTransform, since it is based on double attribute values. Must implement hashCode to be consistent with equals as specified by contract of hashCode in Object.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a hashCode for this object
  - getMatrix
```
protected Jama.Matrix getMatrix()
```
    Return the internal matrix representation.
    
    Returns:
    
    the Jama matrix object
  - assignMatrix
```
protected void assignMatrix(Jama.Matrix matValue)
```
    Sets the internal matrix value to that given in the argument. This is a deep copy operation.
    
    Parameters:
    
    matValue - internal implementation of matrix values
    
    Since:
    
    Oct 1, 2013
  - newInstance
```
protected abstract M newInstance()
```
    Creates a new, uninitialized instance of this matrix type.
    
    NOTE: · This method was made abstract by Ivo List. Rather than use reflection to instantiate new objects, this function is now delegated to the concrete classes. This architecture is more robust and allows the compiler to do more error checking.
    
    Returns:
    
    uninitialized matrix object of type M
    
    Since:
    
    Oct 1, 2013
  - newInstance
```
protected M newInstance(Jama.Matrix impInit)
```
    Creates a new instance of this matrix type initialized to the given implementation matrix.
    
    Parameters:
    
    impInit - implementation matrix containing initialization values
    
    Returns:
    
    initialized matrix object of type M
    
    Since:
    
    Oct 1, 2013

Class BaseMatrix<M extends BaseMatrix<M>>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ATTR_DATA

matImpl

Constructor Detail

BaseMatrix

BaseMatrix

BaseMatrix

BaseMatrix

Method Detail

clone

setElem

setSubMatrix

setMatrix

setMatrix

getRowCnt

getColCnt

getElem

getElem

NOTES

getArrayCopy

copy

assignZero

conditionNumber

plus

plusEquals

minus

minusEquals

max

norm1

NOTES:

norm2

normInf

NOTES:

normF

NOTES

print

save

load

equals

toString

toStringMatrix

toStringMatrix

toStringMatrix

hashCode

getMatrix

assignMatrix

newInstance

newInstance