umontreal.iro.lecuyer.hups
Class PointSet

java.lang.Object
  umontreal.iro.lecuyer.hups.PointSet

Direct Known Subclasses:

CachedPointSet, ContainerPointSet, CycleBasedPointSet, DigitalNet, HaltonSequence, HammersleyPointSet, PaddedPointSet, Rank1Lattice, SubsetOfPointSet

public abstract class PointSet
extends Object

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 RandomStream interface, so that the iterator can also be seen as a 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.

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 practically all 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 discouraged. One should access the coordinates only via the iterators.

Constructor Summary

PointSet()

Method Summary

void	addRandomShift() Deprecated.
void	addRandomShift(int d1, int d2) Deprecated.
void	addRandomShift(int d1, int d2, RandomStream stream) This method does nothing for this generic class.
void	addRandomShift(RandomStream stream) This method does nothing for this generic class.
void	clearRandomShift() Erases the current random shift, if any.
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 n points.
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 b.
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.
abstract double	getCoordinate(int i, int j) Returns ui, j, the coordinate j of the point i.
int	getDimension() Returns the dimension (number of available coordinates) of the point set.
int	getNumPoints() Returns the number of points.
RandomStream	getStream() Returns the random stream used to generate random shifts.
PointSetIterator	iterator() Constructs and returns a point set iterator.
void	randomize() Deprecated.
void	randomize(int d1, int d2) Deprecated.
void	randomize(int d1, int d2, RandomStream stream) By default, this method simply calls addRandomShift(d1, d2, stream).
void	randomize(PointSetRandomization rand) Randomizes the point set using the given rand.
void	randomize(RandomStream stream) By default, this method simply calls addRandomShift(stream).
void	setStream(RandomStream stream) Sets the random stream used to generate random shifts to stream.
String	toString() Formats a string that contains information about the point set.
void	unrandomize() By default, this method simply calls clearRandomShift().

Methods inherited from class java.lang.Object

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

Constructor Detail

PointSet

public PointSet()

Method Detail

getDimension

public 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

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

getCoordinate

public abstract double getCoordinate(int i,
                                     int j)

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

Parameters:

i - index of the point to look for

j - index of the coordinate to look for

Returns:

the value of u_{i, j}

iterator

public 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

setStream

public void setStream(RandomStream stream)

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

Parameters:

stream - the new random stream

getStream

public RandomStream getStream()

Returns the random stream used to generate random shifts.

Returns:

the random stream used

randomize

public void randomize(PointSetRandomization rand)

Randomizes the point set using the given rand.

Parameters:

rand - PointSetRandomization to use

addRandomShift

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

addRandomShift

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

addRandomShift

@Deprecated
public void addRandomShift(int d1,
                                      int d2)

Deprecated.

Similar to addRandomShift(d1, d2, stream), with the current random stream.

addRandomShift

@Deprecated
public void addRandomShift()

Deprecated.

clearRandomShift

public void clearRandomShift()

Erases the current random shift, if any.

randomize

public void randomize(int d1,
                      int d2,
                      RandomStream stream)

By default, this method simply calls addRandomShift(d1, d2, stream).

randomize

public void randomize(RandomStream stream)

By default, this method simply calls addRandomShift(stream).

randomize

@Deprecated
public void randomize(int d1,
                                 int d2)

Deprecated.

By default, this method simply calls addRandomShift(d1, d2).

randomize

@Deprecated
public void randomize()

Deprecated.

unrandomize

public void unrandomize()

By default, this method simply calls clearRandomShift().

toString

public String toString()

Formats a string that contains information about the point set.

Overrides:

toString in class Object

Returns:

string representation of the point set information

formatPoints

public 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

Throws:

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

formatPoints

public 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

public 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

Throws:

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

formatPoints

public 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

public 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

Throws:

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

formatPointsBase

public 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

public 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

Throws:

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

formatPointsBase

public 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

public 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

Throws:

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

formatPointsNumbered

public 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