org.apache.commons.math3.random

Class SobolSequenceGenerator

java.lang.Object

org.apache.commons.math3.random.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:

• sequential generation of points: nextVector()
• random access to the i-th point in the sequence: skipTo(int)

Since:

3.3

See Also:

Sobol sequence (Wikipedia), Sobol sequence direction numbers

Field Summary

Fields

Modifier and Type	Field and 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 and 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

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().
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

BITS

private static final int BITS

The number of bits to use.

See Also:

Constant Field Values

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