SSJ  3.2.1
Stochastic Simulation in Java
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
DigitalNet Class Reference

This class provides the basic structures for storing and manipulating linear digital nets in base \(b\), for an arbitrary base \(b\ge2\). More...

Inheritance diagram for DigitalNet:
[legend]
Collaboration diagram for DigitalNet:
[legend]

Classes

class  DigitalNetIterator
 
class  DigitalNetIteratorNoGray
 

Public Member Functions

double getCoordinate (int i, int j)
 
PointSetIterator iterator ()
 
 DigitalNet ()
 Empty constructor.
 
double getCoordinateNoGray (int i, int j)
 Returns \(u_{i,j}\), the coordinate \(j\) of point \(i\), the points being enumerated in the standard order (no Gray code). More...
 
PointSetIterator iteratorNoGray ()
 This iterator does not use the Gray code. More...
 
void addRandomShift (int d1, int d2, RandomStream stream)
 Adds a random digital shift to all the points of the point set, using stream stream to generate the random numbers. More...
 
void addRandomShift (RandomStream stream)
 Same as addRandomShift(0, dim, stream), where dim is the dimension of the digital net. More...
 
void clearRandomShift ()
 Erases the current digital random shift, if any.
 
String toString ()
 
void leftMatrixScramble (RandomStream stream)
 Applies a linear scramble by multiplying each \(\mathbf{C}_j\) on the left by a \(w\times w\) nonsingular lower-triangular matrix \(\mathbf{M}_j\), as suggested by Matoušek [169]  and implemented by Hong and Hickernell [86] . More...
 
void leftMatrixScrambleDiag (RandomStream stream)
 Similar to leftMatrixScramble except that all the off-diagonal elements of the \(\mathbf{M}_j\) are 0. More...
 
void leftMatrixScrambleFaurePermut (RandomStream stream, int sb)
 Similar to leftMatrixScramble except that the diagonal elements of each matrix \(\mathbf{M}_j\) are chosen from a restricted set of the best integers as calculated by Faure [56] . More...
 
void leftMatrixScrambleFaurePermutDiag (RandomStream stream, int sb)
 Similar to leftMatrixScrambleFaurePermut except that all off-diagonal elements are 0. More...
 
void leftMatrixScrambleFaurePermutAll (RandomStream stream, int sb)
 Similar to leftMatrixScrambleFaurePermut except that the elements under the diagonal are also chosen from the same restricted set as the diagonal elements. More...
 
void iBinomialMatrixScramble (RandomStream stream)
 Applies the \(i\)-binomial matrix scramble proposed by Tezuka [217]  (see also [184] ). More...
 
void iBinomialMatrixScrambleFaurePermut (RandomStream stream, int sb)
 Similar to iBinomialMatrixScramble except that the diagonal elements of each matrix \(\mathbf{M}_j\) are chosen as in leftMatrixScrambleFaurePermut. More...
 
void iBinomialMatrixScrambleFaurePermutDiag (RandomStream stream, int sb)
 Similar to iBinomialMatrixScrambleFaurePermut except that all the off-diagonal elements are 0. More...
 
void iBinomialMatrixScrambleFaurePermutAll (RandomStream stream, int sb)
 Similar to iBinomialMatrixScrambleFaurePermut except that the elements under the diagonal are also chosen from the same restricted set as the diagonal elements. More...
 
void stripedMatrixScramble (RandomStream stream)
 Applies the striped matrix scramble proposed by Owen [184] . More...
 
void stripedMatrixScrambleFaurePermutAll (RandomStream stream, int sb)
 Similar to stripedMatrixScramble except that the elements on and under the diagonal of each matrix \(\mathbf{M}_j\) are chosen as in leftMatrixScrambleFaurePermut. More...
 
void rightMatrixScramble (RandomStream stream)
 Applies a linear scramble by multiplying each \(\mathbf{C}_j\) on the right by a single \(k\times k\) nonsingular upper-triangular matrix \(\mathbf{M}\), as suggested by Faure and Tezuka [56]  (see also [86] ). More...
 
void unrandomize ()
 Restores the original generator matrices and removes the random shift.
 
void resetGeneratorMatrices ()
 Restores the original generator matrices. More...
 
void eraseOriginalGeneratorMatrices ()
 Erases the original generator matrices and replaces them by the current ones. More...
 
void printGeneratorMatrices (int s)
 Prints the generator matrices in standard form for dimensions 1 to \(s\).
 
- Public Member Functions inherited from PointSet
int getDimension ()
 Returns the dimension (number of available coordinates) of the point set. More...
 
int getNumPoints ()
 Returns the number of points. More...
 
abstract double getCoordinate (int i, int j)
 Returns \(u_{i,j}\), the coordinate \(j\) of the point \(i\). More...
 
PointSetIterator iterator ()
 Constructs and returns a point set iterator. More...
 
void setStream (RandomStream stream)
 Sets the random stream used to generate random shifts to stream. More...
 
RandomStream getStream ()
 Returns the random stream used to generate random shifts. More...
 
void randomize (PointSetRandomization rand)
 Randomizes the point set using the given rand. More...
 
void addRandomShift (int d1, int d2, RandomStream stream)
 This method does nothing for this generic class. More...
 
void addRandomShift (RandomStream stream)
 This method does nothing for this generic class. More...
 
void addRandomShift (int d1, int d2)
 Similar to addRandomShift(d1, d2, stream), with the current random stream.
 
void addRandomShift ()
 Similar to addRandomShift(0, d2, stream) with the current random stream and d2 the dimension of the current random shift.
 
void clearRandomShift ()
 Erases the current random shift, if any.
 
void randomize (int fromDim, int toDim, RandomStream stream)
 By default, this method simply calls addRandomShift (fromDim, toDim, stream), which does nothing.
 
void randomize (RandomStream stream)
 By default, this method simply calls randomize(0, dim, stream).
 
void randomize (int d1, int d2)
 By default, this method simply calls addRandomShift(d1, d2).
 
void randomize ()
 By default, this method simply calls addRandomShift().
 
void unrandomize ()
 By default, this method simply calls clearRandomShift().
 
String toString ()
 Formats a string that contains information about the point set. More...
 
String formatPoints ()
 Same as invoking formatPoints(n, d) with \(n\) and \(d\) equal to the number of points and the dimension of this object, respectively. More...
 
String formatPoints (int n, int d)
 Formats a string that displays the same information as returned by toString, together with the first \(d\) coordinates of the first \(n\) points. More...
 
String formatPoints (PointSetIterator iter)
 Same as invoking formatPoints(iter, n, d) with \(n\) and \(d\) equal to the number of points and the dimension, respectively. More...
 
String formatPoints (PointSetIterator iter, int n, int d)
 Same as invoking formatPoints(n, d), but prints the points by calling iter repeatedly. More...
 
String formatPointsBase (int b)
 Similar to formatPoints(), but the points coordinates are printed in base \(b\). More...
 
String formatPointsBase (int n, int d, int b)
 Similar to formatPoints(n, d), but the points coordinates are printed in base \(b\). More...
 
String formatPointsBase (PointSetIterator iter, int b)
 Similar to formatPoints(iter), but the points coordinates are printed in base \(b\). More...
 
String formatPointsBase (PointSetIterator iter, int n, int d, int b)
 Similar to formatPoints(iter, n, d), but the points coordinates are printed in base \(b\). More...
 
String formatPointsNumbered ()
 Same as invoking formatPointsNumbered(n, d) with \(n\) and \(d\) equal to the number of points and the dimension, respectively. More...
 
String formatPointsNumbered (int n, int d)
 Same as invoking formatPoints(n,d), except that the points are numbered. More...
 

Protected Member Functions

int intToDigitsGray (int b, int i, int numDigits, int[] bary, int[] gray)
 

Protected Attributes

int b = 0
 
int numCols = 0
 
int numRows = 0
 
int outDigits = 0
 
int [][] genMat
 
int [][] digitalShift
 
double normFactor
 
double [] factor
 
- Protected Attributes inherited from PointSet
double EpsilonHalf = 1.0 / Num.TWOEXP[55]
 
int dim = 0
 
int numPoints = 0
 
int dimShift = 0
 
int capacityShift = 0
 
RandomStream shiftStream
 

Additional Inherited Members

- Static Protected Attributes inherited from PointSet
static final int MAXBITS = 31
 

Detailed Description

This class provides the basic structures for storing and manipulating linear digital nets in base \(b\), for an arbitrary base \(b\ge2\).

We recall that a net contains \(n = b^k\) points in \(s\) dimensions, where the \(i\)th point \(\mathbf{u}_i\), for \(i=0,…,b^k-1\), is defined as follows:

\begin{align*} i & = \sum_{\ell=0}^{k-1} a_{i,\ell} b^{\ell}, \\ \begin{pmatrix} u_{i,j,1} \\ u_{i,j,2} \\ \vdots \end{pmatrix} & = \mathbf{C}_j \begin{pmatrix} a_{i,0} \\ a_{i,1} \\ \vdots \\ a_{i,k-1} \end{pmatrix} , \\ u_{i,j} & = \sum_{\ell=1}^{\infty}u_{i,j,\ell} b^{-\ell}, \\ \mathbf{u}_i & = (u_{i,0},…,u_{i,s-1}). \end{align*}

In our implementation, the matrices \(\mathbf{C}_j\) are \(r\times k\), so the expansion of \(u_{i,j}\) is truncated to its first \(r\) terms. The points are stored implicitly by storing the generator matrices \(\mathbf{C}_j\) in a large two-dimensional array of integers, with \(srk\) elements. For general \(b\), the element \((l,c)\) of \(\mathbf{C}_j\) (counting elements from 0) is stored at position \([jk+c][l]\) in this array.

The points \(\mathbf{u}_i\) are enumerated using the Gray code technique as proposed in [8], [219]  (see also [67], [86] ). With this technique, the \(b\)-ary representation of \(i\), \(\mathbf{a}_i = (a_{i,0}, …, a_{i,k-1})\), is replaced in Equation ( digital-Cj ) by a Gray code representation of \(i\), \(\mathbf{g}_i = (g_{i,0}, …, g_{i,k-1})\). The Gray code \(\mathbf{g}_i\) used here is defined by \(g_{i,k-1} = a_{i,k-1}\) and \(g_{i,\ell} = (a_{i,\ell} - a_{i,\ell+1}) \mod b\) for \(\ell= 0,…,k-2\). It has the property that \(\mathbf{g}_i = (g_{i,0}, …, g_{i,k-1})\) and \(\mathbf{g}_{i+1} = (g_{i+1,0}, …, g_{i+1,k-1})\) differ only in the position of the smallest index \(\ell\) such that \(a_{i,\ell} < b - 1\), and we have \(g_{i+1,\ell} = (g_{i,\ell}+1) \mod b\) in that position.

This Gray code representation permits a more efficient enumeration of the points by the iterators. It changes the order in which the points \(\mathbf{u}_i\) are enumerated, but the first \(b^m\) points remain the same for every integer \(m\). The \(i\)th point of the sequence with the Gray enumeration is the \(i’\)th point of the original enumeration, where \(i’\) is the integer whose \(b\)-ary representation \(\mathbf{a}_{i’}\) is given by the Gray code \(\mathbf{g}_i\). To enumerate all the points successively, we never need to compute the Gray codes explicitly. It suffices to know the position \(\ell\) of the Gray code digit that changes at each step, and this can be found quickly from the \(b\)-ary representation \(\mathbf{a}_i\). The digits of each coordinate \(j\) of the current point can be updated by adding column \(\ell\) of the generator matrix \(\mathbf{C}_j\) to the old digits, modulo \(b\).

One should avoid using the method getCoordinate(i, j) for arbitrary values of i and j, because this is much slower than using an iterator to access successive coordinates.

Digital nets can be randomized in various ways [169], [56], [124], [184] . Several types of randomizations specialized for nets are implemented directly in this class.

A simple but important randomization is the random digital shift in base \(b\), defined as follows: replace each digit \(u_{i,j,\ell}\) in ( digital-uij ) by \((u_{i,j,\ell} + d_{j,\ell}) \mod b\), where the \(d_{j,\ell}\)’s are i.i.d. uniform over \(\{0,…,b-1\}\). This is equivalent to applying a single random shift to all the points in a formal series representation of their coordinates [124], [153] . In practice, the digital shift is truncated to \(w\) digits, for some integer \(w\ge r\). Applying a digital shift does not change the equidistribution and \((t,m,s)\)-net properties of a point set [86], [122], [153] . Moreover, with the random shift, each point is uniformly distributed over the unit hypercube (but the points are not independent, of course).

A second class of randomizations specialized for digital nets are the linear matrix scrambles [169], [56], [86], [184] , which multiply the matrices \(\mathbf{C}_j\) by a random invertible matrix \(\mathbf{M}_j\), modulo \(b\). There are several variants, depending on how \(\mathbf{M}_j\) is generated, and on whether \(\mathbf{C}_j\) is multiplied on the left or on the right. In our implementation, the linear matrix scrambles are incorporated directly into the matrices \(\mathbf{C}_j\) (as in [86] ), so they do not slow down the enumeration of points. Methods are available for applying linear matrix scrambles and for removing these randomizations. These methods generate the appropriate random numbers and make the corresponding changes to the \(\mathbf{C}_j\)’s. A copy of the original \(\mathbf{C}_j\)’s is maintained, so the point set can be returned to its original unscrambled state at any time. When a new linear matrix scramble is applied, it is always applied to the original generator matrices. The method resetGeneratorMatrices removes the current matrix scramble by resetting the generator matrices to their original state. On the other hand, the method eraseOriginalGeneratorMatrices replaces the original generator matrices by the current ones, making the changes permanent. This is useful if one wishes to apply two or more linear matrix scrambles on top of each other.

Linear matrix scrambles are usually combined with a random digital shift; this combination is called an affine matrix scramble [184] . These two randomizations are applied via separate methods. The linear matrix scrambles are incorporated into the matrices \(\mathbf{C}_j\) whereas the digital random shift is stored and applied separately, independently of the other scramblings.

Applying a digital shift or a linear matrix scramble to a digital net invalidates all iterators for that randomized point, because each iterator uses a cached copy of the current point, which is updated only when the current point index of that iterator changes, and the update also depends on the cached copy of the previous point. After applying any kind of scrambling, the iterators must be reinitialized to the initial point by invoking PointSetIterator.resetCurPointIndex or reinstantiated by the #iterator method (this is not done automatically).

Member Function Documentation

◆ addRandomShift() [1/2]

void addRandomShift ( int  d1,
int  d2,
RandomStream  stream 
)

Adds a random digital shift to all the points of the point set, using stream stream to generate the random numbers.

For each coordinate \(j\) from d1 to d2-1, the shift vector \((d_{j,0},…,d_{j,k-1})\) is generated uniformly over \(\{0,…,b-1\}^k\) and added modulo \(b\) to the digits of all the points. After adding a digital shift, all iterators must be reconstructed or reset to zero.

Parameters
streamrandom number stream used to generate uniforms

◆ addRandomShift() [2/2]

void addRandomShift ( RandomStream  stream)

Same as addRandomShift(0, dim, stream), where dim is the dimension of the digital net.

Parameters
streamrandom number stream used to generate uniforms

◆ eraseOriginalGeneratorMatrices()

void eraseOriginalGeneratorMatrices ( )

Erases the original generator matrices and replaces them by the current ones.

The current linear matrix scrambles thus become permanent. This is useful if we want to apply several scrambles in succession to a given digital net.

◆ getCoordinateNoGray()

double getCoordinateNoGray ( int  i,
int  j 
)

Returns \(u_{i,j}\), the coordinate \(j\) of point \(i\), the points being enumerated in the standard order (no Gray code).

Parameters
ipoint index
jcoordinate index
Returns
the value of \(u_{i,j}\)

◆ iBinomialMatrixScramble()

void iBinomialMatrixScramble ( RandomStream  stream)

Applies the \(i\)-binomial matrix scramble proposed by Tezuka [217]  (see also [184] ).

This multiplies each \(\mathbf{C}_j\) on the left by a \(w\times w\) nonsingular lower-triangular matrix \(\mathbf{M}_j\) as in leftMatrixScramble, but with the additional constraint that all entries on any given diagonal or subdiagonal of \(\mathbf{M}_j\) are identical.

Parameters
streamrandom number stream used as generator of the randomness

◆ iBinomialMatrixScrambleFaurePermut()

void iBinomialMatrixScrambleFaurePermut ( RandomStream  stream,
int  sb 
)

Similar to iBinomialMatrixScramble except that the diagonal elements of each matrix \(\mathbf{M}_j\) are chosen as in leftMatrixScrambleFaurePermut.

Parameters
streamrandom number stream used to generate the randomness
sbOnly the first \(sb\) elements of \(F\) are used

◆ iBinomialMatrixScrambleFaurePermutAll()

void iBinomialMatrixScrambleFaurePermutAll ( RandomStream  stream,
int  sb 
)

Similar to iBinomialMatrixScrambleFaurePermut except that the elements under the diagonal are also chosen from the same restricted set as the diagonal elements.

Parameters
streamrandom number stream used to generate the randomness
sbOnly the first \(sb\) elements of \(F\) are used

◆ iBinomialMatrixScrambleFaurePermutDiag()

void iBinomialMatrixScrambleFaurePermutDiag ( RandomStream  stream,
int  sb 
)

Similar to iBinomialMatrixScrambleFaurePermut except that all the off-diagonal elements are 0.

Parameters
streamrandom number stream used to generate the randomness
sbOnly the first \(sb\) elements of \(F\) are used

◆ iteratorNoGray()

PointSetIterator iteratorNoGray ( )

This iterator does not use the Gray code.

Thus the points are enumerated in the order of their first coordinate before randomization.

◆ leftMatrixScramble()

void leftMatrixScramble ( RandomStream  stream)

Applies a linear scramble by multiplying each \(\mathbf{C}_j\) on the left by a \(w\times w\) nonsingular lower-triangular matrix \(\mathbf{M}_j\), as suggested by Matoušek [169]  and implemented by Hong and Hickernell [86] .

The diagonal entries of each matrix \(\mathbf{M}_j\) are generated uniformly over \(\{1,…,b-1\}\), the entries below the diagonal are generated uniformly over \(\{0,…,b-1\}\), and all these entries are generated independently. This means that in base \(b=2\), all diagonal elements are equal to 1.

Remarks
Richard: Les matrices de leftMatrixScramble sont carrées et triangulaires inférieures. PL pense qu’il faut considérer la possibilité de rajouter des lignes à ces matrices pour pouvoir randomiser plus les derniers chiffres ou les derniers bits.
Parameters
streamrandom number stream used to generate the randomness

◆ leftMatrixScrambleDiag()

void leftMatrixScrambleDiag ( RandomStream  stream)

Similar to leftMatrixScramble except that all the off-diagonal elements of the \(\mathbf{M}_j\) are 0.

Parameters
streamrandom number stream used to generate the randomness

◆ leftMatrixScrambleFaurePermut()

void leftMatrixScrambleFaurePermut ( RandomStream  stream,
int  sb 
)

Similar to leftMatrixScramble except that the diagonal elements of each matrix \(\mathbf{M}_j\) are chosen from a restricted set of the best integers as calculated by Faure [56] .

They are generated uniformly over the first sb elements of array \(F\), where \(F\) is made up of a permutation of the integers \([1..(b-1)]\). These integers are sorted by increasing order of the upper bounds of the extreme discrepancy for the given integer.

Parameters
streamrandom number stream used to generate the randomness
sbOnly the first \(sb\) elements of \(F\) are used

◆ leftMatrixScrambleFaurePermutAll()

void leftMatrixScrambleFaurePermutAll ( RandomStream  stream,
int  sb 
)

Similar to leftMatrixScrambleFaurePermut except that the elements under the diagonal are also chosen from the same restricted set as the diagonal elements.

Parameters
streamrandom number stream used to generate the randomness
sbOnly the first \(sb\) elements of \(F\) are used

◆ leftMatrixScrambleFaurePermutDiag()

void leftMatrixScrambleFaurePermutDiag ( RandomStream  stream,
int  sb 
)

Similar to leftMatrixScrambleFaurePermut except that all off-diagonal elements are 0.

Parameters
streamrandom number stream used to generate the randomness
sbOnly the first \(sb\) elements of \(F\) are used

◆ resetGeneratorMatrices()

void resetGeneratorMatrices ( )

Restores the original generator matrices.

This removes the current linear matrix scrambles.

◆ rightMatrixScramble()

void rightMatrixScramble ( RandomStream  stream)

Applies a linear scramble by multiplying each \(\mathbf{C}_j\) on the right by a single \(k\times k\) nonsingular upper-triangular matrix \(\mathbf{M}\), as suggested by Faure and Tezuka [56]  (see also [86] ).

The diagonal entries of the matrix \(\mathbf{M}\) are generated uniformly over \(\{1,…,b-1\}\), the entries above the diagonal are generated uniformly over \(\{0,…,b-1\}\), and all the entries are generated independently. The effect of this scramble is only to change the order in which the points are generated. If one computes the average value of a function over all the points of a given digital net, or over a number of points that is a power of the basis, then this scramble makes no difference.

Parameters
streamrandom number stream used as generator of the randomness

◆ stripedMatrixScramble()

void stripedMatrixScramble ( RandomStream  stream)

Applies the striped matrix scramble proposed by Owen [184] .

It multiplies each \(\mathbf{C}_j\) on the left by a \(w\times w\) nonsingular lower-triangular matrix \(\mathbf{M}_j\) as in leftMatrixScramble, but with the additional constraint that in any column, all entries below the diagonal are equal to the diagonal entry, which is generated randomly over \(\{1,…,b-1\}\). Note that for \(b=2\), the matrices \(\mathbf{M}_j\) become deterministic, with all entries on and below the diagonal equal to 1.

Parameters
streamrandom number stream used as generator of the randomness

◆ stripedMatrixScrambleFaurePermutAll()

void stripedMatrixScrambleFaurePermutAll ( RandomStream  stream,
int  sb 
)

Similar to stripedMatrixScramble except that the elements on and under the diagonal of each matrix \(\mathbf{M}_j\) are chosen as in leftMatrixScrambleFaurePermut.

Parameters
streamrandom number stream used as generator of the randomness
sbOnly the first \(sb\) elements of \(F\) are used

The documentation for this class was generated from the following file: