Package io.github.pr0methean.betterrandom.prng

Class Pcg128Random

java.lang.Object

java.util.Random

io.github.pr0methean.betterrandom.prng.BaseRandom

io.github.pr0methean.betterrandom.prng.Pcg128Random

All Implemented Interfaces:

ByteArrayReseedableRandom, EntropyCountingRandom, RepeatableRandom, SeekableRandom, Dumpable, Serializable

public class Pcg128Random
extends BaseRandom
implements SeekableRandom

From the original description, "PCG is a family of simple fast space-efficient statistically good algorithms for random number generation. Unlike many general-purpose RNGs, they are also hard to predict." This is a Java port of the "XSH RR 128/64" generator presented at http://www.pcg-random.org/. Period is 2¹²⁶ bits. This PRNG is seekable.

Sharing a single instance across threads that are frequently using it concurrently isn't recommended, unless memory is too constrained to use with a ThreadLocalRandomWrapper.

Author:

M.E. O'Neill (algorithm and C++ implementation), Chris Hennick (Java port)

See Also:

Serialized Form

Field Summary

Fields inherited from class io.github.pr0methean.betterrandom.prng.BaseRandom

ENTROPY_OF_DOUBLE, ENTROPY_OF_FLOAT, entropyBits, lock, randomSeeder, seed, superConstructorFinished

Constructor Summary

Constructors

Constructor	Description
Pcg128Random()	Creates a new PRNG with a seed from the DefaultSeedGenerator.
Pcg128Random(byte[] seed)	Creates a new PRNG with the provided seed.
Pcg128Random(SeedGenerator seedGenerator)	Creates a new PRNG with a seed from the provided SeedGenerator.

Method Summary

Modifier and Type	Method	Description
protected MoreObjects.ToStringHelper	addSubclassFields(MoreObjects.ToStringHelper original)	Adds the fields that were not inherited from BaseRandom to the given MoreObjects.ToStringHelper for dumping.
void	advance(long delta)	Advances the generator forward delta steps, but does so in logarithmic time.
void	advance(long highDelta, long lowDelta)	Advances the generator forward highDelta << 64 + lowDelta steps, but does so in logarithmic time.
int	getNewSeedLength()	Returns the preferred length of a new byte-array seed.
protected int	next(int bits)	Generates the next pseudorandom number.
protected double	nextDoubleNoEntropyDebit()	Returns the next random double between 0.0 (inclusive) and 1.0 (exclusive), but does not debit entropy.
protected long	nextLongNoEntropyDebit()	Returns the next random long, but does not debit entropy.
void	setSeed(long seed)	Sets the seed of this random number generator using a single long seed, if this implementation supports that.
void	setSeedInternal(byte[] seed)	Sets the seed, and should be overridden to set other state that derives from the seed.

Methods inherited from class io.github.pr0methean.betterrandom.prng.BaseRandom

checkLength, checkValidRange, creditEntropyForNewSeed, debitEntropy, doubles, doubles, doubles, doubles, dump, entropyOfInt, entropyOfLong, fallbackSetSeedIfInitialized, gaussians, gaussians, getEntropyBits, getRandomSeeder, getSeed, initTransientFields, internalNextGaussian, ints, ints, ints, ints, lockForNextGaussian, longs, longs, longs, longs, nextBoolean, nextBytes, nextDouble, nextDouble, nextDouble, nextElement, nextElement, nextEnum, nextFloat, nextGaussian, nextInt, nextInt, nextInt, nextLong, nextLong, nextLong, preferSeedWithLong, setRandomSeeder, setSeed, supportsMultipleSeedLengths, unlockForNextGaussian, usesParallelStreams, withProbability, withProbabilityInternal

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.github.pr0methean.betterrandom.EntropyCountingRandom

needsReseedingEarly

Methods inherited from interface io.github.pr0methean.betterrandom.RepeatableRandom

getSeed

Constructor Detail

Pcg128Random

public Pcg128Random()

Creates a new PRNG with a seed from the DefaultSeedGenerator.

Pcg128Random

public Pcg128Random(SeedGenerator seedGenerator)
             throws SeedException

Creates a new PRNG with a seed from the provided SeedGenerator.

Parameters:

seedGenerator - the seed generator that will generate the initial seed

Throws:

SeedException - if seedGenerator fails to generate a seed

Pcg128Random

public Pcg128Random(byte[] seed)

Creates a new PRNG with the provided seed.

Parameters:

seed - the seed; must be exactly 16 bytes

Method Detail

setSeed

public void setSeed(long seed)

Description copied from class: BaseRandom

Sets the seed of this random number generator using a single long seed, if this implementation supports that. If it is capable of using 64 bits or less of seed data (i.e. if {@link #getNewSeedLength()} <= {@link Long#BYTES}), then this method shall replace the entire seed as Random.setSeed(long) does; otherwise, it shall either combine the input with the existing seed as SecureRandom.setSeed(long) does, or it shall generate a new seed using the DefaultSeedGenerator. The latter is a backward-compatibility measure and can be very slow.

Overrides:

setSeed in class BaseRandom

See Also:

ByteArrayReseedableRandom.preferSeedWithLong()

nextDoubleNoEntropyDebit

protected double nextDoubleNoEntropyDebit()

Description copied from class: BaseRandom

Returns the next random double between 0.0 (inclusive) and 1.0 (exclusive), but does not debit entropy.

Overrides:

nextDoubleNoEntropyDebit in class BaseRandom

Returns:

a pseudorandom double.

advance

public void advance(long delta)

Description copied from interface: SeekableRandom

Advances the generator forward delta steps, but does so in logarithmic time.

Specified by:

advance in interface SeekableRandom

Parameters:

delta - the number of steps to advance; can be negative

advance

public void advance(long highDelta,
                    long lowDelta)

Advances the generator forward highDelta << 64 + lowDelta steps, but does so in logarithmic time.

Parameters:

highDelta - high quadword of the distance to advance

lowDelta - low quadword of the distance to advance

setSeedInternal

public void setSeedInternal(byte[] seed)

Description copied from class: BaseRandom

Sets the seed, and should be overridden to set other state that derives from the seed. Called by BaseRandom.setSeed(byte[]), constructors, and readObject(ObjectInputStream). When called after initialization, the BaseRandom.lock is always held.

Overrides:

setSeedInternal in class BaseRandom

Parameters:

seed - The new seed.

next

protected int next(int bits)

Description copied from class: BaseRandom

Generates the next pseudorandom number. Called by all other random-number-generating methods. Should not debit the entropy count, since that's done by the calling methods according to the amount they actually output (see for example BaseRandom.withProbability(double), which uses 53 random bits but outputs only one, and thus debits only 1 bit of entropy).

Specified by:

next in class BaseRandom

nextLongNoEntropyDebit

protected long nextLongNoEntropyDebit()

Description copied from class: BaseRandom

Returns the next random long, but does not debit entropy.

Overrides:

nextLongNoEntropyDebit in class BaseRandom

Returns:

a pseudorandom long with all possible values equally likely.

addSubclassFields

protected MoreObjects.ToStringHelper addSubclassFields(MoreObjects.ToStringHelper original)

Description copied from class: BaseRandom

Adds the fields that were not inherited from BaseRandom to the given MoreObjects.ToStringHelper for dumping.

Specified by:

addSubclassFields in class BaseRandom

Parameters:

original - a MoreObjects.ToStringHelper object.

Returns:

original with the fields not inherited from BaseRandom written to it.

getNewSeedLength

public int getNewSeedLength()

Description copied from interface: ByteArrayReseedableRandom

Returns the preferred length of a new byte-array seed. "Preferred" is implementation-defined when multiple seed lengths are supported, but should probably usually mean the longest one, since the longer the seed, the more random the output.

Specified by:

getNewSeedLength in interface ByteArrayReseedableRandom

Specified by:

getNewSeedLength in class BaseRandom

Returns:

The desired length of a new byte-array seed.