NAME

       random - Pseudo random number generation

DESCRIPTION

       Random  number  generator.  The method is attributed to B.A. Wichmann and I.D.Hill, in 'An
       efficient and portable pseudo-random number generator',  Journal  of  Applied  Statistics.
       AS183. 1982. Also Byte March 1987.

       The  current algorithm is a modification of the version attributed to Richard A O'Keefe in
       the standard Prolog library.

       Every time a random number is requested, a state is used to calculate it, and a new  state
       produced.  The  state  can  either  be  implicit (kept in the process dictionary) or be an
       explicit argument and return value. In this implementation, the  state  (the  type  ran())
       consists of a tuple of three integers.

       It should be noted that this random number generator is not cryptographically strong. If a
       strong cryptographic random number generator is  needed  for  example  crypto:rand_bytes/1
       could be used instead.

DATA TYPES

       ran() = {integer(), integer(), integer()}

              The state.

EXPORTS

       seed() -> ran()

              Seeds  random  number  generation  with  default  (fixed)  values  in  the  process
              dictionary, and returns the old state.

       seed(A1, A2, A3) -> undefined | ran()

              Types:

                 A1 = A2 = A3 = integer()

              Seeds random number generation with integer values in the process  dictionary,  and
              returns the old state.

              One way of obtaining a seed is to use the BIF now/0:

                        ...
                        {A1,A2,A3} = now(),
                        random:seed(A1, A2, A3),
                        ...

       seed(X1 :: {A1, A2, A3}) -> undefined | ran()

              Types:

                 A1 = A2 = A3 = integer()

              seed({A1, A2, A3}) is equivalent to seed(A1, A2, A3).

       seed0() -> ran()

              Returns the default state.

       uniform() -> float()

              Returns  a  random  float  uniformly  distributed between 0.0 and 1.0, updating the
              state in the process dictionary.

       uniform(N) -> integer() >= 1

              Types:

                 N = integer() >= 1

              Given an integer N >= 1, uniform/1 returns a random integer  uniformly  distributed
              between 1 and N, updating the state in the process dictionary.

       uniform_s(State0) -> {float(), State1}

              Types:

                 State0 = State1 = ran()

              Given  a state, uniform_s/1returns a random float uniformly distributed between 0.0
              and 1.0, and a new state.

       uniform_s(N, State0) -> {integer(), State1}

              Types:

                 N = integer() >= 1
                 State0 = State1 = ran()

              Given an integer N >= 1 and a state, uniform_s/2 returns a random integer uniformly
              distributed between 1 and N, and a new state.

NOTE

       Some  of  the  functions  use  the process dictionary variable random_seed to remember the
       current seed.

       If a process calls uniform/0 or uniform/1 without setting a seed first, seed/0  is  called
       automatically.

       The  implementation changed in R15. Upgrading to R15 will break applications that expect a
       specific output for a given seed. The output is still  deterministic  number  series,  but
       different compared to releases older than R15. The seed {0,0,0} will for example no longer
       produce a flawed series of only zeros.