Class GIMatrix

java.lang.Object
org.openscience.cdk.graph.invariant.GIMatrix

public class GIMatrix extends Object
This class is intended to provide the user an efficient way of implementing matrix of double number and using normal operations (linear operations, addition, subtraction, multiplication, inversion, concatenation) on them. The internal representation of a matrix is an array of array of double objects. For the moment, double class is the best way I have developed to perform exact operation on numbers; however, for irdoubles, normal operations on float and doubles have to be performed, with the well-known risks of error this implies. This class also provides a way of representing matrix as arrays of String for output use.

Please note that although in most books matrix elements' indexes take values between [1..n] I chose not to disturb Java language way of calling indexes; so the indexes used here take values between [0..n-1] instead.

Version:
1.0
Author:
Jean-Sebastien Senecal
Source code:
main
Created on:
1999-05-20
  • Constructor Summary

    Constructors
    Constructor
    Description
    GIMatrix(double[][] array)
    Class constructor.
    GIMatrix(int[][] array)
    Class constructor.
    GIMatrix(int line, int col)
    Class constructor.
    Class constructor.
    GIMatrix(GIMatrix[][] table)
    Class constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    Addition from two matrices.
    addLine(int i, int j, double c)
    Returns the resulting matrix of an elementary linear operation that consists of adding one line, multiplied by some constant factor, to another line.
    double
    Returns the determinant of this matrix.
    Returns a matrix containing all of the diagonal elements of this matrix and zero (0) everywhere else.
    boolean
    Verifies if two given matrix are equal or not.
    Gauss-Jordan algorithm.
    double[][]
    Returns the internal representation of the matrix, that is an array of double objects.
    getColumn(int j)
    Returns the column-matrix at the given line index.
    getLine(int i)
    Returns the line-matrix at the given line index.
    double
    getValueAt(int i, int j)
    Returns the value of the given element.
    int
     
    int
    Returns the number of lines of the matrix.
    static GIMatrix
    identity(int n)
    Returns the identity matrix.
    Returns the transpose of this matrix.
    invertLine(int i, int j)
    Returns the resulting matrix of an elementary linear operation that consists of inverting two lines.
    boolean
    Verifies if the matrix is antisymmetric, that is if the matrix is equal to the opposite of it's transpose.
    boolean
    Verifies whether or not the matrix is diagonal.
    boolean
    Verifies if the matrix is invertible or not by asking for its determinant.
    boolean
    Verifies if the matrix is square, that is if it has an equal number of lines and columns.
    boolean
    Verifies if the matrix is symmetric, that is if the matrix is equal to it's transpose.
    boolean
    Verifies if the matrix is triangular inferior or not.
    boolean
    Verifies if the matrix is triangular superior or not.
    multiply(double c)
    Returns the result of the scalar multiplication of the matrix, that is the multiplication of every of its elements by a given number.
    Returns the result of the matrix multiplication of this matrix by another one.
    multiplyLine(int i, double c)
    Returns the resulting matrix of an elementary linear operation that consists of multiplying a single line of the matrix by a constant.
    void
    setArrayValue(double[][] array)
    Resets the value of the matrix to the given array of double numbers.
    void
    setColumn(int j, GIMatrix column)
    Sets the column of the matrix at the specified index to a new value.
    void
    setLine(int i, GIMatrix line)
    Sets the line of the matrix at the specified index to a new value.
    void
    setValueAt(int i, int j, double element)
    Sets the value of the element at the given index.
    double
    Returns the trace of this matrix, that is the sum of the elements of its diagonal.
    Returns the transpose of this matrix.
    int
    Returns the number of columns of the matrix.
    static GIMatrix
    zero(int m, int n)
    Returns a null matrix (with zeros everywhere) of given dimensions.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • GIMatrix

      public GIMatrix(int[][] array)
      Class constructor. Uses an array of integers to create a new Matrix object. Note that integers will be converted to double objects so mathematical operations may be properly performed and provide exact solutions. The given array should be properly instantiated as a matrix i.e. it must contain a fixed number of lines and columns, otherwise an exception will be thrown. Array must be at leat 1x1.
      Parameters:
      array - an array of integer (first index is the line, second is the column)
    • GIMatrix

      public GIMatrix(double[][] array) throws BadMatrixFormatException
      Class constructor. Uses an array of doubles to create a new Matrix object. The given array should be properly instantiated as a matrix i.e. it must contain a fixed number of lines and columns, otherwise an exception will be thrown. Array must be at leat 1x1.
      Parameters:
      array - an array of double objects (first index is the line, second is the column)
      Throws:
      BadMatrixFormatException - in case the given array is unproper to construct a matrix
    • GIMatrix

      public GIMatrix(int line, int col)
      Class constructor. Creates a new Matrix object with fixed dimensions. The matrix is initialised to the "zero" matrix.
      Parameters:
      line - number of lines
      col - number of columns
    • GIMatrix

      public GIMatrix(GIMatrix matrix)
      Class constructor. Copies an already existing Matrix object in a new Matrix object.
      Parameters:
      matrix - a Matrix object
    • GIMatrix

      public GIMatrix(GIMatrix[][] table) throws BadMatrixFormatException
      Class constructor. Creates a new Matrix object using a table of matrices (an array of Matrix objects). The given array should be properly instantiated i.e. it must contain a fixed number of lines and columns, otherwise an exception will be thrown.
      Parameters:
      table - an array of matrices
      Throws:
      BadMatrixFormatException - if the table is not properly instantiated
  • Method Details

    • height

      public int height()
      Returns the number of lines of the matrix.
      Returns:
      the height of the matrix
    • width

      public int width()
      Returns the number of columns of the matrix.
      Returns:
      the width of the matrix
    • getArrayValue

      public double[][] getArrayValue()
      Returns the internal representation of the matrix, that is an array of double objects.
      Returns:
      an array of double equivalent to the matrix
    • setArrayValue

      public void setArrayValue(double[][] array) throws BadMatrixFormatException
      Resets the value of the matrix to the given array of double numbers.
      Parameters:
      array - an array of double objects (first index is the line, second is the column)
      Throws:
      BadMatrixFormatException - in case the given array is unproper to construct a matrix
    • getValueAt

      public double getValueAt(int i, int j) throws IndexOutOfBoundsException
      Returns the value of the given element.
      Parameters:
      i - the line number
      j - the column number
      Returns:
      the double at the given index in the Matrix
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
    • setValueAt

      public void setValueAt(int i, int j, double element) throws IndexOutOfBoundsException
      Sets the value of the element at the given index.
      Parameters:
      i - the line number
      j - the column number
      element - the double to place at the given index in the Matrix
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
    • getLine

      public GIMatrix getLine(int i) throws IndexOutOfBoundsException
      Returns the line-matrix at the given line index.
      Parameters:
      i - the line number
      Returns:
      the specified line as a Matrix object
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
    • getColumn

      public GIMatrix getColumn(int j) throws IndexOutOfBoundsException
      Returns the column-matrix at the given line index.
      Parameters:
      j - the column number
      Returns:
      the specified column as a Matrix object
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
    • setLine

      public void setLine(int i, GIMatrix line) throws IndexOutOfBoundsException, BadMatrixFormatException
      Sets the line of the matrix at the specified index to a new value.
      Parameters:
      i - the line number
      line - the line to be placed at the specified index
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
      BadMatrixFormatException - in case the given Matrix is unproper to replace a line of this Matrix
    • setColumn

      public void setColumn(int j, GIMatrix column) throws IndexOutOfBoundsException, BadMatrixFormatException
      Sets the column of the matrix at the specified index to a new value.
      Parameters:
      j - the column number
      column - the column to be placed at the specified index
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
      BadMatrixFormatException - in case the given Matrix is unproper to replace a column of this Matrix
    • identity

      public static GIMatrix identity(int n)
      Returns the identity matrix.
      Parameters:
      n - the matrix's dimension (identity matrix is a square matrix)
      Returns:
      the identity matrix of format nxn
    • zero

      public static GIMatrix zero(int m, int n)
      Returns a null matrix (with zeros everywhere) of given dimensions.
      Parameters:
      m - number of lines
      n - number of columns
      Returns:
      the zero (null) matrix of format mxn
    • equals

      public boolean equals(Object obj)
      Verifies if two given matrix are equal or not. The matrix must be of the same size and dimensions, otherwise an exception will be thrown.
      Overrides:
      equals in class Object
      Parameters:
      obj - the Matrix object to be compared to
      Returns:
      true if both matrix are equal element to element
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • isSquare

      public boolean isSquare()
      Verifies if the matrix is square, that is if it has an equal number of lines and columns.
      Returns:
      true if this matrix is square
    • isSymmetric

      public boolean isSymmetric() throws BadMatrixFormatException
      Verifies if the matrix is symmetric, that is if the matrix is equal to it's transpose.
      Returns:
      true if the matrix is symmetric
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • isAntisymmetric

      public boolean isAntisymmetric() throws BadMatrixFormatException
      Verifies if the matrix is antisymmetric, that is if the matrix is equal to the opposite of it's transpose.
      Returns:
      true if the matrix is antisymmetric
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • isTriangularSuperior

      public boolean isTriangularSuperior() throws BadMatrixFormatException
      Verifies if the matrix is triangular superior or not. A triangular superior matrix has zero (0) values everywhere under it's diagonal.
      Returns:
      true if the matrix is triangular superior
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • isTriangularInferior

      public boolean isTriangularInferior() throws BadMatrixFormatException
      Verifies if the matrix is triangular inferior or not. A triangular inferior matrix has zero (0) values everywhere upper it's diagonal.
      Returns:
      true if the matrix is triangular inferior
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • isDiagonal

      public boolean isDiagonal() throws BadMatrixFormatException
      Verifies whether or not the matrix is diagonal. A diagonal matrix only has elements on its diagonal and zeros (0) at every other index. The matrix must be square.
      Returns:
      true if the matrix is diagonal
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • isInvertible

      public boolean isInvertible() throws BadMatrixFormatException
      Verifies if the matrix is invertible or not by asking for its determinant.
      Returns:
      true if the matrix is invertible
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • inverse

      public GIMatrix inverse() throws MatrixNotInvertibleException
      Returns the transpose of this matrix. The transpose of a matrix A = {a(i,j)} is the matrix B = {b(i,j)} such that b(i,j) = a(j,i) for every i,j i.e. it is the symmetrical reflection of the matrix along its diagonal. The matrix must be square to use this method, otherwise an exception will be thrown.
      Returns:
      the matrix's transpose as a Matrix object
      Throws:
      MatrixNotInvertibleException - if the matrix is not square
    • GaussJordan

      public GIMatrix GaussJordan()
      Gauss-Jordan algorithm. Returns the reduced-echeloned matrix of this matrix. The algorithm has not yet been optimised but since it is quite simple, it should not be a serious problem.
      Returns:
      the reduced matrix
    • transpose

      public GIMatrix transpose() throws BadMatrixFormatException
      Returns the transpose of this matrix. The transpose of a matrix A = {a(i,j)} is the matrix B = {b(i,j)} such that b(i,j) = a(j,i) for every i,j i.e. it is the symmetrical reflection of the matrix along its diagonal. The matrix must be square to use this method, otherwise an exception will be thrown.
      Returns:
      the matrix's transpose as a Matrix object
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • diagonal

      public GIMatrix diagonal() throws BadMatrixFormatException
      Returns a matrix containing all of the diagonal elements of this matrix and zero (0) everywhere else. This matrix is called the diagonal of the matrix.
      Returns:
      the diagonal of the matrix
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • multiplyLine

      public GIMatrix multiplyLine(int i, double c) throws IndexOutOfBoundsException
      Returns the resulting matrix of an elementary linear operation that consists of multiplying a single line of the matrix by a constant.
      Parameters:
      i - the line number
      c - the double constant that multiplies the line
      Returns:
      the resulting Matrix object of the linear operation
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
    • invertLine

      public GIMatrix invertLine(int i, int j) throws IndexOutOfBoundsException
      Returns the resulting matrix of an elementary linear operation that consists of inverting two lines.
      Parameters:
      i - the first line number
      j - the second line number
      Returns:
      the resulting Matrix object of the linear operation
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
    • addLine

      public GIMatrix addLine(int i, int j, double c) throws IndexOutOfBoundsException
      Returns the resulting matrix of an elementary linear operation that consists of adding one line, multiplied by some constant factor, to another line.
      Parameters:
      i - the first line number
      j - the second line number (to be added to the first)
      c - the double constant that multiplies the first line
      Returns:
      the resulting Matrix object of the linear operation
      Throws:
      IndexOutOfBoundsException - if the given index is out of the matrix's range
    • add

      public GIMatrix add(GIMatrix b)
      Addition from two matrices.
    • multiply

      public GIMatrix multiply(double c)
      Returns the result of the scalar multiplication of the matrix, that is the multiplication of every of its elements by a given number.
      Parameters:
      c - the constant by which the matrix is multiplied
      Returns:
      the resulting matrix of the scalar multiplication
    • multiply

      public GIMatrix multiply(GIMatrix matrix) throws BadMatrixFormatException
      Returns the result of the matrix multiplication of this matrix by another one. The matrix passed as parameter follows this matrix in the multiplication, so for an example if the dimension of the actual matrix is mxn, the dimension of the second one should be nxp in order for the multiplication to be performed (otherwise an exception will be thrown) and the resulting matrix will have dimension mxp.
      Parameters:
      matrix - the matrix following this one in the matrix multiplication
      Returns:
      the resulting matrix of the matrix multiplication
      Throws:
      BadMatrixFormatException - if the matrix passed in arguments has wrong dimensions
    • determinant

      public double determinant() throws BadMatrixFormatException
      Returns the determinant of this matrix. The matrix must be square in order to use this method, otherwise an exception will be thrown. Warning: this algorithm is very inefficient and takes too much time to compute with large matrices.
      Returns:
      the determinant of the matrix
      Throws:
      BadMatrixFormatException - if the matrix is not square
    • trace

      public double trace() throws BadMatrixFormatException
      Returns the trace of this matrix, that is the sum of the elements of its diagonal. The matrix must be square in order to use this method, otherwise an exception will be thrown.
      Returns:
      the trace of the matrix
      Throws:
      BadMatrixFormatException - if the matrix is not square