public enum RandomSource extends Enum<RandomSource>
Usage examples:
UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
or
final int[] seed = new int[] { 196, 9, 0, 226 };
UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(seed);
or
final int[] seed = RandomSource.createIntArray(256);
UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(seed);
where the enum value is the identifier of the generator's concrete
implementation, and the argument to method create
is the
(optional) seed.
In the first form, a random seed will be generated
automatically
; in the second form, a fixed seed is used; a random seed
is explicitly generated in the third form.
Seeding is the procedure by which a value (or set of values) is used to initialize a generator instance. The requirement that a given seed will always result in the same internal state allows to create different instances of a generator that will produce the same sequence of pseudo-random numbers.
The type of data used as a seed depends on the concrete implementation
as some types may not provide enough information to fully initialize
the generator's internal state.
The reference algorithm's seeding procedure (if provided) operates
on a value of a (single) native type:
Each concrete implementation's constructor creates an instance using
the native type whose information contents is used to set the
internal state.
When the seed value passed by the caller is of the native type, it is
expected that the sequences produced will be identical to those
produced by other implementations of the same reference algorithm.
However, when the seed value passed by the caller is not of the native
type, a transformation is performed by this library and the resulting
native type value will not contain more information than the
original seed value.
If the algorithm's native type is "simpler" than the type passed by
the caller, then some (unused) information will even be lost.
The transformation from non-native to native seed type is arbitrary,
as long as it does not reduce the amount of information required by
the algorithm to initialize its state.
The consequence of the transformation is that sequences produced
by this library may not be the same as the sequences produced
by other implementations of the same algorithm!
For each algorithm, the Javadoc mentions the "ideal" size of the seed,
meaning the number of int
or long
values that is neither
too large (i.e. some of the seed is useless) or too small (i.e. an
internal procedure will fill the state with redundant information
computed from the given seed).
Note that some algorithms are inherently sensitive to having too low diversity in their initial state. For example, it is often a bad idea to use a seed that is mostly composed of zeroes, or of repeated values.
This class provides methods to generate random seeds (single values
or arrays of values, of int
or long
types) that can
be passed to the generator's factory method
.
Although the seed-generating methods defined in this class will likely return different values each time they are called, there is no guarantee:
Note: Seeding is not equivalent to restoring the internal state of an already initialized generator. Indeed, generators can have a state that is more complex than the seed, and seeding is thus a transformation (from seed to state). Implementations do not provide the inverse transformation (from state to seed), hence it is not generally possible to know the seed that would initialize a new generator instance to the current state of another instance. Reseeding is also inefficient if the purpose is to continue the same sequence where another instance left off, as it would require to "replay" all the calls performed by that other instance (and it would require to know the number of calls to the primary source of randomness, which is also not usually accessible).
For parallel applications, some implementations have provision for producing
non-overlapping sequences by copying the generator and then advancing a large number
of steps in the generator sequence. Repeated jumps can create a series of
child generators that will output non-overlapping sequences over a specified number
of outputs. These implementations are identified using the isJumpable()
and isLongJumpable()
methods.
RandomSource source = RandomSource.XO_RO_SHI_RO_128_SS; // Known to be jumpable.
JumpableUniformRandomProvider jumpable = (JumpableUniformRandomProvider) source.create();
// For use in parallel
UniformRandomProvider[] rngs = new UniformRandomProvider[10];
for (int i = 0; i < rngs.length; i++) {
rngs[i] = jumpable.jump();
}
For implementations that have no provision for producing non-overlapping
sequences, a possible workaround is that each thread uses
a generator of a different type (see TWO_CMRES_SELECT
).
Enum Constant and Description |
---|
ISAAC
Source of randomness is
ISAACRandom . |
JDK
Source of randomness is
JDKRandom . |
JSF_32
Source of randomness is
JenkinsSmallFast32 . |
JSF_64
Source of randomness is
JenkinsSmallFast64 . |
KISS
Source of randomness is
KISSRandom . |
L128_X1024_MIX
Source of randomness is
L128X1024Mix . |
L128_X128_MIX
Source of randomness is
L128X128Mix . |
L128_X256_MIX
Source of randomness is
L128X256Mix . |
L32_X64_MIX
Source of randomness is
L32X64Mix . |
L64_X1024_MIX
Source of randomness is
L64X1024Mix . |
L64_X128_MIX
Source of randomness is
L64X128Mix . |
L64_X128_SS
Source of randomness is
L64X128StarStar . |
L64_X256_MIX
Source of randomness is
L64X256Mix . |
MSWS
Source of randomness is
MiddleSquareWeylSequence . |
MT
Source of randomness is
MersenneTwister . |
MT_64
Source of randomness is
MersenneTwister64 . |
MWC_256
Source of randomness is
MultiplyWithCarry256 . |
PCG_MCG_XSH_RR_32
Source of randomness is
PcgMcgXshRr32 . |
PCG_MCG_XSH_RS_32
Source of randomness is
PcgMcgXshRs32 . |
PCG_RXS_M_XS_64
Source of randomness is
PcgRxsMXs64 . |
PCG_RXS_M_XS_64_OS
Source of randomness is
PcgRxsMXs64 . |
PCG_XSH_RR_32
Source of randomness is
PcgXshRr32 . |
PCG_XSH_RR_32_OS
Source of randomness is
PcgXshRr32 . |
PCG_XSH_RS_32
Source of randomness is
PcgXshRs32 . |
PCG_XSH_RS_32_OS
Source of randomness is
PcgXshRs32 . |
SFC_32
Source of randomness is
DotyHumphreySmallFastCounting32 . |
SFC_64
Source of randomness is
DotyHumphreySmallFastCounting64 . |
SPLIT_MIX_64
Source of randomness is
SplitMix64 . |
TWO_CMRES
Source of randomness is
TwoCmres . |
TWO_CMRES_SELECT
Source of randomness is
TwoCmres ,
with explicit selection of the two subcycle generators. |
WELL_1024_A
Source of randomness is
Well1024a . |
WELL_19937_A
Source of randomness is
Well19937a . |
WELL_19937_C
Source of randomness is
Well19937c . |
WELL_44497_A
Source of randomness is
Well44497a . |
WELL_44497_B
Source of randomness is
Well44497b . |
WELL_512_A
Source of randomness is
Well512a . |
XO_RO_SHI_RO_1024_PP
Source of randomness is
XoRoShiRo1024PlusPlus . |
XO_RO_SHI_RO_1024_S
Source of randomness is
XoRoShiRo1024Star . |
XO_RO_SHI_RO_1024_SS
Source of randomness is
XoRoShiRo1024StarStar . |
XO_RO_SHI_RO_128_PLUS
Source of randomness is
XoRoShiRo128Plus . |
XO_RO_SHI_RO_128_PP
Source of randomness is
XoRoShiRo128PlusPlus . |
XO_RO_SHI_RO_128_SS
Source of randomness is
XoRoShiRo128StarStar . |
XO_RO_SHI_RO_64_S
Source of randomness is
XoRoShiRo64Star . |
XO_RO_SHI_RO_64_SS
Source of randomness is
XoRoShiRo64StarStar . |
XO_SHI_RO_128_PLUS
Source of randomness is
XoShiRo128Plus . |
XO_SHI_RO_128_PP
Source of randomness is
XoShiRo128PlusPlus . |
XO_SHI_RO_128_SS
Source of randomness is
XoShiRo128StarStar . |
XO_SHI_RO_256_PLUS
Source of randomness is
XoShiRo256Plus . |
XO_SHI_RO_256_PP
Source of randomness is
XoShiRo256PlusPlus . |
XO_SHI_RO_256_SS
Source of randomness is
XoShiRo256StarStar . |
XO_SHI_RO_512_PLUS
Source of randomness is
XoShiRo512Plus . |
XO_SHI_RO_512_PP
Source of randomness is
XoShiRo512PlusPlus . |
XO_SHI_RO_512_SS
Source of randomness is
XoShiRo512StarStar . |
XOR_SHIFT_1024_S
Deprecated.
Since 1.3, where it is recommended to use
XOR_SHIFT_1024_S_PHI
instead due to its slightly better (more uniform) output. XOR_SHIFT_1024_S
is still quite usable but both are variants of the same algorithm and maintain their
internal state identically. Their outputs are correlated and the two should not be
used together when independent sequences are assumed. |
XOR_SHIFT_1024_S_PHI
Source of randomness is
XorShift1024StarPhi . |
Modifier and Type | Method and Description |
---|---|
RestorableUniformRandomProvider |
create()
Creates a random number generator with a random seed.
|
RestorableUniformRandomProvider |
create(Object seed,
Object... data)
Creates a random number generator with the given
seed . |
static RestorableUniformRandomProvider |
create(RandomSource source)
Deprecated.
It is preferred to use the
create() instance method. |
static RestorableUniformRandomProvider |
create(RandomSource source,
Object seed,
Object... data)
Deprecated.
It is preferred to use the
create(Object, Object...) instance method. |
static int |
createInt()
Creates a number for use as a seed.
|
static int[] |
createIntArray(int n)
Creates an array of numbers for use as a seed.
|
static long |
createLong()
Creates a number for use as a seed.
|
static long[] |
createLongArray(int n)
Creates an array of numbers for use as a seed.
|
byte[] |
createSeed()
Creates a seed suitable for the implementing class represented by this random source.
|
byte[] |
createSeed(UniformRandomProvider rng)
Creates a seed suitable for the implementing class represented by this random source
using the supplied source of randomness.
|
boolean |
isJumpable()
Checks whether the implementing class represented by this random source
supports the
JumpableUniformRandomProvider interface. |
boolean |
isLongJumpable()
Checks whether the implementing class represented by this random source
supports the
LongJumpableUniformRandomProvider interface. |
boolean |
isNativeSeed(Object seed)
Checks whether the type of given
seed is the native type
of the implementation. |
boolean |
isSplittable()
Checks whether the implementing class represented by this random source
supports the
SplittableUniformRandomProvider interface. |
static UniformRandomProvider |
unrestorable(UniformRandomProvider delegate)
Wraps the given
delegate generator in a new instance that
only provides access to the UniformRandomProvider methods. |
static RandomSource |
valueOf(String name)
Returns the enum constant of this type with the specified name.
|
static RandomSource[] |
values()
Returns an array containing the constants of this enum type, in
the order they are declared.
|
public static final RandomSource JDK
JDKRandom
.
Long
.public static final RandomSource WELL_512_A
Well512a
.
int[]
.public static final RandomSource WELL_1024_A
Well1024a
.
int[]
.public static final RandomSource WELL_19937_A
Well19937a
.
int[]
.public static final RandomSource WELL_19937_C
Well19937c
.
int[]
.public static final RandomSource WELL_44497_A
Well44497a
.
int[]
.public static final RandomSource WELL_44497_B
Well44497b
.
int[]
.public static final RandomSource MT
MersenneTwister
.
int[]
.public static final RandomSource ISAAC
ISAACRandom
.
int[]
.public static final RandomSource SPLIT_MIX_64
SplitMix64
.
Long
.@Deprecated public static final RandomSource XOR_SHIFT_1024_S
XOR_SHIFT_1024_S_PHI
instead due to its slightly better (more uniform) output. XOR_SHIFT_1024_S
is still quite usable but both are variants of the same algorithm and maintain their
internal state identically. Their outputs are correlated and the two should not be
used together when independent sequences are assumed.XorShift1024Star
.
long[]
.public static final RandomSource TWO_CMRES
TwoCmres
.
This generator is equivalent to TWO_CMRES_SELECT
with the choice of the
pair (0, 1)
for the two subcycle generators.
Integer
.public static final RandomSource TWO_CMRES_SELECT
TwoCmres
,
with explicit selection of the two subcycle generators.
The selection of the subcycle generator is by passing its index in the internal
table, a value between 0 (included) and 13 (included).
The two indices must be different.
Different choices of an ordered pair of indices create independent generators.
Integer
.public static final RandomSource MT_64
MersenneTwister64
.
long[]
.public static final RandomSource MWC_256
MultiplyWithCarry256
.
int[]
.public static final RandomSource KISS
KISSRandom
.
int[]
.public static final RandomSource XOR_SHIFT_1024_S_PHI
XorShift1024StarPhi
.
long[]
.public static final RandomSource XO_RO_SHI_RO_64_S
XoRoShiRo64Star
.
int[]
.public static final RandomSource XO_RO_SHI_RO_64_SS
XoRoShiRo64StarStar
.
int[]
.public static final RandomSource XO_SHI_RO_128_PLUS
XoShiRo128Plus
.
int[]
.public static final RandomSource XO_SHI_RO_128_SS
XoShiRo128StarStar
.
int[]
.public static final RandomSource XO_RO_SHI_RO_128_PLUS
XoRoShiRo128Plus
.
long[]
.public static final RandomSource XO_RO_SHI_RO_128_SS
XoRoShiRo128StarStar
.
long[]
.public static final RandomSource XO_SHI_RO_256_PLUS
XoShiRo256Plus
.
long[]
.public static final RandomSource XO_SHI_RO_256_SS
XoShiRo256StarStar
.
long[]
.public static final RandomSource XO_SHI_RO_512_PLUS
XoShiRo512Plus
.
long[]
.public static final RandomSource XO_SHI_RO_512_SS
XoShiRo512StarStar
.
long[]
.public static final RandomSource PCG_XSH_RR_32
PcgXshRr32
.
long[]
.public static final RandomSource PCG_XSH_RS_32
PcgXshRs32
.
long[]
.public static final RandomSource PCG_RXS_M_XS_64
PcgRxsMXs64
.
long[]
.public static final RandomSource PCG_MCG_XSH_RR_32
PcgMcgXshRr32
.
Long
.public static final RandomSource PCG_MCG_XSH_RS_32
PcgMcgXshRs32
.
Long
.public static final RandomSource MSWS
MiddleSquareWeylSequence
.
long[]
.public static final RandomSource SFC_32
DotyHumphreySmallFastCounting32
.
int[]
.public static final RandomSource SFC_64
DotyHumphreySmallFastCounting64
.
long[]
.public static final RandomSource JSF_32
JenkinsSmallFast32
.
Integer
.public static final RandomSource JSF_64
JenkinsSmallFast64
.
Long
.public static final RandomSource XO_SHI_RO_128_PP
XoShiRo128PlusPlus
.
int[]
.public static final RandomSource XO_RO_SHI_RO_128_PP
XoRoShiRo128PlusPlus
.
long[]
.public static final RandomSource XO_SHI_RO_256_PP
XoShiRo256PlusPlus
.
long[]
.public static final RandomSource XO_SHI_RO_512_PP
XoShiRo512PlusPlus
.
long[]
.public static final RandomSource XO_RO_SHI_RO_1024_PP
XoRoShiRo1024PlusPlus
.
long[]
.public static final RandomSource XO_RO_SHI_RO_1024_S
XoRoShiRo1024Star
.
long[]
.public static final RandomSource XO_RO_SHI_RO_1024_SS
XoRoShiRo1024StarStar
.
long[]
.public static final RandomSource PCG_XSH_RR_32_OS
PcgXshRr32
.
Long
.public static final RandomSource PCG_XSH_RS_32_OS
PcgXshRs32
.
Long
.public static final RandomSource PCG_RXS_M_XS_64_OS
PcgRxsMXs64
.
Long
.public static final RandomSource L64_X128_SS
L64X128StarStar
.
long[]
.public static final RandomSource L64_X128_MIX
L64X128Mix
.
long[]
.public static final RandomSource L64_X256_MIX
L64X256Mix
.
long[]
.public static final RandomSource L64_X1024_MIX
L64X1024Mix
.
long[]
.public static final RandomSource L128_X128_MIX
L128X128Mix
.
long[]
.public static final RandomSource L128_X256_MIX
L128X256Mix
.
long[]
.public static final RandomSource L128_X1024_MIX
L128X1024Mix
.
long[]
.public static final RandomSource L32_X64_MIX
L32X64Mix
.
int[]
.public static RandomSource[] values()
for (RandomSource c : RandomSource.values()) System.out.println(c);
public static RandomSource valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullpublic boolean isNativeSeed(Object seed)
seed
is the native type
of the implementation.seed
- Seed value.true
if the type of seed
is the native
type for this RNG source.public byte[] createSeed()
The seed will be created as if passing a null
seed to the method
create(Object, Object...)
. It will satisfy the seed size and any
other seed requirements for the implementing class. The seed is converted from the native
type to a byte representation.
Usage example:
RandomSource source = ...;
byte[] seed = source.createSeed();
UniformRandomProvider rng = source.create(seed);
public byte[] createSeed(UniformRandomProvider rng)
The seed will satisfy the seed size and any other seed requirements for the implementing class.
Usage example:
RandomSource source = ...;
UniformRandomProvider seedRng = new JDKRandomWrapper(new SecureRandom());
byte[] seed = source.createSeed(seedRng);
UniformRandomProvider rng = source.create(seed);
rng
- Source of randomness.public boolean isJumpable()
JumpableUniformRandomProvider
interface. If true
the instance returned
by create(RandomSource)
may be cast to the interface; otherwise a class
cast exception will occur.
Usage example:
RandomSource source = ...;
if (source.isJumpable()) {
JumpableUniformRandomProvider rng =
(JumpableUniformRandomProvider) source.create();
}
true
if jumpablepublic boolean isLongJumpable()
LongJumpableUniformRandomProvider
interface. If true
the instance returned
by create(RandomSource)
may be cast to the interface; otherwise a class
cast exception will occur.
Usage example:
RandomSource source = ...;
if (source.isJumpable()) {
LongJumpableUniformRandomProvider rng =
(LongJumpableUniformRandomProvider) source.create();
}
true
if long jumpablepublic boolean isSplittable()
SplittableUniformRandomProvider
interface. If true
the instance returned
by create(RandomSource)
may be cast to the interface; otherwise a class
cast exception will occur.
Usage example:
RandomSource source = ...;
if (source.isSplittable()) {
SplittableUniformRandomProvider rng =
(SplittableUniformRandomProvider) source.create();
}
true
if splittablepublic RestorableUniformRandomProvider create()
Usage example:
UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
or, if a "save/restore"
functionality is needed,
RestorableUniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create();
This method will raise an exception if the generator requires arguments in addition
to a seed (e.g. TWO_CMRES_SELECT
).
IllegalArgumentException
- if the generator requires arguments in addition
to a seed.create(Object,Object[])
public RestorableUniformRandomProvider create(Object seed, Object... data)
seed
.
Usage example:
UniformRandomProvider rng = RandomSource.XO_RO_SHI_RO_128_PP.create(0x123abcL);
UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create(26219, 6, 9);
// null seed with arguments
UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create((Object) null, 6, 9);
Valid types for the seed
are:
Integer
(or int
)Long
(or long
)int[]
long[]
byte[]
Notes:
native type
, the conversion of a
set of different seeds will necessarily result in the same value
of the native seed type.
seed
is null
, a seed of the native type
will be generated. If the native type is an array, the generated
size is limited a maximum of 128.
This method will raise an exception if the additional arguments for
the implementation's constructor are incorrect (e.g. TWO_CMRES_SELECT
).
This includes the case where arguments are supplied and the implementation
does not require additional arguments.
seed
- Seed value. It can be null
(in which case a
random value will be used).data
- Additional arguments to the implementation's constructor.
Please refer to the documentation of each specific implementation.IllegalArgumentException
- if the argument data required to initialize the
generator is incorrect.UnsupportedOperationException
- if the type of the seed
is invalid.create()
@Deprecated public static RestorableUniformRandomProvider create(RandomSource source)
create()
instance method.Usage example:
UniformRandomProvider rng = RandomSource.create(RandomSource.MT);
or, if a "save/restore"
functionality is needed,
RestorableUniformRandomProvider rng = RandomSource.create(RandomSource.MT);
This method will raise an exception if the generator requires arguments in addition
to a seed (e.g. TWO_CMRES_SELECT
).
source
- RNG type.IllegalArgumentException
- if the generator requires arguments in addition
to a seed.create(RandomSource,Object,Object[])
@Deprecated public static RestorableUniformRandomProvider create(RandomSource source, Object seed, Object... data)
create(Object, Object...)
instance method.seed
.
Usage example:
UniformRandomProvider rng = RandomSource.create(RandomSource.XO_RO_SHI_RO_128_PP, 0x123abcL);
UniformRandomProvider rng = RandomSource.create(RandomSource.TWO_CMRES_SELECT, 26219, 6, 9);
Valid types for the seed
are:
Integer
(or int
)Long
(or long
)int[]
long[]
byte[]
Notes:
native type
, the conversion of a
set of different seeds will necessarily result in the same value
of the native seed type.
seed
is null
, a seed of the native type
will be generated. If the native type is an array, the generated
size is limited a maximum of 128.
This method will raise an exception if the additional arguments for
the implementation's constructor are incorrect (e.g. TWO_CMRES_SELECT
).
This includes the case where arguments are supplied and the implementation
does not require additional arguments.
source
- RNG type.seed
- Seed value. It can be null
(in which case a
random value will be used).data
- Additional arguments to the implementation's constructor.
Please refer to the documentation of each specific implementation.IllegalArgumentException
- if the argument data required to initialize the
generator is incorrect.UnsupportedOperationException
- if the type of the seed
is invalid.create(RandomSource)
public static int createInt()
public static long createLong()
public static int[] createIntArray(int n)
n
- Size of the array to create.n
random numbers.public static long[] createLongArray(int n)
n
- Size of the array to create.n
random numbers.public static UniformRandomProvider unrestorable(UniformRandomProvider delegate)
delegate
generator in a new instance that
only provides access to the UniformRandomProvider
methods.
This method can be used to prevent access to any methods of the delegate
that are not defined in the UniformRandomProvider
interface.
For example this will prevent access to the "save/restore" functionality of
any RestorableUniformRandomProvider
created
by the RandomSource
factory methods, or will prevent access to the jump
functionality of generators.
Since the method applies to more than the RestorableUniformRandomProvider
interface it is left to the caller to determine if any methods require hiding,
for example:
UniformRandomProvider rng = ...;
if (rng instanceof JumpableUniformRandomProvider) {
rng = RandomSource.unrestorable(rng);
}
delegate
- Generator to which calls will be delegated.Copyright © 2016–2022 The Apache Software Foundation. All rights reserved.