001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.math3.random;
019
020import org.apache.commons.math3.exception.DimensionMismatchException;
021import org.apache.commons.math3.linear.RealMatrix;
022import org.apache.commons.math3.linear.RectangularCholeskyDecomposition;
023
024/**
025 * A {@link RandomVectorGenerator} that generates vectors with with
026 * correlated components.
027 * <p>Random vectors with correlated components are built by combining
028 * the uncorrelated components of another random vector in such a way that
029 * the resulting correlations are the ones specified by a positive
030 * definite covariance matrix.</p>
031 * <p>The main use for correlated random vector generation is for Monte-Carlo
032 * simulation of physical problems with several variables, for example to
033 * generate error vectors to be added to a nominal vector. A particularly
034 * interesting case is when the generated vector should be drawn from a <a
035 * href="http://en.wikipedia.org/wiki/Multivariate_normal_distribution">
036 * Multivariate Normal Distribution</a>. The approach using a Cholesky
037 * decomposition is quite usual in this case. However, it can be extended
038 * to other cases as long as the underlying random generator provides
039 * {@link NormalizedRandomGenerator normalized values} like {@link
040 * GaussianRandomGenerator} or {@link UniformRandomGenerator}.</p>
041 * <p>Sometimes, the covariance matrix for a given simulation is not
042 * strictly positive definite. This means that the correlations are
043 * not all independent from each other. In this case, however, the non
044 * strictly positive elements found during the Cholesky decomposition
045 * of the covariance matrix should not be negative either, they
046 * should be null. Another non-conventional extension handling this case
047 * is used here. Rather than computing <code>C = U<sup>T</sup>.U</code>
048 * where <code>C</code> is the covariance matrix and <code>U</code>
049 * is an upper-triangular matrix, we compute <code>C = B.B<sup>T</sup></code>
050 * where <code>B</code> is a rectangular matrix having
051 * more rows than columns. The number of columns of <code>B</code> is
052 * the rank of the covariance matrix, and it is the dimension of the
053 * uncorrelated random vector that is needed to compute the component
054 * of the correlated vector. This class handles this situation
055 * automatically.</p>
056 *
057 * @version $Id: CorrelatedRandomVectorGenerator.java 1416643 2012-12-03 19:37:14Z tn $
058 * @since 1.2
059 */
060
061public class CorrelatedRandomVectorGenerator
062    implements RandomVectorGenerator {
063    /** Mean vector. */
064    private final double[] mean;
065    /** Underlying generator. */
066    private final NormalizedRandomGenerator generator;
067    /** Storage for the normalized vector. */
068    private final double[] normalized;
069    /** Root of the covariance matrix. */
070    private final RealMatrix root;
071
072    /**
073     * Builds a correlated random vector generator from its mean
074     * vector and covariance matrix.
075     *
076     * @param mean Expected mean values for all components.
077     * @param covariance Covariance matrix.
078     * @param small Diagonal elements threshold under which  column are
079     * considered to be dependent on previous ones and are discarded
080     * @param generator underlying generator for uncorrelated normalized
081     * components.
082     * @throws org.apache.commons.math3.linear.NonPositiveDefiniteMatrixException
083     * if the covariance matrix is not strictly positive definite.
084     * @throws DimensionMismatchException if the mean and covariance
085     * arrays dimensions do not match.
086     */
087    public CorrelatedRandomVectorGenerator(double[] mean,
088                                           RealMatrix covariance, double small,
089                                           NormalizedRandomGenerator generator) {
090        int order = covariance.getRowDimension();
091        if (mean.length != order) {
092            throw new DimensionMismatchException(mean.length, order);
093        }
094        this.mean = mean.clone();
095
096        final RectangularCholeskyDecomposition decomposition =
097            new RectangularCholeskyDecomposition(covariance, small);
098        root = decomposition.getRootMatrix();
099
100        this.generator = generator;
101        normalized = new double[decomposition.getRank()];
102
103    }
104
105    /**
106     * Builds a null mean random correlated vector generator from its
107     * covariance matrix.
108     *
109     * @param covariance Covariance matrix.
110     * @param small Diagonal elements threshold under which  column are
111     * considered to be dependent on previous ones and are discarded.
112     * @param generator Underlying generator for uncorrelated normalized
113     * components.
114     * @throws org.apache.commons.math3.linear.NonPositiveDefiniteMatrixException
115     * if the covariance matrix is not strictly positive definite.
116     */
117    public CorrelatedRandomVectorGenerator(RealMatrix covariance, double small,
118                                           NormalizedRandomGenerator generator) {
119        int order = covariance.getRowDimension();
120        mean = new double[order];
121        for (int i = 0; i < order; ++i) {
122            mean[i] = 0;
123        }
124
125        final RectangularCholeskyDecomposition decomposition =
126            new RectangularCholeskyDecomposition(covariance, small);
127        root = decomposition.getRootMatrix();
128
129        this.generator = generator;
130        normalized = new double[decomposition.getRank()];
131
132    }
133
134    /** Get the underlying normalized components generator.
135     * @return underlying uncorrelated components generator
136     */
137    public NormalizedRandomGenerator getGenerator() {
138        return generator;
139    }
140
141    /** Get the rank of the covariance matrix.
142     * The rank is the number of independent rows in the covariance
143     * matrix, it is also the number of columns of the root matrix.
144     * @return rank of the square matrix.
145     * @see #getRootMatrix()
146     */
147    public int getRank() {
148        return normalized.length;
149    }
150
151    /** Get the root of the covariance matrix.
152     * The root is the rectangular matrix <code>B</code> such that
153     * the covariance matrix is equal to <code>B.B<sup>T</sup></code>
154     * @return root of the square matrix
155     * @see #getRank()
156     */
157    public RealMatrix getRootMatrix() {
158        return root;
159    }
160
161    /** Generate a correlated random vector.
162     * @return a random vector as an array of double. The returned array
163     * is created at each call, the caller can do what it wants with it.
164     */
165    public double[] nextVector() {
166
167        // generate uncorrelated vector
168        for (int i = 0; i < normalized.length; ++i) {
169            normalized[i] = generator.nextNormalizedDouble();
170        }
171
172        // compute correlated vector
173        double[] correlated = new double[mean.length];
174        for (int i = 0; i < correlated.length; ++i) {
175            correlated[i] = mean[i];
176            for (int j = 0; j < root.getColumnDimension(); ++j) {
177                correlated[i] += root.getEntry(i, j) * normalized[j];
178            }
179        }
180
181        return correlated;
182
183    }
184
185}