Package org.apache.commons.rng.simple.internal

Class SeedFactory

  • public final class SeedFactory
extends java.lang.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 int INT_ARRAY_BLOCK_SIZE
      Size of block to fill in an int[] seed per synchronized operation.
      private static java.util.concurrent.locks.ReentrantLock LOCK
      The lock to own when using the seed generator.
      private static int LONG_ARRAY_BLOCK_SIZE
      Size of block to fill in a long[] seed per synchronized operation.
      private static UniformRandomProvider SEED_GENERATOR
      Generator with a long period.
      private static int XO_RO_SHI_RO_1024_STATE_SIZE
      Size of the state array of "XoRoShiRo1024PlusPlus".

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private SeedFactory()
      Class contains only static methods.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      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 createInt()
      Creates an int number for use as a seed.
      static int[] createIntArray​(int n)
      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 createLong()
      Creates a long number for use as a seed.
      static long[] createLongArray​(int n)
      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 Detail

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • LOCK

        private static final java.util.concurrent.locks.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 Detail

      • SeedFactory

        private SeedFactory()
        Class contains only static methods.

    • Method Detail

      • 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:
        java.lang.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:
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the sub-range is invalid
        See Also:
        createInt()

      • 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:
        java.lang.IndexOutOfBoundsException - if the sub-range is invalid
        See Also:
        createLong()

      • 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:
        java.lang.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