Package no.uib.cipr.matrix

Interface Matrix

All Superinterfaces:
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 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

  • Method Details

    • 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