svn commit: r1175105 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math: linear/RectangularCholeskyDecomposition.java linear/RectangularCholeskyDecompositionImpl.java random/CorrelatedRandomVectorGenerator.java

[ce...@apache.org]

Author: celestin
Date: Sat Sep 24 04:54:28 2011
New Revision: 1175105

URL: http://svn.apache.org/viewvc?rev=1175105&view=rev
Log:
Merged RectangularCholeskyDecomposition and RectangularCholeskyDecompositionImpl (see MATH-662).

Added:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecomposition.java
      - copied, changed from r1175099, commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecompositionImpl.java
Removed:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecompositionImpl.java
Modified:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math/random/CorrelatedRandomVectorGenerator.java

Copied: commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecomposition.java (from r1175099, commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecompositionImpl.java)
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecomposition.java?p2=commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecomposition.java&p1=commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecompositionImpl.java&r1=1175099&r2=1175105&rev=1175105&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecompositionImpl.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RectangularCholeskyDecomposition.java Sat Sep 24 04:54:28 2011
@@ -25,13 +25,24 @@ import org.apache.commons.math.util.Fast
  * semidefinite matrix A consists of a rectangular matrix B with the same
  * number of rows such that: A is almost equal to BB<sup>T</sup>, depending
  * on a user-defined tolerance. In a sense, this is the square root of A.</p>
+ * <p>The difference with respect to the regular {@link CholeskyDecomposition}
+ * is that rows/columns may be permuted (hence the rectangular shape instead
+ * of the traditional triangular shape) and there is a threshold to ignore
+ * small diagonal elements. This is used for example to generate {@link
+ * org.apache.commons.math.random.CorrelatedRandomVectorGenerator correlated
+ * random n-dimensions vectors} in a p-dimension subspace (p < n).
+ * In other words, it allows generating random vectors from a covariance
+ * matrix that is only positive semidefinite, and not positive definite.</p>
+ * <p>Rectangular Cholesky decomposition is <em>not</em> suited for solving
+ * linear systems, so it does not provide any {@link DecompositionSolver
+ * decomposition solver}.</p>
  *
  * @see <a href="http://mathworld.wolfram.com/CholeskyDecomposition.html">MathWorld</a>
  * @see <a href="http://en.wikipedia.org/wiki/Cholesky_decomposition">Wikipedia</a>
  * @version $Id$
- * @since 2.0
+ * @since 2.0 (changed to concrete class in 3.0)
  */
-public class RectangularCholeskyDecompositionImpl implements RectangularCholeskyDecomposition {
+public class RectangularCholeskyDecomposition {
 
     /** Permutated Cholesky root of the symmetric positive semidefinite matrix. */
     private final RealMatrix root;
@@ -48,7 +59,7 @@ public class RectangularCholeskyDecompos
      * @exception NonPositiveDefiniteMatrixException if the matrix is not
      * positive semidefinite.
      */
-    public RectangularCholeskyDecompositionImpl(RealMatrix matrix, double small)
+    public RectangularCholeskyDecomposition(RealMatrix matrix, double small)
         throws NonPositiveDefiniteMatrixException {
 
         int order = matrix.getRowDimension();
@@ -139,12 +150,23 @@ public class RectangularCholeskyDecompos
 
     }
 
-    /** {@inheritDoc} */
+    /** Get the root of the covariance matrix.
+     * The root is the rectangular matrix <code>B</code> such that
+     * the covariance matrix is equal to <code>B.B<sup>T</sup></code>
+     * @return root of the square matrix
+     * @see #getRank()
+     */
     public RealMatrix getRootMatrix() {
         return root;
     }
 
-    /** {@inheritDoc} */
+    /** Get the rank of the symmetric positive semidefinite matrix.
+     * The r is the number of independent rows in the symmetric positive semidefinite
+     * matrix, it is also the number of columns of the rectangular
+     * matrix of the decomposition.
+     * @return r of the square matrix.
+     * @see #getRootMatrix()
+     */
     public int getRank() {
         return rank;
     }

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/random/CorrelatedRandomVectorGenerator.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/random/CorrelatedRandomVectorGenerator.java?rev=1175105&r1=1175104&r2=1175105&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math/random/CorrelatedRandomVectorGenerator.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/random/CorrelatedRandomVectorGenerator.java Sat Sep 24 04:54:28 2011
@@ -20,7 +20,6 @@ package org.apache.commons.math.random;
 import org.apache.commons.math.exception.DimensionMismatchException;
 import org.apache.commons.math.linear.RealMatrix;
 import org.apache.commons.math.linear.RectangularCholeskyDecomposition;
-import org.apache.commons.math.linear.RectangularCholeskyDecompositionImpl;
 
 /**
  * A {@link RandomVectorGenerator} that generates vectors with with
@@ -95,7 +94,7 @@ public class CorrelatedRandomVectorGener
         this.mean = mean.clone();
 
         final RectangularCholeskyDecomposition decomposition =
-            new RectangularCholeskyDecompositionImpl(covariance, small);
+            new RectangularCholeskyDecomposition(covariance, small);
         root = decomposition.getRootMatrix();
 
         this.generator = generator;
@@ -124,7 +123,7 @@ public class CorrelatedRandomVectorGener
         }
 
         final RectangularCholeskyDecomposition decomposition =
-            new RectangularCholeskyDecompositionImpl(covariance, small);
+            new RectangularCholeskyDecomposition(covariance, small);
         root = decomposition.getRootMatrix();
 
         this.generator = generator;