Colt 1.2.0

## cern.colt.matrix.linalg
Class Property

    java.lang.Object
      cern.colt.PersistentObject
          cern.colt.matrix.linalg.Property

All Implemented Interfaces:
  Cloneable, Serializable

public class Property
extends PersistentObject

Tests matrices for linear algebraic properties (equality, tridiagonality, symmetry, singularity, etc).

Except where explicitly indicated, all methods involving equality tests (`==`) allow for numerical instability, to a degree specified upon instance construction and returned by method `tolerance()`. The public static final variable `DEFAULT` represents a default Property object with a tolerance of `1.0E-9`. The public static final variable `ZERO` represents a Property object with a tolerance of `0.0`. The public static final variable `TWELVE` represents a Property object with a tolerance of `1.0E-12`. As long as you are happy with these tolerances, there is no need to construct Property objects. Simply use idioms like `Property.DEFAULT.equals(A,B)`, `Property.ZERO.equals(A,B)`, `Property.TWELVE.equals(A,B)`.

To work with a different tolerance (e.g. `1.0E-15` or `1.0E-5`) use the constructor and/or method `setTolerance(double)`. Note that the public static final Property objects are immutable: Is is not possible to alter their tolerance. Any attempt to do so will throw an Exception.

Note that this implementation is not synchronized.

Example: `equals(DoubleMatrix2D A, DoubleMatrix2D B)` is defined as follows

    { some other tests not related to tolerance go here }
    double epsilon = tolerance();
    for (int row=rows; --row >= 0;) {
       for (int column=columns; --column >= 0;) {
          //if (!(A.getQuick(row,column) == B.getQuick(row,column))) return false;
          if (Math.abs(A.getQuick(row,column) - B.getQuick(row,column)) > epsilon) return false;
       }
    }
    return true;

Here are some example properties

`matrix` | `4 x 4 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0` | `4 x 4 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1` | `4 x 4 1 1 0 0 1 1 1 0 0 1 1 1 0 0 1 1` | `4 x 4 0 1 1 1 0 1 1 1 0 0 0 1 0 0 0 1` | `4 x 4 0 0 0 0 1 1 0 0 1 1 0 0 1 1 1 1` | `4 x 4 1 1 0 0 0 1 1 0 0 1 0 1 1 0 1 1` `` | `4 x 4 1 1 1 0 0 1 0 0 1 1 0 1 0 0 1 1`
`upperBandwidth` | `0` | `0` | `1` | `3` | `0` | `1` | `2`
`lowerBandwidth` | `0` | `0` | `1` | `0` | `3` | `3` | `2`
`semiBandwidth` | `1` | `1` | `2` | `4` | `4` | `4` | `3`
`description` | `zero` | `diagonal` | `tridiagonal` | `upper triangular` | `lower triangular` | `unstructured` | `unstructured`

Version:
  1.1, 28/May/2000 (fixed strange bugs involving NaN, -inf, inf)
See Also:
  Serialized Form

Field Summary
`static Property` | `DEFAULT` The default Property object; currently has `tolerance()==1.0E-9`.
`static Property` | `TWELVE` A Property object with `tolerance()==1.0E-12`.
`static Property` | `ZERO` A Property object with `tolerance()==0.0`.

Fields inherited from class cern.colt.PersistentObject
`serialVersionUID`

Constructor Summary
`Property(double newTolerance)` Constructs an instance with a tolerance of `Math.abs(newTolerance)`.

Method Summary
`void` | `checkRectangular(DoubleMatrix2D A)` Checks whether the given matrix `A` is rectangular.
`void` | `checkSquare(DoubleMatrix2D A)` Checks whether the given matrix `A` is square.
`double` | `density(DoubleMatrix2D A)` Returns the matrix's fraction of non-zero cells; `A.cardinality() / A.size()`.
`boolean` | `equals(DoubleMatrix1D A, double value)` Returns whether all cells of the given matrix `A` are equal to the given value.
`boolean` | `equals(DoubleMatrix1D A, DoubleMatrix1D B)` Returns whether both given matrices `A` and `B` are equal.
`boolean` | `equals(DoubleMatrix2D A, double value)` Returns whether all cells of the given matrix `A` are equal to the given value.
`boolean` | `equals(DoubleMatrix2D A, DoubleMatrix2D B)` Returns whether both given matrices `A` and `B` are equal.
`boolean` | `equals(DoubleMatrix3D A, double value)` Returns whether all cells of the given matrix `A` are equal to the given value.
`boolean` | `equals(DoubleMatrix3D A, DoubleMatrix3D B)` Returns whether both given matrices `A` and `B` are equal.
`void` | `generateNonSingular(DoubleMatrix2D A)` Modifies the given matrix square matrix `A` such that it is diagonally dominant by row and column, hence non-singular, hence invertible.
`boolean` | `isDiagonal(DoubleMatrix2D A)` A matrix `A` is diagonal if `A[i,j] == 0` whenever `i != j`.
`boolean` | `isDiagonallyDominantByColumn(DoubleMatrix2D A)` A matrix `A` is diagonally dominant by column if the absolute value of each diagonal element is larger than the sum of the absolute values of the off-diagonal elements in the corresponding column.
`boolean` | `isDiagonallyDominantByRow(DoubleMatrix2D A)` A matrix `A` is diagonally dominant by row if the absolute value of each diagonal element is larger than the sum of the absolute values of the off-diagonal elements in the corresponding row.
`boolean` | `isIdentity(DoubleMatrix2D A)` A matrix `A` is an identity matrix if `A[i,i] == 1` and all other cells are zero.
`boolean` | `isLowerBidiagonal(DoubleMatrix2D A)` A matrix `A` is lower bidiagonal if `A[i,j]==0` unless `i==j || i==j+1`.
`boolean` | `isLowerTriangular(DoubleMatrix2D A)` A matrix `A` is lower triangular if `A[i,j]==0` whenever `i < j`.
`boolean` | `isNonNegative(DoubleMatrix2D A)` A matrix `A` is non-negative if `A[i,j] >= 0` holds for all cells.
`boolean` | `isOrthogonal(DoubleMatrix2D A)` A square matrix `A` is orthogonal if `A*transpose(A) = I`.
`boolean` | `isPositive(DoubleMatrix2D A)` A matrix `A` is positive if `A[i,j] > 0` holds for all cells.
`boolean` | `isSingular(DoubleMatrix2D A)` A matrix `A` is singular if it has no inverse, that is, iff `det(A)==0`.
`boolean` | `isSkewSymmetric(DoubleMatrix2D A)` A square matrix `A` is skew-symmetric if `A = -transpose(A)`, that is `A[i,j] == -A[j,i]`.
`boolean` | `isSquare(DoubleMatrix2D A)` A matrix `A` is square if it has the same number of rows and columns.
`boolean` | `isStrictlyLowerTriangular(DoubleMatrix2D A)` A matrix `A` is strictly lower triangular if `A[i,j]==0` whenever `i <= j`.
`boolean` | `isStrictlyTriangular(DoubleMatrix2D A)` A matrix `A` is strictly triangular if it is triangular and its diagonal elements all equal 0.
`boolean` | `isStrictlyUpperTriangular(DoubleMatrix2D A)` A matrix `A` is strictly upper triangular if `A[i,j]==0` whenever `i >= j`.
`boolean` | `isSymmetric(DoubleMatrix2D A)` A matrix `A` is symmetric if `A = tranpose(A)`, that is `A[i,j] == A[j,i]`.
`boolean` | `isTriangular(DoubleMatrix2D A)` A matrix `A` is triangular iff it is either upper or lower triangular.
`boolean` | `isTridiagonal(DoubleMatrix2D A)` A matrix `A` is tridiagonal if `A[i,j]==0` whenever `Math.abs(i-j) > 1`.
`boolean` | `isUnitTriangular(DoubleMatrix2D A)` A matrix `A` is unit triangular if it is triangular and its diagonal elements all equal 1.
`boolean` | `isUpperBidiagonal(DoubleMatrix2D A)` A matrix `A` is upper bidiagonal if `A[i,j]==0` unless `i==j || i==j-1`.
`boolean` | `isUpperTriangular(DoubleMatrix2D A)` A matrix `A` is upper triangular if `A[i,j]==0` whenever `i > j`.
`boolean` | `isZero(DoubleMatrix2D A)` A matrix `A` is zero if all its cells are zero.
`int` | `lowerBandwidth(DoubleMatrix2D A)` The lower bandwidth of a square matrix `A` is the maximum `i-j` for which `A[i,j]` is nonzero and `i > j`.
`int` | `semiBandwidth(DoubleMatrix2D A)` Returns the semi-bandwidth of the given square matrix `A`.
`void` | `setTolerance(double newTolerance)` Sets the tolerance to `Math.abs(newTolerance)`.
`double` | `tolerance()` Returns the current tolerance.
`String` | `toString(DoubleMatrix2D A)` Returns summary information about the given matrix `A`.
`int` | `upperBandwidth(DoubleMatrix2D A)` The upper bandwidth of a square matrix `A` is the maximum `j-i` for which `A[i,j]` is nonzero and `j > i`.

Methods inherited from class cern.colt.PersistentObject
`clone`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT

    public static final Property DEFAULT

  The default Property object; currently has `tolerance()==1.0E-9`.

### ZERO

    public static final Property ZERO

  A Property object with `tolerance()==0.0`.

### TWELVE

    public static final Property TWELVE

  A Property object with `tolerance()==1.0E-12`.

Constructor Detail

### Property

    public Property(double newTolerance)

  Constructs an instance with a tolerance of `Math.abs(newTolerance)`.

Method Detail

### checkRectangular

    public void checkRectangular(DoubleMatrix2D A)

  Checks whether the given matrix `A` is rectangular.

  Throws:
    `IllegalArgumentException` - if `A.rows() < A.columns()`.

### checkSquare

    public void checkSquare(DoubleMatrix2D A)

  Checks whether the given matrix `A` is square.

  Throws:
    `IllegalArgumentException` - if `A.rows() != A.columns()`.

### density

    public double density(DoubleMatrix2D A)

  Returns the matrix's fraction of non-zero cells; `A.cardinality() / A.size()`.

### equals

    public boolean equals(DoubleMatrix1D A,
                          double value)

  Returns whether all cells of the given matrix `A` are equal to the given value. The result is `true` if and only if `A != null` and `! (Math.abs(value - A[i]) > tolerance())` holds for all coordinates.

  Parameters:
    `A` - the first matrix to compare.
    `value` - the value to compare against.
  Returns:
    `true` if the matrix is equal to the value; `false` otherwise.

### equals

    public boolean equals(DoubleMatrix1D A,
                          DoubleMatrix1D B)

  Returns whether both given matrices `A` and `B` are equal. The result is `true` if `A==B`. Otherwise, the result is `true` if and only if both arguments are `!= null`, have the same size and `! (Math.abs(A[i] - B[i]) > tolerance())` holds for all indexes.

  Parameters:
    `A` - the first matrix to compare.
    `B` - the second matrix to compare.
  Returns:
    `true` if both matrices are equal; `false` otherwise.

### equals

    public boolean equals(DoubleMatrix2D A,
                          double value)

  Returns whether all cells of the given matrix `A` are equal to the given value. The result is `true` if and only if `A != null` and `! (Math.abs(value - A[row,col]) > tolerance())` holds for all coordinates.

  Parameters:
    `A` - the first matrix to compare.
    `value` - the value to compare against.
  Returns:
    `true` if the matrix is equal to the value; `false` otherwise.

### equals

    public boolean equals(DoubleMatrix2D A,
                          DoubleMatrix2D B)

  Returns whether both given matrices `A` and `B` are equal. The result is `true` if `A==B`. Otherwise, the result is `true` if and only if both arguments are `!= null`, have the same number of columns and rows and `! (Math.abs(A[row,col] - B[row,col]) > tolerance())` holds for all coordinates.

  Parameters:
    `A` - the first matrix to compare.
    `B` - the second matrix to compare.
  Returns:
    `true` if both matrices are equal; `false` otherwise.

### equals

    public boolean equals(DoubleMatrix3D A,
                          double value)

  Returns whether all cells of the given matrix `A` are equal to the given value. The result is `true` if and only if `A != null` and `! (Math.abs(value - A[slice,row,col]) > tolerance())` holds for all coordinates.

  Parameters:
    `A` - the first matrix to compare.
    `value` - the value to compare against.
  Returns:
    `true` if the matrix is equal to the value; `false` otherwise.

### equals

    public boolean equals(DoubleMatrix3D A,
                          DoubleMatrix3D B)

  Returns whether both given matrices `A` and `B` are equal. The result is `true` if `A==B`. Otherwise, the result is `true` if and only if both arguments are `!= null`, have the same number of columns, rows and slices, and `! (Math.abs(A[slice,row,col] - B[slice,row,col]) > tolerance())` holds for all coordinates.

  Parameters:
    `A` - the first matrix to compare.
    `B` - the second matrix to compare.
  Returns:
    `true` if both matrices are equal; `false` otherwise.

### generateNonSingular

    public void generateNonSingular(DoubleMatrix2D A)

  Modifies the given matrix square matrix `A` such that it is diagonally dominant by row and column, hence non-singular, hence invertible. For testing purposes only.

  Parameters:
    `A` - the square matrix to modify.
  Throws:
    `IllegalArgumentException` - if `!isSquare(A)`.

### isDiagonal

    public boolean isDiagonal(DoubleMatrix2D A)

  A matrix `A` is diagonal if `A[i,j] == 0` whenever `i != j`. Matrix may but need not be square.

### isDiagonallyDominantByColumn

    public boolean isDiagonallyDominantByColumn(DoubleMatrix2D A)

  A matrix `A` is diagonally dominant by column if the absolute value of each diagonal element is larger than the sum of the absolute values of the off-diagonal elements in the corresponding column. `returns true if for all i: abs(A[i,i]) > Sum(abs(A[j,i])); j != i.` Matrix may but need not be square.

  Note: Ignores tolerance.

### isDiagonallyDominantByRow

    public boolean isDiagonallyDominantByRow(DoubleMatrix2D A)

  A matrix `A` is diagonally dominant by row if the absolute value of each diagonal element is larger than the sum of the absolute values of the off-diagonal elements in the corresponding row. `returns true if for all i: abs(A[i,i]) > Sum(abs(A[i,j])); j != i.` Matrix may but need not be square.

  Note: Ignores tolerance.

### isIdentity

    public boolean isIdentity(DoubleMatrix2D A)

  A matrix `A` is an identity matrix if `A[i,i] == 1` and all other cells are zero. Matrix may but need not be square.

### isLowerBidiagonal

    public boolean isLowerBidiagonal(DoubleMatrix2D A)

  A matrix `A` is lower bidiagonal if `A[i,j]==0` unless `i==j || i==j+1`. Matrix may but need not be square.

### isLowerTriangular

    public boolean isLowerTriangular(DoubleMatrix2D A)

  A matrix `A` is lower triangular if `A[i,j]==0` whenever `i < j`. Matrix may but need not be square.

### isNonNegative

    public boolean isNonNegative(DoubleMatrix2D A)

  A matrix `A` is non-negative if `A[i,j] >= 0` holds for all cells.

  Note: Ignores tolerance.

### isOrthogonal

    public boolean isOrthogonal(DoubleMatrix2D A)

  A square matrix `A` is orthogonal if `A*transpose(A) = I`.

  Throws:
    `IllegalArgumentException` - if `!isSquare(A)`.

### isPositive

    public boolean isPositive(DoubleMatrix2D A)

  A matrix `A` is positive if `A[i,j] > 0` holds for all cells.

  Note: Ignores tolerance.

### isSingular

    public boolean isSingular(DoubleMatrix2D A)

  A matrix `A` is singular if it has no inverse, that is, iff `det(A)==0`.

### isSkewSymmetric

    public boolean isSkewSymmetric(DoubleMatrix2D A)

  A square matrix `A` is skew-symmetric if `A = -transpose(A)`, that is `A[i,j] == -A[j,i]`.

  Throws:
    `IllegalArgumentException` - if `!isSquare(A)`.

### isSquare

    public boolean isSquare(DoubleMatrix2D A)

  A matrix `A` is square if it has the same number of rows and columns.

### isStrictlyLowerTriangular

    public boolean isStrictlyLowerTriangular(DoubleMatrix2D A)

  A matrix `A` is strictly lower triangular if `A[i,j]==0` whenever `i <= j`. Matrix may but need not be square.

### isStrictlyTriangular

    public boolean isStrictlyTriangular(DoubleMatrix2D A)

  A matrix `A` is strictly triangular if it is triangular and its diagonal elements all equal 0. Matrix may but need not be square.

### isStrictlyUpperTriangular

    public boolean isStrictlyUpperTriangular(DoubleMatrix2D A)

  A matrix `A` is strictly upper triangular if `A[i,j]==0` whenever `i >= j`. Matrix may but need not be square.

### isSymmetric

    public boolean isSymmetric(DoubleMatrix2D A)

  A matrix `A` is symmetric if `A = tranpose(A)`, that is `A[i,j] == A[j,i]`.

  Throws:
    `IllegalArgumentException` - if `!isSquare(A)`.

### isTriangular

    public boolean isTriangular(DoubleMatrix2D A)

  A matrix `A` is triangular iff it is either upper or lower triangular. Matrix may but need not be square.

### isTridiagonal

    public boolean isTridiagonal(DoubleMatrix2D A)

  A matrix `A` is tridiagonal if `A[i,j]==0` whenever `Math.abs(i-j) > 1`. Matrix may but need not be square.

### isUnitTriangular

    public boolean isUnitTriangular(DoubleMatrix2D A)

  A matrix `A` is unit triangular if it is triangular and its diagonal elements all equal 1. Matrix may but need not be square.

### isUpperBidiagonal

    public boolean isUpperBidiagonal(DoubleMatrix2D A)

  A matrix `A` is upper bidiagonal if `A[i,j]==0` unless `i==j || i==j-1`. Matrix may but need not be square.

### isUpperTriangular

    public boolean isUpperTriangular(DoubleMatrix2D A)

  A matrix `A` is upper triangular if `A[i,j]==0` whenever `i > j`. Matrix may but need not be square.

### isZero

    public boolean isZero(DoubleMatrix2D A)

  A matrix `A` is zero if all its cells are zero.

### lowerBandwidth

    public int lowerBandwidth(DoubleMatrix2D A)

  The lower bandwidth of a square matrix `A` is the maximum `i-j` for which `A[i,j]` is nonzero and `i > j`. A banded matrix has a "band" about the diagonal. Diagonal, tridiagonal and triangular matrices are special cases.

  Parameters:
    `A` - the square matrix to analyze.
  Returns:
    the lower bandwith.
  Throws:
    `IllegalArgumentException` - if `!isSquare(A)`.
  See Also:
    `semiBandwidth(DoubleMatrix2D)`, `upperBandwidth(DoubleMatrix2D)`

### semiBandwidth

    public int semiBandwidth(DoubleMatrix2D A)

  Returns the semi-bandwidth of the given square matrix `A`. A banded matrix has a "band" about the diagonal. It is a matrix with all cells equal to zero, with the possible exception of the cells along the diagonal line, the `k` diagonal lines above the diagonal, and the `k` diagonal lines below the diagonal. The semi-bandwith l is the number `k+1`. The bandwidth p is the number `2*k + 1`. For example, a tridiagonal matrix corresponds to `k=1, l=2, p=3`, a diagonal or zero matrix corresponds to `k=0, l=1, p=1`,

  The upper bandwidth is the maximum `j-i` for which `A[i,j]` is nonzero and `j > i`. The lower bandwidth is the maximum `i-j` for which `A[i,j]` is nonzero and `i > j`. Diagonal, tridiagonal and triangular matrices are special cases.

  Examples:

  `matrix` | `4 x 4 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0` | `4 x 4 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1` | `4 x 4 1 1 0 0 1 1 1 0 0 1 1 1 0 0 1 1` | `4 x 4 0 1 1 1 0 1 1 1 0 0 0 1 0 0 0 1` | `4 x 4 0 0 0 0 1 1 0 0 1 1 0 0 1 1 1 1` | `4 x 4 1 1 0 0 0 1 1 0 0 1 0 1 1 0 1 1` `` | `4 x 4 1 1 1 0 0 1 0 0 1 1 0 1 0 0 1 1`
  `upperBandwidth` | `0` | `0` | `1` | `3` | `0` | `1` | `2`
  `lowerBandwidth` | `0` | `0` | `1` | `0` | `3` | `3` | `2`
  `semiBandwidth` | `1` | `1` | `2` | `4` | `4` | `4` | `3`
  `description` | `zero` | `diagonal` | `tridiagonal` | `upper triangular` | `lower triangular` | `unstructured` | `unstructured`

  Parameters:
    `A` - the square matrix to analyze.
  Returns:
    the semi-bandwith `l`.
  Throws:
    `IllegalArgumentException` - if `!isSquare(A)`.
  See Also:
    `lowerBandwidth(DoubleMatrix2D)`, `upperBandwidth(DoubleMatrix2D)`

### setTolerance

    public void setTolerance(double newTolerance)

  Sets the tolerance to `Math.abs(newTolerance)`.

  Throws:
    `UnsupportedOperationException` - if `this==DEFAULT || this==ZERO || this==TWELVE`.

### tolerance

    public double tolerance()

  Returns the current tolerance.

### toString

    public String toString(DoubleMatrix2D A)

  Returns summary information about the given matrix `A`. That is a String with (propertyName, propertyValue) pairs. Useful for debugging or to quickly get the rough picture of a matrix. For example,

      density                      : 0.9
      isDiagonal                   : false
      isDiagonallyDominantByRow    : false
      isDiagonallyDominantByColumn : false
      isIdentity                   : false
      isLowerBidiagonal            : false
      isLowerTriangular            : false
      isNonNegative                : true
      isOrthogonal                 : Illegal operation or error: Matrix must be square.
      isPositive                   : true
      isSingular                   : Illegal operation or error: Matrix must be square.
      isSkewSymmetric              : Illegal operation or error: Matrix must be square.
      isSquare                     : false
      isStrictlyLowerTriangular    : false
      isStrictlyTriangular         : false
      isStrictlyUpperTriangular    : false
      isSymmetric                  : Illegal operation or error: Matrix must be square.
      isTriangular                 : false
      isTridiagonal                : false
      isUnitTriangular             : false
      isUpperBidiagonal            : false
      isUpperTriangular            : false
      isZero                       : false
      lowerBandwidth               : Illegal operation or error: Matrix must be square.
      semiBandwidth                : Illegal operation or error: Matrix must be square.
      upperBandwidth               : Illegal operation or error: Matrix must be square.

### upperBandwidth

    public int upperBandwidth(DoubleMatrix2D A)

  The upper bandwidth of a square matrix `A` is the maximum `j-i` for which `A[i,j]` is nonzero and `j > i`. A banded matrix has a "band" about the diagonal. Diagonal, tridiagonal and triangular matrices are special cases.

  Parameters:
    `A` - the square matrix to analyze.
  Returns:
    the upper bandwith.
  Throws:
    `IllegalArgumentException` - if `!isSquare(A)`.
  See Also:
    `semiBandwidth(DoubleMatrix2D)`, `lowerBandwidth(DoubleMatrix2D)`

Colt 1.2.0

Jump to the Colt Homepage