sp_random.h

Go to the documentation of this file.
00001 /** @file  sp_random.h  Evaluating random variables */
00002 
00003 /* 
00004    FAU Discrete Event System Simulator 
00005 
00006    Copyright (C) 2007  Christoph Doerr
00007    Exclusive copyright is granted to Thomas Moor
00008 
00009 */
00010 
00011 #ifndef FAUDES_SP_RANDOM_H
00012 #define FAUDES_SP_RANDOM_H
00013 
00014 #include "tp_timeinterval.h"
00015 #include "sp_executor.h"
00016 
00017 
00018 namespace faudes {
00019 
00020 /** 
00021 
00022 @defgroup SimRandomVariables Random Variables
00023 
00024 @ingroup SimulatorPlugin 
00025 
00026 Sampling or evaluating random variables for simulation
00027 
00028 This module implements the evaluation (also known as sampling) of random 
00029 variables with various distributions. It specialises on restricted support
00030 PDFs, since this is required for the ProposingExecutor. 
00031 
00032 Random variables and their simulation is a highly involved topic and we give credit
00033 to the sources from which this module stems:
00034 
00035 1) 
00036 Implementation of a random number generator from Stave Park and Dave Geyer, which
00037 we use in original form up to minor cosmetic changes.
00038 
00039 2)  
00040 Inverse gaussian CDF by rational approxomation coefficients, presumably by Peter J, Acjlam,
00041 which we use in its original form up to minor cosmetic changes.
00042 
00043 
00044 3)
00045 Gaussian CDF by an aproximation that we found in "Handbook of Mathematical Functions" by
00046 Abromowitz and Stegun.
00047 
00048 All sources were available freely and we did not find any restricting licensing terms. 
00049 Thanks!
00050 
00051 
00052 ---------------------------------------------------------------------
00053 
00054 Regarding 1), from the header of rngs.c
00055  
00056 This is an ANSI C library for multi-stream random number generation.  
00057 The use of this library is recommended as a replacement for the ANSI C 
00058 rand() and srand() functions, particularly in simulation applications 
00059 where the statistical 'goodness' of the random number generator is 
00060 important.  The library supplies 256 streams of random numbers; use 
00061 SelectStream(s) to switch between streams indexed s = 0,1,...,255.
00062 
00063 The streams must be initialized.  The recommended way to do this is by
00064 using the function PlantSeeds(x) with the value of x used to initialize 
00065 the default stream and all other streams initialized automatically with
00066 values dependent on the value of x.  The following convention is used 
00067 to initialize the default stream: \n
00068 if x > 0 then x is the state \n
00069 if x < 0 then the state is obtained from the system clock \n
00070 if x = 0 then the state is to be supplied interactively. \n
00071 
00072 The generator used in this library is a so-called 'Lehmer random number
00073 generator' which returns a pseudo-random number uniformly distributed
00074 0.0 and 1.0.  The period is (m - 1) where m = 2,147,483,647 and the
00075 smallest and largest possible values are (1 / m) and 1 - (1 / m)
00076 respectively.  For more details see:
00077 
00078       "Random Number Generators: Good Ones Are Hard To Find"         \n
00079                   Steve Park and Keith Miller                        \n
00080              Communications of the ACM, October 1988                 \n
00081 
00082 Name            : rngs.c  (Random Number Generation - Multiple Streams) \n
00083 Authors         : Steve Park & Dave Geyer                               \n
00084 Language        : ANSI C                                                \n
00085 Latest Revision : 09-22-98
00086 
00087 ---------------------------------------------------------------------
00088 
00089 Regarding 2), from the header of rngs.c
00090 
00091 This function returns an approximation of the inverse cumulative
00092 standard normal distribution function.  I.e., given P, it returns
00093 an approximation to the X satisfying P = Pr{Z <= X} where Z is a
00094 random variable from the standard normal distribution.
00095  
00096 The algorithm uses a minimax approximation by rational functions
00097 and the result has a relative error whose absolute value is less
00098 than 1.15e-9.
00099 
00100 Author:      Peter J. Acklam                                   \n
00101 Time-stamp:  2002-06-09 18:45:44 +0200                         \n
00102 E-mail:      jacklam at math dot uio dor no                    \n
00103 WWW URL:     http www dot math dot uio dot no /~jacklam        \n
00104  
00105 C implementation adapted from Peter's Perl version             \n
00106 
00107 ---------------------------------------------------------------------
00108 
00109 Regarding 3), found as code example in Wikipedia
00110 
00111 ---------------------------------------------------------------------
00112 
00113 
00114 @{
00115 
00116 */
00117 
00118 
00119 
00120 
00121 /** 
00122  * Use this function to set the state of all the random number generator 
00123  * streams by "planting" a sequence of states (seeds), one per stream, 
00124  * with all states dictated by the state of the default stream. 
00125  * The sequence of planted states is separated one from the next by 
00126  * 8,367,782 calls to ran().
00127  */
00128 void ran_plant_seeds(long x);
00129 
00130 /**
00131  * Use this function to set the current random number generator
00132  * stream -- that stream from which the next random number will come.
00133  */
00134 void ran_select_stream(int index);
00135 
00136 /**
00137 * Put a seed 
00138 *   @param seed
00139 *      Random generator seed  
00140 */
00141 void ran_put_seed(long seed);
00142 
00143 /**
00144 * Initialize random generator 
00145 * @param seed
00146 *     Random generator seed
00147 */
00148 void ran_init(long seed);
00149 
00150 /**
00151 * Run random generator 
00152 * Random Number Generator 
00153 * (for more details see "Random Number Generators: Good Ones Are Hard To Find"
00154 *                   Steve Park and Keith Miller
00155 *              Communications of the ACM, October 1988)
00156 * @return
00157 *   Random value in [0,1) ( excluding 1 (?)) 
00158 */
00159 double ran(void);
00160 
00161 
00162 /**
00163 * Sample a random variable uniformly on interval [a;b)
00164 *    Distribution: f(t) dt= {1/(b-a)} dt  for t, a <=t< b, else 0
00165 * @param a
00166 *   Lower bound
00167 * @param b 
00168 *   Upper bound
00169 * @return 
00170 *   Random value
00171 */
00172 double ran_uniform(double a, double b);
00173 
00174 /**
00175 * Sample a discrete random variable uniformly on interval [a;b)
00176 *    Distribution: p(n) = 1/(b-a-1)
00177 * @param a
00178 *   Lower bound
00179 * @param b 
00180 *   Upper bound
00181 * @return 
00182 *   Random value
00183 */
00184 long ran_uniform_int(long a, long b);
00185 
00186 /**
00187 * Sample a random variable exponentially 
00188 *     Distribution: f(t) dt = 1/mu  exp(-t/mu) dt  for t>=0
00189 * @param mu
00190 *   mu
00191 * @return 
00192 *   Random variabe
00193 */
00194 double ran_exponential(double mu);
00195   
00196 /**
00197 * Sample a random variable exponentially on a restricted interval
00198 *     Distribution: f(t) dt = 1/mu  exp(-t/mu) dt  for t>=0
00199 * @param mu
00200 *   mu
00201 * @param tossLB
00202 *   Lower interval bound
00203 * @param tossUB
00204 *   Upper interval bound
00205 */
00206 double ran_exponential(double mu, tpTime::Type tossLB, tpTime::Type tossUB);
00207 
00208 /**
00209 * Sample a random variable gaussian distributed on a restricted interval
00210 *     Distribution: f(t)  = 1 / sqrt(2 pi sigma^2) * exp( -1/2 ((t-mu)/sigma)^2) for  t>=0
00211 * @param mu
00212 *   mu
00213 * @param sigma
00214 *   sigma
00215 * @param tossLB
00216 *   Lower interval bound
00217 * @param tossUB
00218 *   Upper interval bound
00219 */
00220 double ran_gauss(double mu, double sigma, tpTime::Type tossLB, tpTime::Type tossUB);
00221 
00222 /**
00223 * Help function: calculate gaussian CDF 
00224 * using an approximation from 
00225 * Abromowitz and Stegun: Handbook of Mathematical Functions 
00226 * @param x
00227 * @return CDF(x)
00228 */
00229 double ran_gaussian_cdf_P(double x);
00230 
00231 /** @} doxygen group */
00232 
00233 
00234 } // namespace
00235 
00236 
00237 #define FAUDES_STOCHRAN_H
00238 #endif

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen