This abstract class represents a general point set. More...

Inheritance diagram for umontreal.ssj.hups.PointSet:

Classes
class	DefaultPointSetIterator
	This class implements a default point set iterator. More...

Public Member Functions
int	getDimension ()
	Returns the dimension (number of available coordinates) of the points.
int	getNumPoints ()
	Returns the number of points.
abstract double	getCoordinate (int i, int j)
	Returns \(u_{i,j}\), the coordinate \(j\) of the point \(i\).
PointSetIterator	iterator ()
	Constructs and returns a point set iterator.
void	randomize (PointSetRandomization rand)
	Randomizes this point set using the given rand.
void	addRandomShift (int d1, int d2, RandomStream stream)
	By default, this method generates a random shift in the protected double[] array shift, to be used eventually for a random shift modulo 1.
void	addRandomShift (RandomStream stream)
	Same as `addRandomShift(0, dim, stream)`, where dim is the dimension of the point set.
void	addRandomShift (int d1, int d2)
	Refreshes the random shift (generates new uniform values for the random shift coordinates) for coordinates d1 to d2-1, using the saved shiftStream.
void	addRandomShift ()
	Same as `addRandomShift(0, dim)`, where dim is the dimension of the point set.
void	clearRandomShift ()
	Erases the current random shift, if any.
String	toString ()
	Formats a string that contains information about the point set.
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.
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.
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.
String	formatPoints (PointSetIterator iter, int n, int d)
	Same as invoking `formatPoints(n, d)`, but prints the points by calling iter repeatedly.
String	formatPointsBase (int b)
	Similar to `formatPoints()`, but the points coordinates are printed in base \(b\).
String	formatPointsBase (int n, int d, int b)
	Similar to `formatPoints(n, d)`, but the points coordinates are printed in base \(b\).
String	formatPointsBase (PointSetIterator iter, int b)
	Similar to `formatPoints(iter)`, but the points coordinates are printed in base.
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\).
String	formatPointsNumbered ()
	Same as invoking `formatPointsNumbered(n, d)` with \(n\) and \(d\) equal to the number of points and the dimension, respectively.
String	formatPointsNumbered (int n, int d)
	Same as invoking `formatPoints(n,d)`, except that the points are numbered.

Static Public Member Functions
static int	getMaxBits ()
	Returns the maximum number of usable bits.

Protected Attributes
double	EpsilonHalf = 1.0 / Num.TWOEXP[55]
	To avoid 0 for nextCoordinate when random shifting, we add this to each coordinate.
int	dim = 0
	Dimension of the points.
int	numPoints = 0
	Number of points.
int	dimShift = 0
	Current dimension of the shift.
int	capacityShift = 0
	Number of array elements in the shift vector, always >= dimShift.
double[]	shift
	This is the shift vector as a double[] array, which contains the current random shift in case we apply a random shift modulo 1.
RandomStream	shiftStream
	Stream used to generate the random shifts.

Static Protected Attributes
static final int	MAXBITS = 31
	Since Java has no unsigned type, the 32nd bit cannot be used efficiently, so we have only 31 bits.

Detailed Description

This abstract class represents a general point set.

It defines some basic methods for accessing and manipulating the points and other properties of the point set. Conceptually, a point set can be viewed as a two-dimensional array, whose element \((i,j)\) contains \(u_{i,j}\), the coordinate \(j\) of point \(i\), for \(i\geq 0\) and \(j\geq 0\). Each coordinate \(u_{i,j}\) is assumed to be in the unit interval \([0,1]\). Whether the values 0 and 1 can occur or not may depend on the actual implementation of the point set. In general, when the points are randomized, after the randomization we add (internally, when the points or coordinates are requested)

\(\epsilon/2\) to each coordinate for a very small \(\epsilon > 0\), so that 0 never occurs in the output. By default, in this PointSet class, we have \(\epsilon = 2^{-54}\).

All points have the same number of coordinates (their dimension) and this number can be queried by getDimension. The number of points is queried by getNumPoints. The points and coordinates are both numbered starting from 0 and their number can actually be infinite.

The iterator method provides a PointSetIterator object which can enumerate the points and their coordinates. Several iterators over the same point set can coexist at any given time. However, in the current implementation they will all enumerate the same randomized points when the points are randomized, because the randomizations are integrated in the point sets and not in the iterators. These iterators are instances of a hidden inner-class that implements the PointSetIterator interface. The default implementation of iterator provided here relies on the method getCoordinate to access the coordinates directly. However, this approach is rarely efficient. (One exception is in a CachedPointSet.) Specialized implementations that dramatically improve the performance are provided in subclasses of PointSet. The PointSetIterator interface actually extends the umontreal.ssj.rng.RandomStream interface, so that the iterator can also be seen as a umontreal.ssj.rng.RandomStream and used wherever such a stream is required for generating uniform random numbers. This permits one to easily replace pseudorandom numbers by the coordinates of a selected set of highly-uniform points, i.e., to replace Monte Carlo by QMC or RQMC in a simulation program.

The present abstract class has only one abstract method: getCoordinate. Providing an implementation for this method is already sufficient for the subclass to work. However, in most cases, efficiency can be dramatically improved by overwriting iterator to provide a custom iterator that does not necessarily rely on getCoordinate. Direct use of getCoordinate to access the coordinates is generally discouraged. One should access the points and coordinates via the iterators. Built-in range checks when generating the points require some extra time and also assume that nobody ever uses negative indices. If getCoordinate is never accessed directly by the user, it may be implemented without range checks.

In this abstract class, the addRandomShift() methods generate a double[] array to be used eventually to add a random shift modulo 1, but this random shift is not used here. It can be used in subclasses when generating coordinates. In subclasses, addRandomShift (d1, d2, stream) can also be optionally re-implemented to produce something else than a double[] array, for example when we want the random shift to be digital. There are also some types of point sets that do not use at all such a random shift.

Definition at line 99 of file PointSet.java.

Member Function Documentation

◆ addRandomShift() [1/4]

void umontreal.ssj.hups.PointSet.addRandomShift ( )

Same as addRandomShift(0, dim), where dim is the dimension of the point set.

Reimplemented in umontreal.ssj.hups.RandShiftedMod1PointSet.

Definition at line 283 of file PointSet.java.

◆ addRandomShift() [2/4]

void umontreal.ssj.hups.PointSet.addRandomShift	(	int	d1,
		int	d2 )

Refreshes the random shift (generates new uniform values for the random shift coordinates) for coordinates d1 to d2-1, using the saved shiftStream.

Reimplemented in umontreal.ssj.hups.RandShiftedMod1PointSet.

Definition at line 275 of file PointSet.java.

◆ addRandomShift() [3/4]

void umontreal.ssj.hups.PointSet.addRandomShift	(	int	d1,
		int	d2,
		RandomStream	stream )

By default, this method generates a random shift in the protected double[] array shift, to be used eventually for a random shift modulo 1.

This random shift will be added (modulo 1) to all the points when they are enumerated by the iterator. The random shift is generated using the stream to generate the uniform random numbers, one for each of the coordinates d1 to d2-1. The variable shiftStream is also set to this stream. Allowing an arbitrary range d1 to d2-1 permits one to extends the random shift to additional coordinates when needed, e.g., when the number of coordinates that we need is unknown a priori. There are also other situations in which we may want to randomize only specific coordinates, e.g., in the Array-RQMC method.

This method is re-implemented in subclasses for which a different form of shift is appropriate, e.g., should produce a random digital shift in base \(b\) for a DigitalNet, a binary digital shift for a DigitalNetBase2, etc.

These methods are used internally by randomizations. For example, calling RandomShift.randomize(PointSet) calls addRandomShift. Normally, one should not call them directly, but use PointSetRandomization objects instead.

Definition at line 241 of file PointSet.java.

◆ addRandomShift() [4/4]

void umontreal.ssj.hups.PointSet.addRandomShift ( RandomStream stream )

Same as addRandomShift(0, dim, stream), where dim is the dimension of the point set.

Parameters

stream random number stream used to generate uniforms for the random shift

Reimplemented in umontreal.ssj.hups.ContainerPointSet, umontreal.ssj.hups.DigitalNet, umontreal.ssj.hups.DigitalNetBase2, and umontreal.ssj.hups.RandShiftedMod1PointSet.

Definition at line 267 of file PointSet.java.

◆ clearRandomShift()

void umontreal.ssj.hups.PointSet.clearRandomShift ( )

Erases the current random shift, if any.

Reimplemented in umontreal.ssj.hups.ContainerPointSet, umontreal.ssj.hups.CycleBasedPointSet, umontreal.ssj.hups.CycleBasedPointSetBase2, umontreal.ssj.hups.DigitalNet, umontreal.ssj.hups.DigitalNetBase2, and umontreal.ssj.hups.Rank1Lattice.

Definition at line 290 of file PointSet.java.

◆ formatPoints() [1/4]

String umontreal.ssj.hups.PointSet.formatPoints ( )

Same as invoking formatPoints(n, d) with \(n\) and \(d\) equal to the number of points and the dimension of this object, respectively.

Returns: string representation of all the points in the point set

Exceptions

UnsupportedOperationException if the number of points or dimension of the point set is infinite

Reimplemented in umontreal.ssj.hups.CycleBasedPointSet, and umontreal.ssj.hups.CycleBasedPointSetBase2.

Definition at line 327 of file PointSet.java.

◆ formatPoints() [2/4]

String umontreal.ssj.hups.PointSet.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. If \(n\) is larger than the number of points in the point set, it is reset to that number. If \(d\) is larger than the dimension of the points, it is reset to that dimension. The points are printed in the simplest format, separated by spaces, by calling the default iterator repeatedly.

Parameters

n	number of points
d	dimension

Returns: string representation of first d coordinates of first n points in the point set

Definition at line 346 of file PointSet.java.

◆ formatPoints() [3/4]

String umontreal.ssj.hups.PointSet.formatPoints ( PointSetIterator iter )

Same as invoking formatPoints(iter, n, d) with \(n\) and \(d\) equal to the number of points and the dimension, respectively.

Parameters

iter	iterator associated to the point set

Returns: string representation of all the points in the point set

Exceptions

UnsupportedOperationException if the number of points or dimension of the point set is infinite

Definition at line 362 of file PointSet.java.

◆ formatPoints() [4/4]

String umontreal.ssj.hups.PointSet.formatPoints	(	PointSetIterator	iter,
		int	n,
		int	d )

Same as invoking formatPoints(n, d), but prints the points by calling iter repeatedly.

The order of the printed points may be different than the one resulting from the default iterator.

Parameters

iter	iterator associated to the point set
n	number of points
d	dimension

Returns: string representation of first d coordinates of first n points in the point set

Definition at line 383 of file PointSet.java.

◆ formatPointsBase() [1/4]

String umontreal.ssj.hups.PointSet.formatPointsBase ( int b )

Similar to formatPoints(), but the points coordinates are printed in base \(b\).

Parameters

b base

Returns: string representation of all the points in the point set

Exceptions

UnsupportedOperationException if the number of points or dimension of the point set is infinite

Definition at line 411 of file PointSet.java.

◆ formatPointsBase() [2/4]

String umontreal.ssj.hups.PointSet.formatPointsBase	(	int	n,
		int	d,
		int	b )

Similar to formatPoints(n, d), but the points coordinates are printed in base \(b\).

Parameters

n	number of points
d	dimension
b	base

Returns: string representation of first d coordinates of first n points in the point set

Definition at line 426 of file PointSet.java.

◆ formatPointsBase() [3/4]

String umontreal.ssj.hups.PointSet.formatPointsBase	(	PointSetIterator	iter,
		int	b )

Similar to formatPoints(iter), but the points coordinates are printed in base.

\(b\).

Parameters

iter	iterator associated to the point set
b	base

Returns: string representation of all the points in the point set

Exceptions

UnsupportedOperationException if the number of points or dimension of the point set is infinite

Definition at line 442 of file PointSet.java.

◆ formatPointsBase() [4/4]

String umontreal.ssj.hups.PointSet.formatPointsBase	(	PointSetIterator	iter,
		int	n,
		int	d,
		int	b )

Similar to formatPoints(iter, n, d), but the points coordinates are printed in base \(b\).

Parameters

iter	iterator associated to the point set
n	number of points
d	dimension
b	base

Returns: string representation of first d coordinates of first n points in the point set

Definition at line 463 of file PointSet.java.

◆ formatPointsNumbered() [1/2]

String umontreal.ssj.hups.PointSet.formatPointsNumbered ( )

Same as invoking formatPointsNumbered(n, d) with \(n\) and \(d\) equal to the number of points and the dimension, respectively.

Returns: string representation of all the points in the point set

Exceptions

UnsupportedOperationException if the number of points or dimension of the point set is infinite

Definition at line 503 of file PointSet.java.

◆ formatPointsNumbered() [2/2]

String umontreal.ssj.hups.PointSet.formatPointsNumbered	(	int	n,
		int	d )

Same as invoking formatPoints(n,d), except that the points are numbered.

Parameters

n	number of points
d	dimension

Returns: string representation of first d coordinates of first n points in the point set

Definition at line 522 of file PointSet.java.

◆ getCoordinate()

abstract double umontreal.ssj.hups.PointSet.getCoordinate	(	int	i,
		int	j )

abstract

Returns \(u_{i,j}\), the coordinate \(j\) of the point \(i\).

When the points are randomized (e.g., a random shift is added), the values returned by this method should incorporate the randomizations. Richard: La méthode getCoordinate de certaines classes ne tient pas compte du random shift, contrairement à l’itérateur de la même classe. Faut-il que toutes les getCoordinate implémentent le random shift quand il existe? Oui.

Parameters

i	index of the point to look for
j	index of the coordinate to look for

Returns: the value of \(u_{i,j}\)

◆ getDimension()

int umontreal.ssj.hups.PointSet.getDimension ( )

Returns the dimension (number of available coordinates) of the points.

If the dimension is actually infinite, Integer.MAX_VALUE is returned.

Returns: the dimension of the point set or Integer.MAX_VALUE if it is infinite

Reimplemented in umontreal.ssj.hups.ContainerPointSet, umontreal.ssj.hups.CycleBasedPointSet, and umontreal.ssj.hups.SortedAndCutPointSet.

Definition at line 159 of file PointSet.java.

◆ getMaxBits()

int umontreal.ssj.hups.PointSet.getMaxBits ( )

static

Returns the maximum number of usable bits.

Definition at line 177 of file PointSet.java.

◆ getNumPoints()

int umontreal.ssj.hups.PointSet.getNumPoints ( )

Returns the number of points.

If this number is actually infinite, Integer.MAX_VALUE is returned.

Returns: the number of points in the point set or Integer.MAX_VALUE if the point set has infinity cardinality.

Reimplemented in umontreal.ssj.hups.ContainerPointSet, and umontreal.ssj.hups.HaltonSequence.

Definition at line 170 of file PointSet.java.

◆ iterator()

PointSetIterator umontreal.ssj.hups.PointSet.iterator ( )

Constructs and returns a point set iterator.

The default implementation returns an iterator that uses the method getCoordinate(i,j) to iterate over the points and coordinates, but subclasses can reimplement it for better efficiency.

Returns: point set iterator for the point set

Reimplemented in umontreal.ssj.hups.AntitheticPointSet, umontreal.ssj.hups.BakerTransformedPointSet, umontreal.ssj.hups.CachedPointSet, umontreal.ssj.hups.ContainerPointSet, umontreal.ssj.hups.CycleBasedPointSet, umontreal.ssj.hups.CycleBasedPointSetBase2, umontreal.ssj.hups.DigitalNet, umontreal.ssj.hups.DigitalNetBase2, umontreal.ssj.hups.RandShiftedMod1PointSet, umontreal.ssj.hups.Rank1Lattice, umontreal.ssj.hups.SortedAndCutPointSet, and umontreal.ssj.hups.SubsetOfPointSet.

Definition at line 203 of file PointSet.java.

◆ randomize()

void umontreal.ssj.hups.PointSet.randomize ( PointSetRandomization rand )

Randomizes this point set using the given rand.

Use the equivalent rand.randomize(this) instead.

Parameters

rand	PointSetRandomization to use

Reimplemented in umontreal.ssj.hups.CachedPointSet, umontreal.ssj.hups.ContainerPointSet, umontreal.ssj.hups.IndependentPointsCached, umontreal.ssj.hups.LatinHypercube, umontreal.ssj.hups.SortedAndCutPointSet, umontreal.ssj.hups.StratifiedUnitCube, and umontreal.ssj.hups.StratifiedUnitCubeAnti.

Definition at line 214 of file PointSet.java.

◆ toString()

String umontreal.ssj.hups.PointSet.toString ( )

Formats a string that contains information about the point set.

Returns: string representation of the point set information

Definition at line 301 of file PointSet.java.

Member Data Documentation

◆ capacityShift

int umontreal.ssj.hups.PointSet.capacityShift = 0

protected

Number of array elements in the shift vector, always >= dimShift.

Definition at line 135 of file PointSet.java.

◆ dim

int umontreal.ssj.hups.PointSet.dim = 0

protected

Dimension of the points.

Definition at line 118 of file PointSet.java.

◆ dimShift

int umontreal.ssj.hups.PointSet.dimShift = 0

protected

Current dimension of the shift.

This is useful mostly for the case where the points have an unlimited number of coordinates.

Definition at line 130 of file PointSet.java.

◆ EpsilonHalf

double umontreal.ssj.hups.PointSet.EpsilonHalf = 1.0 / Num.TWOEXP[55]

protected

To avoid 0 for nextCoordinate when random shifting, we add this to each coordinate.

Definition at line 113 of file PointSet.java.

◆ MAXBITS

final int umontreal.ssj.hups.PointSet.MAXBITS = 31

staticprotected

Since Java has no unsigned type, the 32nd bit cannot be used efficiently, so we have only 31 bits.

This mainly affects digit scrambling and bit vectors. This also limits the maximum number of columns for the generating matrices of digital nets in base 2.

Definition at line 107 of file PointSet.java.

◆ numPoints

int umontreal.ssj.hups.PointSet.numPoints = 0

protected

Number of points.

Definition at line 123 of file PointSet.java.

◆ shift

double [] umontreal.ssj.hups.PointSet.shift

protected

This is the shift vector as a double[] array, which contains the current random shift in case we apply a random shift modulo 1.

It is initially null.

Definition at line 141 of file PointSet.java.

◆ shiftStream

RandomStream umontreal.ssj.hups.PointSet.shiftStream

protected

Stream used to generate the random shifts.

This stream is saved from the last time we have called addRandomShift, in case this method has to be called again internally by an iterator. This may happen for example if the points have unbounded dimension and we need to extend the random shift to additional coordinates.

Definition at line 150 of file PointSet.java.

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

src/main/java/umontreal/ssj/hups/PointSet.java

SSJ API Documentation Stochastic Simulation in Java

Classes

Public Member Functions

Static Public Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ addRandomShift() [1/4]

◆ addRandomShift() [2/4]

◆ addRandomShift() [3/4]

◆ addRandomShift() [4/4]

◆ clearRandomShift()

◆ formatPoints() [1/4]

◆ formatPoints() [2/4]

◆ formatPoints() [3/4]

◆ formatPoints() [4/4]

◆ formatPointsBase() [1/4]

◆ formatPointsBase() [2/4]

◆ formatPointsBase() [3/4]

◆ formatPointsBase() [4/4]

◆ formatPointsNumbered() [1/2]

◆ formatPointsNumbered() [2/2]

◆ getCoordinate()

◆ getDimension()

◆ getMaxBits()

◆ getNumPoints()

◆ iterator()

◆ randomize()

◆ toString()

Member Data Documentation

◆ capacityShift

◆ dim

◆ dimShift

◆ EpsilonHalf

◆ MAXBITS

◆ numPoints

◆ shift

◆ shiftStream