Apache Commons Math 3.6.1 · org.apache.commons.math3.random.SobolSequenceGenerator

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)

Field Summary

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

Constructor Summary

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

Method Summary

Modifier and Type	Method and Description
public int	Returns: the index of the next point getNextIndex() Returns the index i of the next point in the Sobol sequence that will be returned by calling `nextVector()`.
private void	initDirectionVector(final int the dimension, zero-based d, final int the coefficients of the primitive polynomial a, final int[] the initial direction numbers m) Calculate the direction numbers from the given polynomial.
private int	Returns: the last dimension that has been read from the input stream initFromStream(final InputStream the input stream to read the direction vector from is) Load the direction vector for each dimension from the given stream.
public double[]	nextVector() Implements org.apache.commons.math3.random.RandomVectorGenerator.nextVector. Generate a random vector.
public double[]	Returns: the i-th point in the Sobol sequence skipTo(final int the index in the sequence to skip to index) Skip to the i-th point in the Sobol sequence.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

BITS	back to summary
private static final int BITS The number of bits to use.

count	back to summary
private int count The current index in the sequence.

dimension	back to summary
private final int dimension Space dimension.

direction	back to summary
private final long[][] direction The direction vector for each component.

FILE_CHARSET	back to summary
private static final String FILE_CHARSET Character set for file input.

MAX_DIMENSION	back to summary
private static final int MAX_DIMENSION The maximum supported space dimension.

RESOURCE_NAME	back to summary
private static final String RESOURCE_NAME The resource containing the direction numbers.

SCALE	back to summary
private static final double SCALE The scaling factor.

x	back to summary
private final long[] x The current state.

Constructor Detail

SobolSequenceGenerator	back to summary
public SobolSequenceGenerator(final int dimension) throws OutOfRangeException Construct a new Sobol sequence generator for the given space dimension. Parameters dimension:int the space dimension Exceptions OutOfRangeException: if the space dimension is outside the allowed range of [1, 1000]

SobolSequenceGenerator

back to summary

public SobolSequenceGenerator(final int dimension) throws OutOfRangeException

Construct a new Sobol sequence generator for the given space dimension.

Parameters

dimension:int: the space dimension

Exceptions

OutOfRangeException:: if the space dimension is outside the allowed range of [1, 1000]

SobolSequenceGenerator	back to summary
public SobolSequenceGenerator(final int dimension, final 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:int the space dimension is:InputStream the stream to read the direction vectors from Exceptions NotStrictlyPositiveException: if the space dimension is < 1 MathParseException: if the content in the stream could not be parsed successfully IOException: if an error occurs while reading from the input stream OutOfRangeException: if the space dimension is outside the range [1, max], where max refers to the maximum dimension found in the input stream

SobolSequenceGenerator

back to summary

public SobolSequenceGenerator(final int dimension, final 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:int: the space dimension
is:InputStream: the stream to read the direction vectors from

Exceptions

NotStrictlyPositiveException:: if the space dimension is < 1
MathParseException:: if the content in the stream could not be parsed successfully
IOException:: if an error occurs while reading from the input stream
OutOfRangeException:: if the space dimension is outside the range [1, max], where max refers to the maximum dimension found in the input stream

Method Detail

getNextIndex back to summary

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

public int getNextIndex()

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

Returns:int: the index of the next point

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

initDirectionVector

back to summary

private void initDirectionVector(final int d, final int a, final int[] m)

Calculate the direction numbers from the given polynomial.

Parameters

d:int: the dimension, zero-based
a:int: the coefficients of the primitive polynomial
m:int[]: the initial direction numbers

initFromStream	back to summary
private int initFromStream(final InputStream is) throws MathParseException, 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:InputStream the input stream to read the direction vector from Returns:int the last dimension that has been read from the input stream Exceptions MathParseException: if the content could not be parsed successfully IOException: if the stream could not be read

initFromStream

back to summary

private int initFromStream(final InputStream is) throws MathParseException, 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:InputStream: the input stream to read the direction vector from

Returns:int

the last dimension that has been read from the input stream

Exceptions

MathParseException:: if the content could not be parsed successfully
IOException:: if the stream could not be read

nextVector	back to summary
public double[] nextVector() Implements org.apache.commons.math3.random.RandomVectorGenerator.nextVector. Doc from org.apache.commons.math3.random.RandomVectorGenerator.nextVector. Generate a random vector. Returns:double[] a random vector as an array of double.

nextVector

back to summary

public double[] nextVector()

Implements org.apache.commons.math3.random.RandomVectorGenerator.nextVector.

Doc from org.apache.commons.math3.random.RandomVectorGenerator.nextVector.

Generate a random vector.

Returns:double[]: a random vector as an array of double.

skipTo	back to summary
public double[] skipTo(final int index) throws NotPositiveException Skip to the i-th point in the Sobol sequence. This operation can be performed in O(1). Parameters index:int the index in the sequence to skip to Returns:double[] the i-th point in the Sobol sequence Exceptions NotPositiveException: if index < 0

skipTo

back to summary

public double[] skipTo(final int index) throws NotPositiveException

Skip to the i-th point in the Sobol sequence.

This operation can be performed in O(1).

Parameters

index:int: the index in the sequence to skip to

Returns:double[]

the i-th point in the Sobol sequence

Exceptions

NotPositiveException:: if index < 0

public Class SobolSequenceGenerator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail