Class RandomUtil

java.lang.Object
edu.cmu.tetrad.util.RandomUtil
public class RandomUtil extends Object
Provides a common random number generator to be used throughout Tetrad, to avoid problems that happen when random number generators are created more often than once per millisecond. When this happens, the generators are synced, and there is less randomness than expected.

A seed can be set for the generator using the setSeed method. This is useful if an experiment needs to be repeated under different conditions. The seed for an experiment can be printed using the getSeed method.

Uses Apache Commons RNG XoRoShiRo128++ as the underlying generator.

To see what distributions are currently supported, look at the methods of the class. These may change over time.

Version:
$Id: $Id
Author:
josephramsey

  • Method Summary

    Modifier and Type
    Method
    Description
    static RandomUtil
    getInstance()
    Retrieves the singleton instance of RandomUtil associated with the current thread.
    org.apache.commons.math3.random.RandomGenerator
    getRandomGenerator()
    Retrieves the RandomGenerator instance being used.
    static void
    main(String[] args)
    The main method serves as the entry point for the program execution.
    double
    nextBeta(double alpha, double beta)
    Generates a random value sampled from a Beta distribution with the specified shape parameters.
    boolean
    nextBoolean()
    Generates a random boolean value.
    void
    nextBytes(byte[] bytes)
    Fills the given byte array with random bytes.
    double
    nextChiSquare(double df)
    Generates a random value from a chi-squared distribution with the specified degrees of freedom.
    double
    nextDouble()
    Generates the next pseudorandom double value between 0.0 (inclusive) and 1.0 (exclusive) from the underlying random number generator.
    double
    nextExponential(double scale)
    Generates a random value following an exponential distribution with the specified scale parameter.
    float
    nextFloat()
    Generates a random float value uniformly distributed in the range [0, 1).
    double
    nextGamma(double shape, double scale)
    Generates a random value following a Gamma distribution parameterized by the given shape and scale.
    double
    nextGaussian()
    Generates the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
    double
    nextGaussian(double mean, double sd)
    Generates a random value from a normal (Gaussian) distribution with the specified mean and standard deviation.
    double
    nextGumbel(double mu, double beta)
    Generates a random sample from the Gumbel distribution with the specified location and scale parameters.
    int
    nextInt()
    Generates the next pseudorandom integer.
    int
    nextInt(int n)
    Generates a random integer between 0 (inclusive) and the specified value (exclusive).
    double
    nextLaplace(double mu, double beta)
    Generates a random sample from the Laplace (double exponential) distribution with the specified location and scale parameters.
    long
    nextLong()
    Generates and returns the next pseudorandom long value from the underlying random number generator.
    double
    nextPoisson(double lambda)
    Generates a random value sampled from a Poisson distribution with the specified mean (lambda).
    double
    nextT(double df)
    Generates a random value sampled from a Student's t-distribution with the specified degrees of freedom.
    double
    nextTruncatedNormal(double mean, double sd, double low, double high)
    Generates a random value from a truncated normal (Gaussian) distribution with the specified mean, standard deviation, lower bound, and upper bound.
    double
    nextUniform(double low, double high)
    Generates a random double value uniformly distributed within the specified range [low, high].
    double
    normalCdf(double mean, double sd, double value)
    Computes the cumulative distribution function (CDF) of a normal (Gaussian) distribution with the specified mean and standard deviation at the given value.
    double
    normalPdf(double mean, double sd, double value)
    Computes the value of the Probability Density Function (PDF) of a normal (Gaussian) distribution with the specified mean and standard deviation at the given value.
    void
    revertSeed(long seed)
    Resets the internal random number generator with the specified seed value, ensuring deterministic behavior for subsequent random operations starting from this seed.
    void
    setSeed(long seed)
    Sets the seed to the given value.
    static void
    shuffle(List<?> list)
    This is just the Collections.shuffle logic but using Tetrad RandomUtil to get random numbers.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • getInstance

      public static RandomUtil getInstance()
      Retrieves the singleton instance of RandomUtil associated with the current thread.
      Returns:
      the RandomUtil instance associated with the current thread

    • shuffle

      public static void shuffle(List<?> list)
      This is just the Collections.shuffle logic but using Tetrad RandomUtil to get random numbers. The purpose is to allow shuffles to happen deterministically given the RandomUtil seed.
      Parameters:
      list - The list to be shuffled.

    • main

      public static void main(String[] args)
      The main method serves as the entry point for the program execution.
      Parameters:
      args - Command-line arguments passed to the program. These arguments are not used in this implementation.

    • nextInt

      public int nextInt(int n)
      Generates a random integer between 0 (inclusive) and the specified value (exclusive).
      Parameters:
      n - the upper bound (exclusive) for the random number; must be greater than 0
      Returns:
      a random integer between 0 (inclusive) and n (exclusive)
      Throws:
      IllegalArgumentException - if n is less than or equal to 0

    • nextInt

      public int nextInt()
      Generates the next pseudorandom integer.
      Returns:
      A pseudorandom integer produced by the internal random number generator.

    • nextDouble

      public double nextDouble()
      Generates the next pseudorandom double value between 0.0 (inclusive) and 1.0 (exclusive) from the underlying random number generator.
      Returns:
      a pseudorandom double value between 0.0 (inclusive) and 1.0 (exclusive)

    • nextFloat

      public float nextFloat()
      Generates a random float value uniformly distributed in the range [0, 1).
      Returns:
      a random float value in the range [0, 1)

    • nextBoolean

      public boolean nextBoolean()
      Generates a random boolean value.
      Returns:
      a randomly generated boolean value. The result is either true or false.

    • nextUniform

      public double nextUniform(double low, double high)
      Generates a random double value uniformly distributed within the specified range [low, high].
      Parameters:
      low - the lower bound of the range (inclusive).
      high - the upper bound of the range (inclusive when low equals high). Must be greater than or equal to low.
      Returns:
      a random double value within the range [low, high].
      Throws:
      IllegalArgumentException - if low > high.

    • nextGaussian

      public double nextGaussian(double mean, double sd)
      Generates a random value from a normal (Gaussian) distribution with the specified mean and standard deviation.
      Parameters:
      mean - the mean (or expectation) of the normal distribution.
      sd - the standard deviation of the normal distribution. Must be non-negative.
      Returns:
      a randomly generated double value from the normal distribution with the given parameters.
      Throws:
      IllegalArgumentException - if sd is negative.

    • nextTruncatedNormal

      public double nextTruncatedNormal(double mean, double sd, double low, double high)
      Generates a random value from a truncated normal (Gaussian) distribution with the specified mean, standard deviation, lower bound, and upper bound. The generated value will be within the range [low, high].
      Parameters:
      mean - the mean (or expectation) of the normal distribution.
      sd - the standard deviation of the normal distribution. Must be non-negative.
      low - the lower bound of the truncation interval. Must be less than high.
      high - the upper bound of the truncation interval. Must be greater than low.
      Returns:
      a randomly generated double value from the truncated normal distribution with the given parameters, constrained to the interval [low, high].
      Throws:
      IllegalArgumentException - if sd is negative, or if low >= high, or if mean is outside the interval [low, high] when sd is zero.

    • nextPoisson

      public double nextPoisson(double lambda)
      Generates a random value sampled from a Poisson distribution with the specified mean (lambda).
      Parameters:
      lambda - the mean (expected value) of the Poisson distribution. Must be greater than 0.
      Returns:
      a random double value sampled from the Poisson distribution with the specified mean (lambda).
      Throws:
      IllegalArgumentException - if lambda is not greater than 0.

    • normalPdf

      public double normalPdf(double mean, double sd, double value)
      Computes the value of the Probability Density Function (PDF) of a normal (Gaussian) distribution with the specified mean and standard deviation at the given value.
      Parameters:
      mean - the mean (or expectation) of the normal distribution
      sd - the standard deviation of the normal distribution. Must be greater than 0
      value - the point at which the PDF is evaluated
      Returns:
      the value of the normal distribution's PDF at the given point
      Throws:
      IllegalArgumentException - if sd is not greater than 0

    • normalCdf

      public double normalCdf(double mean, double sd, double value)
      Computes the cumulative distribution function (CDF) of a normal (Gaussian) distribution with the specified mean and standard deviation at the given value.
      Parameters:
      mean - the mean (or expectation) of the normal distribution.
      sd - the standard deviation of the normal distribution. Must be greater than 0.
      value - the point at which the CDF is evaluated.
      Returns:
      the cumulative probability of the normal distribution at the given point.
      Throws:
      IllegalArgumentException - if sd is not greater than 0.

    • nextBeta

      public double nextBeta(double alpha, double beta)
      Generates a random value sampled from a Beta distribution with the specified shape parameters.
      Parameters:
      alpha - the first shape parameter of the Beta distribution. Must be greater than 0.
      beta - the second shape parameter of the Beta distribution. Must be greater than 0.
      Returns:
      a random double value sampled from the Beta(alpha, beta) distribution.
      Throws:
      IllegalArgumentException - if alpha <= 0 or beta <= 0.

    • nextT

      public double nextT(double df)
      Generates a random value sampled from a Student's t-distribution with the specified degrees of freedom.
      Parameters:
      df - the degrees of freedom for the t-distribution. Must be greater than 0.
      Returns:
      a random double value sampled from the t-distribution with the given degrees of freedom.
      Throws:
      IllegalArgumentException - if df <= 0.

    • nextExponential

      public double nextExponential(double scale)
      Generates a random value following an exponential distribution with the specified scale parameter.
      Parameters:
      scale - the scale parameter of the exponential distribution; must be greater than 0
      Returns:
      a randomly generated value from the exponential distribution
      Throws:
      IllegalArgumentException - if the scale parameter is not greater than 0

    • nextGumbel

      public double nextGumbel(double mu, double beta)
      Generates a random sample from the Gumbel distribution with the specified location and scale parameters.
      Parameters:
      mu - the location parameter of the Gumbel distribution
      beta - the scale parameter of the Gumbel distribution; must be greater than 0
      Returns:
      a random sample from the Gumbel distribution
      Throws:
      IllegalArgumentException - if the scale parameter beta is not greater than 0

    • nextLaplace

      public double nextLaplace(double mu, double beta)
      Generates a random sample from the Laplace (double exponential) distribution with the specified location and scale parameters. The variance of this distribution is 2 * beta^2.
      Parameters:
      mu - the location parameter of the Laplace distribution
      beta - the scale parameter of the Laplace distribution; must be greater than 0
      Returns:
      a random sample from the Laplace distribution
      Throws:
      IllegalArgumentException - if the scale parameter beta is not greater than 0

    • nextChiSquare

      public double nextChiSquare(double df)
      Generates a random value from a chi-squared distribution with the specified degrees of freedom.
      Parameters:
      df - The degrees of freedom for the chi-squared distribution. Must be greater than zero.
      Returns:
      A random value sampled from the chi-squared distribution.
      Throws:
      IllegalArgumentException - If the degrees of freedom (df) is less than or equal to zero.

    • nextGamma

      public double nextGamma(double shape, double scale)
      Generates a random value following a Gamma distribution parameterized by the given shape and scale.
      Parameters:
      shape - the shape parameter of the Gamma distribution; must be greater than 0
      scale - the scale parameter of the Gamma distribution; must be greater than 0
      Returns:
      a random value sampled from the Gamma distribution
      Throws:
      IllegalArgumentException - if the shape or scale parameter is not greater than 0

    • setSeed

      public void setSeed(long seed)
      Sets the seed to the given value.
      Parameters:
      seed - A long value. Once this seed is set, behavior is deterministic.

    • revertSeed

      public void revertSeed(long seed)
      Resets the internal random number generator with the specified seed value, ensuring deterministic behavior for subsequent random operations starting from this seed.
      Parameters:
      seed - the seed value to initialize the random generator. Must be a long value.

    • getRandomGenerator

      public org.apache.commons.math3.random.RandomGenerator getRandomGenerator()
      Retrieves the RandomGenerator instance being used.
      Returns:
      the RandomGenerator instance maintained by this class

    • nextLong

      public long nextLong()
      Generates and returns the next pseudorandom long value from the underlying random number generator.
      Returns:
      a pseudorandom long value generated by the random number generator.

    • nextBytes

      public void nextBytes(byte[] bytes)
      Fills the given byte array with random bytes.
      Parameters:
      bytes - target array

    • nextGaussian

      public double nextGaussian()
      Generates the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
      Returns:
      a pseudorandom, Gaussian-distributed double value with mean 0.0 and standard deviation 1.0