1 02/06/84  random_
  2 
  3 The random_ subroutine is a random number generator with entry points
  4 that, given an input seed, generate a pseudo-random variable with a
  5 uniform, exponential, or normal distribution.  The seed is an optional
  6 input argument; if it is not included in the call, an internal static
  7 variable is used and updated.
  8 
  9 
 10 There are two sets of entry points to the random_ subroutine.  For one
 11 set of entry points, each call produces a single random number.  To
 12 obtain a sequence of random numbers with the desired distribution,
 13 repeated calls are made, each time using the value of the seed,
 14 returned from a call, as the input value of the seed for the next call
 15 in the sequence.
 16 
 17 The second set of entry points returns an array with a sequence of
 18 random numbers.  The first element of the array is generated from the
 19 input seed.  The returned value of the seed is used to generate the
 20 next random number of the sequence.  The modification of the input seed
 21 value occurs once for each element in the array.  The programmer can
 22 obtain the same result by making one call to an array entry point
 23 having N elements or by making N calls to the corresponding single
 24 random number entry point.
 25 
 26 
 27 In addition, for the uniform and normal distributions, there are entry
 28 points that produce the negative random variables, either singly or as
 29 a sequence.  For any given seed, the random variable produced is
 30 negatively correlated with that produced at the corresponding entry
 31 point.
 32 
 33 
 34 Entry points in random_:
 35    (List is generated by the help command)
 36 
 37 
 38 :Entry:  exponential:  02/06/84 random_$exponential
 39 
 40 
 41 Function: generates a positive random number.  The sequence of random
 42 numbers has an exponential distribution with a mean of 1.  The random
 43 number is generated by taking successive random numbers from the
 44 uniformly distributed sequence and applying the Von Neumann method for
 45 generating an exponentially distributed random variable.
 46 
 47 
 48 Syntax:
 49 declare random_$exponential entry (float bin(27));
 50 call random_$exponential (random_no);
 51 
 52 -or-
 53 
 54 declare random_$exponential entry (fixed bin(35), float bin(27));
 55 call random_$exponential (seed, random_no);
 56 
 57 
 58 Arguments:
 59 seed
 60    is the optional seed.  (Input/Output)
 61    Input
 62       must be a nonzero positive integer; used to generate the random
 63       number.
 64    Output
 65       is the new value (modification of input value); used to generate
 66       the next random number of the sequence.
 67 random_no
 68    is the random number that is generated.  (Output)
 69 
 70 
 71 :Entry:  exponential_seq:  02/06/84 random_$exponential_seq
 72 
 73 
 74 Function: produces an array of exponentially distributed random
 75 variables.
 76 
 77 
 78 Syntax:
 79 declare random_$exponential_seq entry ((*) float bin(27), fixed bin);
 80 call random_$exponential_seq (array, array_size);
 81 
 82 -or-
 83 
 84 declare random_$exponential_seq entry (fixed bin(35),
 85       (*) float bin(27), fixed bin);
 86 call random_$exponential_seq (seed, array, array_size);
 87 
 88 
 89 Arguments:
 90 seed
 91    is the optional seed.  (Input/Output)
 92    Input
 93       must be a nonzero positive integer; used to generate the random
 94       number.
 95    Output
 96       is the new value (modification of input value); used to generate
 97       the next random number of the sequence.
 98 array (N)
 99    is the array of generated random numbers where N is greater than or
100    equal to array_size.  (Output)
101 array_size
102    is the number of values returned in the array.  (Input)
103 
104 
105 :Entry:  get_seed:  02/06/84 random_$get_seed
106 
107 
108 Function: is used to obtain the current value of the internal seed.
109 
110 
111 Syntax:
112 declare random_$get_seed entry (fixed bin(35));
113 call random_$get_seed (seed_value);
114 
115 
116 Arguments:
117 seed_value
118    is the current value of the internal seed.  (Output)
119 
120 
121 :Entry:  normal:  02/06/84 random_$normal
122 
123 
124 Function: generates a random number greater than -6.0 and less than
125 6.0.  The sequence of random numbers has an approximately normal
126 distribution with a mean of 0 and a variance of 1.  The random number
127 is formed by taking the sum of 12 successive random numbers from the
128 uniformly distributed sequence and then adjusting the sum for a mean
129 of 0 by subtracting 6.0.
130 
131 
132 Syntax:
133 declare random_$normal entry (float bin(27));
134 call random_$normal (random_no);
135 
136 -or-
137 
138 declare random_$normal entry (fixed bin(35), float bin(27));
139 call random_$normal (seed, random_no);
140 
141 
142 Arguments:
143 seed
144    is the optional seed.  (Input/Output)
145    Input
146       must be a nonzero positive integer; used to generate the random
147       number.
148    Output
149       is the new value (modification of input value); used to generate
150       the next random number of the sequence.
151 random_no
152    is the random number that is generated.  (Output)
153 
154 
155 :Entry:  normal_ant:  02/06/84 random_$normal_ant
156 
157 
158 Function: generates a random number that is negatively correlated with
159 the random_no argument produced by the random_$normal entry point.
160 For any particular value of the seed:
161 
162         (random_ant + random_no) = 0.0
163 
164 
165 Syntax:
166 declare random_$normal_ant entry (float bin(27));
167 call random_$normal_ant (random_ant);
168 
169 -or-
170 
171 declare random_$normal_ant entry (fixed bin(35), float bin(27));
172 call random_$normal_ant (seed, random_ant);
173 
174 
175 Arguments:
176 seed
177    is the optional seed.  (Input/Output)
178    Input
179       must be a nonzero positive integer; used to generate the random
180       number.
181    Output
182       is the new value (modification of input value); used to generate
183       the next random number of the sequence.
184 random_ant
185    is the random number that is generated.  (Output)
186 
187 
188 :Entry:  normal_ant_seq:  02/06/84 random_$normal_ant_seq
189 
190 
191 Function: generates a sequence of array_size, of random variables with
192 approximately normal distribution.  The sequence contains the number
193 of values specified in the array_size argument.  These variables are
194 negatively correlated with those produced by the random_$normal_seq
195 entry point.
196 
197 
198 Syntax:
199 declare random_$normal_ant_seq entry ((*) float bin(27), fixed bin);
200 call random_$normal_ant_seq (ant_array, array_size);
201 
202 -or-
203 
204 declare random_$normal_ant_seq entry (fixed bin(35), (*) float bin(27),
205      fixed bin);
206 call random_$normal_ant_seq (seed, ant_array, array_size);
207 
208 
209 Arguments:
210 seed
211    is the optional seed.  (Input/Output)
212    Input
213       must be a nonzero positive integer; used to generate the random
214       number.
215    Output
216       is the new value (modification of input value); used to generate
217       the next random number of the sequence.
218 ant_array (N)
219    is the array of generated random numbers where N is greater than or
220    equal to array_size.  (Output)
221 array_size
222    is the number of values returned in ant_array.  (Input)
223 
224 
225 :Entry:  normal_seq:  02/06/84 random_$normal_seq
226 
227 
228 Function: generates a sequence of random variables with an
229 approximately normal distribution.  The sequence contains the number
230 of values specified in the array_size argument.
231 
232 
233 Syntax:
234 declare random_$normal_seq entry ((*) float bin(27), fixed bin);
235 call random_$normal_seq (array, array_size);
236 
237 -or-
238 
239 declare random_$normal_seq entry (fixed bin(35), (*) float bin(27),
240      fixed bin);
241 call random_$normal_seq (seed, array, array_size);
242 
243 
244 Arguments:
245 seed
246    is the optional seed.  (Input/Output)
247    Input
248       must be a nonzero positive integer; used to generate the random
249       number.
250    Output
251       is the new value (modification of input value); used to generate
252       the next random number of the sequence.
253 array (N)
254    is an array of the generated random numbers where N is greater than
255    or equal to array_size.  (Output)
256 array_size
257    specifies the number of random variables to be returned in array.
258    (Input)
259 
260 
261 :Entry:  set_seed:  02/06/84 random_$set_seed
262 
263 
264 Function: sets the value of the internal seed.  This internal seed is
265 used as the seed for the next call to any random_ entry point in which
266 the optional argument, seed, is not provided.
267 
268 
269 Syntax:
270 declare random_$set_seed entry (fixed bin(35));
271 call random_$set_seed (seed_value);
272 
273 
274 Arguments:
275 seed_value
276    is the value to which the internal seed is set.  (Input) This value
277    must be a nonzero positive integer.
278 
279 
280 :Entry:  uniform:  02/06/84 random_$uniform
281 
282 
283 Function: generates a random number with a value between 0.0 and 1.0.
284 The sequence of random numbers has a uniform distribution on the
285 interval 0 to 1.
286 
287 
288 Syntax:
289 declare random_$uniform entry (float bin(27));
290 call random_$uniform (random_no);
291 
292 -or-
293 
294 declare random_$uniform entry (fixed bin(35), float bin(27));
295 call random_$uniform (seed, random_no);
296 
297 
298 Arguments:
299 seed
300    is the optional seed.  (Input/Output)
301    Input
302       must be a nonzero positive integer; used to generate the random
303       number.
304    Output
305       is the new value (modification of input value); used to generate
306       the next random number of the sequence.
307 random_no
308    is the random number that is generated.  (Output)
309 
310 
311 :Entry:  uniform_ant:  02/06/84 random_$uniform_ant
312 
313 
314 Function: generates a uniformly distributed random number that is
315 negatively correlated with the random_no produced by the
316 random_$uniform entry point.  For any particular value of the seed:
317 
318         (random_ant + random_no) = 1.0
319 
320 
321 Syntax:
322 declare random_$uniform_ant entry (float bin(27));
323 call random_$uniform_ant (random_ant);
324 
325 -or-
326 
327 declare random_$uniform_ant entry (fixed bin(35), float bin(27));
328 call random_$uniform_ant (seed, random_ant);
329 
330 
331 Arguments:
332 seed
333    is the optional seed.  (Input/Output)
334    Input
335       must be a nonzero positive integer; used to generate the random
336       number.
337    Output
338       is the new value (modification of input value); used to generate
339       the next random number of the sequence.
340 random_ant
341    is the random number that is generated.  (Output)
342 
343 
344 :Entry:  uniform_ant_seq:  02/06/84 random_$uniform_ant_seq
345 
346 
347 Function: returns an array of uniformly distributed random numbers
348 that are negatively correlated with the array produced by the
349 random_$uniform_seq entry point.  For any particular value of the
350 seed:
351         (ant_array(i) + array(i)) = 1.0
352 
353 where the range of values for i is from 1 to array_size.
354 
355 
356 Syntax:
357 declare random_$uniform_ant_seq entry ((*) float bin(27), fixed bin);
358 call random_$uniform_ant_seq (ant_array, array_size);
359 
360 -or-
361 
362 declare random_$uniform_ant_seq entry (fixed bin(35),
363      (*) float bin(27), fixed bin);
364 call random_$uniform_ant_seq (seed, ant_array, array_size);
365 
366 
367 Arguments:
368 seed
369    is the optional seed.  (Input/Output)
370    Input
371       must be a nonzero positive integer; used to generate the random
372       number.
373    Output
374       is the new value (modification of input value); used to generate
375       the next random number of the sequence.
376 ant_array
377    is the array of generated random numbers where N is greater than or
378    equal to array_size.  (Output)
379 array_size
380    is the number of values returned in ant_array.  (Input)
381 
382 
383 :Entry:  uniform_seq:  02/06/84 random_$uniform_seq
384 
385 
386 Function: returns an array of random numbers from the uniform
387 sequence.
388 
389 
390 Syntax:
391 declare random_$uniform_seq entry ((*) float bin(27), fixed bin);
392 call random_$uniform_seq (array, array_size);
393 
394 -or-
395 
396 declare random_$uniform_seq entry (fixed bin(35), (*) float bin(27),
397      fixed bin);
398 call random_$uniform_seq (seed, array, array_size);
399 
400 
401 Arguments:
402 seed
403    is the optional seed. (Input/Output)
404    Input
405       must be a nonzero positive integer; used to generate the first
406       random number in the array.
407    Output
408       is the new value (modification of input value); used to generate
409       the next random number of the sequence; the modification of the
410       input value occurs array_size times.
411 array (N)
412    is an array of the generated random numbers where N is greater than
413    or equal to array_size.  (Output)
414 array_size
415    specifies the number of random variables to be returned in array.
416    (Input)
417