HELP RANDOM                                        A. Sloman June 1987


RANDOM
LIB NEWRANDOM

    random(<integer|biginteger|decimal|ddecimal>) -> <number>
    random0(<integer|biginteger|decimal|ddecimal>) -> <number>

Two versions of these random number generators are provided, one version
built in and one in the library LIB NEWRANDOM. The built in procedures
are fast, but use a simpler algorithm with a smaller cycle.

The built in versions are described first.

-- Built-in random0 and random ----------------------------------------

random0(<int_or_float>) -> random
random(<int_or_float>)  -> random

N.B. These were changed in Version 13 of POPLOG to be far superior to
the previous version.

Given a strictly-positive integer, biginteger, or floating-point
argument, these procedures generate a random number of the same type.

For random0 the number generated is in the range:

        0  <=  random  <  int_or_float

For random, it is in the range

        0 <  random <=  int_or_float        for a float, or
        1 <= random <= int_or_float         for an integer.

The distribution of RANDOM will be approximately uniform.

For simple integers and single floats, the cycle length of the sequence
generated (i.e. how many are produced before the sequence starts to
repeat) is 2**30 on all systems (for big integers and double floats
it will be at least 2**29).

ranseed

This integer variable is used to hold the next seed for generation of
random numbers by RANDOM0 or RANDOM, both of which give it a new value
after each call.

If set to <false>, it will be re-initialised to a random simple integer
the next time either procedure is called (by using SYS_REAL_TIME).
Otherwise, its value must always be a simple integer.

RANDOM and RANDOM0 can be made predictable by assigning e.g. 1 to
RANSEED. This can be useful in debugging programs.

-- Versions in LIB NEWRANDOM ------------------------------------------

The command LIB NEWRANDOM cancels both "random" and "random0" and
defines two new procedures which work like the procedures described
above, with the following differences.

1. A more complicated algorithm is used with a cycle of approximately
    30000 ** 3, and a more uniform distribution

2. It is much slower.

3. It accepts negative numbers, and produces results with the above
    ranges reversed.

3. There are three seeds instead of only 1

    ranseed     initialised randomly when the library is loaded

    ranseed2    Given a fixed initialisation
    ranseed3    Given a fixed initialisation

Users may assign to any of these. If RANSEED2 and RANSEED3 are ignored
then this program is analogous to the built in procedures.

Assigning FALSE to RANSEED will not cause it to be given an
unpredictable value. In order to start a predictable sequence of random
numbers assign a fixed set of integers (not bigintegers) to all three
seeds.

In order to start an unpredictable sequence, *sys_real_time can be used,
provided that care is taken to make the value a simple integer and not a
biginteger. The following method can be used:

    uses int_parameters

    sys_real_time() mod (pop_max_int + 1) -> ranseed;
    sys_real_time() mod (pop_max_int + 1) -> ranseed2;
    sys_real_time() mod (pop_max_int + 1) -> ranseed3;


See also:

HELP *ONEOF         - uses RANDOM to select a 'random' element from a list
HELP *SHUFFLE       - shuffles the contents of a list using ONEOF
REF  *NUMBERS       - for full information on number types
REF  *SYSUTIL       - for information on SYS_REAL_TIME
SHOWLIB *NEWRANDOM  - gives details of lib NEWRANDOM


--- C.all/help/random
--- Copyright University of Sussex 1998. All rights reserved.
