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.rng
Class RandomStreamWithCache

    java.lang.Object
      umontreal.iro.lecuyer.rng.RandomStreamWithCache

All Implemented Interfaces:
  RandomStream

    public class RandomStreamWithCache

extends Object
implements RandomStream

This class represents a random stream whose uniforms are cached for more efficiency when using common random numbers. An object from this class is constructed with a reference to a `RandomStream` instance used to get the random numbers. These numbers are stored in an internal array to be retrieved later. The dimension of the array increases as the values are generated. If the `nextDouble` method is called after the object is reset, it gives back the cached values instead of computing new ones. If the cache is exhausted before the stream is reset, new values are computed, and added to the cache.

Such caching allows for a better performance with common random numbers, when generating uniforms is time-consuming. It can also help with restoring the simulation to a certain state without setting stream-specific seeds. However, using such caching may lead to memory problems if a large quantity of random numbers are needed.

Constructor Summary
`RandomStreamWithCache(RandomStream stream)` Constructs a new cached random stream with internal stream `stream`.
`RandomStreamWithCache(RandomStream stream, int initialCapacity)` Constructs a new cached random stream with internal stream `stream`.

Method Summary
`void` | `clearCache()` Clears the cached values for this random stream.
`RandomStream` | `getCachedStream()` Returns a reference to the random stream whose values are cached.
`DoubleArrayList` | `getCachedValues()` Returns an array list containing the values cached by this random stream.
`int` | `getCacheIndex()` Return the index of the next cached value that will be returned by the stream.
`int` | `getNumCachedValues()` Returns the total number of values cached by this random stream.
`void` | `initCache()` Resets this random stream to recover values from the cache.
`boolean` | `isCaching()` Determines if the random stream is caching values, default being `true`.
`void` | `nextArrayOfDouble(double[] u, int start, int n)` Generates `n` (pseudo)random numbers from the uniform distribution and stores them into the array `u` starting at index `start`.
`void` | `nextArrayOfInt(int i, int j, int[] u, int start, int n)` Generates `n` (pseudo)random numbers from the discrete uniform distribution over the integers {i, i + 1,..., j}, using this stream and stores the result in the array `u` starting at index `start`.
`double` | `nextDouble()` Returns a (pseudo)random number from the uniform distribution over the interval [0, 1), using this stream, after advancing its state by one step.
`int` | `nextInt(int i, int j)` Returns a (pseudo)random number from the discrete uniform distribution over the integers {i, i + 1,..., j}, using this stream.
`void` | `resetNextSubstream()` Reinitializes the stream to the beginning of its next substream: Ng is computed, and Cg and Bg are set to Ng.
`void` | `resetStartStream()` Reinitializes the stream to its initial state Ig: Cg and Bg are set to Ig.
`void` | `resetStartSubstream()` Reinitializes the stream to the beginning of its current substream: Cg is set to Bg.
`void` | `setCachedStream(RandomStream stream)` Sets the random stream whose values are cached to `stream`.
`void` | `setCachedValues(DoubleArrayList values)` Sets the array list containing the cached values to `values`.
`void` | `setCacheIndex(int newIndex)` Sets the index, in the cache, of the next value returned by `nextDouble`.
`void` | `setCaching(boolean caching)` Sets the caching indicator to `caching`.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface umontreal.iro.lecuyer.rng.RandomStream
`toString`

Constructor Detail

### RandomStreamWithCache

    public RandomStreamWithCache(RandomStream stream)

  Constructs a new cached random stream with internal stream `stream`.

  Parameters:
    `stream` - the random stream whose uniforms are cached.
  Throws:
    `NullPointerException` - if `stream` is `null`.

### RandomStreamWithCache

    public RandomStreamWithCache(RandomStream stream,
                                 int initialCapacity)

  Constructs a new cached random stream with internal stream `stream`. The `initialCapacity` parameter is used to set the initial capacity of the internal array which can grow as needed; it does not limit the total size of the cache.

  Parameters:
    `stream` - the random stream whose values are cached.
    `initialCapacity` - the initial capacity of the cache.
  Throws:
    `NullPointerException` - if `stream` is `null`.

Method Detail

### isCaching

    public boolean isCaching()

  Determines if the random stream is caching values, default being `true`. When caching is turned OFF, the `nextDouble` method simply calls the corresponding method on the internal random stream, without storing the generated uniforms.

  Returns:
    the caching indicator.

### setCaching

    public void setCaching(boolean caching)

  Sets the caching indicator to `caching`. If caching is turned OFF, this method calls `clearCache` to clear the cached values.

  Parameters:
    `caching` - the new value of the caching indicator.

### getCachedStream

    public RandomStream getCachedStream()

  Returns a reference to the random stream whose values are cached.

  Returns:
    a reference to the random stream whose values are cached.

### setCachedStream

    public void setCachedStream(RandomStream stream)

  Sets the random stream whose values are cached to `stream`. If the stream is changed, the `clearCache` method is called to clear the cache.

  Parameters:
    `stream` - the new random stream whose values will be cached.
  Throws:
    `NullPointerException` - if `stream` is `null`.

### clearCache

    public void clearCache()

  Clears the cached values for this random stream. Any subsequent call will then obtain new values from the internal stream.

### initCache

    public void initCache()

  Resets this random stream to recover values from the cache. Subsequent calls to `nextDouble` will return the cached uniforms until all the values are returned. When the array of cached values is exhausted, the internal random stream is used to generate new values which are added to the internal array as well. This method is equivalent to calling `setCacheIndex`.

### getNumCachedValues

    public int getNumCachedValues()

  Returns the total number of values cached by this random stream.

  Returns:
    the total number of cached values.

### getCacheIndex

    public int getCacheIndex()

  Return the index of the next cached value that will be returned by the stream. If the cache is exhausted, the returned value corresponds to the value returned by `getNumCachedValues`, and a subsequent call to `nextDouble` will generate a new variate rather than reading a previous one from the cache. If caching is disabled, this always returns 0.

  Returns:
    the index of the next cached value.

### setCacheIndex

    public void setCacheIndex(int newIndex)

  Sets the index, in the cache, of the next value returned by `nextDouble`. If `newIndex` is 0, this is equivalent to calling `initCache`. If `newIndex` is `getNumCachedValues`, subsequent calls to `nextDouble` will add new values to the cache.

  Parameters:
    `newIndex` - the new index.
  Throws:
    `IllegalArgumentException` - if `newIndex` is negative or greater than or equal to the cache size.

### getCachedValues

    public DoubleArrayList getCachedValues()

  Returns an array list containing the values cached by this random stream.

  Returns:
    the array of cached values.

### setCachedValues

    public void setCachedValues(DoubleArrayList values)

  Sets the array list containing the cached values to `values`. This resets the cache index to the size of the given array.

  Parameters:
    `values` - the array list of cached values.
  Throws:
    `NullPointerException` - if `values` is `null`.

### resetStartStream

    public void resetStartStream()

  Description copied from interface: `RandomStream`
  Reinitializes the stream to its initial state Ig: Cg and Bg are set to Ig.

  Specified by:
    `resetStartStream` in interface `RandomStream`

### resetStartSubstream

    public void resetStartSubstream()

  Description copied from interface: `RandomStream`
  Reinitializes the stream to the beginning of its current substream: Cg is set to Bg.

  Specified by:
    `resetStartSubstream` in interface `RandomStream`

### resetNextSubstream

    public void resetNextSubstream()

  Description copied from interface: `RandomStream`
  Reinitializes the stream to the beginning of its next substream: Ng is computed, and Cg and Bg are set to Ng.

  Specified by:
    `resetNextSubstream` in interface `RandomStream`

### nextDouble

    public double nextDouble()

  Description copied from interface: `RandomStream`
  Returns a (pseudo)random number from the uniform distribution over the interval [0, 1), using this stream, after advancing its state by one step.

  Specified by:
    `nextDouble` in interface `RandomStream`
  Returns:
    the next generated uniform

### nextArrayOfDouble

    public void nextArrayOfDouble(double[] u,
                                  int start,
                                  int n)

  Description copied from interface: `RandomStream`
  Generates `n` (pseudo)random numbers from the uniform distribution and stores them into the array `u` starting at index `start`.

  Specified by:
    `nextArrayOfDouble` in interface `RandomStream`
  Parameters:
    `u` - array that will contain the generated uniforms
    `start` - starting index, in the array `u`, to write uniforms from
    `n` - number of uniforms to generate

### nextInt

    public int nextInt(int i,
                       int j)

  Description copied from interface: `RandomStream`
  Returns a (pseudo)random number from the discrete uniform distribution over the integers {i, i + 1,..., j}, using this stream. (Calls `nextDouble` once.)

  Specified by:
    `nextInt` in interface `RandomStream`
  Parameters:
    `i` - smallest integer that can be generated
    `j` - greatest integer that can be generated
  Returns:
    the generated integer

### nextArrayOfInt

    public void nextArrayOfInt(int i,
                               int j,
                               int[] u,
                               int start,
                               int n)

  Description copied from interface: `RandomStream`
  Generates `n` (pseudo)random numbers from the discrete uniform distribution over the integers {i, i + 1,..., j}, using this stream and stores the result in the array `u` starting at index `start`. (Calls `nextInt` `n` times.)

  Specified by:
    `nextArrayOfInt` in interface `RandomStream`
  Parameters:
    `i` - smallest integer that can be generated
    `j` - greatest integer that can be generated
    `u` - array that will contain the generated values
    `start` - starting index, in the array `u`, to write integers from
    `n` - number of values being generated

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.