Previous: Bitwise Operations, Up: Numbers

5.5.2.15 Random Number Generation

Pseudo-random numbers are generated from a random state object, which can be created with seed->random-state. The state parameter to the various functions below is optional, it defaults to the state object in the *random-state* variable.

— Scheme Procedure: copy-random-state [state]
— C Function: scm_copy_random_state (state)

Return a copy of the random state state.

— Scheme Procedure: random n [state]
— C Function: scm_random (n, state)

Return a number in [0, n).

Accepts a positive integer or real n and returns a number of the same type between zero (inclusive) and n (exclusive). The values returned have a uniform distribution.

— Scheme Procedure: random:exp [state]
— C Function: scm_random_exp (state)

Return an inexact real in an exponential distribution with mean 1. For an exponential distribution with mean u use (* u (random:exp)).

— Scheme Procedure: random:hollow-sphere! vect [state]
— C Function: scm_random_hollow_sphere_x (vect, state)

Fills vect with inexact real random numbers the sum of whose squares is equal to 1.0. Thinking of vect as coordinates in space of dimension n = (vector-length vect), the coordinates are uniformly distributed over the surface of the unit n-sphere.

— Scheme Procedure: random:normal [state]
— C Function: scm_random_normal (state)

Return an inexact real in a normal distribution. The distribution used has mean 0 and standard deviation 1. For a normal distribution with mean m and standard deviation d use (+ m (* d (random:normal))).

— Scheme Procedure: random:normal-vector! vect [state]
— C Function: scm_random_normal_vector_x (vect, state)

Fills vect with inexact real random numbers that are independent and standard normally distributed (i.e., with mean 0 and variance 1).

— Scheme Procedure: random:solid-sphere! vect [state]
— C Function: scm_random_solid_sphere_x (vect, state)

Fills vect with inexact real random numbers the sum of whose squares is less than 1.0. Thinking of vect as coordinates in space of dimension n = (vector-length vect), the coordinates are uniformly distributed within the unit n-sphere.

— Scheme Procedure: random:uniform [state]
— C Function: scm_random_uniform (state)

Return a uniformly distributed inexact real random number in [0,1).

— Scheme Procedure: seed->random-state seed
— C Function: scm_seed_to_random_state (seed)

Return a new random state using seed.

— Variable: *random-state*

The global random state used by the above functions when the state parameter is not given.

Note that the initial value of *random-state* is the same every time Guile starts up. Therefore, if you don't pass a state parameter to the above procedures, and you don't set *random-state* to (seed->random-state your-seed), where your-seed is something that isn't the same every time, you'll get the same sequence of “random” numbers on every run.

For example, unless the relevant source code has changed, (map random (cdr (iota 30))), if the first use of random numbers since Guile started up, will always give: 

     (map random (cdr (iota 19)))
     ⇒
     (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)

To use the time of day as the random seed, you can use code like this: 

     (let ((time (gettimeofday)))
       (set! *random-state*
             (seed->random-state (+ (car time)
                                    (cdr time)))))

And then (depending on the time of day, of course): 

     (map random (cdr (iota 19)))
     ⇒
     (0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17)

For security applications, such as password generation, you should use more bits of seed. Otherwise an open source password generator could be attacked by guessing the seed... but that's a subject for another manual.