Package com.github.tommyettinger.random
Class AceRandom
java.lang.Object
java.util.Random
com.github.tommyettinger.random.EnhancedRandom
com.github.tommyettinger.random.AceRandom
- All Implemented Interfaces:
Externalizable
,Serializable
,RandomGenerator
Like TrimRandom with five 64-bit states; does not use multiplication, only add, subtract, XOR, and left-rotate
operations. Has a state that runs like a counter, guaranteeing a minimum period of 2 to the 64. This passes roughly
180 petabytes of intensive testing on the GPU with ReMort, as well as 64TB of PractRand's broad spectrum of tests.
It is usually the fastest generator here, outpacing
An unexpected advantage AceRandom has over PasarRandom and WhiskerRandom is that if many generators of each of those types have their states assigned with small and/or repeated values, AceRandom looks clearly better. AceRandom only has non-random patterns briefly as it escapes the non-random initial state, then returns to typical uncorrelated white noise. On the other hand, PasarRandom and WhiskerRandom will alternate between two different patterns - if the small states were assigned using x and y positions on a grid, then the patterns will be horizontal or vertical stripes.
This implements all optional methods in EnhancedRandom except
The name comes from the 52 cards (excluding jokers, but including aces) in a standard playing card deck, since this uses a left rotation by exactly 52 as one of its critical components. Rotations by anything else I tried didn't pass testing as well, or even at all.
WhiskerRandom
and PouchRandom
on any Java
versions 17 and up, but it is slightly slower on Java 8 (still very fast). Whisker doesn't have a
guaranteed minimum period, Pouch has a lower guaranteed minimum period, and this is
usually faster than PasarRandom
, another 5-state generator with a minimum period of 2 to the 64. The maximum
and/or expected periods for both PasarRandom and AceRandom are far larger than they would need to be, even if run for
decades on current hardware. The minimum period alone would take multiple years to exhaust if using a CPU, let alone
to find that particular cycle with the shortest period. Running on a fast GPU would take less time, but still an
impractically long time.
An unexpected advantage AceRandom has over PasarRandom and WhiskerRandom is that if many generators of each of those types have their states assigned with small and/or repeated values, AceRandom looks clearly better. AceRandom only has non-random patterns briefly as it escapes the non-random initial state, then returns to typical uncorrelated white noise. On the other hand, PasarRandom and WhiskerRandom will alternate between two different patterns - if the small states were assigned using x and y positions on a grid, then the patterns will be horizontal or vertical stripes.
ScruffRandom
can also show stripe artifacts, typically on every third generation if given a very
non-random initial state. The reason AceRandom does better probably has to do with how it mixes its five states more
than the others - WhiskerRandom and ScruffRandom each only mix one pair of states per generation, and PasarRandom
only mixes two pairs of states, but AceRandom mixes three pairs. Ace looks about as random as PouchRandom once
sufficient values have been generated (about 30 longs usually works).
This implements all optional methods in EnhancedRandom except
EnhancedRandom.skip(long)
; it does implement
previousLong()
without using skip().
The name comes from the 52 cards (excluding jokers, but including aces) in a standard playing card deck, since this uses a left rotation by exactly 52 as one of its critical components. Rotations by anything else I tried didn't pass testing as well, or even at all.
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from interface java.util.random.RandomGenerator
RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator
-
Field Summary
Modifier and TypeFieldDescriptionprotected long
The first state; can be any long.protected long
The second state; can be any long.protected long
The third state; can be any long.protected long
The fourth state; can be any long.protected long
The fifth state; can be any long. -
Constructor Summary
ConstructorDescriptionCreates a new AceRandom with a random state.AceRandom
(long seed) Creates a new AceRandom with the given seed; alllong
values are permitted.AceRandom
(long stateA, long stateB) Creates a new AceRandom with the given two states; alllong
values are permitted.AceRandom
(long stateA, long stateB, long stateC) Creates a new AceRandom with the given three states; alllong
values are permitted.AceRandom
(long stateA, long stateB, long stateC, long stateD) Creates a new AceRandom with the given four states; alllong
values are permitted.AceRandom
(long stateA, long stateB, long stateC, long stateD, long stateE) Creates a new AceRandom with the given five states; alllong
values are permitted. -
Method Summary
Modifier and TypeMethodDescriptioncopy()
Creates a new EnhancedRandom with identical states to this one, so if the same EnhancedRandom methods are called on this object and its copy (in the same order), the same outputs will be produced.boolean
long
getSelectedState
(int selection) Gets the state determined byselection
, as-is.long
long
long
int
This generator has 5long
states, so this returns 5.long
long
getTag()
Gets the tag used to identify this type of EnhancedRandom, as a String.long
leap()
Jumps extremely far in the generator's sequence, such that one call to leap() advances the state as many asMath.pow(2, 48)
calls tonextLong()
.int
next
(int bits) Generates the next pseudorandom number with a specific maximum size in bits (not a max number).long
nextLong()
Returns the next pseudorandom, uniformly distributedlong
value from this random number generator's sequence.long
Optional; moves the state to its previous value and returns the previous long that would have been produced byEnhancedRandom.nextLong()
.void
setSeed
(long seed) This initializes all 5 states of the generator to random values based on the given seed.void
setSelectedState
(int selection, long value) Sets one of the states, determined byselection
, tovalue
, as-is.void
setState
(long state) Delegates tosetSeed(long)
, using a hash function on the input to get a variety of initial states.void
setState
(long stateA, long stateB) Sets the state completely to the given two state variables.void
setState
(long stateA, long stateB, long stateC) Sets the state completely to the given three state variables.void
setState
(long stateA, long stateB, long stateC, long stateD) Sets the state completely to the given four state variables.void
setState
(long stateA, long stateB, long stateC, long stateD, long stateE) Sets the state completely to the given five state variables.void
setStateA
(long stateA) Sets the first part of the state.void
setStateB
(long stateB) Sets the second part of the state.void
setStateC
(long stateC) Sets the third part of the state.void
setStateD
(long stateD) Sets the fourth part of the state.void
setStateE
(long stateE) Sets the fifth part of the state.toString()
Methods inherited from class com.github.tommyettinger.random.EnhancedRandom
areEqual, fixGamma, maxDoubleOf, maxFloatOf, maxIntOf, maxLongOf, minDoubleOf, minFloatOf, minIntOf, minLongOf, nextBoolean, nextBoolean, nextBytes, nextDouble, nextDouble, nextDouble, nextExclusiveDouble, nextExclusiveDouble, nextExclusiveDouble, nextExclusiveDoubleEquidistant, nextExclusiveFloat, nextExclusiveFloat, nextExclusiveFloat, nextExclusiveFloatEquidistant, nextExclusiveSignedDouble, nextExclusiveSignedFloat, nextFloat, nextFloat, nextFloat, nextGaussian, nextGaussian, nextInclusiveDouble, nextInclusiveDouble, nextInclusiveDouble, nextInclusiveFloat, nextInclusiveFloat, nextInclusiveFloat, nextInt, nextInt, nextInt, nextLong, nextLong, nextSign, nextSignedInt, nextSignedInt, nextSignedLong, nextSignedLong, nextTriangular, nextTriangular, nextTriangular, nextTriangular, nextUnsignedInt, previousInt, probit, randomElement, randomElement, readExternal, seedFromMath, setState, setWith, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, shuffle, skip, stringDeserialize, stringDeserialize, stringSerialize, stringSerialize, writeExternal
Methods inherited from class java.util.Random
doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.random.RandomGenerator
isDeprecated, nextExponential
-
Field Details
-
stateA
protected long stateAThe first state; can be any long. -
stateB
protected long stateBThe second state; can be any long. -
stateC
protected long stateCThe third state; can be any long. -
stateD
protected long stateDThe fourth state; can be any long. -
stateE
protected long stateEThe fifth state; can be any long. The first call tonextLong()
will return this verbatim, if no other methods have been called.
-
-
Constructor Details
-
AceRandom
public AceRandom()Creates a new AceRandom with a random state. -
AceRandom
public AceRandom(long seed) Creates a new AceRandom with the given seed; alllong
values are permitted. The seed will be passed tosetSeed(long)
to attempt to adequately distribute the seed randomly.- Parameters:
seed
- anylong
value
-
AceRandom
public AceRandom(long stateA, long stateB) Creates a new AceRandom with the given two states; alllong
values are permitted. These states will be used verbatim, and the third, fourth, and fifth states will be assignedstateA + stateB
,stateA ^ stateB
, andstateB - stateA
, respectively.- Parameters:
stateA
- anylong
valuestateB
- anylong
value
-
AceRandom
public AceRandom(long stateA, long stateB, long stateC) Creates a new AceRandom with the given three states; alllong
values are permitted. These states will be used verbatim, and the fourth and fifth states will be assignedstateA + stateC
andstateB ^ stateC
, respectively.- Parameters:
stateA
- anylong
valuestateB
- anylong
valuestateC
- anylong
value
-
AceRandom
public AceRandom(long stateA, long stateB, long stateC, long stateD) Creates a new AceRandom with the given four states; alllong
values are permitted. These states will be used verbatim, and the fifth state will be assignedstateA + stateC ^ stateB + stateD
.- Parameters:
stateA
- anylong
valuestateB
- anylong
valuestateC
- anylong
valuestateD
- anylong
value
-
AceRandom
public AceRandom(long stateA, long stateB, long stateC, long stateD, long stateE) Creates a new AceRandom with the given five states; alllong
values are permitted. These states will be used verbatim.- Parameters:
stateA
- anylong
valuestateB
- anylong
valuestateC
- anylong
valuestateD
- anylong
valuestateE
- anylong
value
-
-
Method Details
-
getTag
Description copied from class:EnhancedRandom
Gets the tag used to identify this type of EnhancedRandom, as a String. This tag should be unique, and for uniformity purposes, all tags used in this library are 4 characters long. User-defined tags should have a different length.- Specified by:
getTag
in classEnhancedRandom
- Returns:
- a unique String identifier for this type of EnhancedRandom; usually 4 chars long.
-
getStateCount
public int getStateCount()This generator has 5long
states, so this returns 5.- Overrides:
getStateCount
in classEnhancedRandom
- Returns:
- 5 (five)
-
getSelectedState
public long getSelectedState(int selection) Gets the state determined byselection
, as-is. The value for selection should be between 0 and 4, inclusive; if it is any other value this gets state E as if 4 was given.- Overrides:
getSelectedState
in classEnhancedRandom
- Parameters:
selection
- used to select which state variable to get; generally 0, 1, 2, 3, or 4- Returns:
- the value of the selected state
-
setSelectedState
public void setSelectedState(int selection, long value) Sets one of the states, determined byselection
, tovalue
, as-is. Selections 0, 1, 2, 3, and 4 refer to states A, B, C, D, and E, and if the selection is anything else, this treats it as 4 and sets stateE.- Overrides:
setSelectedState
in classEnhancedRandom
- Parameters:
selection
- used to select which state variable to set; generally 0, 1, 2, 3, or 4value
- the exact value to use for the selected state, if valid
-
setSeed
public void setSeed(long seed) This initializes all 5 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 bynextLong()
.- Specified by:
setSeed
in classEnhancedRandom
- Parameters:
seed
- the initial seed; may be any long
-
getStateA
public long getStateA() -
setStateA
public void setStateA(long stateA) Sets the first part of the state.- Parameters:
stateA
- can be any long
-
getStateB
public long getStateB() -
setStateB
public void setStateB(long stateB) Sets the second part of the state.- Parameters:
stateB
- can be any long
-
getStateC
public long getStateC() -
setStateC
public void setStateC(long stateC) Sets the third part of the state.- Parameters:
stateC
- can be any long
-
getStateD
public long getStateD() -
setStateD
public void setStateD(long stateD) Sets the fourth part of the state.- Parameters:
stateD
- can be any long
-
getStateE
public long getStateE() -
setStateE
public void setStateE(long stateE) Sets the fifth part of the state.- Parameters:
stateE
- can be any long
-
setState
public void setState(long state) Delegates tosetSeed(long)
, using a hash function on the input to get a variety of initial states. To set the states all to exactly what you want, usesetState(long, long, long, long, long)
.- Overrides:
setState
in classEnhancedRandom
- Parameters:
state
- the long value to pass tosetSeed(long)
- See Also:
-
setState
public void setState(long stateA, long stateB) Sets the state completely to the given two state variables. The third state variable will be set as if you had calledsetStateE(stateA + stateB)
. The fourth state variable will be set as if you had calledsetStateE(stateA ^ stateB)
. The fifth state variable will be set as if you had calledsetStateE(stateB - stateA)
. This is the same as callingsetStateA(long)
,setStateB(long)
,setStateC(long)
,setStateD(long)
, andsetStateE(long)
(as mentioned) as a group. To set the states all to exactly what you want, usesetState(long, long, long, long, long)
.- Overrides:
setState
in classEnhancedRandom
- Parameters:
stateA
- the first state; can be any longstateB
- the second state; can be any long
-
setState
public void setState(long stateA, long stateB, long stateC) Sets the state completely to the given three state variables. The fourth state variable will be set as if you had calledsetStateE(stateA + stateC)
. The fifth state variable will be set as if you had calledsetStateE(stateB ^ stateC)
. This is the same as callingsetStateA(long)
,setStateB(long)
,setStateC(long)
,setStateD(long)
, andsetStateE(long)
(as mentioned) as a group. To set the states all to exactly what you want, usesetState(long, long, long, long, long)
.- Overrides:
setState
in classEnhancedRandom
- Parameters:
stateA
- the first state; can be any longstateB
- the second state; can be any longstateC
- the third state; can be any long
-
setState
public void setState(long stateA, long stateB, long stateC, long stateD) Sets the state completely to the given four state variables. The fifth state variable will be set as if you had calledsetStateE(stateA + stateC ^ stateB + stateD)
. This is the same as callingsetStateA(long)
,setStateB(long)
,setStateC(long)
,setStateD(long)
, andsetStateE(long)
(as mentioned) as a group. To set the states all to exactly what you want, usesetState(long, long, long, long, long)
.- Overrides:
setState
in classEnhancedRandom
- Parameters:
stateA
- the first state; can be any longstateB
- the second state; can be any longstateC
- the third state; can be any longstateD
- the fourth state; can be any long
-
setState
public void setState(long stateA, long stateB, long stateC, long stateD, long stateE) Sets the state completely to the given five state variables. This is the same as callingsetStateA(long)
,setStateB(long)
,setStateC(long)
,setStateD(long)
, andsetStateE(long)
as a group.- Overrides:
setState
in classEnhancedRandom
- Parameters:
stateA
- the first state; can be any longstateB
- the second state; can be any longstateC
- the third state; can be any longstateD
- the fourth state; can be any longstateE
- the fifth state; can be any long
-
nextLong
public long nextLong()Description copied from class:EnhancedRandom
Returns the next pseudorandom, uniformly distributedlong
value from this random number generator's sequence. The general contract ofnextLong
is that onelong
value is pseudorandomly generated and returned.
The only methods that need to be implemented by this interface are this andEnhancedRandom.copy()
, though other methods can be implemented as appropriate for generators that, for instance, natively produce ints rather than longs.- Specified by:
nextLong
in interfaceRandomGenerator
- Specified by:
nextLong
in classEnhancedRandom
- Returns:
- the next pseudorandom, uniformly distributed
long
value from this random number generator's sequence
-
previousLong
public long previousLong()Description copied from class:EnhancedRandom
Optional; moves the state to its previous value and returns the previous long that would have been produced byEnhancedRandom.nextLong()
. This can be equivalent to callingEnhancedRandom.skip(long)
with -1L, but not always; many generators can't efficiently skip long distances, but can step back by one value.
Generators that natively generateint
results typically producelong
values by generating an int for the high 32 bits and an int for the low 32 bits. When producing the previous long, the order the high and low bits are generated, such as byEnhancedRandom.previousInt()
, should be reversed. Generators that natively producelong
values usually don't need to implementEnhancedRandom.previousInt()
, but those that produceint
usually should implement it, and may optionally call previousInt() twice in this method.
If you know how to implement the reverse of a particular random number generator, it is recommended you do so here, rather than rely on skip(). This isn't always easy, but should always be possible for any decent PRNG (some historical PRNGs, such as the Middle-Square PRNG, cannot be reversed at all). If a generator cannot be reversed because multiple initial states can transition to the same subsequent state, it is known to have statistical problems that are not necessarily present in a generator that matches one initial state to one subsequent state.
The public implementation callsEnhancedRandom.skip(long)
with -1L, and if skip() has not been implemented differently, then it will throw an UnsupportedOperationException.- Overrides:
previousLong
in classEnhancedRandom
- Returns:
- the previous number this would have produced with
EnhancedRandom.nextLong()
-
next
public int next(int bits) Description copied from class:EnhancedRandom
Generates the next pseudorandom number with a specific maximum size in bits (not a max number). If you want to get a random number in a range, you should usually useEnhancedRandom.nextInt(int)
instead. For some specific cases, this method is more efficient and less biased thanEnhancedRandom.nextInt(int)
. Forbits
values between 1 and 30, this should be similar in effect tonextInt(1 << bits)
; though it won't typically produce the same values, they will have the correct range. Ifbits
is 31, this can return any non-negativeint
; note thatnextInt(1 << 31)
won't behave this way because1 << 31
is negative. Ifbits
is 32 (or 0), this can return anyint
.The general contract of
next
is that it returns anint
value and if the argumentbits
is between1
and32
(inclusive), then that many low-order bits of the returned value will be (approximately) independently chosen bit values, each of which is (approximately) equally likely to be0
or1
.Note that you can give this values for
bits
that are outside its expected range of 1 to 32, but the value used, as long as bits is positive, will effectively bebits % 32
. As stated before, a value of 0 for bits is the same as a value of 32.- Overrides:
next
in classEnhancedRandom
- Parameters:
bits
- the amount of random bits to request, from 1 to 32- Returns:
- the next pseudorandom value from this random number generator's sequence
-
leap
public long leap()Jumps extremely far in the generator's sequence, such that one call to leap() advances the state as many asMath.pow(2, 48)
calls tonextLong()
. This can be used to create 65536 substreams of this generator's sequence, each with a period of at leastMath.pow(2, 48)
but likely much more.- Returns:
- the result of what nextLong() would return if it was called at the state this jumped to
-
copy
Description copied from class:EnhancedRandom
Creates a new EnhancedRandom with identical states to this one, so if the same EnhancedRandom methods are called on this object and its copy (in the same order), the same outputs will be produced. This is not guaranteed to copy the inherited state of any parent class, so if you call methods that are only implemented by a superclass (likeRandom
) and not this one, the results may differ.- Specified by:
copy
in classEnhancedRandom
- Returns:
- a deep copy of this EnhancedRandom.
-
equals
-
toString
-