Class Property

java.lang.Object
cern.colt.PersistentObject
cern.colt.matrix.linalg.Property
All Implemented Interfaces:
Serializable, Cloneable

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:
  • Field Details

    • 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.
    • tolerance

      protected double tolerance
  • Constructor Details

    • Property

      private Property()
      Not instantiable by no-arg constructor.
    • Property

      public Property(double newTolerance)
      Constructs an instance with a tolerance of Math.abs(newTolerance).
  • Method Details

    • blanks

      protected static String blanks(int length)
      Returns a String with length blanks.
    • checkRectangular

      public void checkRectangular(DoubleMatrix2D A)
      Checks whether the given matrix A is rectangular.
      Throws:
      IllegalArgumentException - if A.rows() invalid input: '<' 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).
    • get

      protected static String get(ObjectArrayList list, int index)
    • 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

      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:
    • 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: