squidpony.squidmath

Class TrimRNG

java.lang.Object

squidpony.squidmath.TrimRNG

All Implemented Interfaces:

java.io.Serializable, RandomnessSource

public class TrimRNG
extends java.lang.Object
implements RandomnessSource, java.io.Serializable

A RandomnessSource with four long states; one is a simple counter, and the rest mix and match all four states to get their next value. This has been backported from jdkgdxds. This generator has a known minimum period of at least 2 to the 64 and is statistically extremely likely to be much longer; no combinations of states are known that put it in a bad starting state, and none are possible that reduce period below 2 to the 64. It uses no multiplication and actually only needs addition, bitwise-rotation, and XOR to run; this may help on some exotic hardware.
It is a very fast generator on Java 16 and newer, though FourWheelRNG is faster on desktop hardware. Another RandomnessSource that avoids multiplication, StrangerRNG, is not as fast as this (in general). It has passed 64TB of PractRand testing with no anomalies, and 300TB of hwd testing.
Trim, because it uses a trimmed-down set of operations (just add, bitwise-rotate, and XOR).
Created by Tommy Ettinger on 12/20/2021.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
long	stateA Can be any long value.
long	stateB Can be any long value.
long	stateC Can be any long value.
long	stateD Can be any long value.

Constructor Summary

Constructors

Constructor and Description
TrimRNG() Creates a new generator seeded using Math.random.
TrimRNG(long seed) Creates a new generator by passing the seed to setSeed(long).
TrimRNG(long seedA, long seedB, long seedC, long seedD) Creates a new generator by specifying each state exactly.

Method Summary

Modifier and Type	Method and Description
TrimRNG	copy() Produces a copy of this RandomnessSource that, if next() and/or nextLong() are called on this object and the copy, both will generate the same sequence of random numbers from the point copy() was called.
boolean	equals(java.lang.Object o)
long	getStateA() Get the "A" part of the internal state as a long.
long	getStateB() Get the "B" part of the internal state as a long.
long	getStateC() Get the "C" part of the internal state as a long.
long	getStateD() Get the "D" part of the internal state as a long.
int	hashCode()
int	next(int bits) Using this method, any algorithm that might use the built-in Java Random can interface with this randomness source.
long	nextLong() Using this method, any algorithm that needs to efficiently generate more than 32 bits of random data can interface with this randomness source.
long	previousLong()
void	setSeed(long seed) This initializes all 4 states of the generator to random values based on the given seed.
void	setStateA(long stateA) Set the "A" part of the internal state with a long.
void	setStateB(long stateB) Set the "B" part of the internal state with a long.
void	setStateC(long stateC) Set the "C" part of the internal state with a long.
void	setStateD(long stateD) Set the "D" part of the internal state with a long.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

stateA

public long stateA

Can be any long value.

stateB

public long stateB

Can be any long value.

stateC

public long stateC

Can be any long value.

stateD

public long stateD

Can be any long value.

Constructor Detail

TrimRNG

public TrimRNG()

Creates a new generator seeded using Math.random.

TrimRNG

public TrimRNG(long seed)

Creates a new generator by passing the seed to setSeed(long).

Parameters:

seed - any long

TrimRNG

public TrimRNG(long seedA,
               long seedB,
               long seedC,
               long seedD)

Creates a new generator by specifying each state exactly. All values are acceptable.

Parameters:

seedA - any long

seedB - any long

seedC - any long

seedD - any long

Method Detail

setSeed

public void setSeed(long seed)

This initializes all 4 states of the generator to random values based on the given seed. (2 to the 64) possible initial generator states can be produced here, all with a different first value returned by nextLong().
This uses MX3 by Jon Maiga to mix seed, then only does a little distribution of the mixed long so that 128 of 256 bits are always set across the four states.

Parameters:

seed - the initial seed; may be any long

getStateA

public long getStateA()

Get the "A" part of the internal state as a long.

Returns:

the current internal state of this object.

setStateA

public void setStateA(long stateA)

Set the "A" part of the internal state with a long.

Parameters:

stateA - any 64-bit long

getStateB

public long getStateB()

Get the "B" part of the internal state as a long.

Returns:

the current internal "B" state of this object.

setStateB

public void setStateB(long stateB)

Set the "B" part of the internal state with a long.

Parameters:

stateB - any 64-bit long

getStateC

public long getStateC()

Get the "C" part of the internal state as a long.

Returns:

the current internal "C" state of this object.

setStateC

public void setStateC(long stateC)

Set the "C" part of the internal state with a long.

Parameters:

stateC - any 64-bit long

getStateD

public long getStateD()

Get the "D" part of the internal state as a long.

Returns:

the current internal "D" state of this object.

setStateD

public void setStateD(long stateD)

Set the "D" part of the internal state with a long.

Parameters:

stateD - any 64-bit long

nextLong

public long nextLong()

Description copied from interface: RandomnessSource

Using this method, any algorithm that needs to efficiently generate more than 32 bits of random data can interface with this randomness source. Get a random long between Long.MIN_VALUE and Long.MAX_VALUE (both inclusive).

Specified by:

nextLong in interface RandomnessSource

Returns:

a random long between Long.MIN_VALUE and Long.MAX_VALUE (both inclusive)

previousLong

public long previousLong()

next

public int next(int bits)

Description copied from interface: RandomnessSource

Using this method, any algorithm that might use the built-in Java Random can interface with this randomness source.

Specified by:

next in interface RandomnessSource

Parameters:

bits - the number of bits to be returned

Returns:

the integer containing the appropriate number of bits

copy

public TrimRNG copy()

Produces a copy of this RandomnessSource that, if next() and/or nextLong() are called on this object and the copy, both will generate the same sequence of random numbers from the point copy() was called. This just need to copy the state so that it isn't shared, usually, and produce a new value with the same exact state.

Specified by:

copy in interface RandomnessSource

Returns:

a copy of this RandomnessSource

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object