6.6.2.14 Random Number Generation

Pseudo-random numbers are generated from a random state object, which can be created with seed->random-state or datum->random-state. An external representation (i.e. one which can written with write and read with read) of a random state object can be obtained via random-state->datum. 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.

Scheme Procedure: datum->random-state datum

C Function: scm_datum_to_random_state (datum)

Return a new random state from datum, which should have been obtained by random-state->datum.

Scheme Procedure: random-state->datum state

C Function: scm_random_state_to_datum (state)

Return a datum representation of state that may be written out and read back with the Scheme reader.

Scheme Procedure: random-state-from-platform

C Function: scm_random_state_from_platform ()

Construct a new random state seeded from a platform-specific source of entropy, appropriate for use in non-security-critical applications. Currently /dev/urandom is tried first, or else the seed is based on the time, date, process ID, an address from a freshly allocated heap cell, an address from the local stack frame, and a high-resolution timer if available.

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 seed the random state in a sensible way for non-security-critical applications, do this during initialization of your program:

(set! *random-state* (random-state-from-platform))