Package squidpony.squidmath

Class SilkRNG

java.lang.Object
squidpony.squidmath.AbstractRNG
squidpony.squidmath.SilkRNG
All Implemented Interfaces:
Serializable, IRNG, IStatefulRNG, RandomnessSource, StatefulRandomness
public final class SilkRNG
extends AbstractRNG
implements IStatefulRNG, Serializable
An IStatefulRNG implementation that is meant to provide random numbers very quickly when targeting GWT but also to produce the same numbers when used on desktop, Android, or other platforms, and that can have its state read as a StatefulRandomness; it is thus like GWTRNG but should perform better on recent desktop JVMs. This uses a related algorithm to OrbitRNG, modified to use 32-bit math and more stringently randomize output. It has two 32-bit ints for state and a period of 0x10000000000000000 (2 to the 64), while passing 32TB of PractRand tests without any failures or anomalies (so its quality is very good). It is extremely fast when run on Java 13, at least using OpenJ9 as the compiler; it can produce a billion ints a second on moderately-recent laptop hardware. A nice quality of the implementation is that it allows any int for both of its states, so you don't need to check and avoid setting both states to 0 (which GWTRNG has to do in its internals).
Internally, this uses two Weyl sequences (counters with different large increments), and rarely but at specific intervals (when stateA is 0) introduces a lag into one sequence (making stateB keep its value instead of incrementing for one generated number). A multiplier is taken from the upper bits of stateB and multiplied with a xorshifted stateA, then part of a unary hash in the style of SplitMix64 is used to improve quality. A particularly devious piece of bitwise hackery allows this to avoid branching as it decides whether to add the lag or not, and is responsible for this implementation's high speed.
The name comes from spider silk, used in a web, and how this is optimized for Google Web Toolkit.
This was changed on February 29, 2020 to reduce correlation between very similar generators with the same stateA but different stateB; it still passes 32TB of PractRand without anomalies, but may be slightly slower. The reasoning here is that users may want to initialize their RNGs in varied ways, and none of those ways should be unexpectedly flawed. A similar change was applied to TangleRNG, which is much like a 64-bit simplified version of SilkRNG, 4 days later.
Written in 2019 by Tommy Ettinger.
Author:
Tommy Ettinger
See Also:
Serialized Form

  • Field Details

  • Constructor Details

    • SilkRNG

      public SilkRNG()
      Creates a new generator seeded using two calls to Math.random().

    • SilkRNG

      public SilkRNG​(int seed)
      Constructs this SilkRNG by dispersing the bits of seed using setSeed(int) across the two parts of state this has.
      Parameters:
      seed - an int that won't be used exactly, but will affect both components of state

    • SilkRNG

      public SilkRNG​(long seed)
      Constructs this SilkRNG by splitting the given seed across the two parts of state this has with setState(long).
      Parameters:
      seed - a long that will be split across both components of state

    • SilkRNG

      public SilkRNG​(int stateA, int stateB)
      Constructs this SilkRNG by calling setState(int, int) on stateA and stateB as given; see that method for the specific details (stateA and stateB are kept as-is).
      Parameters:
      stateA - the number to use as the first part of the state
      stateB - the number to use as the second part of the state

    • SilkRNG

      public SilkRNG​(String seed)
      Hashes seed using both CrossHash.hash(CharSequence) and String.hashCode() and uses those two results as the two states with setState(int, int). If seed is null, this won't call String.hashCode() on it and will instead use 0 as that state.
      Parameters:
      seed - any String; may be null

  • Method Details

    • next

      public final int next​(int bits)
      Get up to 32 bits (inclusive) of random output; the int this produces will not require more than bits bits to represent.
      Specified by:
      next in interface IRNG
      Specified by:
      next in interface RandomnessSource
      Specified by:
      next in class AbstractRNG
      Parameters:
      bits - an int between 1 and 32, both inclusive
      Returns:
      a random number that fits in the specified number of bits

    • nextInt

      public final int nextInt()
      Get a random integer between Integer.MIN_VALUE to Integer.MAX_VALUE (both inclusive).
      Specified by:
      nextInt in interface IRNG
      Specified by:
      nextInt in class AbstractRNG
      Returns:
      a 32-bit random int.

    • nextInt

      public final int nextInt​(int bound)
      Returns a random non-negative integer below the given bound, or 0 if the bound is 0 or negative.
      Specified by:
      nextInt in interface IRNG
      Overrides:
      nextInt in class AbstractRNG
      Parameters:
      bound - the upper bound (exclusive)
      Returns:
      the found number

    • nextLong

      public final long nextLong()
      Get a random long between Long.MIN_VALUE to Long.MAX_VALUE (both inclusive).
      Specified by:
      nextLong in interface IRNG
      Specified by:
      nextLong in interface RandomnessSource
      Specified by:
      nextLong in class AbstractRNG
      Returns:
      a 64-bit random long.

    • nextBoolean

      public final boolean nextBoolean()
      Get a random bit of state, interpreted as true or false with approximately equal likelihood. This implementation uses a sign check as an optimization.
      Specified by:
      nextBoolean in interface IRNG
      Specified by:
      nextBoolean in class AbstractRNG
      Returns:
      a random boolean.

    • nextDouble

      public final double nextDouble()
      Gets a random double between 0.0 inclusive and 1.0 exclusive. This returns a maximum of 0.9999999999999999 because that is the largest double value that is less than 1.0 .
      Specified by:
      nextDouble in interface IRNG
      Specified by:
      nextDouble in class AbstractRNG
      Returns:
      a double between 0.0 (inclusive) and 0.9999999999999999 (inclusive)

    • nextFloat

      public final float nextFloat()
      Gets a random float between 0.0f inclusive and 1.0f exclusive. This returns a maximum of 0.99999994 because that is the largest float value that is less than 1.0f .
      Specified by:
      nextFloat in interface IRNG
      Specified by:
      nextFloat in class AbstractRNG
      Returns:
      a float between 0f (inclusive) and 0.99999994f (inclusive)

    • copy

      public SilkRNG copy()
      Creates a copy of this SilkRNG; it will generate the same random numbers, given the same calls in order, as this SilkRNG at the point copy() is called. The copy will not share references with this SilkRNG.
      Specified by:
      copy in interface IRNG
      Specified by:
      copy in interface RandomnessSource
      Specified by:
      copy in interface StatefulRandomness
      Specified by:
      copy in class AbstractRNG
      Returns:
      a copy of this SilkRNG

    • toSerializable

      public Serializable toSerializable()
      Gets a view of this IRNG in a way that implements Serializable, which is simply this IRNG.
      Specified by:
      toSerializable in interface IRNG
      Specified by:
      toSerializable in class AbstractRNG
      Returns:
      a Serializable view of this IRNG or a similar one; always this

    • setSeed

      public void setSeed​(int seed)
      Sets the state of this generator using one int, running it through Zog32RNG's algorithm two times to get two ints. If the states would both be 0, state A is assigned 1 instead.
      Parameters:
      seed - the int to use to produce this generator's state

    • getStateA

      public int getStateA()

    • setStateA

      public void setStateA​(int stateA)
      Sets the first part of the state to the given int.
      Parameters:
      stateA - any int

    • getStateB

      public int getStateB()

    • setStateB

      public void setStateB​(int stateB)
      Sets the second part of the state to the given int.
      Parameters:
      stateB - any int

    • setState

      public void setState​(int stateA, int stateB)
      Sets the current internal state of this SilkRNG with two ints, where stateA and stateB can each be any int.
      Parameters:
      stateA - any int
      stateB - any int

    • getState

      public long getState()
      Get the current internal state of the StatefulRandomness as a long.
      Specified by:
      getState in interface StatefulRandomness
      Returns:
      the current internal state of this object.

    • setState

      public void setState​(long state)
      Set the current internal state of this StatefulRandomness with a long.
      Specified by:
      setState in interface StatefulRandomness
      Parameters:
      state - a 64-bit long. You should avoid passing 0; this implementation will treat it as 1.

    • equals

      public boolean equals​(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • determineInt

      public static int determineInt​(int state)
      A deterministic random int generator that, given one int state as input, irreversibly returns an almost-always-different int as a result. Unlike the rest of SilkRNG, this will not produce all possible ints given all ints as inputs, and probably a third of all possible ints cannot be returned. You should call this with SilkRNG.determineInt(state = state + 1 | 0) (you can subtract 1 to go backwards instead of forwards), which will allow overflow in the incremented state to be handled the same on GWT as on desktop.
      Parameters:
      state - an int that should go up or down by 1 each call, as with SilkRNG.determineInt(state = state + 1 | 0) to handle overflow
      Returns:
      a not-necessarily-unique int that is usually very different from state

    • determineBounded

      public static int determineBounded​(int state, int bound)
      A deterministic random int generator that, given one int state and an outer int bound as input, returns an int between 0 (inclusive) and bound (exclusive) as a result, which should have no noticeable correlation between state and the result. You should call this with SilkRNG.determineBound(state = state + 1 | 0, bound) (you can subtract 1 to go backwards instead of forwards), which will allow overflow in the incremented state to be handled the same on GWT as on desktop. Like most bounded int generation in SquidLib, this uses some long math, but most of the function uses ints.
      Parameters:
      state - an int that should go up or down by 1 each call, as with SilkRNG.determineBounded(state = state + 1 | 0, bound) to handle overflow
      bound - the outer exclusive bound, as an int; may be positive or negative
      Returns:
      an int between 0 (inclusive) and bound (exclusive)

    • determine

      public static long determine​(int state)
      A deterministic random long generator that, given one int state as input, returns an almost-always-different long as a result. This can only return a tiny fraction of all possible longs, since there are at most 2 to the 32 possible ints and this doesn't even return different values for each of those. You should call this with SilkRNG.determine(state = state + 1 | 0) (you can subtract 1 to go backwards instead of forwards), which will allow overflow in the incremented state to be handled the same on GWT as on desktop.
      Parameters:
      state - an int that should go up or down by 1 each call, as with SilkRNG.determine(state = state + 1 | 0) to handle overflow
      Returns:
      a not-necessarily-unique long that is usually very different from state

    • determineFloat

      public static float determineFloat​(int state)
      A deterministic random float generator that, given one int state as input, returns an almost-always-different float between 0.0f and 1.0f as a result. Unlike the rest of SilkRNG, this might not produce all possible floats given all ints as inputs, and some fraction of possible floats cannot be returned. You should call this with SilkRNG.determineFloat(state = state + 1 | 0) (you can subtract 1 to go backwards instead of forwards), which will allow overflow in the incremented state to be handled the same on GWT as on desktop.
      Parameters:
      state - an int that should go up or down by 1 each call, as with SilkRNG.determineFloat(state = state + 1 | 0) to handle overflow
      Returns:
      a not-necessarily-unique float from 0.0f to 1.0f that is usually very different from state

    • determineDouble

      public static double determineDouble​(int state)
      A deterministic random double generator that, given one int state as input, returns an almost-always-different double between 0.0 and 1.0 as a result. This cannot produce more than a tiny fraction of all possible doubles because the input is 32 bits and at least 53 bits are needed to represent most doubles from 0.0 to 1.0. You should call this with SilkRNG.determineDouble(state = state + 1 | 0) (you can subtract 1 to go backwards instead of forwards), which will allow overflow in the incremented state to be handled the same on GWT as on desktop.
      Parameters:
      state - an int that should go up or down by 1 each call, as with SilkRNG.determineDouble(state = state + 1 | 0) to handle overflow
      Returns:
      a not-necessarily-unique double from 0.0 to 1.0 that is usually very different from state