RandomStreamWithCache (Java Libraries for Stochastic Simulation)

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

All Implemented Interfaces:

RandomStream
```
public class RandomStreamWithCache
extends java.lang.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

Constructors
Constructor and Description
`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

Methods
Modifier and Type	Method and Description
`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: N_g is computed, and C_g and B_g are set to N_g.
`void`	`resetStartStream()` Reinitializes the stream to its initial state I_g: C_g and B_g are set to I_g.
`void`	`resetStartSubstream()` Reinitializes the stream to the beginning of its current substream: C_g is set to B_g.
`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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.NullPointerException - if values is null.
  - resetStartStream
```
public void resetStartStream()
```
    Description copied from interface: RandomStream
    
    Reinitializes the stream to its initial state I_g: C_g and B_g are set to I_g.
    
    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: C_g is set to B_g.
    
    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: N_g is computed, and C_g and B_g are set to N_g.
    
    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. The generators programmed in SSJ never return the values 0 or 1.
    
    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

Class RandomStreamWithCache

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

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

Constructor Detail

RandomStreamWithCache

RandomStreamWithCache

Method Detail

isCaching

setCaching

getCachedStream

setCachedStream

clearCache

initCache

getNumCachedValues

getCacheIndex

setCacheIndex

getCachedValues

setCachedValues

resetStartStream

resetStartSubstream

resetNextSubstream

nextDouble

nextArrayOfDouble

nextInt

nextArrayOfInt