org.apache.commons.math3.random.RandomDataImpl Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-math3 Show documentation
Show all versions of commons-math3 Show documentation
The Apache Commons Math project is a library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems not immediately available in the Java programming language or commons-lang.
/*
* 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.random;
import java.io.Serializable;
import java.security.NoSuchAlgorithmException;
import java.security.NoSuchProviderException;
import java.util.Collection;
import org.apache.commons.math3.distribution.IntegerDistribution;
import org.apache.commons.math3.distribution.RealDistribution;
import org.apache.commons.math3.exception.NotANumberException;
import org.apache.commons.math3.exception.NotFiniteNumberException;
import org.apache.commons.math3.exception.NotPositiveException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.MathIllegalArgumentException;
import org.apache.commons.math3.exception.NumberIsTooLargeException;
import org.apache.commons.math3.exception.OutOfRangeException;
/**
* Generates random deviates and other random data using a {@link RandomGenerator}
* instance to generate non-secure data and a {@link java.security.SecureRandom}
* instance to provide data for the nextSecureXxx methods. If no
* RandomGenerator is provided in the constructor, the default is
* to use a {@link Well19937c} generator. To plug in a different
* implementation, either implement RandomGenerator directly or
* extend {@link AbstractRandomGenerator}.
*
* Supports reseeding the underlying pseudo-random number generator (PRNG). The
* SecurityProvider and Algorithm used by the
* SecureRandom instance can also be reset.
*
*
* For details on the default PRNGs, see {@link java.util.Random} and
* {@link java.security.SecureRandom}.
*
*
* Usage Notes:
*
* -
* Instance variables are used to maintain
RandomGenerator and
* SecureRandom instances used in data generation. Therefore, to
* generate a random sequence of values or strings, you should use just
* one RandomDataGenerator instance repeatedly.
* -
* The "secure" methods are *much* slower. These should be used only when a
* cryptographically secure random sequence is required. A secure random
* sequence is a sequence of pseudo-random values which, in addition to being
* well-dispersed (so no subsequence of values is an any more likely than other
* subsequence of the the same length), also has the additional property that
* knowledge of values generated up to any point in the sequence does not make
* it any easier to predict subsequent values.
* -
* When a new
RandomDataGenerator is created, the underlying random
* number generators are not initialized. If you do not
* explicitly seed the default non-secure generator, it is seeded with the
* current time in milliseconds plus the system identity hash code on first use.
* The same holds for the secure generator. If you provide a RandomGenerator
* to the constructor, however, this generator is not reseeded by the constructor
* nor is it reseeded on first use.
* -
* The
reSeed and reSeedSecure methods delegate to the
* corresponding methods on the underlying RandomGenerator and
* SecureRandom instances. Therefore, reSeed(long)
* fully resets the initial state of the non-secure random number generator (so
* that reseeding with a specific value always results in the same subsequent
* random sequence); whereas reSeedSecure(long) does not
* reinitialize the secure random number generator (so secure sequences started
* with calls to reseedSecure(long) won't be identical).
* -
* This implementation is not synchronized. The underlying
RandomGenerator
* or SecureRandom instances are not protected by synchronization and
* are not guaranteed to be thread-safe. Therefore, if an instance of this class
* is concurrently utilized by multiple threads, it is the responsibility of
* client code to synchronize access to seeding and data generation methods.
*
*
*
* @deprecated to be removed in 4.0. Use {@link RandomDataGenerator} instead
*/
@Deprecated
public class RandomDataImpl implements RandomData, Serializable {
/** Serializable version identifier */
private static final long serialVersionUID = -626730818244969716L;
/** RandomDataGenerator delegate */
private final RandomDataGenerator delegate;
/**
* Construct a RandomDataImpl, using a default random generator as the source
* of randomness.
*
* The default generator is a {@link Well19937c} seeded
* with {@code System.currentTimeMillis() + System.identityHashCode(this))}.
* The generator is initialized and seeded on first use.
*/
public RandomDataImpl() {
delegate = new RandomDataGenerator();
}
/**
* Construct a RandomDataImpl using the supplied {@link RandomGenerator} as
* the source of (non-secure) random data.
*
* @param rand the source of (non-secure) random data
* (may be null, resulting in the default generator)
* @since 1.1
*/
public RandomDataImpl(RandomGenerator rand) {
delegate = new RandomDataGenerator(rand);
}
/**
* @return the delegate object.
* @deprecated To be removed in 4.0.
*/
@Deprecated
RandomDataGenerator getDelegate() {
return delegate;
}
/**
* {@inheritDoc}
*
* Algorithm Description: hex strings are generated using a
* 2-step process.
*
* - {@code len / 2 + 1} binary bytes are generated using the underlying
* Random
* - Each binary byte is translated into 2 hex digits
*
*
*
* @param len the desired string length.
* @return the random string.
* @throws NotStrictlyPositiveException if {@code len <= 0}.
*/
public String nextHexString(int len) throws NotStrictlyPositiveException {
return delegate.nextHexString(len);
}
/** {@inheritDoc} */
public int nextInt(int lower, int upper) throws NumberIsTooLargeException {
return delegate.nextInt(lower, upper);
}
/** {@inheritDoc} */
public long nextLong(long lower, long upper) throws NumberIsTooLargeException {
return delegate.nextLong(lower, upper);
}
/**
* {@inheritDoc}
*
* Algorithm Description: hex strings are generated in
* 40-byte segments using a 3-step process.
*
* -
* 20 random bytes are generated using the underlying
*
SecureRandom.
* -
* SHA-1 hash is applied to yield a 20-byte binary digest.
* -
* Each byte of the binary digest is converted to 2 hex digits.
*
*
*/
public String nextSecureHexString(int len) throws NotStrictlyPositiveException {
return delegate.nextSecureHexString(len);
}
/** {@inheritDoc} */
public int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException {
return delegate.nextSecureInt(lower, upper);
}
/** {@inheritDoc} */
public long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException {
return delegate.nextSecureLong(lower,upper);
}
/**
* {@inheritDoc}
*
* Algorithm Description:
*
- For small means, uses simulation of a Poisson process
* using Uniform deviates, as described
* here.
* The Poisson process (and hence value returned) is bounded by 1000 * mean.
*
* - For large means, uses the rejection algorithm described in
* Devroye, Luc. (1981).The Computer Generation of Poisson Random Variables
* Computing vol. 26 pp. 197-207.
*/
public long nextPoisson(double mean) throws NotStrictlyPositiveException {
return delegate.nextPoisson(mean);
}
/** {@inheritDoc} */
public double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException {
return delegate.nextGaussian(mu,sigma);
}
/**
* {@inheritDoc}
*
*
* Algorithm Description: Uses the Algorithm SA (Ahrens)
* from p. 876 in:
* [1]: Ahrens, J. H. and Dieter, U. (1972). Computer methods for
* sampling from the exponential and normal distributions.
* Communications of the ACM, 15, 873-882.
*
*/
public double nextExponential(double mean) throws NotStrictlyPositiveException {
return delegate.nextExponential(mean);
}
/**
* {@inheritDoc}
*
*
* Algorithm Description: scales the output of
* Random.nextDouble(), but rejects 0 values (i.e., will generate another
* random double if Random.nextDouble() returns 0). This is necessary to
* provide a symmetric output interval (both endpoints excluded).
*
*/
public double nextUniform(double lower, double upper)
throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException {
return delegate.nextUniform(lower, upper);
}
/**
* {@inheritDoc}
*
*
* Algorithm Description: if the lower bound is excluded,
* scales the output of Random.nextDouble(), but rejects 0 values (i.e.,
* will generate another random double if Random.nextDouble() returns 0).
* This is necessary to provide a symmetric output interval (both
* endpoints excluded).
*
* @since 3.0
*/
public double nextUniform(double lower, double upper, boolean lowerInclusive)
throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException {
return delegate.nextUniform(lower, upper, lowerInclusive);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.BetaDistribution Beta Distribution}.
* This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
* to generate random values.
*
* @param alpha first distribution shape parameter
* @param beta second distribution shape parameter
* @return random value sampled from the beta(alpha, beta) distribution
* @since 2.2
*/
public double nextBeta(double alpha, double beta) {
return delegate.nextBeta(alpha, beta);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.BinomialDistribution Binomial Distribution}.
* This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
* to generate random values.
*
* @param numberOfTrials number of trials of the Binomial distribution
* @param probabilityOfSuccess probability of success of the Binomial distribution
* @return random value sampled from the Binomial(numberOfTrials, probabilityOfSuccess) distribution
* @since 2.2
*/
public int nextBinomial(int numberOfTrials, double probabilityOfSuccess) {
return delegate.nextBinomial(numberOfTrials, probabilityOfSuccess);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.CauchyDistribution Cauchy Distribution}.
* This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
* to generate random values.
*
* @param median the median of the Cauchy distribution
* @param scale the scale parameter of the Cauchy distribution
* @return random value sampled from the Cauchy(median, scale) distribution
* @since 2.2
*/
public double nextCauchy(double median, double scale) {
return delegate.nextCauchy(median, scale);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.ChiSquaredDistribution ChiSquare Distribution}.
* This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
* to generate random values.
*
* @param df the degrees of freedom of the ChiSquare distribution
* @return random value sampled from the ChiSquare(df) distribution
* @since 2.2
*/
public double nextChiSquare(double df) {
return delegate.nextChiSquare(df);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.FDistribution F Distribution}.
* This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
* to generate random values.
*
* @param numeratorDf the numerator degrees of freedom of the F distribution
* @param denominatorDf the denominator degrees of freedom of the F distribution
* @return random value sampled from the F(numeratorDf, denominatorDf) distribution
* @throws NotStrictlyPositiveException if
* {@code numeratorDf <= 0} or {@code denominatorDf <= 0}.
* @since 2.2
*/
public double nextF(double numeratorDf, double denominatorDf) throws NotStrictlyPositiveException {
return delegate.nextF(numeratorDf, denominatorDf);
}
/**
* Generates a random value from the
* {@link org.apache.commons.math3.distribution.GammaDistribution Gamma Distribution}.
*
* This implementation uses the following algorithms:
*
* For 0 < shape < 1:
* Ahrens, J. H. and Dieter, U., Computer methods for
* sampling from gamma, beta, Poisson and binomial distributions.
* Computing, 12, 223-246, 1974.
*
* For shape >= 1:
* Marsaglia and Tsang, A Simple Method for Generating
* Gamma Variables. ACM Transactions on Mathematical Software,
* Volume 26 Issue 3, September, 2000.
*
* @param shape the median of the Gamma distribution
* @param scale the scale parameter of the Gamma distribution
* @return random value sampled from the Gamma(shape, scale) distribution
* @throws NotStrictlyPositiveException if {@code shape <= 0} or
* {@code scale <= 0}.
* @since 2.2
*/
public double nextGamma(double shape, double scale) throws NotStrictlyPositiveException {
return delegate.nextGamma(shape, scale);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.HypergeometricDistribution Hypergeometric Distribution}.
* This implementation uses {@link #nextInversionDeviate(IntegerDistribution) inversion}
* to generate random values.
*
* @param populationSize the population size of the Hypergeometric distribution
* @param numberOfSuccesses number of successes in the population of the Hypergeometric distribution
* @param sampleSize the sample size of the Hypergeometric distribution
* @return random value sampled from the Hypergeometric(numberOfSuccesses, sampleSize) distribution
* @throws NumberIsTooLargeException if {@code numberOfSuccesses > populationSize},
* or {@code sampleSize > populationSize}.
* @throws NotStrictlyPositiveException if {@code populationSize <= 0}.
* @throws NotPositiveException if {@code numberOfSuccesses < 0}.
* @since 2.2
*/
public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize)
throws NotPositiveException, NotStrictlyPositiveException, NumberIsTooLargeException {
return delegate.nextHypergeometric(populationSize, numberOfSuccesses, sampleSize);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.PascalDistribution Pascal Distribution}.
* This implementation uses {@link #nextInversionDeviate(IntegerDistribution) inversion}
* to generate random values.
*
* @param r the number of successes of the Pascal distribution
* @param p the probability of success of the Pascal distribution
* @return random value sampled from the Pascal(r, p) distribution
* @since 2.2
* @throws NotStrictlyPositiveException if the number of successes is not positive
* @throws OutOfRangeException if the probability of success is not in the
* range {@code [0, 1]}.
*/
public int nextPascal(int r, double p)
throws NotStrictlyPositiveException, OutOfRangeException {
return delegate.nextPascal(r, p);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.TDistribution T Distribution}.
* This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
* to generate random values.
*
* @param df the degrees of freedom of the T distribution
* @return random value from the T(df) distribution
* @since 2.2
* @throws NotStrictlyPositiveException if {@code df <= 0}
*/
public double nextT(double df) throws NotStrictlyPositiveException {
return delegate.nextT(df);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.WeibullDistribution Weibull Distribution}.
* This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
* to generate random values.
*
* @param shape the shape parameter of the Weibull distribution
* @param scale the scale parameter of the Weibull distribution
* @return random value sampled from the Weibull(shape, size) distribution
* @since 2.2
* @throws NotStrictlyPositiveException if {@code shape <= 0} or
* {@code scale <= 0}.
*/
public double nextWeibull(double shape, double scale) throws NotStrictlyPositiveException {
return delegate.nextWeibull(shape, scale);
}
/**
* Generates a random value from the {@link org.apache.commons.math3.distribution.ZipfDistribution Zipf Distribution}.
* This implementation uses {@link #nextInversionDeviate(IntegerDistribution) inversion}
* to generate random values.
*
* @param numberOfElements the number of elements of the ZipfDistribution
* @param exponent the exponent of the ZipfDistribution
* @return random value sampled from the Zipf(numberOfElements, exponent) distribution
* @since 2.2
* @exception NotStrictlyPositiveException if {@code numberOfElements <= 0}
* or {@code exponent <= 0}.
*/
public int nextZipf(int numberOfElements, double exponent) throws NotStrictlyPositiveException {
return delegate.nextZipf(numberOfElements, exponent);
}
/**
* Reseeds the random number generator with the supplied seed.
*
* Will create and initialize if null.
*
*
* @param seed
* the seed value to use
*/
public void reSeed(long seed) {
delegate.reSeed(seed);
}
/**
* Reseeds the secure random number generator with the current time in
* milliseconds.
*
* Will create and initialize if null.
*
*/
public void reSeedSecure() {
delegate.reSeedSecure();
}
/**
* Reseeds the secure random number generator with the supplied seed.
*
* Will create and initialize if null.
*
*
* @param seed
* the seed value to use
*/
public void reSeedSecure(long seed) {
delegate.reSeedSecure(seed);
}
/**
* Reseeds the random number generator with
* {@code System.currentTimeMillis() + System.identityHashCode(this))}.
*/
public void reSeed() {
delegate.reSeed();
}
/**
* Sets the PRNG algorithm for the underlying SecureRandom instance using
* the Security Provider API. The Security Provider API is defined in
* Java Cryptography Architecture API Specification & Reference.
*
* USAGE NOTE: This method carries significant
* overhead and may take several seconds to execute.
*
*
* @param algorithm
* the name of the PRNG algorithm
* @param provider
* the name of the provider
* @throws NoSuchAlgorithmException
* if the specified algorithm is not available
* @throws NoSuchProviderException
* if the specified provider is not installed
*/
public void setSecureAlgorithm(String algorithm, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
delegate.setSecureAlgorithm(algorithm, provider);
}
/**
* {@inheritDoc}
*
*
* Uses a 2-cycle permutation shuffle. The shuffling process is described
* here.
*
*/
public int[] nextPermutation(int n, int k)
throws NotStrictlyPositiveException, NumberIsTooLargeException {
return delegate.nextPermutation(n, k);
}
/**
* {@inheritDoc}
*
*
* Algorithm Description: Uses a 2-cycle permutation
* shuffle to generate a random permutation of c.size() and
* then returns the elements whose indexes correspond to the elements of the
* generated permutation. This technique is described, and proven to
* generate random samples
* here
*
*/
public Object[] nextSample(Collection c, int k)
throws NotStrictlyPositiveException, NumberIsTooLargeException {
return delegate.nextSample(c, k);
}
/**
* Generate a random deviate from the given distribution using the
* inversion method.
*
* @param distribution Continuous distribution to generate a random value from
* @return a random value sampled from the given distribution
* @throws MathIllegalArgumentException if the underlynig distribution throws one
* @since 2.2
* @deprecated use the distribution's sample() method
*/
@Deprecated
public double nextInversionDeviate(RealDistribution distribution)
throws MathIllegalArgumentException {
return distribution.inverseCumulativeProbability(nextUniform(0, 1));
}
/**
* Generate a random deviate from the given distribution using the
* inversion method.
*
* @param distribution Integer distribution to generate a random value from
* @return a random value sampled from the given distribution
* @throws MathIllegalArgumentException if the underlynig distribution throws one
* @since 2.2
* @deprecated use the distribution's sample() method
*/
@Deprecated
public int nextInversionDeviate(IntegerDistribution distribution)
throws MathIllegalArgumentException {
return distribution.inverseCumulativeProbability(nextUniform(0, 1));
}
}