Stochastic Simulation in Java
PointSet Class Referenceabstract

This abstract class defines the basic methods for accessing and manipulating point sets. More...

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

## Classes

class  DefaultPointSetIterator

## Public Member Functions

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

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.

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 Attributes

double EpsilonHalf = 1.0 / Num.TWOEXP[55]

int dim = 0

int numPoints = 0

int dimShift = 0

int capacityShift = 0

RandomStream shiftStream

## Static Protected Attributes

static final int MAXBITS = 31

## Detailed Description

This abstract class defines the basic methods for accessing and manipulating point sets.

A point set can be represented as a two-dimensional array, whose element $$(i,j)$$ contains $$u_{i,j}$$, the coordinate $$j$$ of point $$i$$. Each coordinate $$u_{i,j}$$ is assumed to be in the unit interval $$[0,1]$$. Whether the values 0 and 1 can occur may depend on the actual implementation of the point set.

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 point set iterator which permits one to enumerate the points and their coordinates. Several iterators over the same point set can coexist at any given time. 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. 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 quasi-Monte Carlo in a simulation program.

The class also offers tools to manipulate a list of randomizations that can be applied to this point set.

Remarks
Pierre: So far, the general types of randomizations have been implemented as containers. We may remove this concept of list.
Richard: La nouvelle randomisation d’Adam rend l’ancienne liste de randomisations obsolète: nous n’avons jamais utilisé l’ancienne version.
Pierre: Now removed.

This abstract class has only one abstract method: getCoordinate. Providing an implementation for this method is already sufficient for the subclass to work. However, in many cases, efficiency can be dramatically improved by overwriting iterator to provide a custom iterator that does not necessarily rely on getCoordinate. In fact, direct use of getCoordinate to access the coordinates is generally discouraged. One should access the points and coordinates via the iterators.

The built-in range checks require some extra time and also assumes that nobody ever uses negative indices. If getCoordinate is not accessed directly by the user, it may be implemented without range checks.

Remarks
Pierre: I think we should remove the addRandomShift and clearRandomShift methods, because they are too specialized and not appropriate for all kinds of point sets. We can also make the randomize(stream) methods abstract, or make them do nothing by default.

## Member Function Documentation

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

This method does nothing for this generic class.

In some subclasses, it adds a random shift to all the points of the point set, using stream stream to generate the random numbers, for coordinates d1 to d2-1.

 void addRandomShift ( RandomStream stream )

This method does nothing for this generic class.

Similar to addRandomShift (0, d2, stream), with d2 the dimension of the current random shift.

## ◆ formatPoints() [1/4]

 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.

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

## ◆ formatPoints() [2/4]

 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.

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

## ◆ formatPoints() [3/4]

 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.

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

## ◆ formatPoints() [4/4]

 String 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

## ◆ formatPointsBase() [1/4]

 String 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

## ◆ formatPointsBase() [2/4]

 String 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

## ◆ formatPointsBase() [3/4]

 String 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

## ◆ formatPointsBase() [4/4]

 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$$.

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

## ◆ formatPointsNumbered() [1/2]

 String 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

## ◆ formatPointsNumbered() [2/2]

 String 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

## ◆ getCoordinate()

 abstract double getCoordinate ( int i, int j )
abstract

Returns $$u_{i,j}$$, the coordinate $$j$$ of the point $$i$$.

Remarks
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?
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 getDimension ( )

Returns the dimension (number of available coordinates) of the point set.

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

## ◆ getNumPoints()

 int 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 an infinity of points.

## ◆ getStream()

 RandomStream getStream ( )

Returns the random stream used to generate random shifts.

Returns
the random stream used

## ◆ iterator()

 PointSetIterator 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

## ◆ randomize()

 void randomize ( PointSetRandomization rand )

Randomizes the point set using the given rand.

Parameters
 rand PointSetRandomization to use

## ◆ setStream()

 void setStream ( RandomStream stream )

Sets the random stream used to generate random shifts to stream.

Parameters
 stream the new random stream

## ◆ toString()

 String toString ( )

Formats a string that contains information about the point set.

Returns
string representation of the point set information

The documentation for this class was generated from the following file:
• PointSet.java