SobolSequenceGenerator (Apache Commons Math 3.3 API)

org.apache.commons.math3.random

## Class SobolSequenceGenerator

- java.lang.Object
- - org.apache.commons.math3.random.SobolSequenceGenerator

- All Implemented Interfaces:
    RandomVectorGenerator

      public class SobolSequenceGenerator
      extends 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:

  - sequential generation of points: `nextVector()`
  - random access to the i-th point in the sequence: `skipTo(int)`
  Since:
    3.3
  Version:
    $Id: SobolSequenceGenerator.java 1538368 2013-11-03 13:57:37Z erans $
  See Also:
    Sobol sequence (Wikipedia), Sobol sequence direction numbers

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SobolSequenceGenerator(int dimension)` Construct a new Sobol sequence generator for the given space dimension.
    `SobolSequenceGenerator(int dimension, InputStream is)` Construct a new Sobol sequence generator for the given space dimension with direction vectors loaded from the given stream.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getNextIndex()` Returns the index i of the next point in the Sobol sequence that will be returned by calling `nextVector()`.
    `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`

- - ### 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,
                                InputStream is)
                                 throws NotStrictlyPositiveException,
                                        MathParseException,
                                        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
        `IOException` - if an error occurs while reading from the input stream

  - ### Method Detail

    - #### 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

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.