Package edu.cmu.tetrad.util

Class Matrix

java.lang.Object
edu.cmu.tetrad.util.Matrix
All Implemented Interfaces:
TetradSerializable, Serializable
public class Matrix extends Object implements TetradSerializable
Wraps the EJML linear algebra library for most uses in Tetrad. Specialized uses will still have to use the library directly. One issue is that we need to be able to represent empty matrices gracefully; this case is handled separately and incorporated into the class.
Version:
$Id: $Id
Author:
josephramsey
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Matrix(double[][] data)
    Constructor for Matrix.
    Matrix(int m, int n)
    Constructor for Matrix.
    Matrix(Matrix m)
    Constructor for Matrix.
    Matrix(org.ejml.simple.SimpleMatrix data)
    Constructs a Matrix object based on the given SimpleMatrix data.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    assign(Matrix matrix)
    assign.
    void
    assignColumn(int col, Vector doubles)
    assignColumn.
    void
    assignPart(int[] range1, int[] range2, Matrix from)
    Assigns a part of the given matrix to a specified submatrix while adding the values to the existing data.
    void
    assignRow(int row, Vector doubles)
    assignRow.
    Matrix
    chooseInverse(double lambda)
    Calculates and returns the appropriate inverse of the matrix based on the provided lambda value: If lambda is 0.0, the inverse of the matrix is computed using the standard inversion method. If lambda is greater than 0.0, the matrix is regularized by adding lambda to the diagonal, ensuring numerical stability for near-singular matrices, and then the inverse is computed. If lambda is less than 0.0, the Moore-Penrose pseudoinverse is computed, which is useful for non-square or singular matrices. This method is designed to handle a variety of inverse computations depending on the requirements, such as regularization or handling singular matrices.
    Vector
    col(int i)
    Retrieves the specified column from a data structure as a Vector object.
    Matrix
    copy()
    copy.
    double
    det()
    det.
    Vector
    diag()
    diag.
    boolean
    equals(Matrix m, double tolerance)
    equals.
    double
    get(int i, int j)
    get.
    Vector
    getColumn(int j)
    getColumn.
    org.ejml.simple.SimpleMatrix
    getData()
    Returns the wrapped SimpleMatrix.
    int
    getNumColumns()
    getNumColumns.
    int
    getNumRows()
    getNumRows.
    Matrix
    getPart(int i, int j, int k, int l)
    Extracts a submatrix from the current matrix based on the specified row and column ranges.
    org.ejml.simple.SimpleMatrix
    getSimpleMatrix()
    Creates and returns a copy of the internal data matrix.
    static Matrix
    identity(int rows)
    identity.
    Matrix
    inverse()
    Returns the inverse of the matrix.
    boolean
    isSquare()
    isSquare.
    Matrix
    like()
    like.
    Matrix
    minus(Matrix mb)
    minus.
    double
    norm1()
    norm1.
    Matrix
    plus(Matrix mb)
    plus.
    Matrix
    pseudoinverse()
    Returns the Moore-Penrose pseudoinverse of the matrix.
    int
    rank()
    rank.
    Matrix
    regularize(double lambda)
    Regularizes the diagonal of the matrix by adding a scaled identity matrix to it.
    Vector
    row(int i)
    getRow.
    Matrix
    scalarMult(double scalar)
    scalarMult.
    Matrix
    scalarPlus(double scalar)
    Adds the specified scalar value to each element of the matrix and returns the resulting matrix.
    static Matrix
    serializableInstance()
    Generates a simple exemplar of this class to test serialization.
    void
    set(int i, int j, double v)
    set.
    Matrix
    solve(Matrix rhs)
    Solves the linear system A * X = B where this matrix is A and the argument is B.
    Matrix
    sqrt()
    sqrt.
    Vector
    sum(int direction)
    sum.
    Matrix
    times(Matrix m)
    times.
    Vector
    times(Vector v)
    times.
    double[][]
    toArray()
    toArray.
    String
    toString()
    toString.
    double
    trace()
    trace.
    Matrix
    transpose()
    transpose.
    MView
    view()
    Creates a view of the entire matrix.
    MView
    view(int[] range1, int[] range2)
    Creates a view of a matrix using the specified row and column indices.
    MView
    viewColumn(int column)
    Creates a view of a specific column from the matrix.
    MView
    viewPart(int fromRow, int toRow, int fromColumn, int toColumn)
    Creates a view of a specified submatrix defined by the given row and column ranges.
    MView
    viewRow(int row)
    Creates a sub-view of the matrix representing a specific row.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Matrix

      public Matrix(double[][] data)

      Constructor for Matrix.

      Parameters:
      data - an array of objects

    • Matrix

      public Matrix(org.ejml.simple.SimpleMatrix data)
      Constructs a Matrix object based on the given SimpleMatrix data.
      Parameters:
      data - the SimpleMatrix object containing the data to initialize the matrix

    • Matrix

      public Matrix(int m, int n)

      Constructor for Matrix.

      Parameters:
      m - a int
      n - a int

    • Matrix

      public Matrix(Matrix m)

      Constructor for Matrix.

      Parameters:
      m - a Matrix object

  • Method Details

    • identity

      public static Matrix identity(int rows)

      identity.

      Parameters:
      rows - a int
      Returns:
      a Matrix object

    • serializableInstance

      public static Matrix serializableInstance()
      Generates a simple exemplar of this class to test serialization.
      Returns:
      a Matrix object

    • assignPart

      public void assignPart(int[] range1, int[] range2, Matrix from)
      Assigns a part of the given matrix to a specified submatrix while adding the values to the existing data. The values from the 'from' matrix are added to the corresponding elements of the submatrix defined by the ranges.
      Parameters:
      range1 - an array of integers representing the row indices of the submatrix to which the values will be assigned
      range2 - an array of integers representing the column indices of the submatrix to which the values will be assigned
      from - a Matrix object providing the values to be added to the specified submatrix

    • assign

      public void assign(Matrix matrix)

      assign.

      Parameters:
      matrix - a Matrix object

    • getNumColumns

      public int getNumColumns()

      getNumColumns.

      Returns:
      a int

    • diag

      public Vector diag()

      diag.

      Returns:
      a Vector object

    • copy

      public Matrix copy()

      copy.

      Returns:
      a Matrix object

    • getColumn

      public Vector getColumn(int j)

      getColumn.

      Parameters:
      j - a int
      Returns:
      a Vector object

    • times

      public Matrix times(Matrix m)

      times.

      Parameters:
      m - a Matrix object
      Returns:
      a Matrix object

    • times

      public Vector times(Vector v)

      times.

      Parameters:
      v - a Vector object
      Returns:
      a Vector object

    • toArray

      public double[][] toArray()

      toArray.

      Returns:
      an array of objects

    • get

      public double get(int i, int j)

      get.

      Parameters:
      i - a int
      j - a int
      Returns:
      a double

    • like

      public Matrix like()

      like.

      Returns:
      a Matrix object

    • set

      public void set(int i, int j, double v)

      set.

      Parameters:
      i - a int
      j - a int
      v - a double

    • row

      public Vector row(int i)

      getRow.

      Parameters:
      i - a int
      Returns:
      a Vector object

    • col

      public Vector col(int i)
      Retrieves the specified column from a data structure as a Vector object.
      Parameters:
      i - the index of the column to retrieve
      Returns:
      a Vector representing the specified column

    • getPart

      public Matrix getPart(int i, int j, int k, int l)
      Extracts a submatrix from the current matrix based on the specified row and column ranges.
      Parameters:
      i - the starting row index (inclusive) of the submatrix
      j - the ending row index (inclusive) of the submatrix
      k - the starting column index (inclusive) of the submatrix
      l - the ending column index (inclusive) of the submatrix
      Returns:
      a new Matrix instance representing the extracted submatrix

    • inverse

      public Matrix inverse()
      Returns the inverse of the matrix. If the matrix is not square, an exception is thrown. If the matrix is singular, an exception is thrown.
      Returns:
      a Matrix object

    • pseudoinverse

      public Matrix pseudoinverse()
      Returns the Moore-Penrose pseudoinverse of the matrix.
      Returns:
      a Matrix object

    • chooseInverse

      public Matrix chooseInverse(double lambda)
      Calculates and returns the appropriate inverse of the matrix based on the provided lambda value:
      • If lambda is 0.0, the inverse of the matrix is computed using the standard inversion method.
      • If lambda is greater than 0.0, the matrix is regularized by adding lambda to the diagonal, ensuring numerical stability for near-singular matrices, and then the inverse is computed.
      • If lambda is less than 0.0, the Moore-Penrose pseudoinverse is computed, which is useful for non-square or singular matrices.
      This method is designed to handle a variety of inverse computations depending on the requirements, such as regularization or handling singular matrices.
      Parameters:
      lambda - A value controlling the method of inversion:
      • 0.0: Standard matrix inversion.
      • > 0.0: Regularized inversion for numerical stabilit. A small value should be chosen.
      • < 0.0: Moore-Penrose pseudoinverse.
      Returns:
      The calculated inverse of the matrix based on the specified lambda value.
      Throws:
      IllegalArgumentException - If lambda is neither -1.0, 0.0, nor a positive value.

    • regularize

      public Matrix regularize(double lambda)
      Regularizes the diagonal of the matrix by adding a scaled identity matrix to it.
      Parameters:
      lambda - the scalar value used to scale the identity matrix before adding it to the current matrix
      Returns:
      a new Matrix object representing the result of adding the scaled identity matrix to the current matrix

    • assignRow

      public void assignRow(int row, Vector doubles)

      assignRow.

      Parameters:
      row - a int
      doubles - a Vector object

    • assignColumn

      public void assignColumn(int col, Vector doubles)

      assignColumn.

      Parameters:
      col - a int
      doubles - a Vector object

    • trace

      public double trace()

      trace.

      Returns:
      a double

    • det

      public double det()

      det.

      Returns:
      a double

    • transpose

      public Matrix transpose()

      transpose.

      Returns:
      a Matrix object

    • equals

      public boolean equals(Matrix m, double tolerance)

      equals.

      Parameters:
      m - a Matrix object
      tolerance - a double
      Returns:
      a boolean

    • isSquare

      public boolean isSquare()

      isSquare.

      Returns:
      a boolean

    • minus

      public Matrix minus(Matrix mb)

      minus.

      Parameters:
      mb - a Matrix object
      Returns:
      a Matrix object

    • norm1

      public double norm1()

      norm1.

      Returns:
      a double

    • plus

      public Matrix plus(Matrix mb)

      plus.

      Parameters:
      mb - a Matrix object
      Returns:
      a Matrix object

    • rank

      public int rank()

      rank.

      Returns:
      a int

    • getNumRows

      public int getNumRows()

      getNumRows.

      Returns:
      a int

    • scalarMult

      public Matrix scalarMult(double scalar)

      scalarMult.

      Parameters:
      scalar - a double
      Returns:
      a Matrix object

    • scalarPlus

      public Matrix scalarPlus(double scalar)
      Adds the specified scalar value to each element of the matrix and returns the resulting matrix.
      Parameters:
      scalar - the scalar value to be added to each element of the matrix
      Returns:
      a new Matrix instance where each element is the sum of the corresponding element in the original matrix and the scalar value

    • sqrt

      public Matrix sqrt()

      sqrt.

      Returns:
      a Matrix object

    • sum

      public Vector sum(int direction)

      sum.

      Parameters:
      direction - a int
      Returns:
      a Vector object

    • view

      public MView view(int[] range1, int[] range2)
      Creates a view of a matrix using the specified row and column indices.
      Parameters:
      range1 - an array of row indices to include in the view. Each index must be within the range [0, number of rows).
      range2 - an array of column indices to include in the view. Each index must be within the range [0, number of columns).
      Returns:
      a MatrixView object representing the specified subset of the matrix.
      Throws:
      IllegalArgumentException - if any row index in range1 is out of bounds or any column index in range2 is out of bounds.

    • view

      public MView view()
      Creates a view of the entire matrix.
      Returns:
      a MatrixView object representing the entire matrix.

    • viewRow

      public MView viewRow(int row)
      Creates a sub-view of the matrix representing a specific row.
      Parameters:
      row - the index of the row to be viewed
      Returns:
      a MatrixView object representing the specified row

    • viewColumn

      public MView viewColumn(int column)
      Creates a view of a specific column from the matrix.
      Parameters:
      column - the index of the column to be viewed
      Returns:
      a MatrixView object representing the specified column

    • viewPart

      public MView viewPart(int fromRow, int toRow, int fromColumn, int toColumn)
      Creates a view of a specified submatrix defined by the given row and column ranges.
      Parameters:
      fromRow - the starting row index (inclusive) of the submatrix
      toRow - the ending row index (exclusive) of the submatrix
      fromColumn - the starting column index (inclusive) of the submatrix
      toColumn - the ending column index (exclusive) of the submatrix
      Returns:
      a MatrixView object representing the specified submatrix view

    • toString

      public String toString()

      toString.

      Overrides:
      toString in class Object
      Returns:
      a String object

    • getSimpleMatrix

      public org.ejml.simple.SimpleMatrix getSimpleMatrix()
      Creates and returns a copy of the internal data matrix.
      Returns:
      A new SimpleMatrix instance that is a copy of the internal data.

    • getData

      public org.ejml.simple.SimpleMatrix getData()
      Returns the wrapped SimpleMatrix. Be careful with this.
      Returns:
      the wrapped SimpleMatrix instance.

    • solve

      public Matrix solve(Matrix rhs)
      Solves the linear system A * X = B where this matrix is A and the argument is B.

      If A is square and nonsingular, uses a direct solver. Otherwise falls back to a least-squares solution via the Moore–Penrose pseudoinverse.

      Parameters:
      rhs - The right-hand side matrix B.
      Returns:
      The solution matrix X.
      Throws:
      IllegalArgumentException - if the row dimensions are incompatible.