All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.commons.math3.random.RandomDataImpl Maven / Gradle / Ivy

Go to download

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.

The newest version!
/*
 * 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.
     * 
    
     * 
  1. {@code len / 2 + 1} binary bytes are generated using the underlying
     * Random
    2. 
     * 
  2. Each binary byte is translated into 2 hex digits
    3. 
     * 

     * 

     *
     * @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.
     * 
    
     * 
  1. 
     * 20 random bytes are generated using the underlying
     * SecureRandom.
    2. 
     * 
  2. 
     * SHA-1 hash is applied to yield a 20-byte binary digest.
    3. 
     * 
  3. 
     * Each byte of the binary digest is converted to 2 hex digits.
    4. 
     * 

     * 

     */
    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));
    }

}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy