/* *
 * Title:        

 * Description:  

 * Copyright:    Copyright (c) 

 * Company:      

 * @author
 * @version 1.0
 */

package umontreal.iro.lecuyer.rng;

/**
 * This interface defines the basic structures to handle multiple streams
 * of uniform (pseudo)random numbers and convenient
 * tools to move around within and across these streams.
 * The actual random number generators (RNGs) are provided in classes
 * that implement this RandomStream interface.
 * Each stream of random numbers is an object of the class that implements
 * this interface, and can be viewed as a virtual random number generator.
 * 
 * 

 * For each type of base RNG (i.e., each implementation of the 
 * RandomStream interface), the full period of the generator
 * is cut into adjacent streams (or segments) of length Z, 
 * and each of these streams is partitioned into V substreams
 * of length W, where Z = VW.
 * The values of V and W depend on the specific RNG, but are usually
 * larger than 250.
 * Thus, the distance Z between the starting points of two successive 
 * streams provided by an RNG usually exceeds 2100.
 * The initial seed of the RNG is the starting point of the first stream.  
 * It has a default value for each type of RNG,
 * but this initial value can be changed by calling setPackageSeed 
 * for the corresponding class.
 * Each time a new RandomStream is created, its starting point
 * (initial seed) is computed automatically,
 * Z steps ahead of the starting point of the previously created stream
 * of the same type, and its current state is set equal to this starting point.
 * 
 * 

 * For each stream, one can advance by one step and generate one value,
 * or go ahead to the beginning of the next substream within this stream, 
 * or go back to the beginning of the current substream, or to the beginning
 * of the stream, or jump ahead or back by an arbitrary number of steps.
 * Denote by Cg the current state of a stream g,
 * Ig its initial state, Bg the state at the beginning of the
 * current substream, and Ng the state at the beginning of the next substream.
 * 
 * The form of the state of a stream depends on its type.
 * For example, the state of a stream of class {@link MRG32k3a} is a vector
 * of six 32-bit integers represented internally as floating-point numbers
 * (in double).
 * 
 * 

 * The methods for manipulating the streams and generating random
 * numbers are implemented differently for each type of RNG.
 * The methods whose formal parameter types do not depend
 * on the RNG type are specified in the interface RandomStream.
 * The others (e.g., for setting the seeds) are given only in the
 * classes that implement the specific RNG types.
 * 
 * 

 * 
 * 

 * Methods for generating random variates from non-uniform distributions
 * are provided in the {@link umontreal.iro.lecuyer.randvar randvar} package.
 * 
 */
public interface RandomStream  { 


   /**
    * Reinitializes the stream to its initial state Ig:
    *    Cg and Bg are set to Ig.
    * 
    */
   public void resetStartStream();


   /**
    * Reinitializes the stream to the beginning of its current
    *    substream: Cg is set to Bg.
    * 
    */
   public void resetStartSubstream();


   /**
    * Reinitializes the stream to the beginning of its next
    *    substream: Ng is computed, and
    *    Cg and Bg are set to Ng.
    * 
    */
   public void resetNextSubstream();


   /**
    * Returns a string containing the current state of this stream.
    *   
    * @return the state of the generator formated as a string
    * 
    */
   public String toString();


   /**
    * 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.
    *   
    * @return the next generated uniform
    * 
    */
   public double nextDouble();


   /**
    * Generates n (pseudo)random numbers from the
    *    uniform distribution and stores them into the array u
    *    starting at index start.
    *   
    * @param u array that will contain the generated uniforms
    * 
    *    @param start starting index, in the array u, to write uniforms from
    * 
    *    @param n number of uniforms to generate
    * 
    * 
    */
   public void nextArrayOfDouble (double[] u, int start, int n);


   /**
    * Returns a (pseudo)random number from the discrete uniform 
    *    distribution over the integers 
    * {i, i + 1,..., j},
    *    using this stream.  (Calls nextDouble once.)
    *  
    * @param i smallest integer that can be generated
    * 
    *    @param j greatest integer that can be generated
    * 
    *    @return the generated integer
    * 
    */
   public int nextInt (int i, int j);


   /**
    * 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.)
    *   
    * @param i smallest integer that can be generated
    * 
    *    @param j greatest integer that can be generated
    * 
    *    @param u array that will contain the generated values
    * 
    *    @param start starting index, in the array u, to write integers from
    * 
    *    @param n number of values being generated
    * 
    * 
    */
   public void nextArrayOfInt (int i, int j, int[] u, int start, int n);
 
}