Package org.apache.commons.rng.simple

Enum RandomSource

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<RandomSource>, java.lang.constant.Constable
    public enum RandomSource
extends java.lang.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 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.

      • 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

        @Deprecated
public static final RandomSource 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.
        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.

      • KISS

        public static final RandomSource KISS
        Source of randomness is KISSRandom.
        • Native seed type: int[].
        • Native seed size: 4.

      • XOR_SHIFT_1024_S_PHI

        public static final RandomSource XOR_SHIFT_1024_S_PHI
        Source of randomness is XorShift1024StarPhi.
        • Native seed type: long[].
        • Native seed size: 16.

      • XO_RO_SHI_RO_64_S

        public static final RandomSource XO_RO_SHI_RO_64_S
        Source of randomness is XoRoShiRo64Star.
        • Native seed type: int[].
        • Native seed size: 2.

      • XO_RO_SHI_RO_64_SS

        public static final RandomSource XO_RO_SHI_RO_64_SS
        Source of randomness is XoRoShiRo64StarStar.
        • Native seed type: int[].
        • Native seed size: 2.

      • XO_SHI_RO_128_PLUS

        public static final RandomSource XO_SHI_RO_128_PLUS
        Source of randomness is XoShiRo128Plus.
        • Native seed type: int[].
        • Native seed size: 4.

      • XO_SHI_RO_128_SS

        public static final RandomSource XO_SHI_RO_128_SS
        Source of randomness is XoShiRo128StarStar.
        • Native seed type: int[].
        • Native seed size: 4.

      • XO_RO_SHI_RO_128_PLUS

        public static final RandomSource XO_RO_SHI_RO_128_PLUS
        Source of randomness is XoRoShiRo128Plus.
        • Native seed type: long[].
        • Native seed size: 2.

      • XO_RO_SHI_RO_128_SS

        public static final RandomSource XO_RO_SHI_RO_128_SS
        Source of randomness is XoRoShiRo128StarStar.
        • Native seed type: long[].
        • Native seed size: 2.

      • XO_SHI_RO_256_PLUS

        public static final RandomSource XO_SHI_RO_256_PLUS
        Source of randomness is XoShiRo256Plus.
        • Native seed type: long[].
        • Native seed size: 4.

      • XO_SHI_RO_256_SS

        public static final RandomSource XO_SHI_RO_256_SS
        Source of randomness is XoShiRo256StarStar.
        • Native seed type: long[].
        • Native seed size: 4.

      • XO_SHI_RO_512_PLUS

        public static final RandomSource XO_SHI_RO_512_PLUS
        Source of randomness is XoShiRo512Plus.
        • Native seed type: long[].
        • Native seed size: 8.

      • XO_SHI_RO_512_SS

        public static final RandomSource XO_SHI_RO_512_SS
        Source of randomness is XoShiRo512StarStar.
        • Native seed type: long[].
        • Native seed size: 8.

    • Method Detail

      • values

        public static RandomSource[] 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

        public static RandomSource valueOf​(java.lang.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:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null

      • isNativeSeed

        public boolean isNativeSeed​(java.lang.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 RestorableUniformRandomProvider create​(RandomSource source,
                                                     java.lang.Object seed,
                                                     java.lang.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:
        java.lang.UnsupportedOperationException - if the type of the seed is invalid.
        java.lang.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 UniformRandomProvider unrestorable​(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.