SSJ
V. 2.6.

umontreal.iro.lecuyer.rng
Class RandomStreamBase

java.lang.Object
  extended by umontreal.iro.lecuyer.rng.RandomStreamBase
All Implemented Interfaces:
Serializable, Cloneable, CloneableRandomStream, RandomStream
Direct Known Subclasses:
F2NL607, GenF2w32, LFSR113, LFSR258, MRG31k3p, MRG32k3a, MRG32k3aL, MT19937, RandRijndael, WELL1024, WELL512, WELL607

public abstract class RandomStreamBase
extends Object
implements CloneableRandomStream, Serializable

This class provides a convenient foundation on which RNGs can be built. It implements all the methods which do not depend directly on the generator itself, but only on its output, which is to be defined by implementing the abstract method nextValue. In the present class, all methods returning random numbers directly or indirectly (nextDouble, nextArrayOfDouble, nextInt and nextArrayOfInt) call nextValue. Thus, to define a subclass that implements a RNG, it suffices to implement nextValue, in addition to the reset... and toString methods. Of course, the other methods may also be overridden for improved efficiency.

If the nextValue already generates numbers with a precision of 53-bits or higher, then nextDouble can be overridden to improve the performance. The mechanism for increasing the precision assumes that nextValue returns at least 29 bits of precision, in which case the higher precision numbers will have roughly 52 bits of precision. This mechanism was designed primarily for RNGs that return numbers with around 30 to 32 bits of precision.

RandomStreamBase and its subclasses are implementing the Serializable interface. Each class has a serial number wich represent the class version. For instance 70510 means that the last change was the 10th May 2007.

See Also:
Serialized Form

Constructor Summary
RandomStreamBase()
           
 
Method Summary
 RandomStreamBase clone()
          Clones the current generator and return its copy.
 String formatState()
          Deprecated. 
 String formatStateFull()
          Deprecated. 
 void increasedPrecision(boolean incp)
          After calling this method with incp = true, each call to the RNG (direct or indirect) for this stream will return a uniform random number with more bits of precision than what is returned by nextValue, and will advance the state of the stream by 2 steps instead of 1 (i.e., nextValue will be called twice for each random number).
 void nextArrayOfDouble(double[] u, int start, int n)
          Calls nextDouble n times to fill the array u.
 void nextArrayOfInt(int i, int j, int[] u, int start, int n)
          Calls nextInt n times to fill the array u.
 double nextDouble()
          Returns a uniform random number between 0 and 1 from the stream.
 int nextInt(int i, int j)
          Calls nextDouble once to create one integer between i and j.
abstract  void resetNextSubstream()
          Reinitializes the stream to the beginning of its next substream: Ng is computed, and Cg and Bg are set to Ng.
abstract  void resetStartStream()
          Reinitializes the stream to its initial state Ig: Cg and Bg are set to Ig.
abstract  void resetStartSubstream()
          Reinitializes the stream to the beginning of its current substream: Cg is set to Bg.
abstract  String toString()
          Returns a string containing the current state of this stream.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RandomStreamBase

public RandomStreamBase()
Method Detail

resetStartStream

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

toString

public abstract String toString()
Description copied from interface: RandomStream
Returns a string containing the current state of this stream.

Specified by:
toString in interface RandomStream
Overrides:
toString in class Object
Returns:
the state of the generator formated as a string

increasedPrecision

public void increasedPrecision(boolean incp)
After calling this method with incp = true, each call to the RNG (direct or indirect) for this stream will return a uniform random number with more bits of precision than what is returned by nextValue, and will advance the state of the stream by 2 steps instead of 1 (i.e., nextValue will be called twice for each random number).

More precisely, if s is a stream of a subclass of RandomStreamBase, when the precision has been increased, the instruction ``u = s.nextDouble()'', is equivalent to ``u = (s.nextValue() + s.nextValue()*fact) % 1.0'' where the constant fact is equal to 2-24. This also applies when calling nextDouble indirectly (e.g., via nextInt, etc.). By default, or if this method is called again with incp = false, each call to nextDouble for this stream advances the state by 1 step and returns the same number as nextValue.

Parameters:
incp - if the generator will be set to high precision mode

nextDouble

public double nextDouble()
Returns a uniform random number between 0 and 1 from the stream. Its behavior depends on the last call to increasedPrecision. The generators programmed in SSJ never return the values 0 or 1.

Specified by:
nextDouble in interface RandomStream
Returns:
a number in the interval (0,1)

nextArrayOfDouble

public void nextArrayOfDouble(double[] u,
                              int start,
                              int n)
Calls nextDouble n times to fill the array u.

Specified by:
nextArrayOfDouble in interface RandomStream
Parameters:
u - the array in which the numbers will be stored
start - the first index of u to be used
n - the number of random numbers to put in u

nextInt

public int nextInt(int i,
                   int j)
Calls nextDouble once to create one integer between i and j. This method always uses the highest order bits of the random number. It should be overridden if a faster implementation exists for the specific generator.

Specified by:
nextInt in interface RandomStream
Parameters:
i - the smallest possible returned integer
j - the largest possible returned integer
Returns:
a random integer between i and j

nextArrayOfInt

public void nextArrayOfInt(int i,
                           int j,
                           int[] u,
                           int start,
                           int n)
Calls nextInt n times to fill the array u. This method should be overridden if a faster implementation exists for the specific generator.

Specified by:
nextArrayOfInt in interface RandomStream
Parameters:
i - the smallest possible integer to put in u
j - the largest possible integer to put in u
u - the array in which the numbers will be stored
start - the first index of u to be used
n - the number of random numbers to put in u

formatState

@Deprecated
public String formatState()
Deprecated. 

Use the toString method.


formatStateFull

@Deprecated
public String formatStateFull()
Deprecated. 


clone

public RandomStreamBase clone()
Clones the current generator and return its copy.

Specified by:
clone in interface CloneableRandomStream
Overrides:
clone in class Object
Returns:
A deep copy of the current generator

SSJ
V. 2.6.

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