Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## umontreal.iro.lecuyer.hups
Interface PointSetIterator

All Superinterfaces:
  RandomStream

All Known Implementing Classes:
  CycleBasedPointSet.CycleBasedPointSetIterator, CycleBasedPointSetBase2.CycleBasedPointSetBase2Iterator

    public interface PointSetIterator

extends RandomStream

Objects of classes that implement this interface are iterators that permit one to enumerate (or observe) the successive points of a point set and the successive coordinates of these points. Each `PointSetIterator` is associated with a given point set and maintains a current point index i and a current coordinate index j, which are both initialized to zero.

Successive coordinates can be accessed one or many at a time by the methods `nextCoordinate` and `nextCoordinates`, respectively. The current coordinate index j can be set explicitely by `setCurCoordIndex` and `resetCurCoordIndex`. Similar methods are available for resetting and accessing the current point. The method `nextPoint` permits one to enumerate the successive points in natural order.

This class also implements the `RandomStream` interface. This permits one to replace random numbers by the coordinates of (randomized) quasi-Monte Carlo points without changing the code that calls the generators in a simulation program. That is, the same simulation program can be used for both Monte Carlo and quasi-Monte Carlo simulations. The method `nextDouble` does exactly the same as `nextCoordinate`, it returns the current coordinate of the current point and advances the current coordinate by one. The substreams correspond to the points, so `resetStartSubstream` resets the current point coordinate to zero, `resetNextSubstream` resets the iterator to the next point, and `resetStartStream` resets the iterator to the first point of the point set.

There can be several iterators over the same point set. These iterators are independent from each other. Classes that implement this interface must maintain enough information so that each iterator is unaffected by other iterator's operations. However, the iterator does not need to be independent of the underlying point set. If the point set is modified (e.g., randomized), the iterator may continue to work as usual.

Point set iterators are implemented as inner classes because this gives a direct access to the private members (or variables) of the class. This is important for efficiency. They are quite similar to the iterators in Java collections.

Method Summary
`int` | `getCurCoordIndex()` Returns the index j of the current coordinate.
`int` | `getCurPointIndex()` Returns the index i of the current point.
`boolean` | `hasNextCoordinate()` Returns `true` if the current point has another coordinate.
`boolean` | `hasNextPoint()` Returns `true` if there is a next point.
`double` | `nextCoordinate()` Returns the current coordinate ui, j and advances to the next one.
`void` | `nextCoordinates(double[] p, int d)` Returns the next `d` coordinates of the current point in `p` and advances the current coordinate index by `d`.
`int` | `nextPoint(double[] p, int d)` Returns the first `d` coordinates of the current point in `p`, advances to the next point, and returns the index of the new current point.
`void` | `resetCurCoordIndex()` Equivalent to `setCurCoordIndex` `(0)`.
`void` | `resetCurPointIndex()` Equivalent to `setCurPointIndex` `(0)`.
`int` | `resetToNextPoint()` Increases the current point index by 1 and returns its new value.
`void` | `setCurCoordIndex(int j)` Sets the current coordinate index to j, so that the next calls to `nextCoordinate` or `nextCoordinates` will return the values ui, j, ui, j+1,..., where i is the index of the current point.
`void` | `setCurPointIndex(int i)` Resets the current point index to i and the current coordinate index to zero.

Methods inherited from interface umontreal.iro.lecuyer.rng.RandomStream
`nextArrayOfDouble, nextArrayOfInt, nextDouble, nextInt, resetNextSubstream, resetStartStream, resetStartSubstream, toString`

Method Detail

### setCurCoordIndex

    void setCurCoordIndex(int j)

  Sets the current coordinate index to j, so that the next calls to `nextCoordinate` or `nextCoordinates` will return the values ui, j, ui, j+1,..., where i is the index of the current point.

  Parameters:
    `j` - index of the new current coordinate

### resetCurCoordIndex

    void resetCurCoordIndex()

  Equivalent to `setCurCoordIndex` `(0)`.

### getCurCoordIndex

    int getCurCoordIndex()

  Returns the index j of the current coordinate. This may be useful, e.g., for testing if enough coordinates are still available.

  Returns:
    index of the current coordinate

### hasNextCoordinate

    boolean hasNextCoordinate()

  Returns `true` if the current point has another coordinate. This can be useful for testing if coordinates are still available.

  Returns:
    `true` if the current point has another coordinate

### nextCoordinate

    double nextCoordinate()

  Returns the current coordinate ui, j and advances to the next one. If no current coordinate is available (either because the current point index has reached the number of points or because the current coordinate index has reached the number of dimensions), it throws a `NoSuchElementException`.

  Returns:
    value of the current coordinate
  Throws:
    `NoSuchElementException` - if no such coordinate is available

### nextCoordinates

    void nextCoordinates(double[] p,
                         int d)

  Returns the next `d` coordinates of the current point in `p` and advances the current coordinate index by `d`. If the remaining number of coordinates is too small, a `NoSuchElementException` is thrown, as in `nextCoordinate`.

  Parameters:
    `p` - array to be filled with the coordinates, starting at index 0
    `d` - number of coordinates to get
  Throws:
    `NoSuchElementException` - if there are not enough remaining coordinates in the current point

### setCurPointIndex

    void setCurPointIndex(int i)

  Resets the current point index to i and the current coordinate index to zero. If `i` is larger or equal to the number of points, an exception will not be raised here, but only later if we ask for a new coordinate or point.

  Parameters:
    `i` - new index of the current point

### resetCurPointIndex

    void resetCurPointIndex()

  Equivalent to `setCurPointIndex` `(0)`.

### resetToNextPoint

    int resetToNextPoint()

  Increases the current point index by 1 and returns its new value. If there is no more point, an exception will be raised only if we ask for a new coordinate or point later on.

  Returns:
    index of the new current point

### getCurPointIndex

    int getCurPointIndex()

  Returns the index i of the current point. This can be useful, e.g., for caching point sets.

  Returns:
    index of the current point

### hasNextPoint

    boolean hasNextPoint()

  Returns `true` if there is a next point. This can be useful for testing if points are still available.

  Returns:
    `true` if a next point is available from the iterated point set

### nextPoint

    int nextPoint(double[] p,
                  int d)

  Returns the first `d` coordinates of the current point in `p`, advances to the next point, and returns the index of the new current point. Even if the current coordinate index is 0, the point returned starts from coordinate 0. After obtaining the last point via this method, the current point index (returned by the method) is equal to the number of points, so it is no longer a valid point index. An exception will then be raised if we attempt to generate additional points or coordinates.

  Specialized implementations of this method often allow for increased efficiency, e.g., for cycle-based point sets where the cycles (but not the points) are stored explicitly or for digital nets by allowing non-incremental point enumerations via Gray-code counters.

  Parameters:
    `p` - array to be filled with the coordinates, starting from array index 0
    `d` - number of coordinates to return
  Returns:
    index of the new current point
  Throws:
    `NoSuchElementException` - if there are not enough coordinates available in the current point for filling `p`

Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

To submit a bug or ask questions, send an e-mail to Pierre L'Ecuyer.