RandomSource (Apache Commons RNG Simple 1.0 API)

java.lang.Object
- java.lang.Enum<RandomSource>
- - org.apache.commons.rng.simple.RandomSource

All Implemented Interfaces:

Serializable, Comparable<RandomSource>
```
public enum RandomSource
extends Enum<RandomSource>
```
This class provides the API for creating generators of random numbers.
Usage examples:
```
  UniformRandomProvider rng = RandomSource.create(RandomSource.MT);
 
```
or
```
  final int[] seed = new int[] { 196, 9, 0, 226 };
  UniformRandomProvider rng = RandomSource.create(RandomSource.MT, seed);
 
```
or
```
  final int[] seed = RandomSource.createIntArray(256);
  UniformRandomProvider rng = RandomSource.create(RandomSource.MT, seed);
 
```
where the first argument to method create is the identifier of the generator's concrete implementation, and the second the 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 generators 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.
The current implementations have no provision for producing non-overlapping sequences. For parallel applications, a possible workaround is that each thread uses a generator of a different type (see TWO_CMRES_SELECT).

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).
Since:

1.0

Enum Constant Summary

Enum Constants
Enum Constant and Description
`ISAAC` Source of randomness is `ISAACRandom`.
`JDK` Source of randomness is `JDKRandom`.
`KISS` Source of randomness is `KISSRandom`.
`MT` Source of randomness is `MersenneTwister`.
`MT_64` Source of randomness is `MersenneTwister64`.
`MWC_256` Source of randomness is `MultiplyWithCarry256`.
`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`.
`XOR_SHIFT_1024_S` Source of randomness is `XorShift1024Star`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static org.apache.commons.rng.RestorableUniformRandomProvider`	`create(RandomSource source)` Creates a random number generator with a random seed.
`static org.apache.commons.rng.RestorableUniformRandomProvider`	`create(RandomSource source, Object seed, Object... data)` Creates a random number generator with the given `seed`.
`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.
`boolean`	`isNativeSeed(Object seed)` Checks whether the type of given `seed` is the native type of the implementation.
`static org.apache.commons.rng.UniformRandomProvider`	`unrestorable(org.apache.commons.rng.UniformRandomProvider delegate)` Wraps the given `delegate` generator in a new instance that does not allow access to the "save/restore" functionality.
`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.

Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Enum Constant Detail
  - JDK
```
public static final RandomSource JDK
```
    Source of randomness is JDKRandom.
    - Native seed type: Long.
    - Native seed size: 1.
  - WELL_512_A
```
public static final RandomSource WELL_512_A
```
    Source of randomness is Well512a.
    - Native seed type: int[].
    - Native seed size: 16.
  - WELL_1024_A
```
public static final RandomSource WELL_1024_A
```
    Source of randomness is Well1024a.
    - Native seed type: int[].
    - Native seed size: 32.
  - WELL_19937_A
```
public static final RandomSource WELL_19937_A
```
    Source of randomness is Well19937a.
    - Native seed type: int[].
    - Native seed size: 624.
  - WELL_19937_C
```
public static final RandomSource WELL_19937_C
```
    Source of randomness is Well19937c.
    - Native seed type: int[].
    - Native seed size: 624.
  - WELL_44497_A
```
public static final RandomSource WELL_44497_A
```
    Source of randomness is Well44497a.
    - Native seed type: int[].
    - Native seed size: 1391.
  - WELL_44497_B
```
public static final RandomSource WELL_44497_B
```
    Source of randomness is Well44497b.
    - Native seed type: int[].
    - Native seed size: 1391.
  - MT
```
public static final RandomSource MT
```
    Source of randomness is MersenneTwister.
    - Native seed type: int[].
    - Native seed size: 624.
  - ISAAC
```
public static final RandomSource ISAAC
```
    Source of randomness is ISAACRandom.
    - Native seed type: int[].
    - Native seed size: 256.
  - SPLIT_MIX_64
```
public static final RandomSource SPLIT_MIX_64
```
    Source of randomness is SplitMix64.
    - Native seed type: Long.
    - Native seed size: 1.
  - XOR_SHIFT_1024_S
```
public static final RandomSource XOR_SHIFT_1024_S
```
    Source of randomness is XorShift1024Star.
    - Native seed type: long[].
    - Native seed size: 16.
  - TWO_CMRES
```
public static final RandomSource TWO_CMRES
```
    Source of randomness is TwoCmres. This generator is equivalent to TWO_CMRES_SELECT with the choice of the pair (0, 1) for the two subcycle generators.
    - Native seed type: Integer.
    - Native seed size: 1.
  - TWO_CMRES_SELECT
```
public static final RandomSource TWO_CMRES_SELECT
```
    Source of randomness is 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.
    - Native seed type: Integer.
    - Native seed size: 1.
  - MT_64
```
public static final RandomSource MT_64
```
    Source of randomness is MersenneTwister64.
    - Native seed type: long[].
    - Native seed size: 312.
  - MWC_256
```
public static final RandomSource MWC_256
```
    Source of randomness is MultiplyWithCarry256.
    - Native seed type: int[].
    - Native seed size: 257.
  - KISS
```
public static final RandomSource KISS
```
    Source of randomness is KISSRandom.
    - Native seed type: int[].
    - Native seed size: 4.
- Method Detail
  - values
```
public static RandomSource[] values()
```
    Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
```
for (RandomSource c : RandomSource.values())
    System.out.println(c);
```
    Returns:
    
    an array containing the constants of this enum type, in the order they are declared
  - valueOf
```
public static RandomSource valueOf(String name)
```
    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 name
    
    NullPointerException - if the argument is null
  - isNativeSeed
```
public boolean isNativeSeed(Object seed)
```
    Checks whether the type of given seed is the native type of the implementation.
    
    Parameters:
    
    seed - Seed value.
    
    Returns:
    
    true if the type of seed is the native type for this RNG source.
  - create
```
public static org.apache.commons.rng.RestorableUniformRandomProvider create(RandomSource source)
```
    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);
 
```
    Parameters:
    
    source - RNG type.
    
    Returns:
    
    the RNG.
    
    See Also:
    
    create(RandomSource,Object,Object[])
  - create
```
public static org.apache.commons.rng.RestorableUniformRandomProvider create(RandomSource source,
                                                                            Object seed,
                                                                            Object... data)
```
    Creates a random number generator with the given seed.
    Usage example:
```
  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:
    - 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 native seed type is an array and the seed is null, the size of the generated array will be 128.
    Parameters:
    
    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.
    
    Returns:
    
    the RNG.
    
    Throws:
    
    UnsupportedOperationException - if the type of the seed is invalid.
    
    IllegalStateException - if data is missing to initialize the generator implemented by the given source.
    
    See Also:
    
    create(RandomSource)
  - 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
```
public static org.apache.commons.rng.UniformRandomProvider unrestorable(org.apache.commons.rng.UniformRandomProvider delegate)
```
    Wraps the given delegate generator in a new instance that does not allow access to the "save/restore" functionality.
    
    Parameters:
    
    delegate - Generator to which calls will be delegated.
    
    Returns:
    
    a new instance whose state cannot be saved or restored.

Enum RandomSource

Enum Constant Summary

Method Summary

Methods inherited from class java.lang.Enum

Methods inherited from class java.lang.Object

Enum Constant Detail

JDK

WELL_512_A

WELL_1024_A

WELL_19937_A

WELL_19937_C

WELL_44497_A

WELL_44497_B

MT

ISAAC

SPLIT_MIX_64

XOR_SHIFT_1024_S

TWO_CMRES

TWO_CMRES_SELECT

MT_64

MWC_256

KISS

Method Detail

values

valueOf

isNativeSeed

create

create

createInt

createLong

createIntArray

createLongArray

unrestorable