sp_random.h
Go to the documentation of this file.
1 /** @file sp_random.h Evaluating random variables */
2 
3 /*
4  FAU Discrete Event System Simulator
5 
6  Copyright (C) 2007 Christoph Doerr
7  Exclusive copyright is granted to Thomas Moor
8 
9 */
10 
11 #ifndef FAUDES_SP_RANDOM_H
12 #define FAUDES_SP_RANDOM_H
13 
14 #include "tp_timeinterval.h"
15 #include "sp_executor.h"
16 
17 
18 namespace faudes {
19 
20 /**
21 
22 @defgroup SimRandomVariables Random Variables
23 
24 @ingroup SimulatorPlugin
25 
26 Sampling or evaluating random variables for simulation
27 
28 This module implements the evaluation (also known as sampling) of random
29 variables with various distributions. It specialises on restricted support
30 PDFs, since this is required for the ProposingExecutor.
31 
32 Random variables and their simulation is a highly involved topic and we give credit
33 to the sources from which this module stems:
34 
35 1)
36 Implementation of a random number generator from Stave Park and Dave Geyer, which
37 we use in original form up to minor cosmetic changes.
38 
39 2)
40 Inverse gaussian CDF by rational approxomation coefficients, presumably by Peter J, Acjlam,
41 which we use in its original form up to minor cosmetic changes.
42 
43 
44 3)
45 Gaussian CDF by an aproximation that we found in "Handbook of Mathematical Functions" by
46 Abromowitz and Stegun.
47 
48 All sources were available freely and we did not find any restricting licensing terms.
49 Thanks!
50 
51 
52 ---------------------------------------------------------------------
53 
54 Regarding 1), from the header of rngs.c
55 
56 This is an ANSI C library for multi-stream random number generation.
57 The use of this library is recommended as a replacement for the ANSI C
58 rand() and srand() functions, particularly in simulation applications
59 where the statistical 'goodness' of the random number generator is
60 important. The library supplies 256 streams of random numbers; use
61 SelectStream(s) to switch between streams indexed s = 0,1,...,255.
62 
63 The streams must be initialized. The recommended way to do this is by
64 using the function PlantSeeds(x) with the value of x used to initialize
65 the default stream and all other streams initialized automatically with
66 values dependent on the value of x. The following convention is used
67 to initialize the default stream: \n
68 if x > 0 then x is the state \n
69 if x < 0 then the state is obtained from the system clock \n
70 if x = 0 then the state is to be supplied interactively. \n
71 
72 The generator used in this library is a so-called 'Lehmer random number
73 generator' which returns a pseudo-random number uniformly distributed
74 0.0 and 1.0. The period is (m - 1) where m = 2,147,483,647 and the
75 smallest and largest possible values are (1 / m) and 1 - (1 / m)
76 respectively. For more details see:
77 
78  "Random Number Generators: Good Ones Are Hard To Find" \n
79  Steve Park and Keith Miller \n
80  Communications of the ACM, October 1988 \n
81 
82 Name : rngs.c (Random Number Generation - Multiple Streams) \n
83 Authors : Steve Park & Dave Geyer \n
84 Language : ANSI C \n
85 Latest Revision : 09-22-98
86 
87 ---------------------------------------------------------------------
88 
89 Regarding 2), from the header of rngs.c
90 
91 This function returns an approximation of the inverse cumulative
92 standard normal distribution function. I.e., given P, it returns
93 an approximation to the X satisfying P = Pr{Z <= X} where Z is a
94 random variable from the standard normal distribution.
95 
96 The algorithm uses a minimax approximation by rational functions
97 and the result has a relative error whose absolute value is less
98 than 1.15e-9.
99 
100 Author: Peter J. Acklam \n
101 Time-stamp: 2002-06-09 18:45:44 +0200 \n
102 E-mail: jacklam at math dot uio dor no \n
103 WWW URL: http www dot math dot uio dot no /~jacklam \n
104 
105 C implementation adapted from Peter's Perl version \n
106 
107 ---------------------------------------------------------------------
108 
109 Regarding 3) found as code example in Wikipedia
110 
111 ---------------------------------------------------------------------
112 
113 {@
114 
115 */
116 
117 /**
118  * Use this function to set the state of all the random number generator
119  * streams by "planting" a sequence of states (seeds), one per stream,
120  * with all states dictated by the state of the default stream.
121  * The sequence of planted states is separated one from the next by
122  * 8,367,782 calls to ran().
123  */
124 void ran_plant_seeds(long x);
125 
126 /**
127  * Use this function to set the current random number generator
128  * stream -- that stream from which the next random number will come.
129  */
130 void ran_select_stream(int index);
131 
132 /**
133 * Put a seed
134 * @param seed
135 * Random generator seed
136 */
137 void ran_put_seed(long seed);
138 
139 /**
140 * Initialize random generator
141 * @param seed
142 * Random generator seed
143 */
144 void ran_init(long seed);
145 
146 /**
147 * Run random generator
148 * Random Number Generator
149 * (for more details see "Random Number Generators: Good Ones Are Hard To Find"
150 * Steve Park and Keith Miller
151 * Communications of the ACM, October 1988)
152 * @return
153 * Random value in [0,1) ( excluding 1 (?))
154 */
155 double ran(void);
156 
157 
158 /**
159 * Sample a random variable uniformly on interval [a;b)
160 * Distribution: f(t) dt= {1/(b-a)} dt for t, a <=t< b, else 0
161 * @param a
162 * Lower bound
163 * @param b
164 * Upper bound
165 * @return
166 * Random value
167 */
168 double ran_uniform(double a, double b);
169 
170 /**
171 * Sample a discrete random variable uniformly on interval [a;b)
172 * Distribution: p(n) = 1/(b-a-1)
173 * @param a
174 * Lower bound
175 * @param b
176 * Upper bound
177 * @return
178 * Random value
179 */
180 long ran_uniform_int(long a, long b);
181 
182 /**
183 * Sample a random variable exponentially
184 * Distribution: f(t) dt = 1/mu exp(-t/mu) dt for t>=0
185 * @param mu
186 * mu
187 * @return
188 * Random variabe
189 */
190 double ran_exponential(double mu);
191 
192 /**
193 * Sample a random variable exponentially on a restricted interval
194 * Distribution: f(t) dt = 1/mu exp(-t/mu) dt for t>=0
195 * @param mu
196 * mu
197 * @param tossLB
198 * Lower interval bound
199 * @param tossUB
200 * Upper interval bound
201 */
202 double ran_exponential(double mu, Time::Type tossLB, Time::Type tossUB);
203 
204 /**
205 * Sample a random variable gaussian distributed on a restricted interval
206 * Distribution: f(t) = 1 / sqrt(2 pi sigma^2) * exp( -1/2 ((t-mu)/sigma)^2) for t>=0
207 * @param mu
208 * mu
209 * @param sigma
210 * sigma
211 * @param tossLB
212 * Lower interval bound
213 * @param tossUB
214 * Upper interval bound
215 */
216 double ran_gauss(double mu, double sigma, Time::Type tossLB, Time::Type tossUB);
217 
218 /**
219 * Help function: calculate gaussian CDF
220 * using an approximation from
221 * Abromowitz and Stegun: Handbook of Mathematical Functions
222 * @param x
223 * @return CDF(x)
224 */
225 double ran_gaussian_cdf_P(double x);
226 
227 /** @} doxygen group */
228 
229 
230 } // namespace
231 
232 
233 #define FAUDES_STOCHRAN_H
234 #endif
Int Type
Datatype for point on time axis.
libFAUDES resides within the namespace faudes.
double ran_gauss(double mu, double sigma, Time::Type tossLB, Time::Type tossUB)
Sample a random variable gaussian distributed on a restricted interval Distribution: f(t) = 1 / sqrt(...
Definition: sp_random.cpp:132
long ran_uniform_int(long a, long b)
Sample a discrete random variable uniformly on interval [a;b) Distribution: p(n) = 1/(b-a-1)
Definition: sp_random.cpp:98
void ran_put_seed(long seed)
Put a seed.
Definition: sp_random.cpp:55
double ran_exponential(double mu)
Sample a random variable exponentially Distribution: f(t) dt = 1/mu exp(-t/mu) dt for t>=0.
Definition: sp_random.cpp:107
void ran_plant_seeds(long x)
Use this function to set the state of all the random number generator streams by "planting" a sequenc...
Definition: sp_random.cpp:35
void ran_select_stream(int index)
Use this function to set the current random number generator stream – that stream from which the next...
Definition: sp_random.cpp:60
void ran_init(long seed)
Initialize random generator.
Definition: sp_random.cpp:67
double ran(void)
Run random generator Random Number Generator (for more details see "Random Number Generators: Good On...
Definition: sp_random.cpp:75
double ran_gaussian_cdf_P(double x)
Help function: calculate gaussian CDF using an approximation from Abromowitz and Stegun: Handbook of ...
Definition: sp_random.cpp:224
double ran_uniform(double a, double b)
Sample a random variable uniformly on interval [a;b) Distribution: f(t) dt= {1/(b-a)} dt for t,...
Definition: sp_random.cpp:91
Execute transitions in a timed generator
Class TimeInterval.

libFAUDES 2.31h --- 2024.01.29 --- c++ api documentaion by doxygen