org.apache.commons.math3.random

Class HaltonSequenceGenerator

java.lang.Object

org.apache.commons.math3.random.HaltonSequenceGenerator

All Implemented Interfaces:

RandomVectorGenerator

public class HaltonSequenceGenerator
extends java.lang.Object
implements RandomVectorGenerator

Implementation of a Halton sequence.

A Halton sequence is a low-discrepancy sequence generating points in the interval [0, 1] according to

   H(n) = d_0 / b + d_1 / b^2 .... d_j / b^j+1

   with

   n = d_j * b^j-1 + ... d_1 * b + d_0 * b^0
 

For higher dimensions, subsequent prime numbers are used as base, e.g. { 2, 3, 5 } for a Halton sequence in R^3.

Halton sequences are known to suffer from linear correlation for larger prime numbers, thus the individual digits are usually scrambled. This implementation already comes with support for up to 40 dimensions with optimal weight numbers from H. Chi: Scrambled quasirandom sequences and their applications.

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:

Halton sequence (Wikipedia), On the Halton sequence and its scramblings

Constructor Summary

Constructors

Constructor and Description
HaltonSequenceGenerator(int dimension) Construct a new Halton sequence generator for the given space dimension.
HaltonSequenceGenerator(int dimension, int[] bases, int[] weights) Construct a new Halton sequence generator with the given base numbers and weights for each dimension.

Method Summary

Modifier and Type	Method and Description
int	getNextIndex() Returns the index i of the next point in the Halton 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 Halton sequence.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HaltonSequenceGenerator

public HaltonSequenceGenerator(int dimension)
                        throws OutOfRangeException

Construct a new Halton 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, 40]

HaltonSequenceGenerator

public HaltonSequenceGenerator(int dimension,
                               int[] bases,
                               int[] weights)
                        throws NullArgumentException,
                               OutOfRangeException,
                               DimensionMismatchException

Construct a new Halton sequence generator with the given base numbers and weights for each dimension. The length of the bases array defines the space dimension and is required to be > 0.

Parameters:

dimension - the space dimension

bases - the base number for each dimension, entries should be (pairwise) prime, may not be null

weights - the weights used during scrambling, may be null in which case no scrambling will be performed

Throws:

NullArgumentException - if base is null

OutOfRangeException - if the space dimension is outside the range [1, len], where len refers to the length of the bases array

DimensionMismatchException - if weights is non-null and the length of the input arrays differ

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 Halton 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 Halton sequence

Throws:

NotPositiveException - if index < 0

getNextIndex

public int getNextIndex()

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

Returns:

the index of the next point