02/06/84  random_

The random_ subroutine is a random number generator with entry points
that, given an input seed, generate a pseudo-random variable with a
uniform, exponential, or normal distribution.  The seed is an optional
input argument; if it is not included in the call, an internal static
variable is used and updated.


There are two sets of entry points to the random_ subroutine.  For one
set of entry points, each call produces a single random number.  To
obtain a sequence of random numbers with the desired distribution,
repeated calls are made, each time using the value of the seed,
returned from a call, as the input value of the seed for the next call
in the sequence.

The second set of entry points returns an array with a sequence of
random numbers.  The first element of the array is generated from the
input seed.  The returned value of the seed is used to generate the
next random number of the sequence.  The modification of the input seed
value occurs once for each element in the array.  The programmer can
obtain the same result by making one call to an array entry point
having N elements or by making N calls to the corresponding single
random number entry point.


In addition, for the uniform and normal distributions, there are entry
points that produce the negative random variables, either singly or as
a sequence.  For any given seed, the random variable produced is
negatively correlated with that produced at the corresponding entry
point.


Entry points in random_:
   (List is generated by the help command)


:Entry:  exponential:  02/06/84 random_$exponential


Function: generates a positive random number.  The sequence of random
numbers has an exponential distribution with a mean of 1.  The random
number is generated by taking successive random numbers from the
uniformly distributed sequence and applying the Von Neumann method for
generating an exponentially distributed random variable.


Syntax:
declare random_$exponential entry (float bin(27));
call random_$exponential (random_no);

-or-

declare random_$exponential entry (fixed bin(35), float bin(27));
call random_$exponential (seed, random_no);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
random_no
   is the random number that is generated.  (Output)


:Entry:  exponential_seq:  02/06/84 random_$exponential_seq


Function: produces an array of exponentially distributed random
variables.


Syntax:
declare random_$exponential_seq entry ((*) float bin(27), fixed bin);
call random_$exponential_seq (array, array_size);

-or-

declare random_$exponential_seq entry (fixed bin(35),
      (*) float bin(27), fixed bin);
call random_$exponential_seq (seed, array, array_size);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
array (N)
   is the array of generated random numbers where N is greater than or
   equal to array_size.  (Output)
array_size
   is the number of values returned in the array.  (Input)


:Entry:  get_seed:  02/06/84 random_$get_seed


Function: is used to obtain the current value of the internal seed.


Syntax:
declare random_$get_seed entry (fixed bin(35));
call random_$get_seed (seed_value);


Arguments:
seed_value
   is the current value of the internal seed.  (Output)


:Entry:  normal:  02/06/84 random_$normal


Function: generates a random number greater than -6.0 and less than
6.0.  The sequence of random numbers has an approximately normal
distribution with a mean of 0 and a variance of 1.  The random number
is formed by taking the sum of 12 successive random numbers from the
uniformly distributed sequence and then adjusting the sum for a mean
of 0 by subtracting 6.0.


Syntax:
declare random_$normal entry (float bin(27));
call random_$normal (random_no);

-or-

declare random_$normal entry (fixed bin(35), float bin(27));
call random_$normal (seed, random_no);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
random_no
   is the random number that is generated.  (Output)


:Entry:  normal_ant:  02/06/84 random_$normal_ant


Function: generates a random number that is negatively correlated with
the random_no argument produced by the random_$normal entry point.
For any particular value of the seed:

        (random_ant + random_no) = 0.0


Syntax:
declare random_$normal_ant entry (float bin(27));
call random_$normal_ant (random_ant);

-or-

declare random_$normal_ant entry (fixed bin(35), float bin(27));
call random_$normal_ant (seed, random_ant);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
random_ant
   is the random number that is generated.  (Output)


:Entry:  normal_ant_seq:  02/06/84 random_$normal_ant_seq


Function: generates a sequence of array_size, of random variables with
approximately normal distribution.  The sequence contains the number
of values specified in the array_size argument.  These variables are
negatively correlated with those produced by the random_$normal_seq
entry point.


Syntax:
declare random_$normal_ant_seq entry ((*) float bin(27), fixed bin);
call random_$normal_ant_seq (ant_array, array_size);

-or-

declare random_$normal_ant_seq entry (fixed bin(35), (*) float bin(27),
     fixed bin);
call random_$normal_ant_seq (seed, ant_array, array_size);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
ant_array (N)
   is the array of generated random numbers where N is greater than or
   equal to array_size.  (Output)
array_size
   is the number of values returned in ant_array.  (Input)


:Entry:  normal_seq:  02/06/84 random_$normal_seq


Function: generates a sequence of random variables with an
approximately normal distribution.  The sequence contains the number
of values specified in the array_size argument.


Syntax:
declare random_$normal_seq entry ((*) float bin(27), fixed bin);
call random_$normal_seq (array, array_size);

-or-

declare random_$normal_seq entry (fixed bin(35), (*) float bin(27),
     fixed bin);
call random_$normal_seq (seed, array, array_size);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
array (N)
   is an array of the generated random numbers where N is greater than
   or equal to array_size.  (Output)
array_size
   specifies the number of random variables to be returned in array.
   (Input)


:Entry:  set_seed:  02/06/84 random_$set_seed


Function: sets the value of the internal seed.  This internal seed is
used as the seed for the next call to any random_ entry point in which
the optional argument, seed, is not provided.


Syntax:
declare random_$set_seed entry (fixed bin(35));
call random_$set_seed (seed_value);


Arguments:
seed_value
   is the value to which the internal seed is set.  (Input) This value
   must be a nonzero positive integer.


:Entry:  uniform:  02/06/84 random_$uniform


Function: generates a random number with a value between 0.0 and 1.0.
The sequence of random numbers has a uniform distribution on the
interval 0 to 1.


Syntax:
declare random_$uniform entry (float bin(27));
call random_$uniform (random_no);

-or-

declare random_$uniform entry (fixed bin(35), float bin(27));
call random_$uniform (seed, random_no);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
random_no
   is the random number that is generated.  (Output)


:Entry:  uniform_ant:  02/06/84 random_$uniform_ant


Function: generates a uniformly distributed random number that is
negatively correlated with the random_no produced by the
random_$uniform entry point.  For any particular value of the seed:

        (random_ant + random_no) = 1.0


Syntax:
declare random_$uniform_ant entry (float bin(27));
call random_$uniform_ant (random_ant);

-or-

declare random_$uniform_ant entry (fixed bin(35), float bin(27));
call random_$uniform_ant (seed, random_ant);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
random_ant
   is the random number that is generated.  (Output)


:Entry:  uniform_ant_seq:  02/06/84 random_$uniform_ant_seq


Function: returns an array of uniformly distributed random numbers
that are negatively correlated with the array produced by the
random_$uniform_seq entry point.  For any particular value of the
seed:
        (ant_array(i) + array(i)) = 1.0

where the range of values for i is from 1 to array_size.


Syntax:
declare random_$uniform_ant_seq entry ((*) float bin(27), fixed bin);
call random_$uniform_ant_seq (ant_array, array_size);

-or-

declare random_$uniform_ant_seq entry (fixed bin(35),
     (*) float bin(27), fixed bin);
call random_$uniform_ant_seq (seed, ant_array, array_size);


Arguments:
seed
   is the optional seed.  (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the random
      number.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence.
ant_array
   is the array of generated random numbers where N is greater than or
   equal to array_size.  (Output)
array_size
   is the number of values returned in ant_array.  (Input)


:Entry:  uniform_seq:  02/06/84 random_$uniform_seq


Function: returns an array of random numbers from the uniform
sequence.


Syntax:
declare random_$uniform_seq entry ((*) float bin(27), fixed bin);
call random_$uniform_seq (array, array_size);

-or-

declare random_$uniform_seq entry (fixed bin(35), (*) float bin(27),
     fixed bin);
call random_$uniform_seq (seed, array, array_size);


Arguments:
seed
   is the optional seed. (Input/Output)
   Input
      must be a nonzero positive integer; used to generate the first
      random number in the array.
   Output
      is the new value (modification of input value); used to generate
      the next random number of the sequence; the modification of the
      input value occurs array_size times.
array (N)
   is an array of the generated random numbers where N is greater than
   or equal to array_size.  (Output)
array_size
   specifies the number of random variables to be returned in array.
   (Input)



                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved