Class RandomDataGenerator

java.lang.Object
org.apache.commons.math3.random.RandomDataGenerator
All Implemented Interfaces:
Serializable, RandomData

public class RandomDataGenerator extends Object implements RandomData, Serializable
Implements the RandomData interface using a RandomGenerator instance to generate non-secure data and a SecureRandom instance to provide data for the nextSecureXxx methods. If no RandomGenerator is provided in the constructor, the default is to use a Well19937c generator. To plug in a different implementation, either implement RandomGenerator directly or extend 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 Random and 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 RandomDataImpl 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 RandomDataImpl 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.

Since:
3.1
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    underlying random number generator
    underlying secure random number generator
    private static final long
    Serializable version identifier
  • Constructor Summary

    Constructors
    Constructor
    Description
    Construct a RandomDataGenerator, using a default random generator as the source of randomness.
    Construct a RandomDataGenerator using the supplied RandomGenerator as the source of (non-secure) random data.
  • Method Summary

    Modifier and Type
    Method
    Description
    Returns the RandomGenerator used to generate non-secure random data.
    Returns the SecureRandom used to generate secure random data.
    private void
    Sets the default generator to a Well19937c generator seeded with System.currentTimeMillis() + System.identityHashCode(this)).
    double
    nextBeta(double alpha, double beta)
    Generates a random value from the Beta Distribution.
    int
    nextBinomial(int numberOfTrials, double probabilityOfSuccess)
    Generates a random value from the Binomial Distribution.
    double
    nextCauchy(double median, double scale)
    Generates a random value from the Cauchy Distribution.
    double
    nextChiSquare(double df)
    Generates a random value from the ChiSquare Distribution.
    double
    nextExponential(double mean)
    Generates a random value from the exponential distribution with specified mean.
    double
    nextF(double numeratorDf, double denominatorDf)
    Generates a random value from the F Distribution.
    double
    nextGamma(double shape, double scale)
    Generates a random value from the Gamma Distribution.
    double
    nextGaussian(double mu, double sigma)
    Generates a random value from the Normal (or Gaussian) distribution with specified mean and standard deviation.
    nextHexString(int len)
    Generates a random string of hex characters of length len.
    int
    nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize)
    Generates a random value from the Hypergeometric Distribution.
    int
    nextInt(int lower, int upper)
    Generates a uniformly distributed random integer between lower and upper (endpoints included).
    long
    nextLong(long lower, long upper)
    Generates a uniformly distributed random long integer between lower and upper (endpoints included).
    private static long
    nextLong(RandomGenerator rng, long n)
    Returns a pseudorandom, uniformly distributed long value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.
    int
    nextPascal(int r, double p)
    Generates a random value from the Pascal Distribution.
    int[]
    nextPermutation(int n, int k)
    Generates an integer array of length k whose entries are selected randomly, without repetition, from the integers 0, ..., n - 1 (inclusive).
    long
    nextPoisson(double mean)
    Generates a random value from the Poisson distribution with the given mean.
    nextSample(Collection<?> c, int k)
    Returns an array of k objects selected randomly from the Collection c.
    Generates a random string of hex characters from a secure random sequence.
    int
    nextSecureInt(int lower, int upper)
    Generates a uniformly distributed random integer between lower and upper (endpoints included) from a secure random sequence.
    long
    nextSecureLong(long lower, long upper)
    Generates a uniformly distributed random long integer between lower and upper (endpoints included) from a secure random sequence.
    double
    nextT(double df)
    Generates a random value from the T Distribution.
    double
    nextUniform(double lower, double upper)
    Generates a uniformly distributed random value from the open interval (lower, upper) (i.e., endpoints excluded).
    double
    nextUniform(double lower, double upper, boolean lowerInclusive)
    Generates a uniformly distributed random value from the interval (lower, upper) or the interval [lower, upper).
    double
    nextWeibull(double shape, double scale)
    Generates a random value from the Weibull Distribution.
    int
    nextZipf(int numberOfElements, double exponent)
    Generates a random value from the Zipf Distribution.
    void
    Reseeds the random number generator with System.currentTimeMillis() + System.identityHashCode(this)).
    void
    reSeed(long seed)
    Reseeds the random number generator with the supplied seed.
    void
    Reseeds the secure random number generator with the current time in milliseconds.
    void
    reSeedSecure(long seed)
    Reseeds the secure random number generator with the supplied seed.
    void
    setSecureAlgorithm(String algorithm, String provider)
    Sets the PRNG algorithm for the underlying SecureRandom instance using the Security Provider API.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serializable version identifier
      See Also:
    • rand

      private RandomGenerator rand
      underlying random number generator
    • secRand

      private RandomGenerator secRand
      underlying secure random number generator
  • Constructor Details

    • RandomDataGenerator

      public RandomDataGenerator()
      Construct a RandomDataGenerator, using a default random generator as the source of randomness.

      The default generator is a Well19937c seeded with System.currentTimeMillis() + System.identityHashCode(this)). The generator is initialized and seeded on first use.

    • RandomDataGenerator

      public RandomDataGenerator(RandomGenerator rand)
      Construct a RandomDataGenerator using the supplied RandomGenerator as the source of (non-secure) random data.
      Parameters:
      rand - the source of (non-secure) random data (may be null, resulting in the default generator)
  • Method Details

    • nextHexString

      public String nextHexString(int len) throws NotStrictlyPositiveException
      Generates a random string of hex characters of length len.

      The generated string will be random, but not cryptographically secure. To generate cryptographically secure strings, use RandomData.nextSecureHexString(int).

      Algorithm Description: hex strings are generated using a 2-step process.

      1. len / 2 + 1 binary bytes are generated using the underlying Random
      2. Each binary byte is translated into 2 hex digits

      Specified by:
      nextHexString in interface RandomData
      Parameters:
      len - the desired string length.
      Returns:
      the random string.
      Throws:
      NotStrictlyPositiveException - if len <= 0.
    • nextInt

      public int nextInt(int lower, int upper) throws NumberIsTooLargeException
      Generates a uniformly distributed random integer between lower and upper (endpoints included).

      The generated integer will be random, but not cryptographically secure. To generate cryptographically secure integer sequences, use RandomData.nextSecureInt(int, int).

      Specified by:
      nextInt in interface RandomData
      Parameters:
      lower - lower bound for generated integer
      upper - upper bound for generated integer
      Returns:
      a random integer greater than or equal to lower and less than or equal to upper
      Throws:
      NumberIsTooLargeException - if lower >= upper
    • nextLong

      public long nextLong(long lower, long upper) throws NumberIsTooLargeException
      Generates a uniformly distributed random long integer between lower and upper (endpoints included).

      The generated long integer values will be random, but not cryptographically secure. To generate cryptographically secure sequences of longs, use RandomData.nextSecureLong(long, long).

      Specified by:
      nextLong in interface RandomData
      Parameters:
      lower - lower bound for generated long integer
      upper - upper bound for generated long integer
      Returns:
      a random long integer greater than or equal to lower and less than or equal to upper
      Throws:
      NumberIsTooLargeException - if lower >= upper
    • nextLong

      private static long nextLong(RandomGenerator rng, long n) throws IllegalArgumentException
      Returns a pseudorandom, uniformly distributed long value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.
      Parameters:
      rng - random generator to use
      n - the bound on the random number to be returned. Must be positive.
      Returns:
      a pseudorandom, uniformly distributed long value between 0 (inclusive) and n (exclusive).
      Throws:
      IllegalArgumentException - if n is not positive.
    • nextSecureHexString

      public String nextSecureHexString(int len) throws NotStrictlyPositiveException
      Generates a random string of hex characters from a secure random sequence.

      If cryptographic security is not required, use RandomData.nextHexString(int).

      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. SHA-1 hash is applied to yield a 20-byte binary digest.
      3. Each byte of the binary digest is converted to 2 hex digits.

      Specified by:
      nextSecureHexString in interface RandomData
      Parameters:
      len - the length of the string to be generated
      Returns:
      a random string of hex characters of length len
      Throws:
      NotStrictlyPositiveException - if len <= 0
    • nextSecureInt

      public int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException
      Generates a uniformly distributed random integer between lower and upper (endpoints included) from a secure random sequence.

      Sequences of integers generated using this method will be cryptographically secure. If cryptographic security is not required, RandomData.nextInt(int, int) should be used instead of this method.

      Definition: Secure Random Sequence

      Specified by:
      nextSecureInt in interface RandomData
      Parameters:
      lower - lower bound for generated integer
      upper - upper bound for generated integer
      Returns:
      a random integer greater than or equal to lower and less than or equal to upper.
      Throws:
      NumberIsTooLargeException - if lower >= upper.
    • nextSecureLong

      public long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException
      Generates a uniformly distributed random long integer between lower and upper (endpoints included) from a secure random sequence.

      Sequences of long values generated using this method will be cryptographically secure. If cryptographic security is not required, RandomData.nextLong(long, long) should be used instead of this method.

      Definition: Secure Random Sequence

      Specified by:
      nextSecureLong in interface RandomData
      Parameters:
      lower - lower bound for generated integer
      upper - upper bound for generated integer
      Returns:
      a random long integer greater than or equal to lower and less than or equal to upper.
      Throws:
      NumberIsTooLargeException - if lower >= upper.
    • nextPoisson

      public long nextPoisson(double mean) throws NotStrictlyPositiveException
      Generates a random value from the Poisson distribution with the given mean.

      Definition: Poisson Distribution

      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.

      Specified by:
      nextPoisson in interface RandomData
      Parameters:
      mean - the mean of the Poisson distribution
      Returns:
      a random value following the specified Poisson distribution
      Throws:
      NotStrictlyPositiveException - if len <= 0
    • nextGaussian

      public double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException
      Generates a random value from the Normal (or Gaussian) distribution with specified mean and standard deviation.

      Definition: Normal Distribution

      Specified by:
      nextGaussian in interface RandomData
      Parameters:
      mu - the mean of the distribution
      sigma - the standard deviation of the distribution
      Returns:
      a random value following the specified Gaussian distribution
      Throws:
      NotStrictlyPositiveException - if sigma <= 0.
    • nextExponential

      public double nextExponential(double mean) throws NotStrictlyPositiveException
      Generates a random value from the exponential distribution with specified mean.

      Definition: Exponential Distribution

      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.

      Specified by:
      nextExponential in interface RandomData
      Parameters:
      mean - the mean of the distribution
      Returns:
      a random value following the specified exponential distribution
      Throws:
      NotStrictlyPositiveException - if mean <= 0.
    • nextGamma

      public double nextGamma(double shape, double scale) throws NotStrictlyPositiveException

      Generates a random value from the Gamma Distribution.

      This implementation uses the following algorithms:

      For 0 invalid input: '<' shape invalid input: '<' 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.

      Parameters:
      shape - the median of the Gamma distribution
      scale - the scale parameter of the Gamma distribution
      Returns:
      random value sampled from the Gamma(shape, scale) distribution
      Throws:
      NotStrictlyPositiveException - if shape <= 0 or scale <= 0.
    • nextHypergeometric

      public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize) throws NotPositiveException, NotStrictlyPositiveException, NumberIsTooLargeException
      Generates a random value from the Hypergeometric Distribution.
      Parameters:
      populationSize - the population size of the Hypergeometric distribution
      numberOfSuccesses - number of successes in the population of the Hypergeometric distribution
      sampleSize - the sample size of the Hypergeometric distribution
      Returns:
      random value sampled from the Hypergeometric(numberOfSuccesses, sampleSize) distribution
      Throws:
      NumberIsTooLargeException - if numberOfSuccesses > populationSize, or sampleSize > populationSize.
      NotStrictlyPositiveException - if populationSize <= 0.
      NotPositiveException - if numberOfSuccesses < 0.
    • nextPascal

      public int nextPascal(int r, double p) throws NotStrictlyPositiveException, OutOfRangeException
      Generates a random value from the Pascal Distribution.
      Parameters:
      r - the number of successes of the Pascal distribution
      p - the probability of success of the Pascal distribution
      Returns:
      random value sampled from the Pascal(r, p) distribution
      Throws:
      NotStrictlyPositiveException - if the number of successes is not positive
      OutOfRangeException - if the probability of success is not in the range [0, 1].
    • nextT

      public double nextT(double df) throws NotStrictlyPositiveException
      Generates a random value from the T Distribution.
      Parameters:
      df - the degrees of freedom of the T distribution
      Returns:
      random value from the T(df) distribution
      Throws:
      NotStrictlyPositiveException - if df <= 0
    • nextWeibull

      public double nextWeibull(double shape, double scale) throws NotStrictlyPositiveException
      Generates a random value from the Weibull Distribution.
      Parameters:
      shape - the shape parameter of the Weibull distribution
      scale - the scale parameter of the Weibull distribution
      Returns:
      random value sampled from the Weibull(shape, size) distribution
      Throws:
      NotStrictlyPositiveException - if shape <= 0 or scale <= 0.
    • nextZipf

      public int nextZipf(int numberOfElements, double exponent) throws NotStrictlyPositiveException
      Generates a random value from the Zipf Distribution.
      Parameters:
      numberOfElements - the number of elements of the ZipfDistribution
      exponent - the exponent of the ZipfDistribution
      Returns:
      random value sampled from the Zipf(numberOfElements, exponent) distribution
      Throws:
      NotStrictlyPositiveException - if numberOfElements <= 0 or exponent <= 0.
    • nextBeta

      public double nextBeta(double alpha, double beta)
      Generates a random value from the Beta Distribution.
      Parameters:
      alpha - first distribution shape parameter
      beta - second distribution shape parameter
      Returns:
      random value sampled from the beta(alpha, beta) distribution
    • nextBinomial

      public int nextBinomial(int numberOfTrials, double probabilityOfSuccess)
      Generates a random value from the Binomial Distribution.
      Parameters:
      numberOfTrials - number of trials of the Binomial distribution
      probabilityOfSuccess - probability of success of the Binomial distribution
      Returns:
      random value sampled from the Binomial(numberOfTrials, probabilityOfSuccess) distribution
    • nextCauchy

      public double nextCauchy(double median, double scale)
      Generates a random value from the Cauchy Distribution.
      Parameters:
      median - the median of the Cauchy distribution
      scale - the scale parameter of the Cauchy distribution
      Returns:
      random value sampled from the Cauchy(median, scale) distribution
    • nextChiSquare

      public double nextChiSquare(double df)
      Generates a random value from the ChiSquare Distribution.
      Parameters:
      df - the degrees of freedom of the ChiSquare distribution
      Returns:
      random value sampled from the ChiSquare(df) distribution
    • nextF

      public double nextF(double numeratorDf, double denominatorDf) throws NotStrictlyPositiveException
      Generates a random value from the F Distribution.
      Parameters:
      numeratorDf - the numerator degrees of freedom of the F distribution
      denominatorDf - the denominator degrees of freedom of the F distribution
      Returns:
      random value sampled from the F(numeratorDf, denominatorDf) distribution
      Throws:
      NotStrictlyPositiveException - if numeratorDf <= 0 or denominatorDf <= 0.
    • nextUniform

      public double nextUniform(double lower, double upper) throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException
      Generates a uniformly distributed random value from the open interval (lower, upper) (i.e., endpoints excluded).

      Definition: Uniform Distribution lower and upper - lower are the location and scale parameters, respectively.

      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).

      Specified by:
      nextUniform in interface RandomData
      Parameters:
      lower - the exclusive lower bound of the support
      upper - the exclusive upper bound of the support
      Returns:
      a uniformly distributed random value between lower and upper (exclusive)
      Throws:
      NumberIsTooLargeException - if lower >= upper
      NotFiniteNumberException - if one of the bounds is infinite
      NotANumberException - if one of the bounds is NaN
    • nextUniform

      public double nextUniform(double lower, double upper, boolean lowerInclusive) throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException
      Generates a uniformly distributed random value from the interval (lower, upper) or the interval [lower, upper). The lower bound is thus optionally included, while the upper bound is always excluded.

      Definition: Uniform Distribution lower and upper - lower are the location and scale parameters, respectively.

      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).

      Specified by:
      nextUniform in interface RandomData
      Parameters:
      lower - the lower bound of the support
      upper - the exclusive upper bound of the support
      lowerInclusive - true if the lower bound is inclusive
      Returns:
      uniformly distributed random value in the (lower, upper) interval, if lowerInclusive is false, or in the [lower, upper) interval, if lowerInclusive is true
      Throws:
      NumberIsTooLargeException - if lower >= upper
      NotFiniteNumberException - if one of the bounds is infinite
      NotANumberException - if one of the bounds is NaN
    • nextPermutation

      public int[] nextPermutation(int n, int k) throws NumberIsTooLargeException, NotStrictlyPositiveException
      Generates an integer array of length k whose entries are selected randomly, without repetition, from the integers 0, ..., n - 1 (inclusive).

      Generated arrays represent permutations of n taken k at a time.

      This method calls MathArrays.shuffle in order to create a random shuffle of the set of natural numbers { 0, 1, ..., n - 1 }.
      Specified by:
      nextPermutation in interface RandomData
      Parameters:
      n - the domain of the permutation
      k - the size of the permutation
      Returns:
      a random k-permutation of n, as an array of integers
      Throws:
      NumberIsTooLargeException - if k > n.
      NotStrictlyPositiveException - if k <= 0.
    • nextSample

      public Object[] nextSample(Collection<?> c, int k) throws NumberIsTooLargeException, NotStrictlyPositiveException
      Returns an array of k objects selected randomly from the Collection c.

      Sampling from c is without replacement; but if c contains identical objects, the sample may include repeats. If all elements of c are distinct, the resulting object array represents a Simple Random Sample of size k from the elements of c.

      This method calls nextPermutation(c.size(), k) in order to sample the collection.
      Specified by:
      nextSample in interface RandomData
      Parameters:
      c - the collection to be sampled
      k - the size of the sample
      Returns:
      a random sample of k elements from c
      Throws:
      NumberIsTooLargeException - if k > c.size().
      NotStrictlyPositiveException - if k <= 0.
    • reSeed

      public void reSeed(long seed)
      Reseeds the random number generator with the supplied seed.

      Will create and initialize if null.

      Parameters:
      seed - the seed value to use
    • reSeedSecure

      public void reSeedSecure()
      Reseeds the secure random number generator with the current time in milliseconds.

      Will create and initialize if null.

    • reSeedSecure

      public void reSeedSecure(long seed)
      Reseeds the secure random number generator with the supplied seed.

      Will create and initialize if null.

      Parameters:
      seed - the seed value to use
    • reSeed

      public void reSeed()
      Reseeds the random number generator with System.currentTimeMillis() + System.identityHashCode(this)).
    • setSecureAlgorithm

      public void setSecureAlgorithm(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException
      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 invalid input: '&' Reference.

      USAGE NOTE: This method carries significant overhead and may take several seconds to execute.

      Parameters:
      algorithm - the name of the PRNG algorithm
      provider - the name of the provider
      Throws:
      NoSuchAlgorithmException - if the specified algorithm is not available
      NoSuchProviderException - if the specified provider is not installed
    • getRandomGenerator

      public RandomGenerator getRandomGenerator()
      Returns the RandomGenerator used to generate non-secure random data.

      Creates and initializes a default generator if null. Uses a Well19937c generator with System.currentTimeMillis() + System.identityHashCode(this)) as the default seed.

      Returns:
      the Random used to generate random data
      Since:
      3.2
    • initRan

      private void initRan()
      Sets the default generator to a Well19937c generator seeded with System.currentTimeMillis() + System.identityHashCode(this)).
    • getSecRan

      private RandomGenerator getSecRan()
      Returns the SecureRandom used to generate secure random data.

      Creates and initializes if null. Uses System.currentTimeMillis() + System.identityHashCode(this) as the default seed.

      Returns:
      the SecureRandom used to generate secure random data, wrapped in a RandomGenerator.