doc.txt

# (require (planet "random.ss" ("schematics" "random.plt" 1 0)))

```(require (planet "random.ss" ("schematics" "random.plt" 1 0)))

RANDOM NUMBERS
==============

Introduction
============

This library provides functions to produce random numbers of various
distributions. The library uses the same approach as taken by SRFI 27:
"Sources of Random Bits".

_Random Variables_
==================

A _random variable_ is a function with no input, that produces a
number each time it is called.

X : -> number

Let x={x_1, x_2, ...} be the sequence of numbers returned by calling
X repeatedly. If the sequence x has the same properties as a random
sequence with a given distribution, we will say that X is a random
variable with the given distribution.

This library provides ways of generating random variables with
different distributions.

Overview of interface
=====================

The "no fuss" interface simply generates the next random number of a
given distribution using bits from the default source of random bits.

> (require (planet "random.ss" ("schematics" "random.plt" 1 0)))

> (random-gaussian)
0.7386912134436788

For simulation purposes it is usually neccesary to have explicit
access to the state of the underlying random bit generator in order to
reliably reproduce results. Therefore functions are provided where one
can specify which random source is to be used.

> (define X (random-source-make-gaussians default-random-source))
> (X)
-0.24588198549160234

_Provided Functions_
====================

The following functions are provided:

Discrete distributions:

_random-source-make-integers_      _random-integer_
_random-source-make-geometrics_    _random-geometric_
_random-source-make-binomials_     _random-binomial_
_random-source-make-poissons_      _random-poisson_

_random-source-make-permutations_  _random-permutation_

_random-source-make-discretes_

Continous distributions:

_random-source-make-reals_         _random-real_
_random-source-make-unit-discs_    _random-unit-disc_
_random-source-make-normals_       _random-normal_
_random-source-make-gaussians_     _random-gaussian_
_random-source-make-exponentials_  _random-exponential_
_random-source-make-gammas_        _random-gamma_
_random-source-make-betas_         _random-beta_
_random-source-make-chi-squares_   _random-chi-square_
_random-source-make-Fs_            _random-F_
_random-source-make-ts_            _random-t_

Sources of random bits:

_default-random-source_

Explicit manipulation of random sources (reexported from srfi-27):

_make-random-source random-source?_ _random-source-state-ref_
_random-source-state-set!_ _random-source-randomize!_
_random-source-pseudo-randomize!_

General Remarks
===============

The functions prefixed with random constitute the no fuss-interface,
they all use default-random-source as their source of random bits.
Some of these distributions have parameters, and they must given in
order to generate a random number. E.g. the normal distribution has
two parameters my and sigma, where my is the mean and sigma squared
is the variance.

> (random-normal 0 2)
-2.1002646826655758

The function named random-source-make-<dist>s generate a function that
behave the same way as the random-<dist> but uses the given random
source in stead of the defualt. As an example, random-normal is
implemented like this:

(define random-normal
(random-source-make-normals default-random-source))

See the documentation for srfi-27 for further explanation.

_Discrete distributions_
========================

_Random integers_

random-integer : integer -> {0, ..., n-1}
(random-integer n) gives the next integer x in {0, ..., n-1}
obtained from default-random-source. Subsequent results of this
procedure appear to be independent uniformly distributed over the
range {0, ..., n-1}. The argument n must be a positive integer,
otherwise an error is signalled.

_The Geometric Distribution_

random-geometric : p -> integer
The geometric distribution of the parameter p has the probability
function:
n-1
P(n) =   p (1-p)      , where 0<p<1

The mean is  my = 1/p  and the variance is  sigma^2 =  (1-p)/p^2 .

_Binomial Distribution_

random-binomial : n p -> integer
n is the number-of-trials-parameter,
p is the probability parameter

_Poisson Distribution_

random-poisson : my -> integer
The Poisson distribution with mean my.

_Permutations_

random-source-make-permutations : source -> (integer - > vector)
produces a function that given an integer n generates permutations
of the numbers 0,...,n-1  i.e. a vector of length n is returned
containing the numbers 0 to n-1 in some order.

_Discrete Distribution_

random-source-make-discretes : s w -> integer
given a source s of random bits in the sense of SRFI-27 and a
vector w of n >= 1 non-negative real numbers, this procedure
constructs and returns a procedure rand such that (rand) returns
the next integer x in {0..n-1} from a pseudo random sequence with

Pr{x = k} = w[k] / Sum(w[i] : i)    , for all k in {0..n-1}.

_Continous Distributions_
=========================

_Uniform distribution on the unit interval_

random-real : -> ]0;1[
Gives the next number 0 < x < 1 obtained from
default-random-source.  Subsequent results of this procedure
appear to be independent uniformly distributed.  The numerical
type of the results and the quantization of the output range
depend on the implementation; refer to random-source-make-reals
for details.

_Normal Distribution_

random-normal : mu sigma -> real
generates N(mu,sigma)-distributed numbers

1     /x         2
Distribution:  F(x) = ---------  |    exp(-t / 2) dt   , mu=0, sigma=1
sqrt(2pi)  /-infinity

random-gaussian :  -> real
generates N(0,1)-distributed numbers

_Exponential Distribution_

random-exponential : my -> real
generates Exp(mu)-distributed random numbers

Distribution:  F(x) = 1 - exp(-x/mu)   , mu is the mean

_Gamma Distribution_

random-gamma : a -> real
generate Gamma(a)-distributed numbers

Distribution: The gamma distribition of order a>0

1       /x    a-1  -t
F(x) = ---------  |    t    e   dt,  x>=0
gamma(a)   /0

_Beta Distribution_

random-beta : a b -> real
generate Beta(a,b)-distributed numbers

Distribution:  Beta distribution with a>0 and b>0

gamma(a+b)     / x   a-1      b-1
F(x) =  -----------------  |    t    (1-t)     dt    , 0<= x <= 1
gamma(a) gamma(b)  / 0

_Chi-Square Distribution_

random-chi-square : ny -> real
generate Chi(ny)-distributed numbers

_F-Distribution_

random-F : ny1 ny2 -> real
generate F(ny1,ny2)-distributed numbers

The F-distribution (variance-ratio distribution) with
ny1 and ny2 degrees of freedom:

ny1/2    ny2/2
ny1      ny2     gamma((ny1+ny2)/2)  / x   ny1/2-1           -ny1/2-ny2/2b-1
F(x) =  -----------------------------------  |    t        (ny2+ny1t)                dt
gamma(ny1/2) gamma(ny2/2)            /0

where x>=0.

_t-distribution_

random-t : ny -> real
generate t(ny)-distributed numbers

The t-distribution with ny degrees of freedom

gamma((ny+1)/2)           / x         2     -(ny+1)/2
F(x) =  -----------------------   |     (1 + t / ny)          dt
sqrt(pi ny) gamma(ny/2)   /-inf

_Uniform Unit Disc-Distribution_

random-unit-disc : -> (values ]0;1[ ]0;1[ )
generate coordinates distributed uniformly in the unit disc
```