cern.colt.matrix.linalg

## Class Property

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

- All Implemented Interfaces:
    java.io.Serializable, java.lang.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:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `java.lang.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:
        `java.lang.IllegalArgumentException` - if `A.rows() < A.columns()`.

    - #### checkSquare

          public void checkSquare(DoubleMatrix2D A)

      Checks whether the given matrix `A` is square.
      Throws:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.IllegalArgumentException` - if `!isSquare(A)`.
      See Also:
        `lowerBandwidth(DoubleMatrix2D)`, `upperBandwidth(DoubleMatrix2D)`

    - #### setTolerance

          public void setTolerance(double newTolerance)

      Sets the tolerance to `Math.abs(newTolerance)`.
      Throws:
        `java.lang.UnsupportedOperationException` - if `this==DEFAULT || this==ZERO || this==TWELVE`.

    - #### tolerance

          public double tolerance()

      Returns the current tolerance.

    - #### toString

          public java.lang.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:
        `java.lang.IllegalArgumentException` - if `!isSquare(A)`.
      See Also:
        `semiBandwidth(DoubleMatrix2D)`, `lowerBandwidth(DoubleMatrix2D)`

Jump to the Colt Homepage