Previous: , Up: Numbers   [Contents][Index]

#### 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))
```

Previous: , Up: Numbers   [Contents][Index]