Class SeedFactory
- java.lang.Object
-
- org.apache.commons.rng.simple.internal.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
orlong
types) that can be passed to themethods 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 anint[]
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 along[]
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 ofbyte
numbers for use as a seed using the supplied source of randomness.static int
createInt()
Creates anint
number for use as a seed.static int[]
createIntArray(int n)
Creates an array ofint
numbers for use as a seed.(package private) static int[]
createIntArray(int n, int from, int to)
Creates an array ofint
numbers for use as a seed.static long
createLong()
Creates along
number for use as a seed.static long[]
createLongArray(int n)
Creates an array oflong
numbers for use as a seed.(package private) static long[]
createLongArray(int n, int from, int to)
Creates an array oflong
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 betweenstart
inclusive andend
exclusive from the seed generator.private static void
fillLongArray(long[] array, int start, int end)
Fill the array betweenstart
inclusive andend
exclusive from the seed generator.
-
-
-
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 anint[]
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 along[]
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.
-
-
Method Detail
-
createInt
public static int createInt()
Creates anint
number for use as a seed.- Returns:
- a random number.
-
createLong
public static long createLong()
Creates along
number for use as a seed.- Returns:
- a random number.
-
createIntArray
public static int[] createIntArray(int n)
Creates an array ofint
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 ofint
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 oflong
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 oflong
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 betweenstart
inclusive andend
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 betweenstart
inclusive andend
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 ofbyte
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
-
-