Package squidpony.squidmath

Class GearRNG

java.lang.Object
squidpony.squidmath.GearRNG
All Implemented Interfaces:
Serializable, RandomnessSource
public final class GearRNG
extends Object
implements RandomnessSource, Serializable
A larger-period generator with 127 bits of state (two longs, one is always odd), a period of 2 to the 127, and what should be slightly better speed than the related OrbitRNG. It passes 32TB of PractRand testing with no anomalies or failures. The idea for this generator is to have a simple Weyl sequence (a counter with a large increment) for stateA, and at one point to multiply a value based on stateA by stateB, which is always odd. The trick is that stateB usually updates by adding a large even number, but about once every 10 billion generated numbers, decided by a comparison between a constant and stateA's value, it "shifts gears" and stays on the same value while stateA updates.
For some purposes you may want to instead consider TangleRNG, which also has two states (one odd) and uses a very similar algorithm, but it never "shifts gears," which drops its period down to 2 to the 64, makes it a SkippingRandomness, and should in theory speed it up (in practice, TangleRNG needs an extra step that actually makes it slower than GearRNG). An individual TangleRNG can't produce all possible long outputs and can produce some duplicates, but each pair of states for a TangleRNG has a different set of which outputs will be skipped and which will be duplicated. Since it would require months of solid number generation to exhaust the period of a TangleRNG, and that's the only time an output can be confirmed as skipped, it's probably fine for most usage to use many different TangleRNGs, all seeded differently. Other choices: you could use one OrbitRNG (which technically has a longer period, but some states produce very similar output), DiverRNG (if you don't mind that it never produces a duplicate output), IsaacRNG (if speed is less important but more secure output is), or Lathe64RNG, though all of those are probably slower than using one GearRNG object or even many TangleRNG objects.
The name comes from shifting gears; pretty straightforward here.
Created by Tommy Ettinger on 3/29/2020.
See Also:
Serialized Form

  • Constructor Summary

    Constructors 
    Constructor Description
    GearRNG()
    Creates a new generator seeded using Math.random.
    GearRNG​(long seed)  
    GearRNG​(long seedA, long seedB)  

  • Method Summary

    Modifier and Type Method Description
    GearRNG 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​(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.
    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.
    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; the lowest bit is always discarded and replaced with 1.
    String toString()  

    Methods inherited from class java.lang.Object

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

  • Constructor Details

  • Method Details

    • 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; the lowest bit is always discarded and replaced with 1. That is, stateB is always an odd number, and if an even number is given it will be incremented.
      Parameters:
      stateB - any 64-bit long

    • next

      public final int next​(int bits)
      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

    • nextLong

      public final 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.

      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)

    • copy

      public GearRNG 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 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 String toString()
      Overrides:
      toString in class Object

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object