Module org.cicirello.rho_mu
Package org.cicirello.math.rand

Class EnhancedRandomGenerator

java.lang.Object
org.cicirello.math.rand.EnhancedRandomGenerator
All Implemented Interfaces:
RandomGenerator
Direct Known Subclasses:
EnhancedStreamableGenerator
public class EnhancedRandomGenerator extends Object implements RandomGenerator
An EnhancedRandomGenerator is used to wrap an object of any class that implements RandomGenerator for the purpose of adding all of the functionality of the RandomIndexer, RandomSampler, and RandomVariates. In this way, the EnhancedRandomGenerator can be used as a drop-in replacement for any of Java's random number generators, while substituting more efficient algorithms in some cases, or adding functionality in others. Methods of the RandomGenerator without equivalent replacements in one of RandomIndexer, RandomSampler, or RandomVariates are simply delegated to the wrapped RandomGenerator.

Enhanced Functionality provided by this class includes:

  • Faster generation of random int values subject to a bound or bound and origin.
  • Faster generation of random int values within an IntStream subject to a bound and origin.
  • Faster generation of Gaussian distributed random doubles.
  • Additional distributions available beyond what is supported by the Java API's RandomGenerator classes, such as Binomial and Cauchy random vaiables.
  • Ultrafast, but biased, nextBiasedInt methods that sacrifices uniformity for speed by excluding the rejection sampling necessary to ensure uniformity, as well as a biasedInts methods for generating streams of such integers.
  • Methods for generating random pairs of integers without replacement, and random triples of integers without replacement.
  • Methods for generating random samples of k integers without replacement from a range of integers.
  • Methods to generate streams of numbers from distributions other than uniform, such as streams of random numbers from binomial distributions, Cauchy distributions, exponential distributions, and Gaussian distributions.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface java.util.random.RandomGenerator

    RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator

  • Constructor Summary

    Constructors
    Constructor
    Description
    EnhancedRandomGenerator()
    Constructs the EnhancedRandomGenerator to wrap an instance of the default random number generator as obtained via a call to RandomGenerator.getDefault().
    EnhancedRandomGenerator(long seed)
    Constructs the EnhancedRandomGenerator to wrap an instance of a random number generator initialized with a specified seed to enable replicating the same sequence of random numbers during subsequent runs.
    EnhancedRandomGenerator(String algorithmName)
    Constructs the EnhancedRandomGenerator to wrap an instance of any random number generator supported by your version of Java as specified by its name, as documented via the RandomGenerator.of(java.lang.String) method.
    EnhancedRandomGenerator(RandomGenerator generator)
    Constructs the EnhancedRandomGenerator from the RandomGenerator to wrap.

  • Method Summary

    Modifier and Type
    Method
    Description
    final boolean[]
    arrayMask(int n)
    Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.
    final boolean[]
    arrayMask(int n, double p)
    Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.
    final boolean[]
    arrayMask(int n, int k)
    Generates an "array mask" of a specified length and specified number of true values, where an "array mask" is an array of boolean values of the same length as another array.
    final IntStream
    biasedInts(int randomNumberOrigin, int randomNumberBound)
    Returns an effectively unlimited stream of pseudorandom int values, each value random from the interval [randomNumberOrigin, randomNumberBound).
    final IntStream
    biasedInts(long streamSize, int randomNumberOrigin, int randomNumberBound)
    Returns a stream of pseudorandom int values, each value random from the interval [randomNumberOrigin, randomNumberBound).
    final IntStream
    binomials(int n, double p)
    Returns an effectively unlimited stream of pseudorandom int values, each value generated from a binomial distribution.
    final IntStream
    binomials(long streamSize, int n, double p)
    Returns a stream of pseudorandom int values, each value generated from a binomial distribution.
    final DoubleStream
    cauchys(double median, double scale)
    Returns an effectively unlimited stream of pseudorandom double values from a Cauchy distribution.
    final DoubleStream
    cauchys(long streamSize, double median, double scale)
    Returns a stream of pseudorandom double values from a Cauchy distribution.
    final DoubleStream
    doubles()
    Returns an effectively unlimited stream of pseudorandom double values, each value uniformly random from the interval [0.0, 1.0).
    final DoubleStream
    doubles(double randomNumberOrigin, double randomNumberBound)
    Returns an effectively unlimited stream of pseudorandom double values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).
    final DoubleStream
    doubles(long streamSize)
    Returns a stream of pseudorandom double values, each value uniformly random from the interval [0.0, 1.0).
    final DoubleStream
    doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
    Returns a stream of pseudorandom double values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).
    final DoubleStream
    exponentials()
    Returns an effectively unlimited stream of pseudorandom non-negative double values from an exponential distribution with mean 1.
    final DoubleStream
    exponentials(long streamSize)
    Returns a stream of pseudorandom non-negative double values from an exponential distribution with mean 1.
    final DoubleStream
    gaussians()
    Returns an effectively unlimited stream of pseudorandom double values from a Gaussian distribution with mean 0 and standard deviation 1.
    final DoubleStream
    gaussians(double mean, double stdev)
    Returns an effectively unlimited stream of pseudorandom double values from a Gaussian distribution with specified mean and standard deviation.
    final DoubleStream
    gaussians(long streamSize)
    Returns a stream of pseudorandom non-negative double values from a Gaussian distribution with mean 0 and standard deviation 1.
    final DoubleStream
    gaussians(long streamSize, double mean, double stdev)
    Returns a stream of pseudorandom double values from a Gaussian distribution with specified mean and standard deviation.
    static EnhancedRandomGenerator
    getDefault()
    Gets an EnhancedRandomGenerator wrapping an instance of the default random number generator as obtained via a call to RandomGenerator.getDefault().
    final IntStream
    ints()
    Returns an effectively unlimited stream of pseudorandom int values.
    final IntStream
    ints(int randomNumberOrigin, int randomNumberBound)
    Returns an effectively unlimited stream of pseudorandom int values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).
    final IntStream
    ints(long streamSize)
    Returns a stream of pseudorandom int values.
    final IntStream
    ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
    Returns a stream of pseudorandom int values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).
    final LongStream
    longs()
    Returns an effectively unlimited stream of pseudorandom long values.
    final LongStream
    longs(long streamSize)
    Returns a stream of pseudorandom long values.
    final LongStream
    longs(long randomNumberOrigin, long randomNumberBound)
    Returns an effectively unlimited stream of pseudorandom long values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).
    final LongStream
    longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
    Returns a stream of pseudorandom long values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).
    final int
    nextBiasedInt(int bound)
    Generates a random integer in the interval: [0, bound).
    final int
    nextBiasedInt(int origin, int bound)
    Generates a random integer in the interval: [origin, bound).
    final int
    nextBinomial(int n, double p)
    Generates a pseudorandom integer from a binomial distribution.
    final boolean
    nextBoolean()
    Generates a pseudorandom boolean value.
    final void
    nextBytes(byte[] bytes)
    Fills a user-supplied byte array with byte values generated pseudorandomly uniformly distributed in the interval [-128, 127].
    final double
    nextCauchy(double scale)
    Generates a pseudorandom number from a Cauchy distribution with median 0 and chosen scale parameter.
    final double
    nextCauchy(double median, double scale)
    Generates a pseudorandom number from a Cauchy distribution.
    final double
    nextDouble()
    Generates a pseudorandom double value in the interval [0, 1).
    final double
    nextDouble(double bound)
    Generates a pseudorandom double value in the interval [0, bound).
    final double
    nextDouble(double origin, double bound)
    Generates a pseudorandom double value in the interval [origin, bound).
    final double
    nextExponential()
    Generates a non-negative pseudorandom number from an exponential distribution with mean 1.
    final float
    nextFloat()
    Generates a pseudorandom float value in the interval [0, 1).
    final float
    nextFloat(float bound)
    Generates a pseudorandom float value in the interval [0, bound).
    final float
    nextFloat(float origin, float bound)
    Generates a pseudorandom float value in the interval [origin, bound).
    final double
    nextGaussian()
    Generates a random number from a Gaussian distribution with mean 0 and standard deviation 1.
    final double
    nextGaussian(double stddev)
    Generates a random number from a Gaussian distribution with mean 0 and standard deviation, stddev, of your choosing.
    final double
    nextGaussian(double mean, double stddev)
    Generates a random number from a Gaussian distribution with mean and standard deviation of your choosing.
    final int
    nextInt()
    Generates a pseudorandom int value.
    final int
    nextInt(int bound)
    Generates a random integer uniformly distributed in the interval: [0, bound).
    final int
    nextInt(int origin, int bound)
    Generates a random integer uniformly distributed in the interval: [origin, bound).
    final int[]
    nextIntPair(int n, int[] result)
    Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n).
    final int[]
    nextIntTriple(int n, int[] result)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    final int[]
    nextIntTriple(int n, int[] result, boolean sort)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    final long
    nextLong()
    Generates a pseudorandom long value.
    final long
    nextLong(long bound)
    Generates a pseudorandom long value in the interval [0, bound).
    final long
    nextLong(long origin, long bound)
    Generates a pseudorandom long value in the interval [origin, bound).
    final int[]
    nextWindowedIntPair(int n, int window, int[] result)
    Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window.
    final int[]
    nextWindowedIntTriple(int n, int window, int[] result)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    final int[]
    nextWindowedIntTriple(int n, int window, int[] result, boolean sort)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static EnhancedRandomGenerator
    of(String algorithmName)
    Gets an EnhancedRandomGenerator wrapping an instance of any random number generator supported by your version of Java as specified by its name, as documented via the RandomGenerator.of(java.lang.String) method.
    final int[]
    sample(int n, double p)
    Generates a random sample, without replacement, from the set of integers in the interval [0, n).
    final int[]
    sample(int n, int k, int[] result)
    Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n).
    final int[]
    sampleInsertion(int n, int k, int[] result)
    Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n).
    final int[]
    samplePool(int n, int k, int[] result)
    Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n).
    final int[]
    sampleReservoir(int n, int k, int[] result)
    Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n).

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.random.RandomGenerator

    isDeprecated

  • Constructor Details

    • EnhancedRandomGenerator

      public EnhancedRandomGenerator()
      Constructs the EnhancedRandomGenerator to wrap an instance of the default random number generator as obtained via a call to RandomGenerator.getDefault().

    • EnhancedRandomGenerator

      public EnhancedRandomGenerator(long seed)
      Constructs the EnhancedRandomGenerator to wrap an instance of a random number generator initialized with a specified seed to enable replicating the same sequence of random numbers during subsequent runs.
      Parameters:
      seed - The seed for the random number generator.

    • EnhancedRandomGenerator

      public EnhancedRandomGenerator(RandomGenerator generator)
      Constructs the EnhancedRandomGenerator from the RandomGenerator to wrap.
      Parameters:
      generator - The RandomGenerator to wrap, which serves as the source of randomness.

    • EnhancedRandomGenerator

      public EnhancedRandomGenerator(String algorithmName)
      Constructs the EnhancedRandomGenerator to wrap an instance of any random number generator supported by your version of Java as specified by its name, as documented via the RandomGenerator.of(java.lang.String) method.
      Parameters:
      algorithmName - The name of the random number generator as documented by the RandomGenerator.of(java.lang.String) method.
      Throws:
      NullPointerException - if algorithmName is null.
      IllegalArgumentException - if algorithmName is not found.

  • Method Details

    • getDefault

      public static EnhancedRandomGenerator getDefault()
      Gets an EnhancedRandomGenerator wrapping an instance of the default random number generator as obtained via a call to RandomGenerator.getDefault().
      Returns:
      an EnhancedRandomGenerator wrapping an instance of the default random number generator

    • of

      public static EnhancedRandomGenerator of(String algorithmName)
      Gets an EnhancedRandomGenerator wrapping an instance of any random number generator supported by your version of Java as specified by its name, as documented via the RandomGenerator.of(java.lang.String) method.
      Parameters:
      algorithmName - The name of the random number generator as documented by the RandomGenerator.of(java.lang.String) method.
      Returns:
      an EnhancedRandomGenerator wrapping an instance of your chosen random number generator.
      Throws:
      NullPointerException - if algorithmName is null.
      IllegalArgumentException - if algorithmName is not found.

    • arrayMask

      public final boolean[] arrayMask(int n)
      Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array. Each position in the result is equally likely true or false. Enhanced Functionality.

      Runtime: O(n).

      Parameters:
      n - The length of the array mask.
      Returns:
      An array of n randomly generated boolean values.

    • arrayMask

      public final boolean[] arrayMask(int n, int k)
      Generates an "array mask" of a specified length and specified number of true values, where an "array mask" is an array of boolean values of the same length as another array. Enhanced Functionality.

      Runtime: O(min(n, k2)), and it uses O(min(k, n-k)) random numbers.

      Parameters:
      n - The length of the array mask.
      k - The desired number of true values, which must be no greater than n.
      Returns:
      An array of n boolean values, exactly k of which are equal to true.

    • arrayMask

      public final boolean[] arrayMask(int n, double p)
      Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array. Enhanced Functionality.

      Runtime: O(n), and it uses O(n) random doubles.

      Parameters:
      n - The length of the array mask.
      p - The probability that an element of the result is true.
      Returns:
      An array of n boolean values, such that each element is true with probability p.

    • biasedInts

      public final IntStream biasedInts(int randomNumberOrigin, int randomNumberBound)
      Returns an effectively unlimited stream of pseudorandom int values, each value random from the interval [randomNumberOrigin, randomNumberBound).

      Enhanced Functionality: Each int produced by the stream is generated by an implementation of a variation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. The difference between this implementation and that algorithm is that we have removed the rejection sampling to create an ultrafast, but not strictly uniform, stream of random integers. If you require strict uniformity, then use the ints(int, int) method instead.

      Parameters:
      randomNumberOrigin - The lower bound, inclusive (must be less than bound)
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      an effectively unlimited stream of pseudorandom int values, random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound

    • biasedInts

      public final IntStream biasedInts(long streamSize, int randomNumberOrigin, int randomNumberBound)
      Returns a stream of pseudorandom int values, each value random from the interval [randomNumberOrigin, randomNumberBound).

      Enhanced Functionality: Each int produced by the stream is generated by an implementation of a variation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. The difference between this implementation and that algorithm is that we have removed the rejection sampling to create an ultrafast, but not strictly uniform, stream of random integers. If you require strict uniformity, then use the ints(long, int, int) method instead.

      Parameters:
      streamSize - The number of values in the stream.
      randomNumberOrigin - The lower bound, inclusive (must be less than bound).
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      a stream of pseudorandom int values, random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound, or if streamSize is negative.

    • binomials

      public final IntStream binomials(int n, double p)
      Returns an effectively unlimited stream of pseudorandom int values, each value generated from a binomial distribution. Enhanced Functionality.
      Parameters:
      n - Number of trials for the binomial distribution.
      p - The probability of a successful trial.
      Returns:
      an effectively unlimited stream of pseudorandom int values generated from a binomial distribution.

    • binomials

      public final IntStream binomials(long streamSize, int n, double p)
      Returns a stream of pseudorandom int values, each value generated from a binomial distribution. Enhanced Functionality.
      Parameters:
      streamSize - The number of values in the stream.
      n - Number of trials for the binomial distribution.
      p - The probability of a successful trial.
      Returns:
      a stream of pseudorandom int values generated from a binomial distribution.

    • cauchys

      public final DoubleStream cauchys(double median, double scale)
      Returns an effectively unlimited stream of pseudorandom double values from a Cauchy distribution. Enhanced Functionality.
      Parameters:
      median - The median of the Cauchy distribution.
      scale - The scale of the Cauchy distribution.
      Returns:
      an effectively unlimited stream of pseudorandom double values from a Cauchy distribution.

    • cauchys

      public final DoubleStream cauchys(long streamSize, double median, double scale)
      Returns a stream of pseudorandom double values from a Cauchy distribution. Enhanced Functionality.
      Parameters:
      streamSize - The number of values in the stream.
      median - The median of the Cauchy distribution.
      scale - The scale of the Cauchy distribution.
      Returns:
      a stream of pseudorandom double values from a Cauchy distribution.

    • exponentials

      public final DoubleStream exponentials()
      Returns an effectively unlimited stream of pseudorandom non-negative double values from an exponential distribution with mean 1. Enhanced Functionality.
      Returns:
      an effectively unlimited stream of pseudorandom double values from an exponential distribution with mean 1.

    • exponentials

      public final DoubleStream exponentials(long streamSize)
      Returns a stream of pseudorandom non-negative double values from an exponential distribution with mean 1. Enhanced Functionality.
      Parameters:
      streamSize - The number of values in the stream.
      Returns:
      a stream of pseudorandom double values from an exponential distribution with mean 1.

    • gaussians

      public final DoubleStream gaussians()
      Returns an effectively unlimited stream of pseudorandom double values from a Gaussian distribution with mean 0 and standard deviation 1. Enhanced Functionality.
      Returns:
      an effectively unlimited stream of pseudorandom double values from a Gaussian distribution with mean 0 and standard deviation 1.

    • gaussians

      public final DoubleStream gaussians(double mean, double stdev)
      Returns an effectively unlimited stream of pseudorandom double values from a Gaussian distribution with specified mean and standard deviation. Enhanced Functionality.
      Parameters:
      mean - The mean of the Gaussian.
      stdev - The standard deviation of the Gaussian.
      Returns:
      an effectively unlimited stream of pseudorandom double values from a Gaussian distribution with specified mean and standard deviation.

    • gaussians

      public final DoubleStream gaussians(long streamSize, double mean, double stdev)
      Returns a stream of pseudorandom double values from a Gaussian distribution with specified mean and standard deviation. Enhanced Functionality.
      Parameters:
      streamSize - The number of values in the stream.
      mean - The mean of the Gaussian.
      stdev - The standard deviation of the Gaussian.
      Returns:
      a stream of pseudorandom double values from a Gaussian distribution with specified mean and standard deviation.

    • gaussians

      public final DoubleStream gaussians(long streamSize)
      Returns a stream of pseudorandom non-negative double values from a Gaussian distribution with mean 0 and standard deviation 1. Enhanced Functionality.
      Parameters:
      streamSize - The number of values in the stream.
      Returns:
      a stream of pseudorandom double values from a Gaussian distribution with mean 0 and standard deviation 1.

    • nextBiasedInt

      public final int nextBiasedInt(int bound)
      Generates a random integer in the interval: [0, bound). Enhanced Functionality.

      The nextBiasedInt(bound) method computes a random int in the target interval but faster than nextInt(bound). It does not correct for bias via rejection sampling, and thus some values in the interval [0, bound) may be more likely than others. There is no bias for bound values that are powers of 2. Otherwise, the lower the value of bound, the less bias; and the higher the value of bound, the more bias. If your bound is relatively low, and if your application does not require strict uniformity, then this method is significantly faster than any approach that corrects for bias. We started with the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. But we removed from it the rejection sampling portion.

      Parameters:
      bound - Upper bound, exclusive, on range of random integers (must be positive).
      Returns:
      a random integer between 0 (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not positive

    • nextBiasedInt

      public final int nextBiasedInt(int origin, int bound)
      Generates a random integer in the interval: [origin, bound). Enhanced Functionality.

      The nextBiasedInt(origin, bound) method computes a random int in the target interval but faster than nextInt(origin, bound). It does not correct for bias via rejection sampling, and thus some values in the interval [origin, bound) may be more likely than others. There is no bias interval width is a power of 2. Otherwise, the smaller the interval, the less bias; and the larger the interval, the more bias. If your interval is relatively low, and if your application does not require strict uniformity, then this method is significantly faster than any approach that corrects for bias. We started with the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. But we removed from it the rejection sampling portion.

      Parameters:
      origin - Lower bound, inclusive, on range of random integers.
      bound - Upper bound, exclusive, on range of random integers (must be greater than origin).
      Returns:
      a random integer between origin (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not greater than origin

    • nextBinomial

      public final int nextBinomial(int n, double p)
      Generates a pseudorandom integer from a binomial distribution. Enhanced Functionality.
      Parameters:
      n - Number of trials for the binomial distribution.
      p - The probability of a successful trial.
      Returns:
      A pseudorandom integer from a binomial distribution.

    • nextCauchy

      public final double nextCauchy(double scale)
      Generates a pseudorandom number from a Cauchy distribution with median 0 and chosen scale parameter. Enhanced Functionality.
      Parameters:
      scale - The scale parameter of the Cauchy.
      Returns:
      a pseudorandom number from a Cauchy distribution

    • nextCauchy

      public final double nextCauchy(double median, double scale)
      Generates a pseudorandom number from a Cauchy distribution. Enhanced Functionality.
      Parameters:
      median - The median of the Cauchy.
      scale - The scale parameter of the Cauchy.
      Returns:
      a pseudorandom number from a Cauchy distribution

    • nextGaussian

      public final double nextGaussian(double stddev)
      Generates a random number from a Gaussian distribution with mean 0 and standard deviation, stddev, of your choosing.

      Enhanced Functionality: This method uses the library's current most-efficient algorithm for Gaussian random number generation, which may change in future releases. If you require a guarantee of the algorithm used, then see the API for the classes that implement specific Gaussian algorithms.

      Parameters:
      stddev - The standard deviation of the Gaussian.
      Returns:
      A random number from a Gaussian distribution with mean 0 and standard deviation stddev.

    • nextIntPair

      public final int[] nextIntPair(int n, int[] result)
      Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n). All n choose 2 combinations are equally likely. Enhanced Functionality.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      Returns:
      An array containing the pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextIntTriple

      public final int[] nextIntTriple(int n, int[] result)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely. Enhanced Functionality.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      Returns:
      An array containing the pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextIntTriple

      public final int[] nextIntTriple(int n, int[] result, boolean sort)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely. Enhanced Functionality.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      sort - If true, the result is sorted in increasing order; otherwise it is in arbitrary order.
      Returns:
      An array containing the pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextWindowedIntPair

      public final int[] nextWindowedIntPair(int n, int window, int[] result)
      Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window. All pairs that satisfy the window constraint are equally likely. Enhanced Functionality.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      Returns:
      An array containing the pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextWindowedIntTriple

      public final int[] nextWindowedIntTriple(int n, int window, int[] result)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely. Enhanced Functionality.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      Returns:
      An array containing the triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextWindowedIntTriple

      public final int[] nextWindowedIntTriple(int n, int window, int[] result, boolean sort)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely. Enhanced Functionality.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      sort - If true, the result is sorted in increasing order, otherwise it is in random order.
      Returns:
      An array containing the triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • sample

      public final int[] sample(int n, double p)
      Generates a random sample, without replacement, from the set of integers in the interval [0, n). Each of the n integers has a probability p of inclusion in the sample. Enhanced Functionality.
      Parameters:
      n - The number of integers to choose from.
      p - The probability that each of the n integers is included in the sample.
      Returns:
      An array containing the sample.

    • sample

      public final int[] sample(int n, int k, int[] result)
      Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n). All n choose k combinations are equally likely. Enhanced Functionality.

      This method chooses among the samplePool(int, int, int[]), sampleReservoir(int, int, int[]), and sampleInsertion(int, int, int[]) methods based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      Parameters:
      n - The number of integers to choose from.
      k - The size of the desired sample.
      result - An array to hold the sample that is generated. If result is null or if result.length is less than k, then this method will construct an array for the result.
      Returns:
      An array containing the sample of k randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if k > n.
      NegativeArraySizeException - if k < 0.

    • sampleInsertion

      public final int[] sampleInsertion(int n, int k, int[] result)
      Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n). All n choose k combinations are equally likely. Enhanced Functionality.

      This implements the insertion sampling algorithm described in:

      Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(k2) and it generates O(k) random numbers. Thus, it is a better choice than both sampleReservoir and samplePool when k2 < n. Just like sampleReservoir, the sampleInsertion method only requires O(1) extra space, while samplePool requires O(n) extra space.

      Parameters:
      n - The number of integers to choose from.
      k - The size of the desired sample.
      result - An array to hold the sample that is generated. If result is null or if result.length is less than k, then this method will construct an array for the result.
      Returns:
      An array containing the sample of k randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if k > n.
      NegativeArraySizeException - if k < 0.

    • samplePool

      public final int[] samplePool(int n, int k, int[] result)
      Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n). All n choose k combinations are equally likely. Enhanced Functionality.

      This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal, 25(1):45-47, 1982.

      The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than sampleReservoir when k < n-k. However, this uses O(n) extra space, whereas the reservoir algorithm uses no extra space.

      Parameters:
      n - The number of integers to choose from.
      k - The size of the desired sample.
      result - An array to hold the sample that is generated. If result is null or if result.length is less than k, then this method will construct an array for the result.
      Returns:
      An array containing the sample of k randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if k > n.
      NegativeArraySizeException - if k < 0.

    • sampleReservoir

      public final int[] sampleReservoir(int n, int k, int[] result)
      Generates a random sample of k integers, without replacement, from the set of integers in the interval [0, n). All n choose k combinations are equally likely. Enhanced Functionality.

      Uses the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software.

      The runtime is O(n) and it generates O(n-k) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

      Parameters:
      n - The number of integers to choose from.
      k - The size of the desired sample.
      result - An array to hold the sample that is generated. If result is null or if result.length is less than k, then this method will construct an array for the result.
      Returns:
      An array containing the sample of k randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if k > n.
      NegativeArraySizeException - if k < 0.

    • nextGaussian

      public final double nextGaussian()
      Generates a random number from a Gaussian distribution with mean 0 and standard deviation 1.

      Enhanced Functionality: This method uses the library's current most-efficient algorithm for Gaussian random number generation, which may change in future releases. If you require a guarantee of the algorithm used, then see the API for the classes that implement specific Gaussian algorithms.

      Specified by:
      nextGaussian in interface RandomGenerator
      Returns:
      A random number from a Gaussian distribution with mean 0 and standard deviation 1.

    • nextGaussian

      public final double nextGaussian(double mean, double stddev)
      Generates a random number from a Gaussian distribution with mean and standard deviation of your choosing.

      Enhanced Functionality: This method uses the library's current most-efficient algorithm for Gaussian random number generation, which may change in future releases. If you require a guarantee of the algorithm used, then see the API for the classes that implement specific Gaussian algorithms.

      Specified by:
      nextGaussian in interface RandomGenerator
      Parameters:
      mean - The mean of the Gaussian.
      stddev - The standard deviation of the Gaussian.
      Returns:
      A random number from a Gaussian distribution with mean 0 and standard deviation stddev.

    • nextInt

      public final int nextInt(int bound)
      Generates a random integer uniformly distributed in the interval: [0, bound).

      Enhanced Functionality: This method is an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      Specified by:
      nextInt in interface RandomGenerator
      Parameters:
      bound - Upper bound, exclusive, on range of random integers (must be positive).
      Returns:
      a random integer between 0 (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not positive

    • nextInt

      public final int nextInt(int origin, int bound)
      Generates a random integer uniformly distributed in the interval: [origin, bound).

      Enhanced Functionality: This method is an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      Specified by:
      nextInt in interface RandomGenerator
      Parameters:
      origin - The lower bound, inclusive (must be less than bound)
      bound - Upper bound, exclusive, on range of random integers.
      Returns:
      a random integer between 0 (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the origin is greater than or equal to bound

    • ints

      public final IntStream ints(int randomNumberOrigin, int randomNumberBound)
      Returns an effectively unlimited stream of pseudorandom int values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).

      Enhanced Functionality: Each int produced by the stream is generated by an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      Specified by:
      ints in interface RandomGenerator
      Parameters:
      randomNumberOrigin - The lower bound, inclusive (must be less than bound)
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      an effectively unlimited stream of pseudorandom int values, uniformly random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound

    • ints

      public final IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
      Returns a stream of pseudorandom int values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound).

      Enhanced Functionality: Each int produced by the stream is generated by an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      Specified by:
      ints in interface RandomGenerator
      Parameters:
      streamSize - The number of values in the stream.
      randomNumberOrigin - The lower bound, inclusive (must be less than bound).
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      a stream of pseudorandom int values, uniformly random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound, or if streamSize is negative.

    • doubles

      public final DoubleStream doubles()
      Returns an effectively unlimited stream of pseudorandom double values, each value uniformly random from the interval [0.0, 1.0). Delegates implementation to the wrapped object.
      Specified by:
      doubles in interface RandomGenerator
      Returns:
      an effectively unlimited stream of pseudorandom double values, uniformly random from the interval [0.0, 1.0).

    • doubles

      public final DoubleStream doubles(double randomNumberOrigin, double randomNumberBound)
      Returns an effectively unlimited stream of pseudorandom double values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound). Delegates implementation to the wrapped object.
      Specified by:
      doubles in interface RandomGenerator
      Parameters:
      randomNumberOrigin - The lower bound, inclusive (must be less than bound)
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      an effectively unlimited stream of pseudorandom double values, uniformly random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound, or if randomNumberOrigin is not finite. or if randomNumberBound is not finite.

    • doubles

      public final DoubleStream doubles(long streamSize)
      Returns a stream of pseudorandom double values, each value uniformly random from the interval [0.0, 1.0). Delegates implementation to the wrapped object.
      Specified by:
      doubles in interface RandomGenerator
      Parameters:
      streamSize - The number of values in the stream.
      Returns:
      a stream of pseudorandom double values, uniformly random from the interval [0.0, 1.0).
      Throws:
      IllegalArgumentException - if streamSize is negative.

    • doubles

      public final DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
      Returns a stream of pseudorandom double values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound). Delegates implementation to the wrapped object.
      Specified by:
      doubles in interface RandomGenerator
      Parameters:
      streamSize - The number of values in the stream.
      randomNumberOrigin - The lower bound, inclusive (must be less than bound).
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      a stream of pseudorandom double values, uniformly random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound, or if streamSize is negative.

    • ints

      public final IntStream ints()
      Returns an effectively unlimited stream of pseudorandom int values. Delegates implementation to the wrapped object.
      Specified by:
      ints in interface RandomGenerator
      Returns:
      an effectively unlimited stream of pseudorandom int values.

    • ints

      public final IntStream ints(long streamSize)
      Returns a stream of pseudorandom int values. Delegates implementation to the wrapped object.
      Specified by:
      ints in interface RandomGenerator
      Parameters:
      streamSize - The number of values in the stream.
      Returns:
      a stream of pseudorandom int values.
      Throws:
      IllegalArgumentException - if streamSize is negative.

    • longs

      public final LongStream longs()
      Returns an effectively unlimited stream of pseudorandom long values. Delegates implementation to the wrapped object.
      Specified by:
      longs in interface RandomGenerator
      Returns:
      an effectively unlimited stream of pseudorandom long values.

    • longs

      public final LongStream longs(long randomNumberOrigin, long randomNumberBound)
      Returns an effectively unlimited stream of pseudorandom long values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound). Delegates implementation to the wrapped object.
      Specified by:
      longs in interface RandomGenerator
      Parameters:
      randomNumberOrigin - The lower bound, inclusive (must be less than bound)
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      an effectively unlimited stream of pseudorandom long values, uniformly random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound

    • longs

      public final LongStream longs(long streamSize)
      Returns a stream of pseudorandom long values. Delegates implementation to the wrapped object.
      Specified by:
      longs in interface RandomGenerator
      Parameters:
      streamSize - The number of values in the stream.
      Returns:
      a stream of pseudorandom long values.
      Throws:
      IllegalArgumentException - if streamSize is negative.

    • longs

      public final LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
      Returns a stream of pseudorandom long values, each value uniformly random from the interval [randomNumberOrigin, randomNumberBound). Delegates implementation to the wrapped object.
      Specified by:
      longs in interface RandomGenerator
      Parameters:
      streamSize - The number of values in the stream.
      randomNumberOrigin - The lower bound, inclusive (must be less than bound).
      randomNumberBound - Upper bound, exclusive, on range of random integers.
      Returns:
      a stream of pseudorandom long values, uniformly random from the interval [randomNumberOrigin, randomNumberBound).
      Throws:
      IllegalArgumentException - if the randomNumberOrigin is greater than or equal to randomNumberBound, or if streamSize is negative.

    • nextBoolean

      public final boolean nextBoolean()
      Generates a pseudorandom boolean value. Delegates implementation to the wrapped object.
      Specified by:
      nextBoolean in interface RandomGenerator
      Returns:
      a pseudorandom boolean value

    • nextBytes

      public final void nextBytes(byte[] bytes)
      Fills a user-supplied byte array with byte values generated pseudorandomly uniformly distributed in the interval [-128, 127]. Delegates implementation to the wrapped object.
      Specified by:
      nextBytes in interface RandomGenerator
      Parameters:
      bytes - The byte array to fill with random bytes.
      Throws:
      NullPointerException - if bytes is null

    • nextDouble

      public final double nextDouble()
      Generates a pseudorandom double value in the interval [0, 1). Delegates implementation to the wrapped object.
      Specified by:
      nextDouble in interface RandomGenerator
      Returns:
      a pseudorandom double in [0, 1).

    • nextDouble

      public final double nextDouble(double bound)
      Generates a pseudorandom double value in the interval [0, bound). Delegates implementation to the wrapped object.
      Specified by:
      nextDouble in interface RandomGenerator
      Parameters:
      bound - The upper bound, exclusive. Must be positive and finite.
      Returns:
      a pseudorandom double in [0, bound).
      Throws:
      IllegalArgumentException - if bound is not finite or not positive.

    • nextDouble

      public final double nextDouble(double origin, double bound)
      Generates a pseudorandom double value in the interval [origin, bound). Delegates implementation to the wrapped object.
      Specified by:
      nextDouble in interface RandomGenerator
      Parameters:
      origin - The lower bound, inclusive.
      bound - The upper bound, exclusive.
      Returns:
      a pseudorandom double in [origin, bound).
      Throws:
      IllegalArgumentException - if origin is greater than or equal to bound, or if origin is not finite or if bound is not finite.

    • nextExponential

      public final double nextExponential()
      Generates a non-negative pseudorandom number from an exponential distribution with mean 1. Delegates implementation to the wrapped object.
      Specified by:
      nextExponential in interface RandomGenerator
      Returns:
      a non-negative pseudorandom number from an exponential distribution

    • nextFloat

      public final float nextFloat()
      Generates a pseudorandom float value in the interval [0, 1). Delegates implementation to the wrapped object.
      Specified by:
      nextFloat in interface RandomGenerator
      Returns:
      a pseudorandom float in [0, 1).

    • nextFloat

      public final float nextFloat(float bound)
      Generates a pseudorandom float value in the interval [0, bound). Delegates implementation to the wrapped object.
      Specified by:
      nextFloat in interface RandomGenerator
      Parameters:
      bound - The upper bound, exclusive. Must be positive and finite.
      Returns:
      a pseudorandom float in [0, bound).
      Throws:
      IllegalArgumentException - if bound is not finite or not positive.

    • nextFloat

      public final float nextFloat(float origin, float bound)
      Generates a pseudorandom float value in the interval [origin, bound). Delegates implementation to the wrapped object.
      Specified by:
      nextFloat in interface RandomGenerator
      Parameters:
      origin - The lower bound, inclusive.
      bound - The upper bound, exclusive.
      Returns:
      a pseudorandom float in [origin, bound).
      Throws:
      IllegalArgumentException - if origin is greater than or equal to bound, or if origin is not finite or if bound is not finite.

    • nextInt

      public final int nextInt()
      Generates a pseudorandom int value. Delegates implementation to the wrapped object.
      Specified by:
      nextInt in interface RandomGenerator
      Returns:
      a pseudorandom int

    • nextLong

      public final long nextLong()
      Generates a pseudorandom long value. Delegates implementation to the wrapped object.
      Specified by:
      nextLong in interface RandomGenerator
      Returns:
      a pseudorandom long

    • nextLong

      public final long nextLong(long bound)
      Generates a pseudorandom long value in the interval [0, bound). Delegates implementation to the wrapped object.
      Specified by:
      nextLong in interface RandomGenerator
      Parameters:
      bound - The upper bound, exclusive (must be positive).
      Returns:
      a pseudorandom long in [0, bound).
      Throws:
      IllegalArgumentException - if bound is not positive.

    • nextLong

      public final long nextLong(long origin, long bound)
      Generates a pseudorandom long value in the interval [origin, bound). Delegates implementation to the wrapped object.
      Specified by:
      nextLong in interface RandomGenerator
      Parameters:
      origin - The lower bound, inclusive.
      bound - The upper bound, exclusive.
      Returns:
      a pseudorandom long in [origin, bound).
      Throws:
      IllegalArgumentException - if origin is greater than or equal to bound.