diff --git a/src/main/java/org/apache/commons/math3/distribution/AbstractMultivariateRealDistribution.java b/src/main/java/org/apache/commons/math3/distribution/AbstractMultivariateRealDistribution.java index 32485c036..db56d2bd5 100644 --- a/src/main/java/org/apache/commons/math3/distribution/AbstractMultivariateRealDistribution.java +++ b/src/main/java/org/apache/commons/math3/distribution/AbstractMultivariateRealDistribution.java @@ -21,17 +21,17 @@ import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.random.RandomGenerator; /** - * Base class for probability distributions on the multivariate reals. - * Default implementations are provided for some of the methods that do - * not vary from distribution to distribution. - * + * Base class for multivariate probability distributions. + * + * @version $Id$ + * @since 3.1 */ public abstract class AbstractMultivariateRealDistribution implements MultivariateRealDistribution { - /** The number of dimensions or columns in the multivariate distribution. */ - private final int numDimensions; /** RNG instance used to generate samples from the distribution. */ protected final RandomGenerator random; + /** The number of dimensions or columns in the multivariate distribution. */ + private final int numDimensions; /** * @param rng Random number generator. @@ -49,8 +49,10 @@ public abstract class AbstractMultivariateRealDistribution } /** - * - * @return the number of dimensions in the multivariate distribution . + * Gets the number of dimensions (i.e. the number of random variables) of + * the distribution. + * + * @return the number of dimensions. */ public int getDimensions() { return numDimensions; diff --git a/src/main/java/org/apache/commons/math3/distribution/MultivariateNormalDistribution.java b/src/main/java/org/apache/commons/math3/distribution/MultivariateNormalDistribution.java index c6672d4d1..18e7ec5b1 100644 --- a/src/main/java/org/apache/commons/math3/distribution/MultivariateNormalDistribution.java +++ b/src/main/java/org/apache/commons/math3/distribution/MultivariateNormalDistribution.java @@ -1,3 +1,19 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.apache.commons.math3.distribution; import org.apache.commons.math3.exception.DimensionMismatchException; @@ -13,11 +29,14 @@ import org.apache.commons.math3.util.MathArrays; /** * Implementation of the multivariate normal (Gaussian) distribution. - * + * * @see * Multivariate normal distribution (Wikipedia) * @see * Multivariate normal distribution (MathWorld) + * + * @version $Id$ + * @since 3.1 */ public class MultivariateNormalDistribution extends AbstractMultivariateRealDistribution { @@ -39,9 +58,15 @@ public class MultivariateNormalDistribution * The number of dimensions is equal to the length of the mean vector * and to the number of rows and columns of the covariance matrix. * It is frequently written as "p" in formulae. - * + * * @param means Vector of means. * @param covariances Covariance matrix. + * @throws DimensionMismatchException if the arrays length are + * inconsistent. + * @throws SingularMatrixException if the eigenvalue decomposition cannot + * be performed on the provided covariance matrix. + * @throws NonPositiveDefiniteMatrixException if any of the eigenvalues is + * negative. */ public MultivariateNormalDistribution(final double[] means, final double[][] covariances) @@ -58,10 +83,16 @@ public class MultivariateNormalDistribution * The number of dimensions is equal to the length of the mean vector * and to the number of rows and columns of the covariance matrix. * It is frequently written as "p" in formulae. - * + * * @param rng Random Number Generator. * @param means Vector of means. * @param covariances Covariance matrix. + * @throws DimensionMismatchException if the arrays length are + * inconsistent. + * @throws SingularMatrixException if the eigenvalue decomposition cannot + * be performed on the provided covariance matrix. + * @throws NonPositiveDefiniteMatrixException if any of the eigenvalues is + * negative. */ public MultivariateNormalDistribution(RandomGenerator rng, final double[] means, @@ -126,7 +157,7 @@ public class MultivariateNormalDistribution /** * Gets the mean vector. - * + * * @return the mean vector. */ public double[] getMeans() { @@ -135,13 +166,13 @@ public class MultivariateNormalDistribution /** * Gets the covariance matrix. - * + * * @return the covariance matrix. */ public RealMatrix getCovariances() { return covarianceMatrix.copy(); } - + /** {@inheritDoc} */ public double density(final double[] vals) throws DimensionMismatchException { final int dim = getDimensions(); @@ -157,7 +188,7 @@ public class MultivariateNormalDistribution /** * Gets the square root of each element on the diagonal of the covariance * matrix. - * + * * @return the standard deviations. */ public double[] getStandardDeviations() { @@ -190,7 +221,7 @@ public class MultivariateNormalDistribution /** * Computes the term used in the exponent (see definition of the distribution). - * + * * @param values Values at which to compute density. * @return the multiplication factor of density calculations. */ diff --git a/src/main/java/org/apache/commons/math3/distribution/MultivariateRealDistribution.java b/src/main/java/org/apache/commons/math3/distribution/MultivariateRealDistribution.java index 47ec28362..5f129f714 100644 --- a/src/main/java/org/apache/commons/math3/distribution/MultivariateRealDistribution.java +++ b/src/main/java/org/apache/commons/math3/distribution/MultivariateRealDistribution.java @@ -16,17 +16,17 @@ */ package org.apache.commons.math3.distribution; -import org.apache.commons.math3.exception.DimensionMismatchException; import org.apache.commons.math3.exception.NotStrictlyPositiveException; -import org.apache.commons.math3.exception.NumberIsTooLargeException; -import org.apache.commons.math3.exception.OutOfRangeException; /** * Base interface for multivariate distributions on the reals. - * + * * This is based largely on the RealDistribution interface, but cumulative * distribution functions are not required because they are often quite * difficult to compute for multivariate distributions. + * + * @version $Id$ + * @since 3.1 */ public interface MultivariateRealDistribution { /** @@ -34,7 +34,7 @@ public interface MultivariateRealDistribution { * this distribution, this method returns {@code P(X = x)}. In other words, * this method represents the probability mass function (PMF) for the * distribution. - * + * * @param x Point at which the PMF is evaluated. * @return the value of the probability mass function at point {@code x}. */ @@ -47,11 +47,11 @@ public interface MultivariateRealDistribution { * does not exist at {@code x}, then an appropriate replacement should be * returned, e.g. {@code Double.POSITIVE_INFINITY}, {@code Double.NaN}, or * the limit inferior or limit superior of the difference quotient. - * + * * @param x Point at which the PDF is evaluated. * @return the value of the probability density function at point {@code x}. */ - double density(double[] x) throws DimensionMismatchException; + double density(double[] x); /** * Access the lower bound of the support. @@ -60,7 +60,7 @@ public interface MultivariateRealDistribution { *

* inf {x in R | P(X <= x) > 0}. *

- * + * * @return the lower bound of the support (might be * {@code Double.NEGATIVE_INFINITY}). */ @@ -73,7 +73,7 @@ public interface MultivariateRealDistribution { *

* inf {x in R | P(X <= x) = 1}. *

- * + * * @return the upper bound of the support (might be * {@code Double.POSITIVE_INFINITY}). */ @@ -82,7 +82,7 @@ public interface MultivariateRealDistribution { /** * Gets information about whether the lower bound of the support is * inclusive or not. - * + * * @return whether the lower bound of the support is inclusive or not. */ boolean isSupportLowerBoundInclusive(); @@ -90,7 +90,7 @@ public interface MultivariateRealDistribution { /** * gets information about whether the upper bound of the support is * inclusive or not. - * + * * @return whether the upper bound of the support is inclusive or not. */ boolean isSupportUpperBoundInclusive(); @@ -99,28 +99,28 @@ public interface MultivariateRealDistribution { * Gets information about whether the support is connected (i.e. all * values between the lower and upper bound of the support are included * in the support). - * + * * @return whether the support is connected or not. */ boolean isSupportConnected(); /** * Reseeds the random generator used to generate samples. - * + * * @param seed Seed with which to initialize the random number generator. */ void reseedRandomGenerator(long seed); /** * Generates a random value vector sampled from this distribution. - * + * * @return a random value vector. */ double[] sample(); /** * Generates a list of a random value vectors from the distribution. - * + * * @param sampleSize the number of random vectors to generate. * @return an array representing the random samples. * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException