Enum RandomSource
- All Implemented Interfaces:
Serializable
,Comparable<RandomSource>
,java.lang.constant.Constable
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
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:
- In any sub-sequence, it is expected that the same numbers can occur, with a probability getting higher as the range of allowed values is smaller and the sequence becomes longer.
- It possible that the resulting "seed" will not be good (i.e. it will not generate a sufficiently uniformly random sequence for the intended purpose), even if the generator is good! The only way to ensure that the selected seed will make the generator produce a good sequence is to submit that sequence to a series of stringent tests, as provided by tools such as dieharder or TestU01.
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).
Parallel applications
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
).
- Since:
- 1.0
-
Nested Class Summary
Nested classes/interfaces inherited from class java.lang.Enum
Enum.EnumDesc<E extends Enum<E>>
-
Enum Constant Summary
Enum ConstantsEnum ConstantDescriptionSource of randomness isISAACRandom
.Source of randomness isJDKRandom
.Source of randomness isJenkinsSmallFast32
.Source of randomness isJenkinsSmallFast64
.Source of randomness isKISSRandom
.Source of randomness isL128X1024Mix
.Source of randomness isL128X128Mix
.Source of randomness isL128X256Mix
.Source of randomness isL32X64Mix
.Source of randomness isL64X1024Mix
.Source of randomness isL64X128Mix
.Source of randomness isL64X128StarStar
.Source of randomness isL64X256Mix
.Source of randomness isMiddleSquareWeylSequence
.Source of randomness isMersenneTwister
.Source of randomness isMersenneTwister64
.Source of randomness isMultiplyWithCarry256
.Source of randomness isPcgMcgXshRr32
.Source of randomness isPcgMcgXshRs32
.Source of randomness isPcgRxsMXs64
.Source of randomness isPcgRxsMXs64
.Source of randomness isPcgXshRr32
.Source of randomness isPcgXshRr32
.Source of randomness isPcgXshRs32
.Source of randomness isPcgXshRs32
.Source of randomness isDotyHumphreySmallFastCounting32
.Source of randomness isDotyHumphreySmallFastCounting64
.Source of randomness isSplitMix64
.Source of randomness isTwoCmres
.Source of randomness isTwoCmres
, with explicit selection of the two subcycle generators.Source of randomness isWell1024a
.Source of randomness isWell19937a
.Source of randomness isWell19937c
.Source of randomness isWell44497a
.Source of randomness isWell44497b
.Source of randomness isWell512a
.Source of randomness isXoRoShiRo1024PlusPlus
.Source of randomness isXoRoShiRo1024Star
.Source of randomness isXoRoShiRo1024StarStar
.Source of randomness isXoRoShiRo128Plus
.Source of randomness isXoRoShiRo128PlusPlus
.Source of randomness isXoRoShiRo128StarStar
.Source of randomness isXoRoShiRo64Star
.Source of randomness isXoRoShiRo64StarStar
.Source of randomness isXoShiRo128Plus
.Source of randomness isXoShiRo128PlusPlus
.Source of randomness isXoShiRo128StarStar
.Source of randomness isXoShiRo256Plus
.Source of randomness isXoShiRo256PlusPlus
.Source of randomness isXoShiRo256StarStar
.Source of randomness isXoShiRo512Plus
.Source of randomness isXoShiRo512PlusPlus
.Source of randomness isXoShiRo512StarStar
.Deprecated.Source of randomness isXorShift1024StarPhi
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final ProviderBuilder.RandomSourceInternal
Internal identifier. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptioncreate()
Creates a random number generator with a random seed.Creates a random number generator with the givenseed
.create
(RandomSource source) Deprecated.It is preferred to use thecreate()
instance method.create
(RandomSource source, Object seed, Object... data) Deprecated.It is preferred to use thecreate(Object, Object...)
instance method.static int
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
Creates a number for use as a seed.static long[]
createLongArray
(int n) Creates an array of numbers for use as a seed.byte[]
Creates a seed suitable for the implementing class represented by this random source.byte[]
Creates a seed suitable for the implementing class represented by this random source using the supplied source of randomness.(package private) ProviderBuilder.RandomSourceInternal
private boolean
isAssignableTo
(Class<?> type) Determines if the implementing class represented by this random source is either the same as, or is a subclass or subinterface of, the class or interface represented by the specifiedClass
parameter.boolean
Checks whether the implementing class represented by this random source supports theJumpableUniformRandomProvider
interface.boolean
Checks whether the implementing class represented by this random source supports theLongJumpableUniformRandomProvider
interface.boolean
isNativeSeed
(Object seed) Checks whether the type of givenseed
is the native type of the implementation.boolean
Checks whether the implementing class represented by this random source supports theSplittableUniformRandomProvider
interface.static UniformRandomProvider
unrestorable
(UniformRandomProvider delegate) Wraps the givendelegate
generator in a new instance that only provides access to theUniformRandomProvider
methods.static RandomSource
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.
-
Enum Constant Details
-
JDK
Source of randomness isJDKRandom
.- Native seed type:
Long
.
- Native seed type:
-
WELL_512_A
Source of randomness isWell512a
.- Native seed type:
int[]
. - Native seed size: 16.
- Native seed type:
-
WELL_1024_A
Source of randomness isWell1024a
.- Native seed type:
int[]
. - Native seed size: 32.
- Native seed type:
-
WELL_19937_A
Source of randomness isWell19937a
.- Native seed type:
int[]
. - Native seed size: 624.
- Native seed type:
-
WELL_19937_C
Source of randomness isWell19937c
.- Native seed type:
int[]
. - Native seed size: 624.
- Native seed type:
-
WELL_44497_A
Source of randomness isWell44497a
.- Native seed type:
int[]
. - Native seed size: 1391.
- Native seed type:
-
WELL_44497_B
Source of randomness isWell44497b
.- Native seed type:
int[]
. - Native seed size: 1391.
- Native seed type:
-
MT
Source of randomness isMersenneTwister
.- Native seed type:
int[]
. - Native seed size: 624.
- Native seed type:
-
ISAAC
Source of randomness isISAACRandom
.- Native seed type:
int[]
. - Native seed size: 256.
- Native seed type:
-
SPLIT_MIX_64
Source of randomness isSplitMix64
.- Native seed type:
Long
.
- Native seed type:
-
XOR_SHIFT_1024_S
Deprecated.Since 1.3, where it is recommended to useXOR_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.Source of randomness isXorShift1024Star
.- Native seed type:
long[]
. - Native seed size: 16.
- Native seed type:
-
TWO_CMRES
Source of randomness isTwoCmres
. This generator is equivalent toTWO_CMRES_SELECT
with the choice of the pair(0, 1)
for the two subcycle generators.- Native seed type:
Integer
.
- Native seed type:
-
TWO_CMRES_SELECT
Source of randomness isTwoCmres
, 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.- Native seed type:
Integer
.
- Native seed type:
-
MT_64
Source of randomness isMersenneTwister64
.- Native seed type:
long[]
. - Native seed size: 312.
- Native seed type:
-
MWC_256
Source of randomness isMultiplyWithCarry256
.- Native seed type:
int[]
. - Native seed size: 257.
- Native seed type:
-
KISS
Source of randomness isKISSRandom
.- Native seed type:
int[]
. - Native seed size: 4.
- Native seed type:
-
XOR_SHIFT_1024_S_PHI
Source of randomness isXorShift1024StarPhi
.- Native seed type:
long[]
. - Native seed size: 16.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_64_S
Source of randomness isXoRoShiRo64Star
.- Native seed type:
int[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_64_SS
Source of randomness isXoRoShiRo64StarStar
.- Native seed type:
int[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_128_PLUS
Source of randomness isXoShiRo128Plus
.- Native seed type:
int[]
. - Native seed size: 4.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_128_SS
Source of randomness isXoShiRo128StarStar
.- Native seed type:
int[]
. - Native seed size: 4.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_128_PLUS
Source of randomness isXoRoShiRo128Plus
.- Native seed type:
long[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_128_SS
Source of randomness isXoRoShiRo128StarStar
.- Native seed type:
long[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_256_PLUS
Source of randomness isXoShiRo256Plus
.- Native seed type:
long[]
. - Native seed size: 4.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_256_SS
Source of randomness isXoShiRo256StarStar
.- Native seed type:
long[]
. - Native seed size: 4.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_512_PLUS
Source of randomness isXoShiRo512Plus
.- Native seed type:
long[]
. - Native seed size: 8.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_512_SS
Source of randomness isXoShiRo512StarStar
.- Native seed type:
long[]
. - Native seed size: 8.
- Since:
- 1.3
- Native seed type:
-
PCG_XSH_RR_32
Source of randomness isPcgXshRr32
.- Native seed type:
long[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
PCG_XSH_RS_32
Source of randomness isPcgXshRs32
.- Native seed type:
long[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
PCG_RXS_M_XS_64
Source of randomness isPcgRxsMXs64
.- Native seed type:
long[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
PCG_MCG_XSH_RR_32
Source of randomness isPcgMcgXshRr32
.- Native seed type:
Long
.
- Since:
- 1.3
- Native seed type:
-
PCG_MCG_XSH_RS_32
Source of randomness isPcgMcgXshRs32
.- Native seed type:
Long
.
- Since:
- 1.3
- Native seed type:
-
MSWS
Source of randomness isMiddleSquareWeylSequence
.- Native seed type:
long[]
. - Native seed size: 3.
- Since:
- 1.3
- Native seed type:
-
SFC_32
Source of randomness isDotyHumphreySmallFastCounting32
.- Native seed type:
int[]
. - Native seed size: 3.
- Since:
- 1.3
- Native seed type:
-
SFC_64
Source of randomness isDotyHumphreySmallFastCounting64
.- Native seed type:
long[]
. - Native seed size: 3.
- Since:
- 1.3
- Native seed type:
-
JSF_32
Source of randomness isJenkinsSmallFast32
.- Native seed type:
Integer
.
- Since:
- 1.3
- Native seed type:
-
JSF_64
Source of randomness isJenkinsSmallFast64
.- Native seed type:
Long
.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_128_PP
Source of randomness isXoShiRo128PlusPlus
.- Native seed type:
int[]
. - Native seed size: 4.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_128_PP
Source of randomness isXoRoShiRo128PlusPlus
.- Native seed type:
long[]
. - Native seed size: 2.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_256_PP
Source of randomness isXoShiRo256PlusPlus
.- Native seed type:
long[]
. - Native seed size: 4.
- Since:
- 1.3
- Native seed type:
-
XO_SHI_RO_512_PP
Source of randomness isXoShiRo512PlusPlus
.- Native seed type:
long[]
. - Native seed size: 8.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_1024_PP
Source of randomness isXoRoShiRo1024PlusPlus
.- Native seed type:
long[]
. - Native seed size: 16.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_1024_S
Source of randomness isXoRoShiRo1024Star
.- Native seed type:
long[]
. - Native seed size: 16.
- Since:
- 1.3
- Native seed type:
-
XO_RO_SHI_RO_1024_SS
Source of randomness isXoRoShiRo1024StarStar
.- Native seed type:
long[]
. - Native seed size: 16.
- Since:
- 1.3
- Native seed type:
-
PCG_XSH_RR_32_OS
Source of randomness isPcgXshRr32
.- Native seed type:
Long
.
- Since:
- 1.4
- Native seed type:
-
PCG_XSH_RS_32_OS
Source of randomness isPcgXshRs32
.- Native seed type:
Long
.
- Since:
- 1.4
- Native seed type:
-
PCG_RXS_M_XS_64_OS
Source of randomness isPcgRxsMXs64
.- Native seed type:
Long
.
- Since:
- 1.4
- Native seed type:
-
L64_X128_SS
Source of randomness isL64X128StarStar
.- Native seed type:
long[]
. - Native seed size: 4.
- Since:
- 1.5
- Native seed type:
-
L64_X128_MIX
Source of randomness isL64X128Mix
.- Native seed type:
long[]
. - Native seed size: 4.
- Since:
- 1.5
- Native seed type:
-
L64_X256_MIX
Source of randomness isL64X256Mix
.- Native seed type:
long[]
. - Native seed size: 6.
- Since:
- 1.5
- Native seed type:
-
L64_X1024_MIX
Source of randomness isL64X1024Mix
.- Native seed type:
long[]
. - Native seed size: 18.
- Since:
- 1.5
- Native seed type:
-
L128_X128_MIX
Source of randomness isL128X128Mix
.- Native seed type:
long[]
. - Native seed size: 6.
- Since:
- 1.5
- Native seed type:
-
L128_X256_MIX
Source of randomness isL128X256Mix
.- Native seed type:
long[]
. - Native seed size: 8.
- Since:
- 1.5
- Native seed type:
-
L128_X1024_MIX
Source of randomness isL128X1024Mix
.- Native seed type:
long[]
. - Native seed size: 20.
- Since:
- 1.5
- Native seed type:
-
L32_X64_MIX
Source of randomness isL32X64Mix
.- Native seed type:
int[]
. - Native seed size: 4.
- Since:
- 1.5
- Native seed type:
-
-
Field Details
-
internalIdentifier
Internal identifier.
-
-
Constructor Details
-
RandomSource
- Parameters:
id
- Internal identifier.
-
-
Method Details
-
values
Returns an array containing the constants of this enum type, in the order they are declared.- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
valueOf
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is null
-
getInternalIdentifier
ProviderBuilder.RandomSourceInternal getInternalIdentifier()- Returns:
- the internal identifier.
-
isNativeSeed
Checks whether the type of givenseed
is the native type of the implementation.- Parameters:
seed
- Seed value.- Returns:
true
if the type ofseed
is the native type for this RNG source.
-
createSeed
public byte[] createSeed()Creates a seed suitable for the implementing class represented by this random source.The seed will be created as if passing a
null
seed to the methodcreate(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);
- Returns:
- the seed
- Since:
- 1.3
-
createSeed
Creates a seed suitable for the implementing class represented by this random source using the supplied source of randomness.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);
- Parameters:
rng
- Source of randomness.- Returns:
- the seed
- Since:
- 1.3
-
isJumpable
public boolean isJumpable()Checks whether the implementing class represented by this random source supports theJumpableUniformRandomProvider
interface. Iftrue
the instance returned bycreate(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(); }
- Returns:
true
if jumpable- Since:
- 1.3
-
isLongJumpable
public boolean isLongJumpable()Checks whether the implementing class represented by this random source supports theLongJumpableUniformRandomProvider
interface. Iftrue
the instance returned bycreate(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(); }
- Returns:
true
if long jumpable- Since:
- 1.3
-
isSplittable
public boolean isSplittable()Checks whether the implementing class represented by this random source supports theSplittableUniformRandomProvider
interface. Iftrue
the instance returned bycreate(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(); }
- Returns:
true
if splittable- Since:
- 1.5
-
isAssignableTo
Determines if the implementing class represented by this random source is either the same as, or is a subclass or subinterface of, the class or interface represented by the specifiedClass
parameter. It returns true if so; otherwise it returns false.- Parameters:
type
- theClass
object to be checked- Returns:
- the boolean value indicating whether the class of this random source can be assigned to objects of the specified type
-
create
Creates a random number generator with a random seed.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
).- Returns:
- the RNG.
- Throws:
IllegalArgumentException
- if the generator requires arguments in addition to a seed.- Since:
- 1.4
- See Also:
-
create
Creates a random number generator with the givenseed
.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
(orint
)Long
(orlong
)int[]
long[]
byte[]
Notes:
-
When the seed type passed as argument is more complex (i.e. more
bits can be independently chosen) than the generator's
native type
, the conversion of a set of different seeds will necessarily result in the same value of the native seed type. - When the native seed type is an array, the same remark applies when the array contains more bits than the state of the generator.
-
When the
seed
isnull
, 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.- Parameters:
seed
- Seed value. It can benull
(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.- Returns:
- the RNG.
- Throws:
IllegalArgumentException
- if the argument data required to initialize the generator is incorrect.UnsupportedOperationException
- if the type of theseed
is invalid.- Since:
- 1.4
- See Also:
-
create
Deprecated.It is preferred to use thecreate()
instance method.Creates a random number generator with a random seed.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
).- Parameters:
source
- RNG type.- Returns:
- the RNG.
- Throws:
IllegalArgumentException
- if the generator requires arguments in addition to a seed.- See Also:
-
create
@Deprecated public static RestorableUniformRandomProvider create(RandomSource source, Object seed, Object... data) Deprecated.It is preferred to use thecreate(Object, Object...)
instance method.Creates a random number generator with the givenseed
.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
(orint
)Long
(orlong
)int[]
long[]
byte[]
Notes:
-
When the seed type passed as argument is more complex (i.e. more
bits can be independently chosen) than the generator's
native type
, the conversion of a set of different seeds will necessarily result in the same value of the native seed type. - When the native seed type is an array, the same remark applies when the array contains more bits than the state of the generator.
-
When the
seed
isnull
, 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.- Parameters:
source
- RNG type.seed
- Seed value. It can benull
(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.- Returns:
- the RNG.
- Throws:
IllegalArgumentException
- if the argument data required to initialize the generator is incorrect.UnsupportedOperationException
- if the type of theseed
is invalid.- See Also:
-
createInt
public static int createInt()Creates a number for use as a seed.- Returns:
- a random number.
-
createLong
public static long createLong()Creates a number for use as a seed.- Returns:
- a random number.
-
createIntArray
public static int[] createIntArray(int n) Creates an array of numbers for use as a seed.- Parameters:
n
- Size of the array to create.- Returns:
- an array of
n
random numbers.
-
createLongArray
public static long[] createLongArray(int n) Creates an array of numbers for use as a seed.- Parameters:
n
- Size of the array to create.- Returns:
- an array of
n
random numbers.
-
unrestorable
Wraps the givendelegate
generator in a new instance that only provides access to theUniformRandomProvider
methods.This method can be used to prevent access to any methods of the
delegate
that are not defined in theUniformRandomProvider
interface. For example this will prevent access to the "save/restore" functionality of anyRestorableUniformRandomProvider
created
by theRandomSource
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); }
- Parameters:
delegate
- Generator to which calls will be delegated.- Returns:
- a new instance
-
XOR_SHIFT_1024_S_PHI
instead due to its slightly better (more uniform) output.