Class SobolSequenceGenerator

  • All Implemented Interfaces:
    RandomVectorGenerator

    public class SobolSequenceGenerator
    extends java.lang.Object
    implements RandomVectorGenerator
    Implementation of a Sobol sequence.

    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 pseudo-random points in a space S, which are equi-distributed.

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

    The generator supports two modes:

    Since:
    3.3
    See Also:
    Sobol sequence (Wikipedia), Sobol sequence direction numbers
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static int BITS
      The number of bits to use.
      private int count
      The current index in the sequence.
      private int dimension
      Space dimension.
      private long[][] direction
      The direction vector for each component.
      private static java.lang.String FILE_CHARSET
      Character set for file input.
      private static int MAX_DIMENSION
      The maximum supported space dimension.
      private static java.lang.String RESOURCE_NAME
      The resource containing the direction numbers.
      private static double SCALE
      The scaling factor.
      private long[] x
      The current state.
    • Constructor Summary

      Constructors 
      Constructor Description
      SobolSequenceGenerator​(int dimension)
      Construct a new Sobol sequence generator for the given space dimension.
      SobolSequenceGenerator​(int dimension, java.io.InputStream is)
      Construct a new Sobol sequence generator for the given space dimension with direction vectors loaded from the given stream.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int getNextIndex()
      Returns the index i of the next point in the Sobol sequence that will be returned by calling nextVector().
      private void initDirectionVector​(int d, int a, int[] m)
      Calculate the direction numbers from the given polynomial.
      private int initFromStream​(java.io.InputStream is)
      Load the direction vector for each dimension from the given stream.
      double[] nextVector()
      Generate a random vector.
      double[] skipTo​(int index)
      Skip to the i-th point in the Sobol sequence.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • SCALE

        private static final double SCALE
        The scaling factor.
      • MAX_DIMENSION

        private static final int MAX_DIMENSION
        The maximum supported space dimension.
        See Also:
        Constant Field Values
      • RESOURCE_NAME

        private static final java.lang.String RESOURCE_NAME
        The resource containing the direction numbers.
        See Also:
        Constant Field Values
      • FILE_CHARSET

        private static final java.lang.String FILE_CHARSET
        Character set for file input.
        See Also:
        Constant Field Values
      • dimension

        private final int dimension
        Space dimension.
      • count

        private int count
        The current index in the sequence.
      • direction

        private final long[][] direction
        The direction vector for each component.
      • x

        private final long[] x
        The current state.
    • Constructor Detail

      • SobolSequenceGenerator

        public SobolSequenceGenerator​(int dimension)
                               throws OutOfRangeException
        Construct a new Sobol sequence generator for the given space dimension.
        Parameters:
        dimension - the space dimension
        Throws:
        OutOfRangeException - if the space dimension is outside the allowed range of [1, 1000]
      • SobolSequenceGenerator

        public SobolSequenceGenerator​(int dimension,
                                      java.io.InputStream is)
                               throws NotStrictlyPositiveException,
                                      MathParseException,
                                      java.io.IOException
        Construct a new Sobol sequence generator for the given space dimension with direction vectors loaded from the given stream.

        The expected format is identical to the files available from Stephen Joe and Frances Kuo. The first line will be ignored as it is assumed to contain only the column headers. The columns are:

        • d: the dimension
        • s: the degree of the primitive polynomial
        • a: the number representing the coefficients
        • m: the list of initial direction numbers
        Example:
         d       s       a       m_i
         2       1       0       1
         3       2       1       1 3
         

        The input stream must be an ASCII text containing one valid direction vector per line.

        Parameters:
        dimension - the space dimension
        is - the stream to read the direction vectors from
        Throws:
        NotStrictlyPositiveException - if the space dimension is < 1
        OutOfRangeException - if the space dimension is outside the range [1, max], where max refers to the maximum dimension found in the input stream
        MathParseException - if the content in the stream could not be parsed successfully
        java.io.IOException - if an error occurs while reading from the input stream
    • Method Detail

      • initFromStream

        private int initFromStream​(java.io.InputStream is)
                            throws MathParseException,
                                   java.io.IOException
        Load the direction vector for each dimension from the given stream.

        The input stream must be an ASCII text containing one valid direction vector per line.

        Parameters:
        is - the input stream to read the direction vector from
        Returns:
        the last dimension that has been read from the input stream
        Throws:
        java.io.IOException - if the stream could not be read
        MathParseException - if the content could not be parsed successfully
      • initDirectionVector

        private void initDirectionVector​(int d,
                                         int a,
                                         int[] m)
        Calculate the direction numbers from the given polynomial.
        Parameters:
        d - the dimension, zero-based
        a - the coefficients of the primitive polynomial
        m - the initial direction numbers
      • nextVector

        public double[] nextVector()
        Generate a random vector.
        Specified by:
        nextVector in interface RandomVectorGenerator
        Returns:
        a random vector as an array of double.
      • skipTo

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

        This operation can be performed in O(1).

        Parameters:
        index - the index in the sequence to skip to
        Returns:
        the i-th point in the Sobol sequence
        Throws:
        NotPositiveException - if index < 0
      • 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