DoubleProperty (Parallel Colt 0.10.1

java.lang.Object
- cern.colt.PersistentObject
- - cern.colt.matrix.tdouble.algo.DoubleProperty

All Implemented Interfaces:: Serializable, Cloneable

public class DoubleProperty
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)
Author:: wolfgang.hoschek@cern.ch, Piotr Wendykier (piotr.wendykier@gmail.com)
See Also:: Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static DoubleProperty`	`DEFAULT` The default Property object; currently has `tolerance()==1.0E-9`.
`static DoubleProperty`	`TWELVE` A Property object with `tolerance()==1.0E-12`.
`static DoubleProperty`	`ZERO` A Property object with `tolerance()==0.0`.

Constructor Summary

Constructors
Constructor and Description

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

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

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`checkDense(DoubleMatrix1D A)`
`void`	`checkDense(DoubleMatrix2D A)`
`void`	`checkRectangular(DoubleMatrix2D A)` Checks whether the given matrix `A` is rectangular.
`void`	`checkSparse(DoubleMatrix1D A)`
`void`	`checkSparse(DoubleMatrix2D A)`
`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 DoubleProperty DEFAULT
```
  The default Property object; currently has tolerance()==1.0E-9.
- ZERO
```
public static final DoubleProperty ZERO
```
  A Property object with tolerance()==0.0.
- TWELVE
```
public static final DoubleProperty TWELVE
```
  A Property object with tolerance()==1.0E-12.

Constructor Detail
- DoubleProperty
```
public DoubleProperty(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().

checkDense

public void checkDense(DoubleMatrix2D A)

checkDense

public void checkDense(DoubleMatrix1D A)

checkSparse

public void checkSparse(DoubleMatrix1D A)

checkSparse

public void checkSparse(DoubleMatrix2D A)

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)

Class DoubleProperty

Field Summary

Constructor Summary

Method Summary

Methods inherited from class cern.colt.PersistentObject

Methods inherited from class java.lang.Object

Field Detail

DEFAULT

ZERO

TWELVE

Constructor Detail

DoubleProperty

Method Detail

checkRectangular

checkSquare

checkDense

checkDense

checkSparse

checkSparse

density

equals

equals

equals

equals

equals

equals

generateNonSingular

isDiagonal

isDiagonallyDominantByColumn

isDiagonallyDominantByRow

isIdentity

isLowerBidiagonal

isLowerTriangular

isNonNegative

isOrthogonal

isPositive

isSingular

isSkewSymmetric

isSquare

isStrictlyLowerTriangular

isStrictlyTriangular

isStrictlyUpperTriangular

isSymmetric

isTriangular

isTridiagonal

isUnitTriangular

isUpperBidiagonal

isUpperTriangular

isZero

lowerBandwidth

semiBandwidth

setTolerance

tolerance

toString

upperBandwidth