ch.javasoft.smx.ops
Class Gauss

java.lang.Object
  ch.javasoft.smx.ops.Gauss

public class Gauss
extends Object

Matrix operations based on gauss, i.e. adding multiples of one row to another row to cancel values. This can be used to create the (reduced) row echelon form of a matrix, from which rank and nullspace can be derived. One could also compute matrix inverses using gauss.

This class currently supports double and rational matrices. Default instances for these cases are available at getDoubleInstance() and getRationalInstance().

Field Summary

double

mTolerance

Constructor Summary

Gauss(double tolerance)
Constructor for Gauss with tolerance, a usually positive number close to zero, indicating which values have to be treated as zero.

Method Summary

static Gauss	getDefaultInstance(Class<? extends Number> numberClass) Returns the default instance depending on the specified number type, which is: rational instance for one of BigFraction BigInteger Long Integer double instance for one of Double Float For other class arguments, an illegal argument exception is thrown.
static Gauss	getDoubleInstance() Returns the default instance for double computations, i.e.
static Gauss	getRationalInstance() Returns the default instance for rational computations, i.e.
BigIntegerRationalMatrix	invert(ReadableBigIntegerRationalMatrix mx) Computes the inverse of a square matrix.
DoubleMatrix	invert(ReadableDoubleMatrix mx) Computes the inverse of a square matrix.
BigIntegerRationalMatrix	invertMaximalSubmatrix(ReadableBigIntegerRationalMatrix mx, int[][] ptrRowmap, int[][] ptrColmap) Computes the inverse of a submatrix of a non-square or singular square matrix.
DoubleMatrix	invertMaximalSubmatrix(ReadableDoubleMatrix mx, int[][] ptrRowmap, int[][] ptrColmap) Computes the inverse of a submatrix of a non-square or singular square matrix.
int	nullity(ReadableBigIntegerRationalMatrix mx) Computes the dimension of the nullspace, that is, columns - rank
int	nullity(ReadableDoubleMatrix mx) Computes the dimension of the nullspace, that is, columns - rank
BigIntegerRationalMatrix	nullspace(ReadableBigIntegerRationalMatrix mx) Computes a basis for the nullspace using gauss with full pivoting.
DoubleMatrix	nullspace(ReadableDoubleMatrix mx) Computes a basis for the nullspace using gauss with full pivoting.
int	rank(ReadableBigIntegerRationalMatrix mx) Computes the rank of the given matrix
int	rank(ReadableDoubleMatrix mx) Computes the rank of the given matrix
int	reducedRowEchelon(DoubleMatrix mx) Reduced row echelon form using gauss with full pivoting.
int	rowEchelon(BigIntegerRationalMatrix mx, boolean reduced, int[] rowmap, int[] colmap) Row echelon form using gauss with full pivoting.
int	rowEchelon(DoubleMatrix mx) Row echelon form using gauss with full pivoting.
int	rowEchelon(DoubleMatrix mx, boolean reduced, int[] rowmap, int[] colmap) Row echelon form using gauss with full pivoting.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mTolerance

public final double mTolerance

Constructor Detail

Gauss

public Gauss(double tolerance)

Constructor for Gauss with tolerance, a usually positive number close to zero, indicating which values have to be treated as zero. For rational computations, zero is typically used.

Parameters:

tolerance - positive number close to zero, e.g. 1e-10

Method Detail

rank

public int rank(ReadableDoubleMatrix mx)

Computes the rank of the given matrix

Parameters:

mx - the matrix for which the rank should be computed

rank

public int rank(ReadableBigIntegerRationalMatrix mx)

Computes the rank of the given matrix

Parameters:

mx - the matrix for which the rank should be computed

nullity

public int nullity(ReadableDoubleMatrix mx)

Computes the dimension of the nullspace, that is, columns - rank

nullity

public int nullity(ReadableBigIntegerRationalMatrix mx)

Computes the dimension of the nullspace, that is, columns - rank

invert

public DoubleMatrix invert(ReadableDoubleMatrix mx)

Computes the inverse of a square matrix. If the matrix is not square, or if it is singular, an exception is thrown.

The method used is computing the reduced row-echelon form of the matrix [mx I], ending up in a matrix [I inv(mx)].

Throws:

IllegalArgumentException - if the matrix is not a square matrix

SingularMatrixException - if the matrix is singular

invertMaximalSubmatrix

public DoubleMatrix invertMaximalSubmatrix(ReadableDoubleMatrix mx,
                                           int[][] ptrRowmap,
                                           int[][] ptrColmap)

Computes the inverse of a submatrix of a non-square or singular square matrix. The submatrix row/column size is determined by the rank of the matrix. For instance, for a rectangular matrix A with m rows and n columns and n = rank(A) and m > n, a submatrix with n rows is chosen, such that the submatrix has full rank. The chosen columns and rows are returned in rowmap/colmap.

The method used is computing the reduced row-echelon form of the matrix [mx I], ending up in a matrix [I inv(mx)].

Parameters:

mx - the matrix from which submatrix of maximal rank is taken and inverted

ptrRowmap - a pointer to the row mapping (out parameter), if not null, ptrRowmap[0] will contain the row indices taken for the inverted submatrix.

ptrColmap - a pointer to the column mapping (out parameter), if not null, ptrColmap[0] will contain the column indices taken for the inverted submatrix.

Returns:

the inverted (sub)matrix, always square

invert

public BigIntegerRationalMatrix invert(ReadableBigIntegerRationalMatrix mx)

Computes the inverse of a square matrix. If the matrix is not square, or if it is singular, an exception is thrown.

The method used is computing the reduced row-echelon form of the matrix [mx I], ending up in a matrix [I inv(mx)].

Throws:

IllegalArgumentException - if the matrix is not a square matrix

SingularMatrixException - if the matrix is singular

invertMaximalSubmatrix

public BigIntegerRationalMatrix invertMaximalSubmatrix(ReadableBigIntegerRationalMatrix mx,
                                                       int[][] ptrRowmap,
                                                       int[][] ptrColmap)

Computes the inverse of a submatrix of a non-square or singular square matrix. The submatrix row/column size is determined by the rank of the matrix. For instance, for a rectangular matrix A with m rows and n columns and n = rank(A) and m > n, a submatrix with n rows is chosen, such that the submatrix has full rank. The chosen columns and rows are returned in rowmap/colmap.

The method used is computing the reduced row-echelon form of the matrix [mx I], ending up in a matrix [I inv(mx)].

Parameters:

mx - the matrix from which submatrix of maximal rank is taken and inverted

ptrRowmap - a pointer to the row mapping (out parameter), if not null, ptrRowmap[0] will contain the row indices taken for the inverted submatrix.

ptrColmap - a pointer to the column mapping (out parameter), if not null, ptrColmap[0] will contain the column indices taken for the inverted submatrix.

Returns:

the inverted (sub)matrix, always square

nullspace

public DoubleMatrix nullspace(ReadableDoubleMatrix mx)

Computes a basis for the nullspace using gauss with full pivoting. The reduced row echelon matrix which is computed from the input has the structure [ I, M ; 0 ], thus the nullspace is simply [ -M ; I ].

Parameters:

mx - the input matrix

Returns:

the kernel, a basis for the nullspace

nullspace

public BigIntegerRationalMatrix nullspace(ReadableBigIntegerRationalMatrix mx)

Computes a basis for the nullspace using gauss with full pivoting. The reduced row echelon matrix which is computed from the input has the structure [ I, M ; 0 ], thus the nullspace is simply [ -M ; I ].

Parameters:

mx - the input matrix

Returns:

the kernel, a basis for the nullspace

rowEchelon

public int rowEchelon(DoubleMatrix mx)

Row echelon form using gauss with full pivoting. Note that columns and rows might be swapped due to the full pivoting.

Parameters:

mx - the matrix to reduce

Returns:

the rank of the matrix

reducedRowEchelon

public int reducedRowEchelon(DoubleMatrix mx)

Reduced row echelon form using gauss with full pivoting. Note that columns and rows might be swapped due to the full pivoting.

Parameters:

mx - the matrix to reduce

Returns:

the rank of the matrix

rowEchelon

public int rowEchelon(DoubleMatrix mx,
                      boolean reduced,
                      int[] rowmap,
                      int[] colmap)

Row echelon form using gauss with full pivoting. Note that columns and rows might be swapped due to the full pivoting, returned in rowmap and colmap if they are not null.

Parameters:

mx - the matrix to reduce

reduced - if true, the reduced row echelon form is returned, that is, zeros above the diagonal, too

rowmap - the row mapping to reestablish the original row ordering. the mapping is only used as out parameter, but its length determines how many rows to use as pivot rows

colmap - the column mapping to reestablish the original column ordering. the mapping is only used as out parameter, but its length determines how many columns to use as pivot columns

Returns:

the rank of the matrix

rowEchelon

public int rowEchelon(BigIntegerRationalMatrix mx,
                      boolean reduced,
                      int[] rowmap,
                      int[] colmap)

Row echelon form using gauss with full pivoting. Note that columns and rows might be swapped due to the full pivoting, returned in rowmap and colmap if they are not null.

Parameters:

mx - the matrix to reduce

reduced - if true, the reduced row echelon form is returned, that is, zeros above the diagonal, too

rowmap - the row mapping to reestablish the original row ordering. the mapping is only used as out parameter, but its length determines how many rows to use as pivot rows

colmap - the column mapping to reestablish the original column ordering. the mapping is only used as out parameter, but its length determines how many columns to use as pivot columns

Returns:

the rank of the matrix

getDoubleInstance

public static Gauss getDoubleInstance()

Returns the default instance for double computations, i.e. using tolerance 10e-10.

getRationalInstance

public static Gauss getRationalInstance()

Returns the default instance for rational computations, i.e. using zero tolerance.

getDefaultInstance

public static Gauss getDefaultInstance(Class<? extends Number> numberClass)

Returns the default instance depending on the specified number type, which is:

• rational instance for one of
  • BigFraction
  • BigInteger
  • Long
  • Integer
• double instance for one of
  • Double
  • Float

For other class arguments, an illegal argument exception is thrown.