no.uib.cipr.matrix
Interface Matrix

All Superinterfaces:
java.lang.Iterable<MatrixEntry>
All Known Implementing Classes:
AbstractMatrix, BandMatrix, CompColMatrix, CompDiagMatrix, CompRowMatrix, DenseMatrix, DistColMatrix, DistRowMatrix, FlexCompColMatrix, FlexCompRowMatrix, LowerSPDBandMatrix, LowerSPDDenseMatrix, LowerSPDPackMatrix, LowerSymmBandMatrix, LowerSymmDenseMatrix, LowerSymmPackMatrix, LowerTriangBandMatrix, LowerTriangDenseMatrix, LowerTriangPackMatrix, SPDTridiagMatrix, SymmTridiagMatrix, TridiagMatrix, UnitLowerTriangBandMatrix, UnitLowerTriangDenseMatrix, UnitLowerTriangPackMatrix, UnitUpperTriangBandMatrix, UnitUpperTriangDenseMatrix, UnitUpperTriangPackMatrix, UpperSPDBandMatrix, UpperSPDDenseMatrix, UpperSPDPackMatrix, UpperSymmBandMatrix, UpperSymmDenseMatrix, UpperSymmPackMatrix, UpperTriangBandMatrix, UpperTriangDenseMatrix, UpperTriangPackMatrix

public interface Matrix
extends java.lang.Iterable<MatrixEntry>

Basic matrix interface. It holds doubles in a rectangular 2D array, and it is used alongside Vector in numerical computations. Implementing classes decides on the actual storage.

Basic operations

Use numRows and numColumns to get the basic size of a matrix. get(int,int) gets an element, and there are corresponding set(int,int,double) and add(int,int,double) methods as well. Note that matrix indices are zero-based (typical for Java and C). This means that the row-indices range from 0 to numRows-1, likewise for the columns. It is legal to have numRows or numColumns equal zero.

Other basic operations are zero which zeros all the entries of the matrix, which can be cheaper than either zeroing the matrix manually, or creating a new matrix, and the operation copy which creates a deep copy of the matrix. This copy has separate storage, but starts with the same contents as the current matrix.

Iterators

The matrix interface extends Iterable, and the iterator returns a MatrixEntry which contains current index and entry value. Note that the iterator may skip non-zero entries. Using an iterator, many simple and efficient algorithms can be created. The iterator also permits changing values in the matrix, however only non-zero entries can be changed.

Basic linear algebra

A large selection of basic linear algebra operations are available. To ensure high efficiency, little or no internal memory allocation is done, and the user is required to supply the output arguments.

The operations available include:

Additions
Matrices can be added to each other, even if their underlying matrix structures are different.
Multiplications
A matrix can be multiplied with vectors and other matrices. For increased efficiency, a multiplication can be combined with addition and scaling, and transpose matrix multiplications are also available.
Rank-updates
A matrix can be efficiently updated using low-rank updates. The updates can be contained in both matrices or vectors.
Transpositions
In-place transpositions of square matrices is supported, and the transpose of a matrix can be stored in another matrix of compatible size (possibly non-rectangular)
Solvers
Many dense and structured sparse matrices have fast, direct solvers, and can be used to solve linear systems without creating a factorization. These solvers are typically backed by subroutines in LAPACK


Nested Class Summary
static class Matrix.Norm
          Supported matrix-norms.
 
Method Summary
 Matrix add(double alpha, Matrix B)
          A = alpha*B + A.
 void add(int row, int column, double value)
          A(row,column) += value
 Matrix add(Matrix B)
          A = B + A.
 Matrix copy()
          Creates a deep copy of the matrix
 double get(int row, int column)
          Returns A(row,column)
 boolean isSquare()
          Returns true if the matrix is square
 Matrix mult(double alpha, Matrix B, Matrix C)
          C = alpha*A*B
 Vector mult(double alpha, Vector x, Vector y)
          y = alpha*A*x
 Matrix mult(Matrix B, Matrix C)
          C = A*B
 Vector mult(Vector x, Vector y)
          y = A*x
 Matrix multAdd(double alpha, Matrix B, Matrix C)
          C = alpha*A*B + C
 Vector multAdd(double alpha, Vector x, Vector y)
          y = alpha*A*x + y
 Matrix multAdd(Matrix B, Matrix C)
          C = A*B + C
 Vector multAdd(Vector x, Vector y)
          y = A*x + y
 double norm(Matrix.Norm type)
          Computes the given norm of the matrix
 int numColumns()
          Number of columns in the matrix
 int numRows()
          Number of rows in the matrix
 Matrix rank1(double alpha, Matrix C)
          A = alpha*C*CT + A.
 Matrix rank1(double alpha, Vector x)
          A = alpha*x*xT + A.
 Matrix rank1(double alpha, Vector x, Vector y)
          A = alpha*x*yT + A.
 Matrix rank1(Matrix C)
          A = C*CT + A.
 Matrix rank1(Vector x)
          A = x*xT + A.
 Matrix rank1(Vector x, Vector y)
          A = x*yT + A.
 Matrix rank2(double alpha, Matrix B, Matrix C)
          A = alpha*B*CT + alpha*C*BT + A.
 Matrix rank2(double alpha, Vector x, Vector y)
          A = alpha*x*yT + alpha*y*xT + A.
 Matrix rank2(Matrix B, Matrix C)
          A = B*CT + C*BT + A.
 Matrix rank2(Vector x, Vector y)
          A = x*yT + y*xT + A.
 Matrix scale(double alpha)
          A = alpha*A
 Matrix set(double alpha, Matrix B)
          A=alpha*B.
 void set(int row, int column, double value)
          A(row,column) = value
 Matrix set(Matrix B)
          A=B.
 Matrix solve(Matrix B, Matrix X)
          X = A\B.
 Vector solve(Vector b, Vector x)
          x = A\b.
 Matrix transABmult(double alpha, Matrix B, Matrix C)
          C = alpha*AT*BT
 Matrix transABmult(Matrix B, Matrix C)
          C = AT*BT
 Matrix transABmultAdd(double alpha, Matrix B, Matrix C)
          C = alpha*AT*BT + C
 Matrix transABmultAdd(Matrix B, Matrix C)
          C = AT*BT + C
 Matrix transAmult(double alpha, Matrix B, Matrix C)
          C = alpha*AT*B
 Matrix transAmult(Matrix B, Matrix C)
          C = AT*B
 Matrix transAmultAdd(double alpha, Matrix B, Matrix C)
          C = alpha*AT*B + C
 Matrix transAmultAdd(Matrix B, Matrix C)
          C = AT*B + C
 Matrix transBmult(double alpha, Matrix B, Matrix C)
          C = alpha*A*BT
 Matrix transBmult(Matrix B, Matrix C)
          C = A*BT
 Matrix transBmultAdd(double alpha, Matrix B, Matrix C)
          C = alpha*A*BT + C
 Matrix transBmultAdd(Matrix B, Matrix C)
          C = A*BT + C
 Vector transMult(double alpha, Vector x, Vector y)
          y = alpha*AT*x
 Vector transMult(Vector x, Vector y)
          y = AT*x
 Vector transMultAdd(double alpha, Vector x, Vector y)
          y = alpha*AT*x + y
 Vector transMultAdd(Vector x, Vector y)
          y = AT*x + y
 Matrix transpose()
          Transposes the matrix in-place.
 Matrix transpose(Matrix B)
          Sets the tranpose of this matrix into B.
 Matrix transRank1(double alpha, Matrix C)
          A = alpha*CT*C + A The matrices must be square and of the same size
 Matrix transRank1(Matrix C)
          A = CT*C + A The matrices must be square and of the same size
 Matrix transRank2(double alpha, Matrix B, Matrix C)
          A = alpha*BT*C + alpha*CT*B + A.
 Matrix transRank2(Matrix B, Matrix C)
          A = BT*C + CT*B + A.
 Matrix transSolve(Matrix B, Matrix X)
          X = AT\B.
 Vector transSolve(Vector b, Vector x)
          x = AT\b.
 Matrix zero()
          Zeros all the entries in the matrix, while preserving any underlying structure.
 
Methods inherited from interface java.lang.Iterable
iterator
 

Method Detail

numRows

int numRows()
Number of rows in the matrix


numColumns

int numColumns()
Number of columns in the matrix


isSquare

boolean isSquare()
Returns true if the matrix is square


set

void set(int row,
         int column,
         double value)
A(row,column) = value


add

void add(int row,
         int column,
         double value)
A(row,column) += value


get

double get(int row,
           int column)
Returns A(row,column)


copy

Matrix copy()
Creates a deep copy of the matrix

Returns:
A

zero

Matrix zero()
Zeros all the entries in the matrix, while preserving any underlying structure. Useful for general, unstructured matrices.

Returns:
A

mult

Vector mult(Vector x,
            Vector y)
y = A*x

Parameters:
x - Vector of size A.numColumns()
y - Vector of size A.numRows()
Returns:
y

mult

Vector mult(double alpha,
            Vector x,
            Vector y)
y = alpha*A*x

Parameters:
x - Vector of size A.numColumns()
y - Vector of size A.numRows()
Returns:
y

multAdd

Vector multAdd(Vector x,
               Vector y)
y = A*x + y

Parameters:
x - Vector of size A.numColumns()
y - Vector of size A.numRows()
Returns:
y

multAdd

Vector multAdd(double alpha,
               Vector x,
               Vector y)
y = alpha*A*x + y

Parameters:
x - Vector of size A.numColumns()
y - Vector of size A.numRows()
Returns:
y

transMult

Vector transMult(Vector x,
                 Vector y)
y = AT*x

Parameters:
x - Vector of size A.numRows()
y - Vector of size A.numColumns()
Returns:
y

transMult

Vector transMult(double alpha,
                 Vector x,
                 Vector y)
y = alpha*AT*x

Parameters:
x - Vector of size A.numRows()
y - Vector of size A.numColumns()
Returns:
y

transMultAdd

Vector transMultAdd(Vector x,
                    Vector y)
y = AT*x + y

Parameters:
x - Vector of size A.numRows()
y - Vector of size A.numColumns()
Returns:
y

transMultAdd

Vector transMultAdd(double alpha,
                    Vector x,
                    Vector y)
y = alpha*AT*x + y

Parameters:
x - Vector of size A.numRows()
y - Vector of size A.numColumns()
Returns:
y

solve

Vector solve(Vector b,
             Vector x)
             throws MatrixSingularException,
                    MatrixNotSPDException
x = A\b. Not all matrices support this operation, those that do not throw UnsupportedOperationException. Note that it is often more efficient to use a matrix decomposition and its associated solver

Parameters:
b - Vector of size A.numRows()
x - Vector of size A.numColumns()
Returns:
x
Throws:
MatrixSingularException - If the matrix is singular
MatrixNotSPDException - If the solver assumes that the matrix is symmetrical, positive definite, but that that property does not hold

transSolve

Vector transSolve(Vector b,
                  Vector x)
                  throws MatrixSingularException,
                         MatrixNotSPDException
x = AT\b. Not all matrices support this operation, those that do not throw UnsupportedOperationException. Note that it is often more efficient to use a matrix decomposition and its associated solver

Parameters:
b - Vector of size A.numColumns()
x - Vector of size A.numRows()
Returns:
x
Throws:
MatrixSingularException - If the matrix is singular
MatrixNotSPDException - If the solver assumes that the matrix is symmetrical, positive definite, but that that property does not hold

rank1

Matrix rank1(Vector x)
A = x*xT + A. The matrix must be square, and the vector of the same length

Returns:
A

rank1

Matrix rank1(double alpha,
             Vector x)
A = alpha*x*xT + A. The matrix must be square, and the vector of the same length

Returns:
A

rank1

Matrix rank1(Vector x,
             Vector y)
A = x*yT + A. The matrix must be square, and the vectors of the same length

Returns:
A

rank1

Matrix rank1(double alpha,
             Vector x,
             Vector y)
A = alpha*x*yT + A. The matrix must be square, and the vectors of the same length

Returns:
A

rank2

Matrix rank2(Vector x,
             Vector y)
A = x*yT + y*xT + A. The matrix must be square, and the vectors of the same length

Returns:
A

rank2

Matrix rank2(double alpha,
             Vector x,
             Vector y)
A = alpha*x*yT + alpha*y*xT + A. The matrix must be square, and the vectors of the same length

Returns:
A

mult

Matrix mult(Matrix B,
            Matrix C)
C = A*B

Parameters:
B - Matrix such that B.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numRows() and B.numColumns() == C.numColumns()
Returns:
C

mult

Matrix mult(double alpha,
            Matrix B,
            Matrix C)
C = alpha*A*B

Parameters:
B - Matrix such that B.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numRows() and B.numColumns() == C.numColumns()
Returns:
C

multAdd

Matrix multAdd(Matrix B,
               Matrix C)
C = A*B + C

Parameters:
B - Matrix such that B.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numRows() and B.numColumns() == C.numColumns()
Returns:
C

multAdd

Matrix multAdd(double alpha,
               Matrix B,
               Matrix C)
C = alpha*A*B + C

Parameters:
B - Matrix such that B.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numRows() and B.numColumns() == C.numColumns()
Returns:
C

transAmult

Matrix transAmult(Matrix B,
                  Matrix C)
C = AT*B

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transAmult

Matrix transAmult(double alpha,
                  Matrix B,
                  Matrix C)
C = alpha*AT*B

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transAmultAdd

Matrix transAmultAdd(Matrix B,
                     Matrix C)
C = AT*B + C

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transAmultAdd

Matrix transAmultAdd(double alpha,
                     Matrix B,
                     Matrix C)
C = alpha*AT*B + C

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transBmult

Matrix transBmult(Matrix B,
                  Matrix C)
C = A*BT

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transBmult

Matrix transBmult(double alpha,
                  Matrix B,
                  Matrix C)
C = alpha*A*BT

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transBmultAdd

Matrix transBmultAdd(Matrix B,
                     Matrix C)
C = A*BT + C

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transBmultAdd

Matrix transBmultAdd(double alpha,
                     Matrix B,
                     Matrix C)
C = alpha*A*BT + C

Parameters:
B - Matrix such that B.numRows() == A.numRows() and B.numColumns() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numColumns() == C.numColumns()
Returns:
C

transABmult

Matrix transABmult(Matrix B,
                   Matrix C)
C = AT*BT

Parameters:
B - Matrix such that B.numColumns() == A.numRows() and B.numRows() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numRows() == C.numColumns()
Returns:
C

transABmult

Matrix transABmult(double alpha,
                   Matrix B,
                   Matrix C)
C = alpha*AT*BT

Parameters:
B - Matrix such that B.numColumns() == A.numRows() and B.numRows() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numRows() == C.numColumns()
Returns:
C

transABmultAdd

Matrix transABmultAdd(Matrix B,
                      Matrix C)
C = AT*BT + C

Parameters:
B - Matrix such that B.numColumns() == A.numRows() and B.numRows() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numRows() == C.numColumns()
Returns:
C

transABmultAdd

Matrix transABmultAdd(double alpha,
                      Matrix B,
                      Matrix C)
C = alpha*AT*BT + C

Parameters:
B - Matrix such that B.numColumns() == A.numRows() and B.numRows() == C.numColumns()
C - Matrix such that C.numRows() == A.numColumns() and B.numRows() == C.numColumns()
Returns:
C

solve

Matrix solve(Matrix B,
             Matrix X)
             throws MatrixSingularException,
                    MatrixNotSPDException
X = A\B. Not all matrices support this operation, those that do not throw UnsupportedOperationException. Note that it is often more efficient to use a matrix decomposition and its associated solver

Parameters:
B - Matrix with the same number of rows as A, and the same number of columns as X
X - Matrix with a number of rows equal A.numColumns(), and the same number of columns as B
Returns:
X
Throws:
MatrixSingularException - If the matrix is singular
MatrixNotSPDException - If the solver assumes that the matrix is symmetrical, positive definite, but that that property does not hold

transSolve

Matrix transSolve(Matrix B,
                  Matrix X)
                  throws MatrixSingularException,
                         MatrixNotSPDException
X = AT\B. Not all matrices support this operation, those that do not throw UnsupportedOperationException. Note that it is often more efficient to use a matrix decomposition and its associated transpose solver

Parameters:
B - Matrix with a number of rows equal A.numColumns(), and the same number of columns as X
X - Matrix with the same number of rows as A, and the same number of columns as B
Returns:
X
Throws:
MatrixSingularException - If the matrix is singular
MatrixNotSPDException - If the solver assumes that the matrix is symmetrical, positive definite, but that that property does not hold

rank1

Matrix rank1(Matrix C)
A = C*CT + A. The matrices must be square and of the same size

Returns:
A

rank1

Matrix rank1(double alpha,
             Matrix C)
A = alpha*C*CT + A. The matrices must be square and of the same size

Returns:
A

transRank1

Matrix transRank1(Matrix C)
A = CT*C + A The matrices must be square and of the same size

Returns:
A

transRank1

Matrix transRank1(double alpha,
                  Matrix C)
A = alpha*CT*C + A The matrices must be square and of the same size

Returns:
A

rank2

Matrix rank2(Matrix B,
             Matrix C)
A = B*CT + C*BT + A. This matrix must be square

Parameters:
B - Matrix with the same number of rows as A and the same number of columns as C
C - Matrix with the same number of rows as A and the same number of columns as B
Returns:
A

rank2

Matrix rank2(double alpha,
             Matrix B,
             Matrix C)
A = alpha*B*CT + alpha*C*BT + A. This matrix must be square

Parameters:
B - Matrix with the same number of rows as A and the same number of columns as C
C - Matrix with the same number of rows as A and the same number of columns as B
Returns:
A

transRank2

Matrix transRank2(Matrix B,
                  Matrix C)
A = BT*C + CT*B + A. This matrix must be square

Parameters:
B - Matrix with the same number of rows as C and the same number of columns as A
C - Matrix with the same number of rows as B and the same number of columns as A
Returns:
A

transRank2

Matrix transRank2(double alpha,
                  Matrix B,
                  Matrix C)
A = alpha*BT*C + alpha*CT*B + A. This matrix must be square

Parameters:
B - Matrix with the same number of rows as C and the same number of columns as A
C - Matrix with the same number of rows as B and the same number of columns as A
Returns:
A

scale

Matrix scale(double alpha)
A = alpha*A

Returns:
A

set

Matrix set(Matrix B)
A=B. The matrices must be of the same size

Returns:
A

set

Matrix set(double alpha,
           Matrix B)
A=alpha*B. The matrices must be of the same size

Returns:
A

add

Matrix add(Matrix B)
A = B + A. The matrices must be of the same size

Returns:
A

add

Matrix add(double alpha,
           Matrix B)
A = alpha*B + A. The matrices must be of the same size

Returns:
A

transpose

Matrix transpose()
Transposes the matrix in-place. In most cases, the matrix must be square for this to work.

Returns:
This matrix

transpose

Matrix transpose(Matrix B)
Sets the tranpose of this matrix into B. Matrix dimensions must be compatible

Parameters:
B - Matrix with as many rows as this matrix has columns, and as many columns as this matrix has rows
Returns:
The matrix B=AT

norm

double norm(Matrix.Norm type)
Computes the given norm of the matrix

Parameters:
type - The type of norm to compute