maspack.matrix
Interface Matrix

All Superinterfaces:
LinearTransformNd
All Known Subinterfaces:
DenseMatrix, MatrixBlock, SparseMatrix
All Known Implementing Classes:
AffineTransform2d, AffineTransform2dBase, AffineTransform3d, AffineTransform3dBase, DenseMatrixBase, FrameBlock, Matrix1x1, Matrix1x1Block, Matrix1x3, Matrix1x3Block, Matrix1x6, Matrix1x6Block, Matrix2d, Matrix2dBase, Matrix2x2Block, Matrix2x3, Matrix2x3Block, Matrix2x6, Matrix2x6Block, Matrix3d, Matrix3dBase, Matrix3x1, Matrix3x1Block, Matrix3x2, Matrix3x2Block, Matrix3x3Block, Matrix3x3DiagBlock, Matrix3x4, Matrix3x4Block, Matrix3x6, Matrix3x6Block, Matrix4d, Matrix4dBase, Matrix4x3, Matrix4x3Block, Matrix6d, Matrix6dBase, Matrix6dBlock, Matrix6x1, Matrix6x1Block, Matrix6x2, Matrix6x2Block, Matrix6x3, Matrix6x3Block, MatrixBase, MatrixBlockBase, MatrixNd, MatrixNdBlock, RigidTransform2d, RigidTransform3d, RotationMatrix2d, RotationMatrix3d, ScaledRigidTransform3d, SparseBlockMatrix, SparseMatrixBase, SparseMatrixCRS, SparseMatrixNd, SparseNumberedBlockMatrix, SpatialInertia, SubMatrixNd, SymmetricMatrix3d

public interface Matrix
extends LinearTransformNd

General interface for matrices. It specifies methods which allow one to set and get various matrix components (e.g., individual elements, rows, columns, submatrics), and do various non-modifying queries such as finding out its size, computing it's determinant, or comparing it with other matrices. There is also a method setSize for resizing, which can be used unless the matrix size is fixed (which can be determined using isFixedSize).

This interface does not support operations such as multiplication or addition. The reason for this is that specific implementations may have a specialized structure which could be compromised by arbitrary operations. For instance, if an implementing class represents orthogonal matrices, then it does not make sense for that class to allow an add operation. Similarly, for an implementation representing symmetric matrices, any muliplication methods should not be open to general matrices.

Of course, it is possible to corrupt any special implementation structure using the set methods provided in this base class, but it was felt that not including such routines would be overly restrictive. It is therefore up to the user to safeguard implementation integrity against misuse of the set methods.

Note that indices for matrix elements, rows, and columns are zero-based. The range of valid indices for a matrix of size m X n is [0, ... , m-1] and code>[0, ... , n-1].


Nested Class Summary
static class Matrix.Partition
          Describes different partitions of a matrix object.
static class Matrix.WriteFormat
          Describes the general format for writing matrix values.
 
Field Summary
static int INDEFINITE
          Identifies a matrix as regular indefinite.
static int POSITIVE_DEFINITE
          Identifies a matrix as positive definite.
static int SPD
          Identifies a matrix as symmetric positive definite.
static int SYMMETRIC
          Identifies a matrix as symmetric.
 
Method Summary
 void checkConsistency()
          Check that the internal structures of this matrix are consistent.
 int colSize()
          Returns the number of columns in this matrix.
 double determinant()
          Returns the determinant of this matrix, which must be square
 boolean epsilonEquals(Matrix M1, double epsilon)
          Returns true if the elements of this matrix equal those of matrix M1within a prescribed tolerance epsilon.
 boolean equals(Matrix M1)
          Returns true if the elements of this matrix exactly equal those of matrix M1.
 double frobeniusNorm()
          Returns the Frobenius norm of this matrix.
 void get(double[] values)
          Copies the elements of this matrix into an array of doubles.
 double get(int i, int j)
          Gets a single element of this matrix.
 int getCCSIndices(int[] rowIdxs, int[] colOffs, Matrix.Partition part)
          Gets the compressed column storage (CCS) indices for this matrix.
 int getCCSIndices(int[] rowIdxs, int[] colOffs, Matrix.Partition part, int numRows, int numCols)
          Gets the compressed column storage (CCS) indices for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns.
 int getCCSValues(double[] vals, Matrix.Partition part)
          Gets the compressed column storage (CCS) values for this matrix, in column-major order.
 int getCCSValues(double[] vals, Matrix.Partition part, int numRows, int numCols)
          Gets the compressed column storage (CCS) values for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns.
 void getColumn(int j, double[] values)
          Copies a column of this matrix into an array of doubles.
 void getColumn(int j, double[] values, int off)
          Copies a column of this matrix into an array of doubles, starting at a specified offset.
 void getColumn(int j, Vector v)
          Copies a column of this matrix into a Vector.
 int getCRSIndices(int[] colIdxs, int[] rowOffs, Matrix.Partition part)
          Gets the compressed row storage (CRS) indices for this matrix.
 int getCRSIndices(int[] colIdxs, int[] rowOffs, Matrix.Partition part, int numRows, int numCols)
          Gets the compressed row storage (CRS) indices for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns.
 int getCRSValues(double[] vals, Matrix.Partition part)
          Gets the compressed row storage (CRS) values for this matrix, in row-major order.
 int getCRSValues(double[] vals, Matrix.Partition part, int numRows, int numCols)
          Gets the compressed row storage (CRS) values for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns.
 void getRow(int i, double[] values)
          Copies a row of this matrix into an array of doubles.
 void getRow(int i, double[] values, int off)
          Copies a row of this matrix into an array of doubles, starting at a specified offset.
 void getRow(int i, Vector v)
          Copies a row of this matrix into a Vector.
 java.lang.String getSize()
          Returns a string indicating the size of this matrix.
 void getSubMatrix(int baseRow, int baseCol, DenseMatrix Mdest)
          Gets a submatrix of this matrix object.
 double infinityNorm()
          Returns the infinity norm of this matrix.
 boolean isFixedSize()
          Returns true if this matrix is of fixed size.
 boolean isSymmetric(double tol)
          Returns true if this matrix is symmetric within a given tolerance.
 void mul(VectorNd vr, VectorNd v1)
          Multiplies this matrix by the column vector v1 and places the result in the vector vr.
 void mul(VectorNd vr, VectorNd v1, int nr, int nc)
          Multiplies a submatrix of this matrix by the column vector v1 and places the result in the vector vr.
 void mul(VectorNd vr, VectorNd v1, int r0, int nr, int c0, int nc)
          Multiplies a submatrix of this matrix by the column vector v1 and places the result in the vector vr.
 void mulAdd(VectorNd vr, VectorNd v1)
          Multiplies this matrix by the column vector v1 and adds the result to the vector vr.
 void mulAdd(VectorNd vr, VectorNd v1, int nr, int nc)
          Multiplies a submatrix of this matrix by the column vector v1 and adds the result to the vector vr.
 void mulAdd(VectorNd vr, VectorNd v1, int r0, int nr, int c0, int nc)
          Multiplies a submatrix of this matrix by the column vector v1 and adds the result to the vector vr.
 void mulTranspose(VectorNd vr, VectorNd v1)
          Multiplies the transpose of this matrix by the vector v1 and places the result in vr.
 void mulTranspose(VectorNd vr, VectorNd v1, int nr, int nc)
          Multiplies a submatrix of the transpose of this matrix by the column vector v1 and places the result in the vector vr.
 void mulTranspose(VectorNd vr, VectorNd v1, int r0, int nr, int c0, int nc)
          Multiplies a submatrix of the transpose of this matrix by the column vector v1 and places the result in the vector vr.
 void mulTransposeAdd(VectorNd vr, VectorNd v1)
          Multiplies the transpose of this matrix by the vector v1 and adds the result to vr.
 void mulTransposeAdd(VectorNd vr, VectorNd v1, int nr, int nc)
          Multiplies a submatrix of the transpose of this matrix by the column vector v1 and adds the result to the vector vr.
 void mulTransposeAdd(VectorNd vr, VectorNd v1, int r0, int nr, int c0, int nc)
          Multiplies a submatrix of the transpose of this matrix by the column vector v1 and adds the result to the vector vr.
 int numNonZeroVals()
          Returns the number of non-zero values in this matrix object.
 int numNonZeroVals(Matrix.Partition part, int numRows, int numCols)
          Returns the number of non-zero values for a specified partition of a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns.
 double oneNorm()
          Returns the 1 norm of this matrix.
 int rowSize()
          Returns the number of rows in this matrix.
 void scan(ReaderTokenizer rtok)
          Sets the contents of this matrix to values read from a ReaderTokenizer.
 void set(double[] values, int[] indices, int numValues)
          Sets the elements of this matrix from an array of doubles and a list of indices.
 void set(Matrix M)
          Sets the size and values of this matrix to those of another matrix.
 void setCCSValues(double[] vals, int[] rowIdxs, int[] colOffs, int nvals, int ncols, Matrix.Partition part)
          Sets the contents of this matrix given a set of values in compressed column storage (CCS).
 void setCRSValues(double[] vals, int[] colIdxs, int[] rowOffs, int nvals, int nrows, Matrix.Partition part)
          Sets the contents of this matrix given a set of values in compressed row storage (CRS).
 void setSize(int numRows, int numCols)
          Sets the size of this matrix.
 java.lang.String toString(NumberFormat fmt)
          Returns a String representation of this matrix, in which each element is formatted using a C printf style format as decribed by the parameter NumberFormat.
 double trace()
          Returns the trace of this matrix, which must be square
 void write(java.io.PrintWriter pw, NumberFormat fmt)
          Writes the contents of this matrix to a PrintWriter.
 void write(java.io.PrintWriter pw, NumberFormat fmt, Matrix.WriteFormat wfmt)
          Writes the contents of this matrix to a PrintWriter.
 void write(java.io.PrintWriter pw, NumberFormat fmt, Matrix.WriteFormat wfmt, int numRows, int numCols)
          Writes the contents of a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns.
 

Field Detail

INDEFINITE

static final int INDEFINITE
Identifies a matrix as regular indefinite.

See Also:
Constant Field Values

SYMMETRIC

static final int SYMMETRIC
Identifies a matrix as symmetric.

See Also:
Constant Field Values

POSITIVE_DEFINITE

static final int POSITIVE_DEFINITE
Identifies a matrix as positive definite.

See Also:
Constant Field Values

SPD

static final int SPD
Identifies a matrix as symmetric positive definite.

See Also:
Constant Field Values
Method Detail

rowSize

int rowSize()
Returns the number of rows in this matrix.

Specified by:
rowSize in interface LinearTransformNd
Returns:
number of rows

colSize

int colSize()
Returns the number of columns in this matrix.

Specified by:
colSize in interface LinearTransformNd
Returns:
number of columns

get

double get(int i,
           int j)
Gets a single element of this matrix.

Parameters:
i - element row index
j - element column index
Returns:
element value

get

void get(double[] values)
Copies the elements of this matrix into an array of doubles. The elements are stored using row-major order, so that element (i,j) is stored at location i*colSize()+j.

Parameters:
values - array into which values are copied

getColumn

void getColumn(int j,
               double[] values)
Copies a column of this matrix into an array of doubles.

Parameters:
j - column index
values - array into which the column is copied

getColumn

void getColumn(int j,
               double[] values,
               int off)
Copies a column of this matrix into an array of doubles, starting at a specified offset.

Parameters:
j - column index
values - array into which the column is copied
off - offset in values where copying should begin

getRow

void getRow(int i,
            double[] values)
Copies a row of this matrix into an array of doubles.

Parameters:
i - row index
values - array into which the row is copied

getRow

void getRow(int i,
            double[] values,
            int off)
Copies a row of this matrix into an array of doubles, starting at a specified offset.

Parameters:
i - row index
values - array into which the row is copied
off - offset in values where copying should begin

getColumn

void getColumn(int j,
               Vector v)
Copies a column of this matrix into a Vector.

Parameters:
j - column index
v - vector into which the column is copied
Throws:
ImproperSizeException - vector's size not equal to the number of matrix rows and the vector cannot be resized

getRow

void getRow(int i,
            Vector v)
Copies a row of this matrix into a Vector.

Parameters:
i - row index
v - vector into which the row is copied
Throws:
ImproperSizeException - vector's size not equal to the number of matrix columns and the vector cannot be resized

set

void set(Matrix M)
Sets the size and values of this matrix to those of another matrix.

Parameters:
M - matrix whose size and values are copied
Throws:
ImproperSizeException - matrices have different sizes and this matrix cannot be resized accordingly

isFixedSize

boolean isFixedSize()
Returns true if this matrix is of fixed size. If this matrix is not of fixed size, then it can be resized dynamically, either explicitly using setSize, or implicitly when used as a result for various matrix operations.

Returns:
true if this matrix is of fixed size
See Also:
setSize(int, int)

setSize

void setSize(int numRows,
             int numCols)
Sets the size of this matrix. This operation is only supported if isFixedSize returns false.

Parameters:
numRows - new row size
numCols - new column size
Throws:
java.lang.UnsupportedOperationException - if this operation is not supported
See Also:
isFixedSize()

determinant

double determinant()
Returns the determinant of this matrix, which must be square

Returns:
matrix determinant
Throws:
ImproperSizeException - if the matrix is not square

trace

double trace()
Returns the trace of this matrix, which must be square

Returns:
matrix trace
Throws:
ImproperSizeException - if the matrix is not square

epsilonEquals

boolean epsilonEquals(Matrix M1,
                      double epsilon)
Returns true if the elements of this matrix equal those of matrix M1within a prescribed tolerance epsilon.

Parameters:
M1 - matrix to compare with
epsilon - comparison tolerance
Returns:
false if the matrices are not equal within the specified tolerance, or have different sizes

equals

boolean equals(Matrix M1)
Returns true if the elements of this matrix exactly equal those of matrix M1.

Parameters:
M1 - matrix to compare with
Returns:
false if the matrices are not equal or have different sizes

oneNorm

double oneNorm()
Returns the 1 norm of this matrix. This is equal to the maximum of the vector 1-norm of each column.

Returns:
1 norm of this matrix

infinityNorm

double infinityNorm()
Returns the infinity norm of this matrix. This is equal to the maximum of the vector 1-norm of each row.

Returns:
infinity norm of this matrix

frobeniusNorm

double frobeniusNorm()
Returns the Frobenius norm of this matrix. This is equal to the square root of the sum of the squares of each element.

Returns:
Frobenius norm of this matrix

write

void write(java.io.PrintWriter pw,
           NumberFormat fmt)
           throws java.io.IOException
Writes the contents of this matrix to a PrintWriter. Element values are written in a dense-format row-major order, one row per line, separated by spaces. Each value is formatted using a C printf style as described by the parameter NumberFormat.

Parameters:
pw - PrintWriter to write this matrix to
fmt - numeric format
Throws:
java.io.IOException

write

void write(java.io.PrintWriter pw,
           NumberFormat fmt,
           Matrix.WriteFormat wfmt)
           throws java.io.IOException
Writes the contents of this matrix to a PrintWriter. The overall write format is specified by wfmt, while the values themselves are formatted using a C printf style as decribed by the parameter NumberFormat.

Parameters:
pw - PrintWriter to write this matrix to
fmt - numeric format
wfmt - specifies the general output format
Throws:
java.io.IOException

write

void write(java.io.PrintWriter pw,
           NumberFormat fmt,
           Matrix.WriteFormat wfmt,
           int numRows,
           int numCols)
           throws java.io.IOException
Writes the contents of a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns. The overall write format is specified by wfmt, while the values themselves are formatted using a C printf style as decribed by the parameter NumberFormat.

Parameters:
pw - PrintWriter to write this matrix to
fmt - numeric format
wfmt - specifies the general output format
numRows - number of rows delimiting the sub-matrix
numCols - number of columns delimiting the sub-matrix
Throws:
java.io.IOException

scan

void scan(ReaderTokenizer rtok)
          throws java.io.IOException
Sets the contents of this matrix to values read from a ReaderTokenizer. Matrix elements may be specified in either a dense or sparse format.

For the dense format, the input should consist of a sequence of numbers, arranged in row-major order, separated by white space, and optionally surrounded by square brackets [ ].

If the input is not surrounded by square brackets, then the number of values should equal the current number of elements in this matrix, as defined by the product of rowSize and colSize.

If the input is surrounded by square brackets, then the matrix dimensions are determined by the input itself: rows should be separated by either semicolons or a newline, the number of values in each row should be the same, and rows are read until a closing square bracket is detected. The resulting input should either match this matrix's dimensions, or this matrix should be resizable to accomodate those dimensions. For example,

 [ 1.2  4   5
   6    3.1 0 ]
 
defines a 2 x 3 matrix.

For the sparse format, the input should be surrounded by square brackets, and each element value is specified as a triple ( i j value ), enclosed in parentheses. No particular ordering is required for the i or j indices, and unspecified elements are set to zero. The entire set of elements should be surrounded by square brackets. For example,

 [ ( 0 0 1.2 )
   ( 0 1 4 )
   ( 0 2 5 )
   ( 1 0 6 )
   ( 1 1 3.1) ]
 
defines that same 2 x 3 matrix given in the previous example.

Parameters:
rtok - Tokenizer from which matrix values are read. Number parsing should be enabled
Throws:
ImproperSizeException - if this matrix has a fixed size which is incompatible with the input, or if the sizes of the specified rows are inconsistent
java.io.IOException

mul

void mul(VectorNd vr,
         VectorNd v1)
Multiplies this matrix by the column vector v1 and places the result in the vector vr. If M represents this matrix, this is equivalent to computing
  vr = M v1
 
The vector vr is resized if it is not sufficiently large.

Specified by:
mul in interface LinearTransformNd
Parameters:
vr - result vector
v1 - vector to multiply by
Throws:
ImproperSizeException - if the size of v1 does not equal the number of columns of this matrix.

mul

void mul(VectorNd vr,
         VectorNd v1,
         int nr,
         int nc)
Multiplies a submatrix of this matrix by the column vector v1 and places the result in the vector vr. The submatrix is defined by the first nr rows and nc columns of this matrix. If M represents this matrix, this is equivalent to computing
  vr = M[0:nr-1][0:nc-1] v1
 
The vector vr is resized if it is not sufficiently large.

Parameters:
vr - result vector
v1 - vector to multiply by
nr - number of initial rows of this matrix to use
nc - number of initial columns of this matrix to use
Throws:
ImproperSizeException - if the size of v1 is less than nc, or if nr or nc exceed the dimensions of this matrix.

mul

void mul(VectorNd vr,
         VectorNd v1,
         int r0,
         int nr,
         int c0,
         int nc)
Multiplies a submatrix of this matrix by the column vector v1 and places the result in the vector vr. The submatrix is defined by the nr rows and nc columns of this matrix starting at r0 and c0, respectively. If M represents this matrix, this is equivalent to computing
  vr = M[r0:r0+nr-1][c0:c0+nc-1] v1
 
The vector vr is resized if it is not sufficiently large.

Parameters:
vr - result vector
v1 - vector to multiply by
r0 - initial row of the submatrix
nr - number of rows in the submatrix
c0 - initial column of the submatrix
nc - number of columns in the submatrix
Throws:
ImproperSizeException - if the size of v1 is less than nc, or if nr or nc exceed the dimensions of this matrix.

mulAdd

void mulAdd(VectorNd vr,
            VectorNd v1)
Multiplies this matrix by the column vector v1 and adds the result to the vector vr. If M represents this matrix, this is equivalent to computing
  vr += M v1
 

Parameters:
vr - result vector
v1 - vector to multiply by
Throws:
ImproperSizeException - if the size of v1 does not equal the number of columns of this matrix, or if the size of vr does not equal the number of rows.

mulAdd

void mulAdd(VectorNd vr,
            VectorNd v1,
            int nr,
            int nc)
Multiplies a submatrix of this matrix by the column vector v1 and adds the result to the vector vr. The submatrix is defined by the first nr rows and nc columns of this matrix. If M represents this matrix, this is equivalent to computing
  vr += M[0:nr-1][0:nc-1] v1
 

Parameters:
vr - result vector
v1 - vector to multiply by
nr - number of initial rows of this matrix to use
nc - number of initial columns of this matrix to use
Throws:
ImproperSizeException - if the size of v1 is less than nc, if the size of vr is less than nr, or if nr or nc exceed the dimensions of this matrix.

mulAdd

void mulAdd(VectorNd vr,
            VectorNd v1,
            int r0,
            int nr,
            int c0,
            int nc)
Multiplies a submatrix of this matrix by the column vector v1 and adds the result to the vector vr. The submatrix is defined by the nr rows and nc columns of this matrix starting at r0 and c0, respectively. If M represents this matrix, this is equivalent to computing
  vr += M[r0:r0+nr-1][c0:c0+nc-1] v1
 

Parameters:
vr - result vector
v1 - vector to multiply by
r0 - initial row of the submatrix
nr - number of rows in the submatrix
c0 - initial column of the submatrix
nc - number of columns in the submatrix
Throws:
ImproperSizeException - if the size of v1 is less than nc, if the size of vr is less than nr, or if nr or nc exceed the dimensions of this matrix.

mulTranspose

void mulTranspose(VectorNd vr,
                  VectorNd v1)
Multiplies the transpose of this matrix by the vector v1 and places the result in vr. If M represents this matrix, this is equivalent to computing
  vr = v1 M
 
The vector vr is resized if it is not sufficiently large.

Parameters:
vr - result vector
v1 - vector to multiply by
Throws:
ImproperSizeException - if the size of v1 does not equal the number of rows of this matrix

mulTranspose

void mulTranspose(VectorNd vr,
                  VectorNd v1,
                  int nr,
                  int nc)
Multiplies a submatrix of the transpose of this matrix by the column vector v1 and places the result in the vector vr. The submatrix is defined by the first nr rows and nc columns of the transpose of this matrix. If M represents this matrix, this is equivalent to computing
  vr = v1 M[0:nc-1][0:nr-1]
 
The vector vr is resized if it is not sufficiently large.

Parameters:
vr - result vector
v1 - vector to multiply by
nr - number of initial rows of the transpose of this matrix to use
nc - number of initial columns of the transpose of this matrix to use
Throws:
ImproperSizeException - if the size of v1 is less than nc, or if nr or nc exceed the dimensions of this matrix.

mulTranspose

void mulTranspose(VectorNd vr,
                  VectorNd v1,
                  int r0,
                  int nr,
                  int c0,
                  int nc)
Multiplies a submatrix of the transpose of this matrix by the column vector v1 and places the result in the vector vr. The submatrix is defined by the nr rows and nc columns of the transpose of this matrix starting at r0 and c0, respectively. If M represents this matrix, this is equivalent to
  vr = v1 M[c0:c0+nc-1][r0:r0+nr-1]
 
The vector vr is resized if it is not sufficiently large.

Parameters:
vr - result vector
v1 - vector to multiply by
r0 - initial row of the submatrix
nr - number of rows in the submatrix
c0 - initial column of the submatrix
nc - number of columns in the submatrix
Throws:
ImproperSizeException - if the size of v1 is less than nc, or if nr or nc exceed the dimensions of this matrix.

mulTransposeAdd

void mulTransposeAdd(VectorNd vr,
                     VectorNd v1)
Multiplies the transpose of this matrix by the vector v1 and adds the result to vr. If M represents this matrix, this is equivalent to computing
  vr += v1 M
 

Parameters:
vr - result vector
v1 - vector to multiply by
Throws:
ImproperSizeException - if the size of v1 does not equal the number of rows of this matrix

mulTransposeAdd

void mulTransposeAdd(VectorNd vr,
                     VectorNd v1,
                     int nr,
                     int nc)
Multiplies a submatrix of the transpose of this matrix by the column vector v1 and adds the result to the vector vr. The submatrix is defined by the first nr rows and nc columns of the transpose of this matrix. If M represents this matrix, this is equivalent to computing
  vr += v1 M[0:nc-1][0:nr-1]
 

Parameters:
vr - result vector
v1 - vector to multiply by
nr - number of initial rows of the transpose of this matrix to use
nc - number of initial columns of the transpose of this matrix to use
Throws:
ImproperSizeException - if the size of v1 is less than nc, or if nr or nc exceed the dimensions of this matrix.

mulTransposeAdd

void mulTransposeAdd(VectorNd vr,
                     VectorNd v1,
                     int r0,
                     int nr,
                     int c0,
                     int nc)
Multiplies a submatrix of the transpose of this matrix by the column vector v1 and adds the result to the vector vr. The submatrix is defined by the nr rows and nc columns of the transpose of this matrix starting at r0 and c0, respectively. If M represents this matrix, this is equivalent to
  vr += v1 M[c0:c0+nc-1][r0:r0+nr-1]
 

Parameters:
vr - result vector
v1 - vector to multiply by
r0 - initial row of the submatrix
nr - number of rows in the submatrix
c0 - initial column of the submatrix
nc - number of columns in the submatrix
Throws:
ImproperSizeException - if the size of v1 is less than nc, or if nr or nc exceed the dimensions of this matrix.

set

void set(double[] values,
         int[] indices,
         int numValues)
Sets the elements of this matrix from an array of doubles and a list of indices. Each value should be associated with two (i,j) index values, which, for the k-th value, are given by indices[k*2] and indices[k*2+1], respectively. All non-specified elements are set to zero.

Parameters:
values - explicit values for specific matrix locations
indices - i and j indices for each explicit value
numValues - number of explicit values

getCRSIndices

int getCRSIndices(int[] colIdxs,
                  int[] rowOffs,
                  Matrix.Partition part)
Gets the compressed row storage (CRS) indices for this matrix. Indices are 1-based and the matrix is traversed in row-major order. For a detailed decsription of the CRS format, see setCRSValues().

Parameters:
colIdxs - returns the column indices of each non-zero element, in row-major order. This array must have a length equal at least to the number of non-zero elements.
rowOffs - returns the row start offsets into colIdxs, followed by nvals+1, where nvals is the number of non-zero elements. This array must have a length equal at least to nrows+1, where nrows is the number of rows in this matrix.
part - specifies what portion of the matrix to store; must be either Full or UpperTriangular
Returns:
number of non-zero elements

getCRSIndices

int getCRSIndices(int[] colIdxs,
                  int[] rowOffs,
                  Matrix.Partition part,
                  int numRows,
                  int numCols)
Gets the compressed row storage (CRS) indices for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns. Indices are 1-based and supplied in row-major order. For a detailed decsription of the CRS format, see setCRSValues(). Some matrix types may place restrictions on the sub-matrix; for instance, a block-structured matrix may require that the sub-matrix be block aligned.

Parameters:
colIdxs - returns the column indices of each non-zero element, in row-major order. This array must have a length equal at least to the number of non-zero elements.
rowOffs - returns the row start offsets into colIdxs, followed by nvals+1, where nvals is the number of non-zero elements in the sub-matrix. This array must have a length equal at least to nrows+1, where nrows is the number of rows in the sub-matrix.
part - specifies what portion of the sub-matrix to store; must be either Full or UpperTriangular
numRows - number of rows delimiting the sub-matrix
numCols - number of columns delimiting the sub-matrix
Returns:
number of non-zero elements

getCRSValues

int getCRSValues(double[] vals,
                 Matrix.Partition part)
Gets the compressed row storage (CRS) values for this matrix, in row-major order. For a detailed decsription of the CRS format, see setCRSValues().

Parameters:
vals - returns the value of each non-zero element. This array must have a length equal at least to the number of non-zero elements.
part - specifies what portion of the matrix to store; must be either Full or UpperTriangular
Returns:
number of non-zero elements

getCRSValues

int getCRSValues(double[] vals,
                 Matrix.Partition part,
                 int numRows,
                 int numCols)
Gets the compressed row storage (CRS) values for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns. Values are supplied in row-major order. For a detailed decsription of the CRS format, see setCRSValues(). Some matrix types may place restrictions on the sub-matrix; for instance, a block-structured matrix may require that the sub-matrix be block aligned.

Parameters:
vals - returns the value of each non-zero element. This array must have a length equal at least to the number of non-zero elements in the sub-matrix.
part - specifies what portion of the sub-matrix to store; must be either Full or UpperTriangular
numRows - number of rows delimiting the sub-matrix
numCols - number of columns delimiting the sub-matrix
Returns:
number of non-zero elements

setCRSValues

void setCRSValues(double[] vals,
                  int[] colIdxs,
                  int[] rowOffs,
                  int nvals,
                  int nrows,
                  Matrix.Partition part)
Sets the contents of this matrix given a set of values in compressed row storage (CRS). The argument part specifies what portion of the matrix is supplied. If it is Full, then the entire matrix is supplied. If it is Matrix.Partition.UpperTriangular, then only the upper triangular part is assumed to be supplied, and the lower triangular part is set from its transpose (matrix bounds permitting). For Partition.UpperTriangular, supplied entries which are not upper triangular will either be ignored or generate an exception.

All specified data must fit within the current matrix bounds; the matrix is not resized.

CRS data takes the form of three arrays:

vals
An array giving the values of all the non-zero elements in the sparse matrix, in row-major order.
colIdxs
An array giving the column indices of all the non-zero elements in the sparse matrix, in row-major order. The indices are 1-based, so that 1 denotes the first column.
rowOffs
An array of size nrows+1, where nrows is the number of matrix rows, giving the offsets into vals and colIdxs corresponding to the first non-zero element in each row. All values are 1-based, so that first offset value is 1, the second offset value is n+1, where n is the number of non-zero elements in the first row, etc. The final value is set to nvals+1, where nvals is the number of non-zero elements in the matrix.
CRS index data is 1-based because this is the most standard form used by solvers and matrix formats.

Parameters:
vals - non-zero element values. This array must have a length equal at least to nvals.
colIdxs - column indices for each non-zero element. This array must have a length equal at least to nvals.
rowOffs - row start offsets into vals and colIdxs. This array must have a length equal at least to nrows+1, where nrows is the number of rows in this matrix.
nvals - number of non-zero values
nrows - number of specified rows. Indicates the maximum value of rowOffs that will be used; will not resize matrix.
part - must be either Full or UpperTriangular.

getCCSIndices

int getCCSIndices(int[] rowIdxs,
                  int[] colOffs,
                  Matrix.Partition part)
Gets the compressed column storage (CCS) indices for this matrix. Indices are 1-based and the matrix is traversed in column-major order. For a detailed decsription of the CCS format, see setCCSValues().

Parameters:
rowIdxs - returns the row indices of each non-zero element, in column-major order. This array must have a length equal at least to the number of non-zero elements.
colOffs - returns the column start offsets into rowIdxs, followed by nvals+1, where nvals is the number of non-zero elements. This array must have a length equal at least to ncols+1, where ncols is the number of columns in this matrix.
part - specifies what portion of the matrix to store; must be either Full or LowerTriangular
Returns:
number of non-zero elements

getCCSIndices

int getCCSIndices(int[] rowIdxs,
                  int[] colOffs,
                  Matrix.Partition part,
                  int numRows,
                  int numCols)
Gets the compressed column storage (CCS) indices for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns. Indices are 1-based and supplied in column-major order. For a detailed decsription of the CCS format, see setCCSValues(). Some matrix types may place restrictions on the sub-matrix; for instance, a block-structured matrix may require that the sub-matrix be block aligned.

Parameters:
rowIdxs - returns the row indices of each non-zero element, in column-major order. This array must have a length equal at least to the number of non-zero elements.
colOffs - returns the column start offsets into rowIdxs, followed by nvals+1, where nvals is the number of non-zero elements in the sub-matrix. This array must have a length equal at least to ncol+1, where ncols is the number of columns in the sub-matrix.
part - specifies what portion of the sub-matrix to store; must be either Full or LowerTriangular
numRows - number of rows delimiting the sub-matrix
numCols - number of columns delimiting the sub-matrix
Returns:
number of non-zero elements

getCCSValues

int getCCSValues(double[] vals,
                 Matrix.Partition part)
Gets the compressed column storage (CCS) values for this matrix, in column-major order. For a detailed decsription of the CCS format, see setCCSValues().

Parameters:
vals - returns the value of each non-zero element. This array must have a length equal at least to the number of non-zero elements.
part - specifies what portion of the matrix to store; must be either Full or LowerTriangular
Returns:
number of non-zero elements

getCCSValues

int getCCSValues(double[] vals,
                 Matrix.Partition part,
                 int numRows,
                 int numCols)
Gets the compressed column storage (CCS) values for a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns. Values are supplied in column-major order. For a detailed decsription of the CCS format, see setCCSValues(). Some matrix types may place restrictions on the sub-matrix; for instance, a block-structured matrix may require that the sub-matrix be block aligned.

Parameters:
vals - returns the value of each non-zero element. This array must have a length equal at least to the number of non-zero elements in the sub-matrix.
part - specifies what portion of the sub-matrix to store; must be either Full or LowerTriangular
numRows - number of rows delimiting the sub-matrix
numCols - number of columns delimiting the sub-matrix
Returns:
number of non-zero elements

setCCSValues

void setCCSValues(double[] vals,
                  int[] rowIdxs,
                  int[] colOffs,
                  int nvals,
                  int ncols,
                  Matrix.Partition part)
Sets the contents of this matrix given a set of values in compressed column storage (CCS). The argument part specifies what portion of the matrix is supplied. If it is Full, then the entire matrix is supplied. If it is Matrix.Partition.LowerTriangular, then only the lower triangular part is assumed to be supplied, and the upper triangular part is set from its transpose (matrix bounds permitting). For Partition.LowerTriangular, supplied entries which are not lower triangular will either be ignored or generate an exception.

All specified data must fit within the current matrix bounds; the matrix is not resized.

CCCS data takes the form of three arrays:

vals
An array giving the values of all the non-zero elements in the sparse matrix, in column-major order.
rowIdxs
An array giving the row indices of all the non-zero elements in the sparse matrix, in column-major order. The indices are 1-based, so that 1 denotes the first row.
colOffs
An array of size ncols+1, where ncols is the number of matrix columns, giving the offsets into vals and colIdxs corresponding to the first non-zero element in each column. All values are 1-based, so that first offset value is 1, the second offset value is n+1, where n is the number of non-zero elements in the first column, etc. The final value is set to nvals+1, where nvals is the number of non-zero elements in the matrix.
CCS index data is 1-based because this is the most standard form used by solvers and matrix formats.

Parameters:
vals - non-zero element values. This array must have a length equal at least to nvals.
rowIdxs - row indices for each non-zero element. This array must have a length equal at least to nvals.
colOffs - column start offsets into vals and rowIdxs. This array must have a length equal at least to ncols+1, where ncols is the number of columns in this matrix.
nvals - number of non-zero values
ncols - number of specified columns. Indicates the maximum value of colOffs that will be used; will not resize matrix.
part - must be either Full or LowerTriangular.

getSubMatrix

void getSubMatrix(int baseRow,
                  int baseCol,
                  DenseMatrix Mdest)
                  throws ImproperSizeException
Gets a submatrix of this matrix object. The first row and column of the submatrix are given by baseRow and baseCol, and the values are written into the matrix object Mdest. The size of the submatrix is determined by the dimensions of Mdest.

Parameters:
baseRow - first row of the submatrix
baseCol - first column of the submatrix
Mdest - destination for submatrix values
Throws:
ImproperSizeException - if baseRow or baseCol are negative, or if the submatrix exceeds the current matrix bounds.
See Also:
MatrixNd.copySubMatrix(int, int, int, int, maspack.matrix.Matrix, int, int)

isSymmetric

boolean isSymmetric(double tol)
Returns true if this matrix is symmetric within a given tolerance. Specifically, each off-diagonal element must equal it's transposed counterpart within the given tolerance.

Parameters:
tol - tolerance for checking equality of off-diagonal elements

numNonZeroVals

int numNonZeroVals()
Returns the number of non-zero values in this matrix object. For dense matrices, this will simply be the product of the number of rows times the number of columns.

Returns:
number of non-zero values

numNonZeroVals

int numNonZeroVals(Matrix.Partition part,
                   int numRows,
                   int numCols)
Returns the number of non-zero values for a specified partition of a principal sub-matrix of this matrix delimited by the first numRows rows and the first numCols columns. If the matrix is dense and the partition is Full, then this will simply be the product of the number of rows times the number of columns.

Parameters:
part - matrix parition to be examined
numRows - number of rows delimiting the sub-matrix
numCols - number of columns delimiting the sub-matrix
Returns:
number of non-zero values

toString

java.lang.String toString(NumberFormat fmt)
Returns a String representation of this matrix, in which each element is formatted using a C printf style format as decribed by the parameter NumberFormat.

Parameters:
fmt - numeric format
Returns:
String representation of this vector

getSize

java.lang.String getSize()
Returns a string indicating the size of this matrix.

Returns:
size of the matrix, in string form

checkConsistency

void checkConsistency()
Check that the internal structures of this matrix are consistent. Used for testing.

Throws:
java.lang.IllegalStateException - if the matrix structure is inconsistent.