Package squidpony.squidmath

Class SobolQRNG

java.lang.Object
squidpony.squidmath.SobolQRNG
All Implemented Interfaces:
Serializable, RandomnessSource
public class SobolQRNG
extends Object
implements RandomnessSource
Implementation of a Sobol sequence as a Quasi-Random Number Generator.

A Sobol sequence is a low-discrepancy sequence with the property that for all values of N, its subsequence (x1, ... xN) has a low discrepancy. It can be used to generate quasi-random points in a space S, which are equi-distributed. This is not a true random number generator, and is not even a pseudo-random number generator; the sequence generated from identical starting points with identical dimensions will be exactly the same. Calling this class' nextVector, nextIntVector, and nextLongVector methods all increment the position in the sequence, and do not use separate sequences for separate types.

The implementation already comes with support for up to 16 dimensions with direction numbers calculated from Stephen Joe and Frances Kuo.

The generator supports two modes:

For reference, Sobol sequence (Wikipedia) and the data, Sobol sequence direction numbers Created by Tommy Ettinger on 5/2/2015 based off Apache Commons Math 4.
See Also:
Serialized Form

  • Constructor Summary

    Constructors 
    Constructor Description
    SobolQRNG​(int dimension)
    Construct a new Sobol sequence generator for the given space dimension.

  • Method Summary

    Modifier and Type Method Description
    SobolQRNG 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)  
    double[] fillVector​(double[] toFill)
    Generate a random vector.
    int getNextIndex()
    Returns the index i of the next point in the Sobol sequence that will be returned by calling nextVector().
    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.
    Coord nextCoord​(int xLimit, int yLimit)
    Generate a random vector as a Coord, scaled between 0 (inclusive) and the given limits (exclusive).
    double nextDouble()  
    double nextDouble​(double max)  
    int[] nextIntVector()
    Generate a random vector.
    int[] nextIntVector​(int max)
    Generate a random vector.
    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.
    long[] nextLongVector()
    Generate a random vector.
    long[] nextLongVector​(long max)
    Generate a random vector.
    double[] nextVector()
    Generate a random vector.
    double[] nextVector​(double max)
    Generate a random vector.
    double[] skipTo​(int index)
    Skip to the i-th point in the Sobol sequence.
    String toString()  

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • SobolQRNG

      public SobolQRNG​(int dimension) throws ArithmeticException
      Construct a new Sobol sequence generator for the given space dimension. You should call skipTo(int) with a fairly large number (over 1000) to ensure the results aren't too obviously non-random. If you skipTo(1), all doubles in that result will be 0.5, and if you skipTo(0), all will be 0 (this class starts at index 1 instead of 0 for that reason). This is true for all dimensions.
      Parameters:
      dimension - the space dimension
      Throws:
      ArithmeticException - if the space dimension is outside the allowed range of [1, 16]

  • Method Details

    • nextVector

      public double[] nextVector()
      Generate a random vector.
      Returns:
      a random vector as an array of double in the range [0.0, 1.0).

    • fillVector

      public double[] fillVector​(double[] toFill)
      Generate a random vector.
      Returns:
      a random vector as an array of double in the range [0.0, 1.0).

    • nextCoord

      public Coord nextCoord​(int xLimit, int yLimit)
      Generate a random vector as a Coord, scaled between 0 (inclusive) and the given limits (exclusive).
      Parameters:
      xLimit - the upper exclusive bound for the Coord's x-coordinate
      yLimit - the upper exclusive bound for the Coord's y-coordinate
      Returns:
      a random vector as a Coord between (0,0) inclusive and (xLimit,yLimit) exclusive

    • nextVector

      public double[] nextVector​(double max)
      Generate a random vector.
      Parameters:
      max - the maximum exclusive value for the elements of the desired vector; minimum is 0 inclusive.
      Returns:
      a random vector as an array of double.

    • nextLongVector

      public long[] nextLongVector()
      Generate a random vector.
      Returns:
      a random vector as an array of long (only 52 bits are actually used for the result, plus sign bit).

    • nextLongVector

      public long[] nextLongVector​(long max)
      Generate a random vector.
      Parameters:
      max - the maximum exclusive value for the elements of the desired vector; minimum is 0 inclusive.
      Returns:
      a random vector as an array of long (only 52 bits are actually used for the result, plus sign bit).

    • nextIntVector

      public int[] nextIntVector()
      Generate a random vector.
      Returns:
      a random vector as an array of int.

    • nextIntVector

      public int[] nextIntVector​(int max)
      Generate a random vector.
      Parameters:
      max - the maximum exclusive value for the elements of the desired vector; minimum is 0 inclusive.
      Returns:
      a random vector as an array of int.

    • skipTo

      public double[] skipTo​(int index)
      Skip to the i-th point in the Sobol sequence.

      This operation can be performed in O(1). If index is somehow negative, this uses its absolute value instead of throwing an exception. If index is 0, the result will always be entirely 0. You should skipTo a number greater than 1000 if you want random-seeming individual numbers in each vector.

      Parameters:
      index - the index in the sequence to skip to
      Returns:
      the i-th point in the Sobol sequence

    • getNextIndex

      public int getNextIndex()
      Returns the index i of the next point in the Sobol sequence that will be returned by calling nextVector().
      Returns:
      the index of the next point

    • next

      public int next​(int bits)
      Description copied from interface: RandomnessSource
      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:
      a quasi-random int with at most the specified number of bits

    • nextLong

      public 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)

    • nextDouble

      public double nextDouble()

    • nextDouble

      public double nextDouble​(double max)

    • copy

      public SobolQRNG 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 needs 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