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 long
Deprecated.2 to the 64 divided by the golden ratio.static final long
Deprecated.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 long
Deprecated.The first state; can be any long.protected long
Deprecated.The second state; can be any long.protected long
Deprecated.The third state; can be any long.protected long
Deprecated.The fourth state; can be any long.protected long
Deprecated.The fifth state; can be any long.protected long
Deprecated.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; alllong
values 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; alllong
values 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 long
deposit
(long bits) Deprecated.Given a longbits
where the first 24 positions can have variable bits, usesMASK
to produce a long where the least-significant 24 bits ofbits
have been placed into consecutively greater set bits inmask
.boolean
Deprecated.static long
extract
(long bits) Deprecated.Given a longbits
which should be a result ofgetStream()
, usesMASK
(with 24 bits set to 1) to determine which positions inbits
will matter, and produces a long result of up to 24 bits, with each successive bit corresponding to a successive position inMASK
changed fromGOLDEN_64
.Deprecated.2 to the 64.long
getSelectedState
(int selection) Deprecated.Gets the state determined byselection
, as-is.long
Deprecated.long
Deprecated.long
Deprecated.int
Deprecated.This generator has 6long
states, so this returns 6.long
Deprecated.long
Deprecated.long
Deprecated.int
Deprecated.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.int
next
(int bits) Deprecated.Generates the next pseudorandom number with a specific maximum size in bits (not a max number).long
nextLong()
Deprecated.Returns the next pseudorandom, uniformly distributedlong
value from this random number generator's sequence.long
Deprecated.Optional; moves the state to its previous value and returns the previous long that would have been produced byEnhancedRandom.nextLong()
.static void
Deprecated.void
setSeed
(long seed) Deprecated.This initializes all 5 states of the generator to random values based on the given seed.void
setSelectedState
(int selection, long value) Deprecated.Sets one of the states, determined byselection
, tovalue
, as-is.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.void
setStateA
(long stateA) Deprecated.Sets the first part of the state.void
setStateB
(long stateB) Deprecated.Sets the second part of the state.void
setStateC
(long stateC) Deprecated.Sets the third part of the state.void
setStateD
(long stateD) Deprecated.Sets the fourth part of the state.void
setStateE
(long stateE) Deprecated.Sets the fifth part of the state.void
setStreamIdentifier
(int streamID) Deprecated.Sets the stream using the low-order 24 bits of the given int.void
setStreamIdentifier
(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, 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, 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
-
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_64
can 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; alllong
values are permitted. The seed will be passed tosetSeed(long)
to attempt to adequately distribute the seed randomly.- Parameters:
seed
- anylong
value
-
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; alllong
values 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
- anylong
valuestateB
- anylong
valuestateC
- anylong
valuestateD
- anylong
valuestateE
- anylong
value
-
-
Method Details
-
registerWithDeserializer
public static void registerWithDeserializer()Deprecated. -
deposit
public static long deposit(long bits) Deprecated.Given a longbits
where the first 24 positions can have variable bits, usesMASK
to produce a long where the least-significant 24 bits ofbits
have 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 longbits
which should be a result ofgetStream()
, usesMASK
(with 24 bits set to 1) to determine which positions inbits
will matter, and produces a long result of up to 24 bits, with each successive bit corresponding to a successive position inMASK
changed 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 bymask
and 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: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.
-
getMinimumPeriod
Deprecated.2 to the 64.- Overrides:
getMinimumPeriod
in classEnhancedRandom
- Returns:
- 2 to the 64
-
getStateCount
public int getStateCount()Deprecated.This generator has 6long
states, so this returns 6.- Overrides:
getStateCount
in 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:
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) 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:
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) 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:
setSeed
in 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:
setState
in 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: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()Deprecated.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) Deprecated.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
-
copy
Deprecated.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
Deprecated. -
toString
Deprecated.
-
TraceRandom
instead, which is nearly the same as this algorithm but avoids "bad" streams.