Class SeedFactory

java.lang.Object
org.apache.commons.rng.simple.internal.SeedFactory

public final class SeedFactory extends Object
Utilities related to seeding.

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 methods that create a generator instance.
Although the seed-generating methods defined in this class will likely return different values for all calls, there is no guarantee that the produced seed will result always in a "good" sequence of numbers (even if the generator initialized with that seed is good).
There is no guarantee that sequences will not overlap.

Since:
1.0
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int
    Size of block to fill in an int[] seed per synchronized operation.
    private static final ReentrantLock
    The lock to own when using the seed generator.
    private static final int
    Size of block to fill in a long[] seed per synchronized operation.
    private static final UniformRandomProvider
    Generator with a long period.
    private static final int
    Size of the state array of "XoRoShiRo1024PlusPlus".
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Class contains only static methods.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) static byte[]
    createByteArray(UniformRandomProvider source, int n, int from, int to)
    Creates an array of byte numbers for use as a seed using the supplied source of randomness.
    static int
    Creates an int number for use as a seed.
    static int[]
    Creates an array of int numbers for use as a seed.
    (package private) static int[]
    createIntArray(int n, int from, int to)
    Creates an array of int numbers for use as a seed.
    static long
    Creates a long number for use as a seed.
    static long[]
    Creates an array of long numbers for use as a seed.
    (package private) static long[]
    createLongArray(int n, int from, int to)
    Creates an array of long numbers for use as a seed.
    (package private) static void
    ensureNonZero(byte[] seed, int from, int to, UniformRandomProvider source)
    Ensure the seed is not all-zero within the specified sub-range.
    (package private) static void
    ensureNonZero(int[] seed, int from, int to)
    Ensure the seed is not all-zero within the specified sub-range.
    (package private) static void
    ensureNonZero(long[] seed, int from, int to)
    Ensure the seed is not all-zero within the specified sub-range.
    (package private) static long
    ensureNonZero(RandomLongSource source, long value)
    Ensure the value is non-zero.
    private static void
    fillIntArray(int[] array, int start, int end)
    Fill the array between start inclusive and end exclusive from the seed generator.
    private static void
    fillLongArray(long[] array, int start, int end)
    Fill the array between start inclusive and end exclusive from the seed generator.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • XO_RO_SHI_RO_1024_STATE_SIZE

      private static final int XO_RO_SHI_RO_1024_STATE_SIZE
      Size of the state array of "XoRoShiRo1024PlusPlus".
      See Also:
    • INT_ARRAY_BLOCK_SIZE

      private static final int INT_ARRAY_BLOCK_SIZE
      Size of block to fill in an int[] seed per synchronized operation.
      See Also:
    • LONG_ARRAY_BLOCK_SIZE

      private static final int LONG_ARRAY_BLOCK_SIZE
      Size of block to fill in a long[] seed per synchronized operation.
      See Also:
    • LOCK

      private static final ReentrantLock LOCK
      The lock to own when using the seed generator. This lock is unfair and there is no particular access order for waiting threads.

      This is used as an alternative to synchronized statements to guard access to the seed generator.

    • SEED_GENERATOR

      private static final UniformRandomProvider SEED_GENERATOR
      Generator with a long period.
  • Constructor Details

    • SeedFactory

      private SeedFactory()
      Class contains only static methods.
  • Method Details

    • createInt

      public static int createInt()
      Creates an int number for use as a seed.
      Returns:
      a random number.
    • createLong

      public static long createLong()
      Creates a long number for use as a seed.
      Returns:
      a random number.
    • createIntArray

      public static int[] createIntArray(int n)
      Creates an array of int numbers for use as a seed.
      Parameters:
      n - Size of the array to create.
      Returns:
      an array of n random numbers.
    • createIntArray

      static int[] createIntArray(int n, int from, int to)
      Creates an array of int numbers for use as a seed. Optionally ensure a sub-range of the array is not all-zero.

      This method is package-private for use by NativeSeedType.

      Parameters:
      n - Size of the array to create.
      from - The start of the not all-zero sub-range (inclusive).
      to - The end of the not all-zero sub-range (exclusive).
      Returns:
      an array of n random numbers.
      Throws:
      IndexOutOfBoundsException - if the sub-range is invalid
      Since:
      1.5
    • createLongArray

      public static long[] createLongArray(int n)
      Creates an array of long numbers for use as a seed.
      Parameters:
      n - Size of the array to create.
      Returns:
      an array of n random numbers.
    • createLongArray

      static long[] createLongArray(int n, int from, int to)
      Creates an array of long numbers for use as a seed. Optionally ensure a sub-range of the array is not all-zero.

      This method is package-private for use by NativeSeedType.

      Parameters:
      n - Size of the array to create.
      from - The start of the not all-zero sub-range (inclusive).
      to - The end of the not all-zero sub-range (exclusive).
      Returns:
      an array of n random numbers.
      Throws:
      IndexOutOfBoundsException - if the sub-range is invalid
      Since:
      1.5
    • fillIntArray

      private static void fillIntArray(int[] array, int start, int end)
      Fill the array between start inclusive and end exclusive from the seed generator. The lock is used to guard access to the generator.
      Parameters:
      array - Array data.
      start - Start (inclusive).
      end - End (exclusive).
    • fillLongArray

      private static void fillLongArray(long[] array, int start, int end)
      Fill the array between start inclusive and end exclusive from the seed generator. The lock is used to guard access to the generator.
      Parameters:
      array - Array data.
      start - Start (inclusive).
      end - End (exclusive).
    • createByteArray

      static byte[] createByteArray(UniformRandomProvider source, int n, int from, int to)
      Creates an array of byte numbers for use as a seed using the supplied source of randomness. A sub-range can be specified that must not contain all zeros.
      Parameters:
      source - Source of randomness.
      n - Size of the array to create.
      from - The start of the not all-zero sub-range (inclusive).
      to - The end of the not all-zero sub-range (exclusive).
      Returns:
      an array of n random numbers.
    • ensureNonZero

      static void ensureNonZero(int[] seed, int from, int to)
      Ensure the seed is not all-zero within the specified sub-range.

      This method will check the sub-range and if all are zero it will fill the range with a random sequence seeded from the default source of random int values. The fill ensures position from has a non-zero value; and the entire sub-range has a maximum of one zero. The method ensures any length sub-range contains non-zero bits. The output seed is suitable for generators that cannot be seeded with all zeros in the specified sub-range.

      Parameters:
      seed - Seed array (modified in place).
      from - The start of the not all-zero sub-range (inclusive).
      to - The end of the not all-zero sub-range (exclusive).
      Throws:
      IndexOutOfBoundsException - if the sub-range is invalid
      See Also:
    • ensureNonZero

      static void ensureNonZero(long[] seed, int from, int to)
      Ensure the seed is not all-zero within the specified sub-range.

      This method will check the sub-range and if all are zero it will fill the range with a random sequence seeded from the default source of random long values. The fill ensures position from has a non-zero value; and the entire sub-range has a maximum of one zero. The method ensures any length sub-range contains non-zero bits. The output seed is suitable for generators that cannot be seeded with all zeros in the specified sub-range.

      Parameters:
      seed - Seed array (modified in place).
      from - The start of the not all-zero sub-range (inclusive).
      to - The end of the not all-zero sub-range (exclusive).
      Throws:
      IndexOutOfBoundsException - if the sub-range is invalid
      See Also:
    • ensureNonZero

      static void ensureNonZero(byte[] seed, int from, int to, UniformRandomProvider source)
      Ensure the seed is not all-zero within the specified sub-range.

      This method will check the sub-range and if all are zero it will fill the range with a random sequence seeded from the provided source of randomness. If the range length is above 8 then the first 8 bytes in the range are ensured to not all be zero. If the range length is below 8 then the first byte in the range is ensured to be non-zero. The method ensures any length sub-range contains non-zero bits. The output seed is suitable for generators that cannot be seeded with all zeros in the specified sub-range.

      Parameters:
      seed - Seed array (modified in place).
      from - The start of the not all-zero sub-range (inclusive).
      to - The end of the not all-zero sub-range (exclusive).
      source - Source of randomness.
      Throws:
      IndexOutOfBoundsException - if the sub-range is invalid
    • ensureNonZero

      static long ensureNonZero(RandomLongSource source, long value)
      Ensure the value is non-zero.

      This method will replace a zero with a non-zero random number from the random source.

      Parameters:
      source - Source of randomness.
      value - Value.
      Returns:
      value if non-zero; else a new random number