Class CorrelatedRandomVectorGenerator
 java.lang.Object

 org.apache.commons.math.random.CorrelatedRandomVectorGenerator

 All Implemented Interfaces:
RandomVectorGenerator
public class CorrelatedRandomVectorGenerator extends java.lang.Object implements RandomVectorGenerator
ARandomVectorGenerator
that generates vectors with with correlated components.Random vectors with correlated components are built by combining the uncorrelated components of another random vector in such a way that the resulting correlations are the ones specified by a positive definite covariance matrix.
The main use for correlated random vector generation is for MonteCarlo simulation of physical problems with several variables, for example to generate error vectors to be added to a nominal vector. A particularly interesting case is when the generated vector should be drawn from a Multivariate Normal Distribution. The approach using a Cholesky decomposition is quite usual in this case. However, it can be extended to other cases as long as the underlying random generator provides
normalized values
likeGaussianRandomGenerator
orUniformRandomGenerator
.Sometimes, the covariance matrix for a given simulation is not strictly positive definite. This means that the correlations are not all independent from each other. In this case, however, the non strictly positive elements found during the Cholesky decomposition of the covariance matrix should not be negative either, they should be null. Another nonconventional extension handling this case is used here. Rather than computing
C = U^{T}.U
whereC
is the covariance matrix andU
is an uppertriangular matrix, we computeC = B.B^{T}
whereB
is a rectangular matrix having more rows than columns. The number of columns ofB
is the rank of the covariance matrix, and it is the dimension of the uncorrelated random vector that is needed to compute the component of the correlated vector. This class handles this situation automatically. Since:
 1.2


Constructor Summary
Constructors Constructor Description CorrelatedRandomVectorGenerator(double[] mean, RealMatrix covariance, double small, NormalizedRandomGenerator generator)
Simple constructor.CorrelatedRandomVectorGenerator(RealMatrix covariance, double small, NormalizedRandomGenerator generator)
Simple constructor.

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description NormalizedRandomGenerator
getGenerator()
Get the underlying normalized components generator.int
getRank()
Get the rank of the covariance matrix.RealMatrix
getRootMatrix()
Get the root of the covariance matrix.double[]
nextVector()
Generate a correlated random vector.



Constructor Detail

CorrelatedRandomVectorGenerator
public CorrelatedRandomVectorGenerator(double[] mean, RealMatrix covariance, double small, NormalizedRandomGenerator generator) throws NotPositiveDefiniteMatrixException, DimensionMismatchException
Simple constructor.Build a correlated random vector generator from its mean vector and covariance matrix.
 Parameters:
mean
 expected mean values for all componentscovariance
 covariance matrixsmall
 diagonal elements threshold under which column are considered to be dependent on previous ones and are discardedgenerator
 underlying generator for uncorrelated normalized components Throws:
java.lang.IllegalArgumentException
 if there is a dimension mismatch between the mean vector and the covariance matrixNotPositiveDefiniteMatrixException
 if the covariance matrix is not strictly positive definiteDimensionMismatchException
 if the mean and covariance arrays dimensions don't match

CorrelatedRandomVectorGenerator
public CorrelatedRandomVectorGenerator(RealMatrix covariance, double small, NormalizedRandomGenerator generator) throws NotPositiveDefiniteMatrixException
Simple constructor.Build a null mean random correlated vector generator from its covariance matrix.
 Parameters:
covariance
 covariance matrixsmall
 diagonal elements threshold under which column are considered to be dependent on previous ones and are discardedgenerator
 underlying generator for uncorrelated normalized components Throws:
NotPositiveDefiniteMatrixException
 if the covariance matrix is not strictly positive definite


Method Detail

getGenerator
public NormalizedRandomGenerator getGenerator()
Get the underlying normalized components generator. Returns:
 underlying uncorrelated components generator

getRootMatrix
public RealMatrix getRootMatrix()
Get the root of the covariance matrix. The root is the rectangular matrixB
such that the covariance matrix is equal toB.B^{T}
 Returns:
 root of the square matrix
 See Also:
getRank()

getRank
public int getRank()
Get the rank of the covariance matrix. The rank is the number of independent rows in the covariance matrix, it is also the number of columns of the rectangular matrix of the decomposition. Returns:
 rank of the square matrix.
 See Also:
getRootMatrix()

nextVector
public double[] nextVector()
Generate a correlated random vector. Specified by:
nextVector
in interfaceRandomVectorGenerator
 Returns:
 a random vector as an array of double. The returned array is created at each call, the caller can do what it wants with it.

