Package io.github.pr0methean.betterrandom.prng

Class Pcg64Random

java.lang.Object

java.util.Random

io.github.pr0methean.betterrandom.prng.BaseRandom

io.github.pr0methean.betterrandom.prng.Pcg64Random

All Implemented Interfaces:

ByteArrayReseedableRandom, EntropyCountingRandom, RepeatableRandom, SeekableRandom, Dumpable, Serializable

public class Pcg64Random
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 64/32" 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
Pcg64Random()	Creates a new PRNG with a seed from the DefaultSeedGenerator.
Pcg64Random(byte[] seed)	Creates a new PRNG with the provided seed.
Pcg64Random(long seed)	Creates a new PRNG with the provided seed.
Pcg64Random(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.
int	getNewSeedLength()	Returns the preferred length of a new byte-array seed.
byte[]	getSeed()	Returns the seed.
protected int	next(int bits)	Generates the next pseudorandom number.
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, initTransientFields, internalNextGaussian, ints, ints, ints, ints, lockForNextGaussian, longs, longs, longs, longs, nextBoolean, nextBytes, nextDouble, nextDouble, nextDouble, nextDoubleNoEntropyDebit, 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

Constructor Detail

Pcg64Random

public Pcg64Random()

Creates a new PRNG with a seed from the DefaultSeedGenerator.

Pcg64Random

public Pcg64Random(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

Pcg64Random

public Pcg64Random(byte[] seed)

Creates a new PRNG with the provided seed.

Parameters:

seed - the seed; must be exactly 8 bytes

Pcg64Random

public Pcg64Random(long seed)

Creates a new PRNG with the provided seed.

Parameters:

seed - the seed

Method Detail

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.

getSeed

public byte[] getSeed()

Description copied from interface: RepeatableRandom

Returns the seed.

Specified by:

getSeed in interface RepeatableRandom

Overrides:

getSeed in class BaseRandom

Returns:

The seed data used to initialize this pseudo-random number generator.

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()

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

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

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.