Package java.util.random
These classes and interfaces that support the definition and use of "random generators", a term that is meant to cover what have traditionally been called "random number generators" as well as generators of other sorts of randomly chosen values, and also to cover not only deterministic (pseudorandom) algorithms but also generators of values that use some "truly random" physical source (perhaps making use of thermal noise, for example, or quantummechanical effects).
The principal interface is RandomGenerator
, which provides
methods for requesting individual values of type int
, long
,
float
, double
, or boolean
chosen (pseudo)randomly
from a uniform distribution; methods for requesting values of type
double
chosen (pseudo)randomly from a normal distribution or from an
exponential distribution; and methods for creating streams of values of type
int
, long
, or double
chosen (pseudo)randomly from a
uniform distribution (such streams are spliteratorbased, allowing for
parallel processing of their elements). There are also static factory methods
for creating an instance of a specific random number generator algorithm
given its name.
The principal supporting class is RandomGenertatorFactor
. This
can be used to generate multiple random number generators for a specific
algorithm. RandomGeneratorFactory
also provides methods for
selecting random number generator algorithms.
An important subsidiary interface is
RandomGenerator.StreamableGenerator
, which provides methods for
creating spliteratorbased streams of RandomGenerator
objects,
allowing for parallel processing of these objects using multiple threads.
Unlike Random
, most implementations of
RandomGenerator
are not threadsafe. The intent is that
instances should not be shared among threads; rather, each thread should have
its own random generator(s) to use. The various pseudorandom algorithms
provided by this package are designed so that multiple instances will (with
very high probability) behave as if statistically independent.
For many purposes, these are the only two interfaces that a consumer of
(pseudo)random values will need. There are also some more specialized
interfaces that describe more specialized categories of random number
generators RandomGenerator.SplittableGenerator
,
RandomGenerator.JumpableGenerator
,
RandomGenerator.LeapableGenerator
, and
RandomGenerator.ArbitrarilyJumpableGenerator
that have specific
strategies for creating statistically independent instances.
Using the Random Number Generator Interfaces
To get started, an application should first create one instance of a generator class. Assume that the contents of the packagejava.util.random
has been imported:
import java.util.random.*;
Then one can choose a specific implementation by giving the name of a generator
algorithm to the static method RandomGenerator.of(java.lang.String)
, in which case the
noarguments constructor for that implementation is used:
RandomGenerator g = RandomGenerator.of("L64X128MixRandom");
For a singlethreaded application, this is all that is needed. One can then
invoke methods of g
such as
nextLong()
,
nextInt()
,
nextFloat()
,
nextDouble()
and
nextBoolean()
to generate individual
randomly chosen values. One can also use the methods
ints()
, longs()
and doubles()
to create streams of randomly
chosen values. The methods
nextGaussian()
and
nextExponential()
draw floatingpoint
values from nonuniform distributions. The method
period()
returns information about the period
of the generator instance.
For a multithreaded application, one can repeat the preceding steps to
create additional RandomGenerators, but often it is preferable
to use methods of the one single initially created generator to create others
like it. (One reason is that some generator algorithms, if asked to create a
new set of generators all at once, can make a special effort to ensure that
the new generators are statistically independent.) If the initial generator
implements the interface StreamableGenerator
, then the method
rngs()
can be used to create a stream of
generators. If this is a parallel stream, then it is easy to get parallel
execution by using the map()
method on the stream.
For a multithreaded application that forks new threads dynamically,
another approach is to use an initial generator that implements the interface
RandomGenerator.SplittableGenerator
, which is then considered to
"belong" to the initial thread for its exclusive use; then whenever any
thread needs to fork a new thread, it first uses the
split()
method of its own generator to create a
new generator, which is then passed to the newly created thread for exclusive
use by that new thread.
Choosing a Random Number Generator Algorithm
If an application requires a random number generator algorithm that is cryptographically secure, then it should use an instance of the classSecureRandom
.
For applications (such as physical simulation, machine learning, and
games) that do not require a cryptographically secure algorithm, this package
provides multiple implementations of interface RandomGenerator
that
provide tradeoffs among speed, space, period, accidental correlation, and
equidistribution properties.
For applications with no special requirements, "L64X128MixRandom" has a good balance among speed, space, and period, and is suitable for both singlethreaded and multithreaded applications when used properly (a separate instance for each thread).
If the application uses only a single thread, then "Xoroshiro128PlusPlus" is even smaller and faster, and certainly has a sufficiently long period.
For an application running in a 32bit hardware environment and using only one thread or a small number of threads, may be a good choice.
For an application that uses many threads that are allocated in one batch at the start of the computation, either a "jumpable" generator such as "Xoroshiro128PlusPlus" or "Xoshiro256PlusPlus" may be used, or a "splittable" generator such as "L64X128MixRandom" or "L64X256MixRandom" may be used.
For an application that creates many threads dynamically, perhaps through the use of spliterators, a "splittable" generator such as "L64X128MixRandom" or "L64X256MixRandom" is recommended. If the number of generators created dynamically may be very large (millions or more), then using generators such as "L128X128MixRandom" or "L128X256MixRandom", which use a 128bit parameter rather than a 64bit parameter for their LCG subgenerator, will make it much less likely that two instances use the same state cycle.
For an application that uses tuples of consecutively generated values, it may be desirable to use a generator that is kequidistributed such that k is at least as large as the length of the tuples being generated. The generator "L64X256MixRandom" is provably 4equidistributed, and "L64X1024MixRandom" is provably 16equidistributed.
For applications that generate large permutations, it may be best to use a generator whose period is much larger than the total number of possible permutations; otherwise it will be impossible to generate some of the intended permutations. For example, if the goal is to shuffle a deck of 52 cards, the number of possible permutations is 52! (52 factorial), \ which is larger than 2^{225} (but smaller than 2^{226}), so it may be best to use a generator whose period at least 2^{256}, such as "L64X256MixRandom" or "L64X1024MixRandom" or "L128X256MixRandom" or "L128X1024MixRandom". (It is of course also necessary to provide sufficiently many seed bits when the generator is initialized, or else it will still be impossible to generate some of the intended permutations.)
Categories of Random Number Generator Algorithms
Historically, most pseudorandom generator algorithms have been based on some sort of finitestate machine with a single, large cycle of states; when it is necessary to have multiple threads use the same algorithm simultaneously, the usual technique is to arrange for each thread to traverse a different region of the state cycle. These regions may be doled out to threads by starting with a single initial state and then using a "jump function" that travels a long distance around the cycle (perhaps 2^{64} steps or more); the jump function is applied repeatedly and sequentially, to identify widely spaced states that are then doled out, one to each thread, to serve as the initial state for the generator to be used by that thread. This strategy is supported by the interfaceJumpableGenerator
. Sometimes it is
desirable to support two levels of jumping (by long distances and by
really long distances); this strategy is supported by the interface
RandomGenerator.LeapableGenerator
. There is also an interface
RandomGenerator.ArbitrarilyJumpableGenerator
for algorithms that allow
jumping along the state cycle by any userspecified distance. In this package,
implementations of these interfaces include
"Xoroshiro128PlusPlus", and
"Xoshiro256PlusPlus".
A more recent category of "splittable" pseudorandom generator algorithms
uses a large family of state cycles and makes some attempt to ensure that
distinct instances use different state cycles; but even if two instances
"accidentally" use the same state cycle, they are highly likely to traverse
different regions parts of that shared state cycle. This strategy is
supported by the interface RandomGenerator.SplittableGenerator
.
In this package, implementations of this interface include
"L32X64MixRandom",
"L64X128StarStarRandom",
"L64X128MixRandom",
"L64X256MixRandom",
"L64X1024MixRandom",
"L128X128MixRandom",
"L128X256MixRandom", and
"L128X1024MixRandom"; note that the class
SplittableRandom
also implements this interface.
The LXM Family of Random Number Generator Algorithms
Each class with a name of the formL
pX
q
SomethingRandom
uses some specific member of the LXM family of random number
algorithms; "LXM" is short for "LCG, Xorshift, Mixing function". Every LXM
generator consists of two subgenerators; one is an LCG (Linear Congruential
Generator) and the other is an Xorshift generator. Each output of an LXM
generator is the result of combining state from the LCG with state from the
Xorshift generator by using a Mixing function (and then the state of the LCG
and the state of the Xorshift generator are advanced).
The LCG subgenerator has an update step of the form s = m*s + a
,
where s
, m
, and a
are all binary integers of the same
size, each having p bits; s
is the mutable state, the
multiplier m
is fixed (the same for all instances of a class) and the
addend a
is a parameter (a final field of the instance). The
parameter a
is required to be odd (this allows the LCG to have the
maximal period, namely 2^{p}); therefore there are
2^{p−1} distinct choices of parameter. (When the size of
s
is 128 bits, then we use the name "sh
" below to refer to
the high half of s
, that is, the highorder 64 bits of s
.)
The Xorshift subgenerator can in principle be any one of a wide variety
of xorshift algorithms; in this package it is always either
xoroshiro128
, xoshiro256
, or xoroshiro1024
, in each
case without any final scrambler such as "+" or "**". Its state consists of
some fixed number of int
or long
fields, generally named
x0
, x1
, and so on, which can take on any values provided that
they are not all zero. The collective total size of these fields is q
bits; therefore the period of this subgenerator is
2^{q}−1.
Because the periods 2^{p} and 2^{q}−1
of the two subgenerators are relatively prime, the period of any
single instance of an LXM algorithm (the length of the series of generated
values before it repeats) is the product of the periods of the subgenerators,
that is, 2^{p}(2^{q}−1), which is just
slightly smaller than 2^{(p+q)}. Moreover, if two
distinct instances of the same LXM algorithm have different a
parameters, then their cycles of produced values will be different.
Generally speaking, among the "L
pX
q"
generators, the memory required for an instance is 2p+q bits.
(If q is 1024 or larger, the Xorshift state is represented as an
array, so additional bits are needed for the array object header, and another
32 bits are used for an array index.)
Larger values of p imply a lower probability that two distinct
instances will traverse the same state cycle, and larger values of q
imply that the generator is equidistributed in a larger number of dimensions
(this is provably true when p is 64, and conjectured to be
approximately true when p is 128). A class with "Mix
" in its
name uses a fairly strong mixing function with excellent avalanche
characteristics; a class with "StarStar
" in its name uses a weaker
but faster mixing function.
The specific LXM algorithms used in this package are all chosen so that
the 64bit values produced by the nextLong()
method are exactly equidistributed (for example, for any specific instance of
"L64X128MixRandom", over the course of its cycle each of the
2^{64} possible long
values will be produced
2^{128}−1 times). The values produced by the
nextInt()
,
nextFloat()
, and
nextDouble()
methods are likewise exactly
equidistributed. Some algorithms provide a further guarantee of
kequidistribution for some k greater than 1, meaning that successive
nonoverlapping ktuples of 64bit values produced by the
nextLong()
method are exactly
equidistributed (equally likely to occur).
The following table gives the period, state size (in bits), parameter size (in bits, including the loworder bit that is required always to be a 1bit), and equidistribution property for each of the specific LXM algorithms used in this package.
Implementation  Period  State size  Parameter size  nextLong() values are 

"L32X64MixRandom"  2^{32}(2^{64}−1)  96 bits  32 bits  
"L64X128StarStarRandom"  2^{64}(2^{128}−1)  192 bits  64 bits  2equidistributed and exactly equidistributed 
"L64X128MixRandom"  2^{64}(2^{128}−1)  192 bits  64 bits  2equidistributed and exactly equidistributed 
"L64X256MixRandom"  2^{64}(2^{256}−1)  320 bits  64 bits  4equidistributed and exactly equidistributed 
"L64X1024MixRandom"  2^{64}(2^{1024}−1)  1088 bits  64 bits  16equidistributed and exactly equidistributed 
"L128X128MixRandom"  2^{128}(2^{128}−1)  256 bits  128 bits  exactly equidistributed 
"L128X256MixRandom"  2^{128}(2^{256}−1)  384 bits  128 bits  exactly equidistributed 
"L128X1024MixRandom"  2^{128}(2^{1024}−1)  1152 bits  128 bits  exactly equidistributed 
L32
, the
32bit values produced by the nextInt()
method are exactly equidistributed, but the 64bit values produced by the
nextLong()
method are not exactly
equidistributed.
For the algorithms listed above whose names begin with L64
or
L128
, the 64bit values produced by the
nextLong()
method are exactly
equidistributed: every instance, over the course of its cycle, will
produce each of the 2^{64} possible long
values exactly the
same number of times. For example, any specific instance of
"L64X256MixRandom", over the course of its cycle each of the
2^{64} possible long
values will be produced
2^{256}−1 times. The values produced by the
nextInt()
,
nextFloat()
, and
nextDouble()
methods are likewise exactly
equidistributed.
In addition, for the algorithms listed above whose names begin with
L64
, the 64bit values produced by the
nextLong()
method are
kequidistributed (but not exactly kequidistributed). To be
precise, and taking "L64X256MixRandom" as an example: for
any specific instance of "L64X256MixRandom", consider the
(overlapping) length4 subsequences of the cycle of 64bit values produced by
nextLong()
(assuming no other methods are
called that would affect the state). There are
2^{64}(2^{256}−1) such subsequences, and each
subsequence, which consists of 4 64bit values, can have one of
2^{256} values. Of those 2^{256} subsequence values, nearly
all of them (2^{256}%minus;2^{64}) occur 2^{64} times
over the course of the entire cycle, and the other 2^{64} subsequence
values occur only 2^{64}−1 times. So the ratio of the
probability of getting any specific one of the less common subsequence values
and the probability of getting any specific one of the more common
subsequence values is 1−2^{64}. (Note that the set of
2^{64} lesscommon subsequence values will differ from one instance
of "L64X256MixRandom" to another, as a function of the
additive parameter of the LCG.) The values produced by the
nextInt()
,
nextFloat()
, and
nextDouble()
methods are likewise
4equidistributed (but not exactly 4equidistributed).
The next table gives the LCG multiplier value, the name of the specific
Xorshift algorithm used, the specific numeric parameters for that Xorshift
algorithm, and the mixing function for each of the specific LXM algorithms
used in this package. (Note that the multiplier used for the 128bit LCG
cases is 65 bits wide, so the constant 0x1d605bbb58c8abbfdL
shown in
the table cannot actually be used in code; instead, only the 64 loworder
bits 0xd605bbb58c8abbfdL
are represented in the source code, and the
missing 1bit is handled through special coding of the multiplyadd algorithm
used in the LCG.)
Implementation  LCG multiplier m 
Xorshift algorithm  Xorshift parameters  Mixing function 

"L32X64MixRandom"  0xadb4a92d 
xoroshiro64 , version 1.0 
(26, 9, 13) 
mixLea32(s+x0) 
"L64X128StarStarRandom"  0xd1342543de82ef95L 
xoroshiro128 , version 1.0 
(24, 16, 37) 
Long.rotateLeft((s+x0)* 5, 7) * 9 
"L64X128MixRandom"  0xd1342543de82ef95L 
xoroshiro128 , version 1.0 
(24, 16, 37) 
mixLea32(s+x0) 
"L64X256MixRandom"  0xd1342543de82ef95L 
xoshiro256 , version 1.0 
(17, 45) 
mixLea32(s+x0) 
"L64X1024MixRandom"  0xd1342543de82ef95L 
xoroshiro1024 , version 1.0 
(25, 27, 36) 
mixLea32(s+x0) 
"L128X128MixRandom"  0x1d605bbb58c8abbfdL 
xoroshiro128 , version 1.0 
(24, 16, 37) 
mixLea32(sh+x0) 
"L128X256MixRandom"  0x1d605bbb58c8abbfdL 
xoshiro256 , version 1.0 
(17, 45) 
mixLea32(sh+x0) 
"L128X1024MixRandom"  0x1d605bbb58c8abbfdL 
xoroshiro1024 , version 1.0 
(25, 27, 36) 
mixLea32(sh+x0) 
 Since:
 16

InterfaceDescriptionThe
RandomGenerator
interface is designed to provide a common protocol for objects that generate random or (more typically) pseudorandom sequences of numbers (or Boolean values).This interface is designed to provide a common protocol for objects that generate sequences of pseudorandom numbers (or Boolean values) and furthermore can easily jump to an arbitrarily specified distant point in the state cycle.This interface is designed to provide a common protocol for objects that generate pseudorandom sequences of numbers (or Boolean values) and furthermore can easily jump forward (by a fixed amount) to a distant point in the state cycle.This interface is designed to provide a common protocol for objects that generate sequences of pseudorandom numbers (or Boolean values) and furthermore can easily not only jump but also leap to a very distant point in the state cycle.This interface is designed to provide a common protocol for objects that generate sequences of pseudorandom numbers (or boolean values) and furthermore can be split into two objects (the original one and a new one) each of which obey that same protocol (and therefore can be recursively split indefinitely).TheRandomGenerator.StreamableGenerator
interface augments theRandomGenerator
interface to provide methods that return streams ofRandomGenerator
objects. 
ClassDescriptionRandomGeneratorFactory<T extends RandomGenerator>This is a factory class for generating multiple random number generators of a specific algorithm.