umontreal.iro.lecuyer.rng.RandomStream Maven / Gradle / Ivy
Show all versions of ssj Show documentation
/*
* Class: RandomStream
* Description: basic structures to handle multiple streams of uniform
(pseudo)-random numbers and tools to move around within
and across these streams
* Environment: Java
* Software: SSJ
* Copyright (C) 2001 Pierre L'Ecuyer and Université de Montréal
* Organization: DIRO, Université de Montréal
* @author Pierre L'Ecuyer
* @since 2000
* SSJ is free software: you can redistribute it and/or modify it under
* the terms of the GNU General Public License (GPL) as published by the
* Free Software Foundation, either version 3 of the License, or
* any later version.
* SSJ is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* A copy of the GNU General Public License is available at
GPL licence site.
*/
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);
}