- All Implemented Interfaces:
RandomGenerator
- Direct Known Subclasses:
EnhancedStreamableGenerator
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
ConstructorsConstructorDescriptionConstructs the EnhancedRandomGenerator to wrap an instance of the default random number generator as obtained via a call toRandomGenerator.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 theRandomGenerator.of(java.lang.String)
method.EnhancedRandomGenerator
(RandomGenerator generator) Constructs the EnhancedRandomGenerator from the RandomGenerator to wrap. -
Method Summary
Modifier and TypeMethodDescriptionfinal 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
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
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
Gets an EnhancedRandomGenerator wrapping an instance of the default random number generator as obtained via a call toRandomGenerator.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
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
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
Generates a non-negative pseudorandom number from an exponential distribution with mean 1.final float
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
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
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 theRandomGenerator.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 toRandomGenerator.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
Constructs the EnhancedRandomGenerator from the RandomGenerator to wrap.- Parameters:
generator
- The RandomGenerator to wrap, which serves as the source of randomness.
-
EnhancedRandomGenerator
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 theRandomGenerator.of(java.lang.String)
method.- Parameters:
algorithmName
- The name of the random number generator as documented by theRandomGenerator.of(java.lang.String)
method.- Throws:
NullPointerException
- if algorithmName is null.IllegalArgumentException
- if algorithmName is not found.
-
-
Method Details
-
getDefault
Gets an EnhancedRandomGenerator wrapping an instance of the default random number generator as obtained via a call toRandomGenerator.getDefault()
.- Returns:
- an EnhancedRandomGenerator wrapping an instance of the default random number generator
-
of
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 theRandomGenerator.of(java.lang.String)
method.- Parameters:
algorithmName
- The name of the random number generator as documented by theRandomGenerator.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
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
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
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
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
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
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
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
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
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
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
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
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[])
, andsampleInsertion(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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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
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 interfaceRandomGenerator
- 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
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 interfaceRandomGenerator
- 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
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 interfaceRandomGenerator
- Returns:
- an effectively unlimited stream of pseudorandom double values, uniformly random from the interval [0.0, 1.0).
-
doubles
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 interfaceRandomGenerator
- 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
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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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
Returns an effectively unlimited stream of pseudorandom int values. Delegates implementation to the wrapped object.- Specified by:
ints
in interfaceRandomGenerator
- Returns:
- an effectively unlimited stream of pseudorandom int values.
-
ints
Returns a stream of pseudorandom int values. Delegates implementation to the wrapped object.- Specified by:
ints
in interfaceRandomGenerator
- Parameters:
streamSize
- The number of values in the stream.- Returns:
- a stream of pseudorandom int values.
- Throws:
IllegalArgumentException
- if streamSize is negative.
-
longs
Returns an effectively unlimited stream of pseudorandom long values. Delegates implementation to the wrapped object.- Specified by:
longs
in interfaceRandomGenerator
- Returns:
- an effectively unlimited stream of pseudorandom long values.
-
longs
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 interfaceRandomGenerator
- 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
Returns a stream of pseudorandom long values. Delegates implementation to the wrapped object.- Specified by:
longs
in interfaceRandomGenerator
- Parameters:
streamSize
- The number of values in the stream.- Returns:
- a stream of pseudorandom long values.
- Throws:
IllegalArgumentException
- if streamSize is negative.
-
longs
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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- Returns:
- a pseudorandom int
-
nextLong
public final long nextLong()Generates a pseudorandom long value. Delegates implementation to the wrapped object.- Specified by:
nextLong
in interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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 interfaceRandomGenerator
- 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.
-