## "Fossies" - the Fresh Open Source Software Archive ### Member "ccmath-2.2.1/manual/C07-simu" (26 Sep 2000, 12792 Bytes) of package /linux/misc/old/ccmath-2.2.1.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

```    1                                Chapter 7
2
3                            SIMULATION SUPPORT
4
5                                 Summary
6
7                The functions in the simulation segment of the
8                library provide support for Monte Carlo
9                simulation analysis of physical systems in the
10                following areas:
11
12                     o Generation of Pseudorandom Numbers
13                     o Random Sampling and Shuffling
14                     o Simulation Output Analysis
15
16                Several types of pseudorandom generator are
17                supplied for both the uniform and normal
18                distributions. Analysis tools compute histograms
19                and serial autocorrelations.
20
21 -------------------------------------------------------------------------------
22
23  Notes on Contents
24
25      This library segment supports Monte Carlo simulation and the associated
26  statistical analysis.
27
28  o Generation of Pseudorandom Numbers:
29
30     lran1  -------- generate pseudorandom integers, with
31                     0 <= n < 2^32, using a one generator
32                     shuffle. (The preferred method with
33                     effectively unlimited period.)
34     lrand  -------- generate pseudorandom integers, with
35                     0 < n < 2^31 - 1 . (Retained because it
36                     is used on many mainframe computers.)
37     bran  --------- generate a random integer in the range
38                     0 <= m < N , with specified N, using a
39                     one generator shuffle.
40     bran2  -------- generate a random integer in the range
41                     0 <= m < N , with specified N, using a
42                     two generator shuffle.
43     unfl  --------- generate pseudorandom numbers uniformly
44                     distributed on [0,1], using a one generator
45                     shuffle.
46     unfl2 --------- uniform pseudorandom generator with a
47                     two generator shuffle with effectively
48                     unlimited period.
49     nrml  --------- generate pseudorandom numbers with a
50                     standard normal distribution, using a
51                     one generator shuffle generator. (The
52                     fastest normal generator.)
53     norm  --------- generate pairs of pseudorandom standard
54                     normals, using a one generator shuffle.
55     norm2  -------- generate pairs  of pseudorandom standard
56                     normals using a two generator shuffle.
57
58
59  o Random Sampling and Shuffling:
60
61     sampl  ------- select a random sample of specified size
62                    from a set of N objects.
63     shuffl  ------ perform a random shuffle of an array of data
64                    pointers.
65
66      Random sampling and random shuffling of a set are supported by a function
67  that produces random integers in the range 0 <= r < m, for a specified value
68  of m. Both of these algorithms operate on input pointer arrays, so that the
69  data records sampled or shuffled may be specified externally.
70
71  o Statistical Analysis Tools:
72
73     hist  -------- compile a histogram of the values of an
74                    input series.
75     autcor  ------ compute the autocorrelation coefficients of
76                    a series.
77
78      The compilation of simulation statistics is supported by a histogram
79  function. In addition, a second utility performs direct computation of serial
80  correlation coefficients. These correlations play an important role in tests
81  of analytic model residuals.
82
83 -------------------------------------------------------------------------------
84
85  General Technical Comments
86
87      Generators based on shuffling the output of one congruential generator
88  using the output of a second independent generator, with period relatively
89  prime to that of the first generator, (bran2, norm2 and unfl2) have an
90  effectively unlimited period. This form is well suited to multidimensional
91  Monte Carlo computations. The single shuffle generators are much faster
92  and also have very long or unlimited periods. Both forms are designed to
93  avoid the lattice structures observed in some congruential generators.
94
95 -------------------------------------------------------------------------------
96                            FUNCTION SYNOPSES
97 -------------------------------------------------------------------------------
98
99      Pseudorandom Generators:
100 -------------------------------------------------------------------------------
101
102 lran1
103
104      Generate pseudorandom unsigned int integers in the range
105      0 =< r <= 2^32 -1.
106
107      unsigned int lran1()
108       return value: r = random long integer
109
110      This generator is initialized by setlran1.
111
112      void setlran1(unsigned int s)
113        s = initializing seed for the generator.
114
115      The generator uses a congruential method and shuffles its
116      output to obtain an effectively unlimited period. It is the
117      recommended integer generator.
118
119      --------------------------------------------------------------
120
121 lrand
122
123      Generate pseudorandom long integers in the range 0 < r < 2^31 - 1.
124
125      long lrand()
126       return value: r = random long integer ( r > 0 )
127
128      This generator is initialized by setlrand.
129
130      void setlrand(unsigned int s)
131        s = initializing seed for the generator (0 < s < 2^31 -1)
132
133
134      The generator is a simple multiplicative congruential one with
135      period 2^31 - 1. It is retained for use when replication of
136      the output produced on an mainframe using this standard IBM
137      GGL algorithm is desired.
138
139      -----------------------------------------------------------------
140
141 bran
142
143      Generate a random integer in the range 0 =< r < n.
144
145      int bran(int n)
146        n = integer defining range of return (n > 0)
147       return value: r = random integer (0 <= r < n)
148
149      The function setbran initializes the generator.
150
151      void setbran(unsigned int s)
152        s = initializing seed for the generator
153
154      The generator combines a congruential generator with a
155      buffer shuffle that yields an effectively unlimited period.
156
157      -------------------------------------------------------------
158
159 bran2
160
161      Generate a random integer in the range 0 <= r < n.
162
163      int bran2(n)
164      int n;
165        n = integer defining range of return (n > 0)
166       return value: r = random integer (0 <= r < n)
167
168      The function setbran2 initializes the generator.
169
170      void setbran2(s)
171      unsigned int s;
172        s = initializing seed for the generator
173
174      The generator combines two congruential generators with a
175      buffer shuffle to produce an effectively unlimited period.
176
177      ------------------------------------------------------------
178
179 unfl
180
181      Generate pseudorandom numbers uniformly distributed on [0,1].
182
183      double unfl()
184       return value: u = variate uniformly distributed on [0,1]
185
186
187      The unfl generator is initialized by calling setunfl.
188
189
190      void setunfl(s)
191      unsigned int s;
192        s = initializing seed for the generator
193
194      The generator combines a congruential generator with a
195      buffer shuffle that yields an effectively unlimited period.
196
197      ----------------------------------------------------------------
198
199 unfl2
200
201      Generate pseudorandom numbers uniformly distributed on [0,1].
202
203      double unfl2()
204       return value: u = variate uniformly distributed on [0,1]
205
206
207      The unfl2 generator is initialized by calling setunfl2.
208
209
210      void setunfl2(unsigned int s)
211
212        s = initializing seed for the generator
213
214      The generator combines two congruential generators with a
215      buffer shuffle to produce an effectively unlimited period.
216
217      ------------------------------------------------------------
218
219 nrml
220
221      Generate normally distributed pseudorandom numbers.
222
223      double nrml()
224       return value: e = normally distributed variate (zero mean
225                         and unit variance)
226
227      Initialize the nrml generator by calling setnrml.
228
229      void setnrml(unsigned int s)
230        s = initializing seed for the generator
231
232
233      The generator combines a congruential generator with a
234      buffer shuffle that yields an effectively unlimited period.
235
236      --------------------------------------------------------------
237
238  norm
239
240      Generate q pair of pseudorandom normals with zero mean and unit
241      variance.
242
243      void norm(double *err)
244        err = pointer to an array for output of an independent
245              pair of normally distributed pseudorandom numbers
246                (output has zero mean and unit variance)
247
248      The norm generator is initialized by setnorm.
249
250      void setnorm(unsigned int s)
251        s = initializing seed for the generator
252
253
254      This function combines a congruential method with a buffer
255      shuffle to generate a pair of random uniform values. The
256      The polar rejection method is used to obtain a pair of
257      standard normal values. This is an analytically "exact" method.
258
259      -----------------------------------------------------------------
260
261 norm2
262
263      Generate q pair of pseudorandom normals with zero mean and unit
264      variance.
265
266      void norm2(double *err)
267        err = pointer to array for output of an independent
268              pair of normally distributed pseudorandom numbers
269                (zero mean and unit variance)
270
271      The norm generator is initialized by setnorm2.
272
273      void setnorm2(unsigned int s)
274        s = initializing seed for the generator
275
276      The generator combines two congruential generators with a
277      buffer shuffle to produce an effectively unlimited period.
278
279
280 -------------------------------------------------------------------------------
281
282  Sampling and Shuffling:
283 -------------------------------------------------------------------------------
284
285 sampl
286
287      Select a random sample of size m from n objects.
288
289      void sampl(void **s,int m,void **d,int n)
290       s = pointer to array of array of sample pointers (dimension m)
291            (loaded with a random sample of m pointers from d at exit)
292       d = pointer to an array of n data pointers
293       n = size of data base
294       m = size of requested sample
295
296
297      The sampling function calls bran, so it is essential to
298      initialize this generator with setbran, prior to use of
299      sampl. (see bran above) The pointers in d and s are
300      declared as generic (char *) to support sampling any
301      type of data record via pointers.
302
303      ---------------------------------------------------------------
304
305 shuffl
306
307      Perform a random shuffle of an array of data pointers.
308
309      void shuffl(void **s,int n)
310        s = pointer to an array of pointers to data records
311            (output s contains a random permutation of the
312             input pointers)
313        n = dimension of array s
314
315
316      This function calls bran, thus, it requires a call
317      to setbran prior to use. (see bran above)
318
319 -------------------------------------------------------------------------------
320
321  Statistical Analysis Tools:
322 -------------------------------------------------------------------------------
323
324 autcor
325
326      Compute the autocorrelation coefficients of a series.
327
328      double *autcor(double *x,int n,int mlag)
329        x = pointer to array containing the input series
330        n = length of input series (dimension of x-array)
331        mlag = maximum lag (autocorrelations are computed up to mlag)
332       return value: pa = pointer to array allocated for storing
333                          autocorrelation coefficients, with:
334                          *pa = sum of squares over the series
335                                 (normalizer for autocorrelations)
336                          *(pa+k) = autocorrelation at lag k,
337                                     k=1,2, -- ,mlag
338
339
340         The autocorrelations are defined by
341
342           c[k] = { Sum(i=0 to n-k-1) x[i]*x[i+k] }/< x^2 >  with
343
344           < x^2 > = Sum(i=0 to n-1) x[i]^2 .
345
346         The storage allocated by autcor is released by calling free(pa).
347
348      --------------------------------------------------------------------
349
350 hist
351
352      Compile a histogram of the values of an input series.
353
354      int *hist(double *x,int n,double xmin,double xmax, \
355                int kbin,double *bin)
356        x = pointer to array containing input series
357        n = size of input series
358        xmin = lower limit of histogram interval
359        xmax = upper limit of histogram interval
360        kbin = number of histogram intervals
361        bin = pointer to store for computed bin size
362                (*bin=(xmax-xmin)/kbin)
363       return value: ph = pointer to storage allocated for
364                          histogram, with:
365                          *(p-1) = number of values < xmin
366                          *(p+kbin) = number of values >xmax
367                          *(p+k) = number of values in kth bin,
368                                    k=0,1, --- ,kbin-1
369
370
371         The storage allocated by hist is released by calling free(ph-1).
```