Class BaseProvider
- java.lang.Object
-
- org.apache.commons.rng.core.BaseProvider
-
- All Implemented Interfaces:
RestorableUniformRandomProvider,UniformRandomProvider
- Direct Known Subclasses:
IntProvider,LongProvider
public abstract class BaseProvider extends Object implements RestorableUniformRandomProvider
Base class with default implementation for common methods.
-
-
Constructor Summary
Constructors Constructor Description BaseProvider()Create an instance.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected voidcheckIndex(int min, int max, int index)Checks whetherindexis in the range[min, max].protected voidcheckStateSize(byte[] state, int expected)Deprecated.Method is used internally and should be made private in some future release.protected byte[]composeStateInternal(byte[] state, byte[] parentState)Combine parent and subclass states.protected static int[]extendSeed(int[] seed, int length)Extend the seed to the specified minimum length.protected static long[]extendSeed(long[] seed, int length)Extend the seed to the specified minimum length.protected voidfillState(int[] state, int[] seed)Simple filling procedure.protected voidfillState(long[] state, long[] seed)Simple filling procedure.protected byte[]getStateInternal()Creates a snapshot of the RNG state.voidrestoreState(RandomProviderState state)RandomProviderStatesaveState()protected voidsetStateInternal(byte[] state)Resets the RNG to the givenstate.protected byte[][]splitStateInternal(byte[] state, int localStateLength)Splits the givenstateinto a part to be consumed by the caller in order to restore its local state, while the reminder is passed to the parent class.StringtoString()-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface org.apache.commons.rng.UniformRandomProvider
doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, nextBoolean, nextBytes, nextBytes, nextDouble, nextDouble, nextDouble, nextFloat, nextFloat, nextFloat, nextInt, nextInt, nextInt, nextLong, nextLong, nextLong
-
-
-
-
Constructor Detail
-
BaseProvider
public BaseProvider()
Create an instance.
-
-
Method Detail
-
saveState
public RandomProviderState saveState()
- Specified by:
saveStatein interfaceRestorableUniformRandomProvider
-
restoreState
public void restoreState(RandomProviderState state)
- Specified by:
restoreStatein interfaceRestorableUniformRandomProvider
-
composeStateInternal
protected byte[] composeStateInternal(byte[] state, byte[] parentState)
Combine parent and subclass states. This method must be called by all subclasses in order to ensure that state can be restored in case some of it is stored higher up in the class hierarchy. I.e. the body of the overriddengetStateInternal(), will end with a statement like the following:
wherereturn composeStateInternal(state, super.getStateInternal());stateis the state needed and defined by the class where the method is overridden.- Parameters:
state- State of the calling class.parentState- State of the calling class' parent.- Returns:
- the combined state. Bytes that belong to the local state will be stored at the beginning of the resulting array.
-
splitStateInternal
protected byte[][] splitStateInternal(byte[] state, int localStateLength)
Splits the givenstateinto a part to be consumed by the caller in order to restore its local state, while the reminder is passed to the parent class. I.e. the body of the overriddensetStateInternal(byte[]), will contain statements like the following:
wherefinal byte[][] s = splitState(state, localStateLength); // Use "s[0]" to recover the local state. super.setStateInternal(s[1]);stateis the combined state of the calling class and of all its parents.- Parameters:
state- State. The local state must be stored at the beginning of the array.localStateLength- Number of elements that will be consumed by the locally defined state.- Returns:
- the local state (in slot 0) and the parent state (in slot 1).
- Throws:
IllegalStateException- ifstate.length < localStateLength.
-
getStateInternal
protected byte[] getStateInternal()
Creates a snapshot of the RNG state.- Returns:
- the internal state.
-
setStateInternal
protected void setStateInternal(byte[] state)
Resets the RNG to the givenstate.- Parameters:
state- State (previously obtained by a call togetStateInternal()).- Throws:
IllegalStateException- if the size of the given array is not consistent with the state defined by this class.- See Also:
checkStateSize(byte[],int)
-
fillState
protected void fillState(int[] state, int[] seed)
Simple filling procedure. It will-
fill the beginning of
stateby copyingmin(seed.length, state.length)elements fromseed, -
set all remaining elements of
statewith non-zero values (even ifseed.length < state.length).
- Parameters:
state- State. Must be allocated.seed- Seed. Cannot be null.
-
fill the beginning of
-
fillState
protected void fillState(long[] state, long[] seed)
Simple filling procedure. It will-
fill the beginning of
stateby copyingmin(seed.length, state.length)elements fromseed, -
set all remaining elements of
statewith non-zero values (even ifseed.length < state.length).
- Parameters:
state- State. Must be allocated.seed- Seed. Cannot be null.
-
fill the beginning of
-
checkStateSize
@Deprecated protected void checkStateSize(byte[] state, int expected)
Deprecated.Method is used internally and should be made private in some future release.Checks that thestatehas theexpectedsize.- Parameters:
state- State.expected- Expected length ofstatearray.- Throws:
IllegalStateException- ifstate.length < expected.
-
checkIndex
protected void checkIndex(int min, int max, int index)
Checks whetherindexis in the range[min, max].- Parameters:
min- Lower bound.max- Upper bound.index- Value that must lie within the[min, max]interval.- Throws:
IndexOutOfBoundsException- ifindexis not within the[min, max]interval.
-
extendSeed
protected static long[] extendSeed(long[] seed, int length)
Extend the seed to the specified minimum length. If the seed is equal or greater than the minimum length, return the same seed unchanged. Otherwise:- Create a new array of the specified length
- Copy all elements of the seed into the array
- Fill the remaining values. The additional values will have at most one occurrence of zero. If the original seed is all zero, the first extended value will be non-zero.
This method can be used in constructors that must pass their seed to the super class to avoid a duplication of seed expansion to the minimum length required by the super class and the class:
public RNG extends AnotherRNG { public RNG(long[] seed) { super(seed = extendSeed(seed, SEED_SIZE)); // Use seed for additional state ... } }Note using the state filling procedure provided in
fillState(long[], long[])is not possible as it is an instance method. Calling a seed extension routine must use a static method.This method functions as if the seed has been extended using a
SplitMix64generator seeded withseed[0], or zero if the input seed length is zero.if (seed.length < length) { final long[] s = Arrays.copyOf(seed, length); final SplitMix64 rng = new SplitMix64(s[0]); for (int i = seed.length; i < length; i++) { s[i] = rng.nextLong(); } return s; }- Parameters:
seed- Input seedlength- The minimum length- Returns:
- the seed
- Since:
- 1.5
-
extendSeed
protected static int[] extendSeed(int[] seed, int length)
Extend the seed to the specified minimum length. If the seed is equal or greater than the minimum length, return the same seed unchanged. Otherwise:- Create a new array of the specified length
- Copy all elements of the seed into the array
- Fill the remaining values. The additional values will have at most one occurrence of zero. If the original seed is all zero, the first extended value will be non-zero.
This method can be used in constructors that must pass their seed to the super class to avoid a duplication of seed expansion to the minimum length required by the super class and the class:
public RNG extends AnotherRNG { public RNG(int[] seed) { super(seed = extendSeed(seed, SEED_SIZE)); // Use seed for additional state ... } }Note using the state filling procedure provided in
fillState(int[], int[])is not possible as it is an instance method. Calling a seed extension routine must use a static method.This method functions as if the seed has been extended using a
SplitMix64-style 32-bit generator seeded withseed[0], or zero if the input seed length is zero. The generator uses the 32-bit mixing function from MurmurHash3.- Parameters:
seed- Input seedlength- The minimum length- Returns:
- the seed
- Since:
- 1.5
-
-