Package com.github.tommyettinger.random
Class MaceRandom
java.lang.Object
java.util.Random
com.github.tommyettinger.random.EnhancedRandom
com.github.tommyettinger.random.MaceRandom
- All Implemented Interfaces:
Externalizable,Serializable,RandomGenerator
Deprecated.
DEPRECATED: Use
Like AceRandom with five 64-bit states but also one unchanging 24-bit stream; does not use multiplication, only add, XOR, and bitwise-rotate operations (this is an ARX generator). Has a state that runs like a counter, guaranteeing a minimum period of 2 to the 64, and each stream should be independent of any other stream after a small number of generations. The expected period is about 2 to the 310 calls to nextLong(), though this is an overly cautious estimate. Even if using the old stand-by advice, that only the square root of the period can be used before a generator starts to have problems, would permit an enormous 2 to the 155 calls before becoming, in some vague way, "bad." That's over 45,000,000,000,000,000,000,000,000,000,000,000,000,000,000,000 calls to
At least one stream passes 64TB with no anomalies, and at least 1% of all total streams pass 256MB without failures or lingering anomalies. Only 1% were tested because testing 100% would take at least until the year 2026 to finish, and the tests were run starting May 10, 2025. This is usually a tiny amount slower than
After about 30 calls to
TraceRandom instead. TraceRandom only differs from MaceRandom in how it selects streams.
Note that this is not deserializable out-of-the-box by Deserializer, unless you call
registerWithDeserializer() on this class.
Like AceRandom with five 64-bit states but also one unchanging 24-bit stream; does not use multiplication, only add, XOR, and bitwise-rotate operations (this is an ARX generator). Has a state that runs like a counter, guaranteeing a minimum period of 2 to the 64, and each stream should be independent of any other stream after a small number of generations. The expected period is about 2 to the 310 calls to nextLong(), though this is an overly cautious estimate. Even if using the old stand-by advice, that only the square root of the period can be used before a generator starts to have problems, would permit an enormous 2 to the 155 calls before becoming, in some vague way, "bad." That's over 45,000,000,000,000,000,000,000,000,000,000,000,000,000,000,000 calls to
nextLong(). With
16 million possible streams, on top of that.
At least one stream passes 64TB with no anomalies, and at least 1% of all total streams pass 256MB without failures or lingering anomalies. Only 1% were tested because testing 100% would take at least until the year 2026 to finish, and the tests were run starting May 10, 2025. This is usually a tiny amount slower than
AceRandom (about 5%
lower throughput), but strangely is slightly faster than AceRandom when run on GraalVM 24.
After about 30 calls to
nextLong(), any two different streams with otherwise identical states should have no
correlations to each other. This likely does not fully avoid the issue of problematic "gamma values" that
SplitMix64 has; roughly 1/9 of all possible streams are considered low-quality by
EnhancedRandom.rateGamma(long), and would be rejected by EnhancedRandom.fixGamma(long, int) with a
threshold value of 8. This
does also use quite a lot more state than SplitMix64, and those extra 320 bits of state change in their own complex
ways, both related and unrelated to the stream, which may be sufficient to not need a gamma of the same quality that
SplitMix64 appears to need to pass tests.- 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
FieldsModifier and TypeFieldDescriptionstatic final longDeprecated.2 to the 64 divided by the golden ratio.static final longDeprecated.A long mask with 24 bits set, all symmetrical around the middle bits, leaving 10 bits all zero at the most significant and the least significant ends.protected longDeprecated.The first state; can be any long.protected longDeprecated.The second state; can be any long.protected longDeprecated.The third state; can be any long.protected longDeprecated.The fourth state; can be any long.protected longDeprecated.The fifth state; can be any long.protected longDeprecated.The unchanging stream; cannot be set directly, but can be obtained directly withgetStream()or get/set indirectly via a 24-bit int withgetStreamIdentifier()andsetStreamIdentifier(int). -
Constructor Summary
ConstructorsConstructorDescriptionDeprecated.Creates a new MaceRandom with a random state.MaceRandom(int streamIdentifier, long stateA, long stateB, long stateC, long stateD, long stateE) Deprecated.Creates a new MaceRandom with the given stream identifier and five states; alllongvalues are permitted for states, and all ints between 0 and 16777215 (or 0xFFFFFF), inclusive, are permitted for streamIdentifier.MaceRandom(long seed) Deprecated.Creates a new MaceRandom with the given seed; alllongvalues are permitted. -
Method Summary
Modifier and TypeMethodDescriptioncopy()Deprecated.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.static longdeposit(long bits) Deprecated.Given a longbitswhere the first 24 positions can have variable bits, usesMASKto produce a long where the least-significant 24 bits ofbitshave been placed into consecutively greater set bits inmask.booleanDeprecated.static longextract(long bits) Deprecated.Given a longbitswhich should be a result ofgetStream(), usesMASK(with 24 bits set to 1) to determine which positions inbitswill matter, and produces a long result of up to 24 bits, with each successive bit corresponding to a successive position inMASKchanged fromGOLDEN_64.Deprecated.2 to the 64.longgetSelectedState(int selection) Deprecated.Gets the state determined byselection, as-is.longDeprecated.longDeprecated.longDeprecated.intDeprecated.This generator has 6longstates, so this returns 6.longDeprecated.longDeprecated.longDeprecated.intDeprecated.Gets an up-to-24-bit long that uniquely identifies the stream this MaceRandom uses.getTag()Deprecated.Gets the tag used to identify this type of EnhancedRandom, as a String.intnext(int bits) Deprecated.Generates the next pseudorandom number with a specific maximum size in bits (not a max number).longnextLong()Deprecated.Returns the next pseudorandom, uniformly distributedlongvalue from this random number generator's sequence.longDeprecated.Optional; moves the state to its previous value and returns the previous long that would have been produced byEnhancedRandom.nextLong().static voidDeprecated.voidsetSeed(long seed) Deprecated.This initializes all 5 states of the generator to random values based on the given seed.voidsetSelectedState(int selection, long value) Deprecated.Sets one of the states, determined byselection, tovalue, as-is.voidsetState(long streamID, long stateA, long stateB, long stateC, long stateD, long stateE) Deprecated.Sets the state completely to the given six state variables.voidsetStateA(long stateA) Deprecated.Sets the first part of the state.voidsetStateB(long stateB) Deprecated.Sets the second part of the state.voidsetStateC(long stateC) Deprecated.Sets the third part of the state.voidsetStateD(long stateD) Deprecated.Sets the fourth part of the state.voidsetStateE(long stateE) Deprecated.Sets the fifth part of the state.voidsetStreamIdentifier(int streamID) Deprecated.Sets the stream using the low-order 24 bits of the given int.voidsetStreamIdentifier(long value) Deprecated.Sets the stream using all mixed bits of the given long.toString()Deprecated.Methods inherited from class com.github.tommyettinger.random.EnhancedRandom
appendSerialized, appendSerialized, areEqual, fixGamma, fixGamma, lcm, mainlyGeneratesInt, maxDoubleOf, maxFloatOf, maxIntOf, maxLongOf, minDoubleOf, minFloatOf, minIntOf, minLongOf, nextBoolean, nextBoolean, nextBytes, nextDouble, nextDouble, nextDouble, nextExclusiveDouble, nextExclusiveDouble, nextExclusiveDouble, nextExclusiveDoubleEquidistant, nextExclusiveFloat, nextExclusiveFloat, nextExclusiveFloat, nextExclusiveFloatEquidistant, nextExclusiveSignedDouble, nextExclusiveSignedFloat, nextExponential, nextFloat, nextFloat, nextFloat, nextGaussian, nextGaussian, nextGaussianFloat, nextGaussianFloat, 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, rateGamma, readExternal, seedFromMath, setState, setState, setState, setState, setState, 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, writeExternalMethods inherited from class java.util.Random
doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longsMethods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface java.util.random.RandomGenerator
isDeprecated
-
Field Details
-
MASK
public static final long MASKDeprecated.A long mask with 24 bits set, all symmetrical around the middle bits, leaving 10 bits all zero at the most significant and the least significant ends. This is used to determine which bits ofGOLDEN_64can be changed by the stream.- See Also:
-
GOLDEN_64
public static final long GOLDEN_64Deprecated.2 to the 64 divided by the golden ratio. In general this is a good number to use in an additive sequence (like a counter with a large increment), and small changes to the middle bits still tend to result in good numbers.- See Also:
-
stream
protected long streamDeprecated.The unchanging stream; cannot be set directly, but can be obtained directly withgetStream()or get/set indirectly via a 24-bit int withgetStreamIdentifier()andsetStreamIdentifier(int). -
stateA
protected long stateADeprecated.The first state; can be any long. -
stateB
protected long stateBDeprecated.The second state; can be any long. The first call tonextLong()will return this verbatim, if no other methods have been called. -
stateC
protected long stateCDeprecated.The third state; can be any long. -
stateD
protected long stateDDeprecated.The fourth state; can be any long. -
stateE
protected long stateEDeprecated.The fifth state; can be any long.
-
-
Constructor Details
-
MaceRandom
public MaceRandom()Deprecated.Creates a new MaceRandom with a random state. -
MaceRandom
public MaceRandom(long seed) Deprecated.Creates a new MaceRandom with the given seed; alllongvalues are permitted. The seed will be passed tosetSeed(long)to attempt to adequately distribute the seed randomly.- Parameters:
seed- anylongvalue
-
MaceRandom
public MaceRandom(int streamIdentifier, long stateA, long stateB, long stateC, long stateD, long stateE) Deprecated.Creates a new MaceRandom with the given stream identifier and five states; alllongvalues are permitted for states, and all ints between 0 and 16777215 (or 0xFFFFFF), inclusive, are permitted for streamIdentifier. The states will be used verbatim, and the streamIdentifier can be retrieved withgetStreamIdentifier().- Parameters:
streamIdentifier- an up-to-24-bit int (between 0 and 16777215, inclusive); higher bits are ignoredstateA- anylongvaluestateB- anylongvaluestateC- anylongvaluestateD- anylongvaluestateE- anylongvalue
-
-
Method Details
-
registerWithDeserializer
public static void registerWithDeserializer()Deprecated. -
deposit
public static long deposit(long bits) Deprecated.Given a longbitswhere the first 24 positions can have variable bits, usesMASKto produce a long where the least-significant 24 bits ofbitshave been placed into consecutively greater set bits inmask. It finished by XORing the masked bits withGOLDEN_64. This method does not allocate. The parameter is usually provided bygetStreamIdentifier()or by callingextract(long).
Based on Hacker's Delight (2nd edition). -
extract
public static long extract(long bits) Deprecated.Given a longbitswhich should be a result ofgetStream(), usesMASK(with 24 bits set to 1) to determine which positions inbitswill matter, and produces a long result of up to 24 bits, with each successive bit corresponding to a successive position inMASKchanged fromGOLDEN_64. This produces a "stream identifier" for a givenstream, as used bygetStreamIdentifier()andsetStreamIdentifier(int).
Based on Hacker's Delight (2nd edition).- Parameters:
bits- the bit values that will be masked bymaskand placed into the low-order bits of the result- Returns:
- a long with the highest bit that can be set equal to the
Long.bitCount(long)ofmask
-
getTag
Deprecated.Description copied from class:EnhancedRandomGets 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:
getTagin classEnhancedRandom- Returns:
- a unique String identifier for this type of EnhancedRandom; usually 4 chars long.
-
getMinimumPeriod
Deprecated.2 to the 64.- Overrides:
getMinimumPeriodin classEnhancedRandom- Returns:
- 2 to the 64
-
getStateCount
public int getStateCount()Deprecated.This generator has 6longstates, so this returns 6.- Overrides:
getStateCountin classEnhancedRandom- Returns:
- 6 (six)
-
getSelectedState
public long getSelectedState(int selection) Deprecated.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:
getSelectedStatein 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) Deprecated.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:
setSelectedStatein 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) Deprecated.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.- Specified by:
setSeedin classEnhancedRandom- Parameters:
seed- the initial seed; may be any long
-
getStream
public long getStream()Deprecated. -
getStreamIdentifier
public int getStreamIdentifier()Deprecated.Gets an up-to-24-bit long that uniquely identifies the stream this MaceRandom uses. This identifier can be passed tosetStreamIdentifier(int)to change the stream.- Returns:
- the smaller identifier used to determine the actual stream
-
setStreamIdentifier
public void setStreamIdentifier(int streamID) Deprecated.Sets the stream using the low-order 24 bits of the given int.- Parameters:
streamID- can be any int, but only the lowest-order 24 bits matter
-
setStreamIdentifier
public void setStreamIdentifier(long value) Deprecated.Sets the stream using all mixed bits of the given long.- Parameters:
value- can be any long, and will have all bits mixed into a stream identifier
-
getStateA
public long getStateA()Deprecated. -
setStateA
public void setStateA(long stateA) Deprecated.Sets the first part of the state.- Parameters:
stateA- can be any long
-
getStateB
public long getStateB()Deprecated. -
setStateB
public void setStateB(long stateB) Deprecated.Sets the second part of the state.- Parameters:
stateB- can be any long
-
getStateC
public long getStateC()Deprecated. -
setStateC
public void setStateC(long stateC) Deprecated.Sets the third part of the state.- Parameters:
stateC- can be any long
-
getStateD
public long getStateD()Deprecated. -
setStateD
public void setStateD(long stateD) Deprecated.Sets the fourth part of the state.- Parameters:
stateD- can be any long
-
getStateE
public long getStateE()Deprecated. -
setStateE
public void setStateE(long stateE) Deprecated.Sets the fifth part of the state.- Parameters:
stateE- can be any long
-
setState
public void setState(long streamID, long stateA, long stateB, long stateC, long stateD, long stateE) Deprecated.Sets the state completely to the given six state variables. This is the same as callingsetStreamIdentifier(long),setStateA(long),setStateB(long),setStateC(long),setStateD(long), andsetStateE(long)as a group.- Overrides:
setStatein classEnhancedRandom- Parameters:
streamID- an up-to-24-bit int (between 0 and 16777215, inclusive); higher bits will be mixed in, and if present the stream may not be uniquestateA- 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()Deprecated.Description copied from class:EnhancedRandomReturns the next pseudorandom, uniformly distributedlongvalue from this random number generator's sequence. The general contract ofnextLongis that onelongvalue 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:
nextLongin interfaceRandomGenerator- Specified by:
nextLongin classEnhancedRandom- Returns:
- the next pseudorandom, uniformly distributed
longvalue from this random number generator's sequence
-
previousLong
public long previousLong()Deprecated.Description copied from class:EnhancedRandomOptional; 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 generateintresults typically producelongvalues 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 producelongvalues usually don't need to implementEnhancedRandom.previousInt(), but those that produceintusually 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:
previousLongin classEnhancedRandom- Returns:
- the previous number this would have produced with
EnhancedRandom.nextLong()
-
next
public int next(int bits) Deprecated.Description copied from class:EnhancedRandomGenerates 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). Forbitsvalues 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. Ifbitsis 31, this can return any non-negativeint; note thatnextInt(1 << 31)won't behave this way because1 << 31is negative. Ifbitsis 32 (or 0), this can return anyint.The general contract of
nextis that it returns anintvalue and if the argumentbitsis between1and32(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 be0or1.Note that you can give this values for
bitsthat 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:
nextin 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
-
copy
Deprecated.Description copied from class:EnhancedRandomCreates 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:
copyin classEnhancedRandom- Returns:
- a deep copy of this EnhancedRandom.
-
equals
Deprecated. -
toString
Deprecated.
-
TraceRandominstead, which is nearly the same as this algorithm but avoids "bad" streams.