[comment {-*- tcl -*- doctools manpage}]
[manpage_begin simulation::random n 0.4]
[keywords math]
[keywords {random numbers}]
[keywords simulation]
[keywords {statistical distribution}]
[copyright {2004 Arjen Markus <arjenmarkus@users.sourceforge.net>}]
[moddesc   {Tcl Simulation Tools}]
[titledesc {Pseudo-random number generators}]
[category  Mathematics]
[require Tcl [opt "8.5 9"]]
[require simulation::random 0.4]

[description]
[para]
This package consists of commands to generate pseudo-random number
generators. These new commands deliver

[list_begin itemized]
[item]
numbers that are distributed normally, uniformly, according to a
Pareto or Gumbel distribution and so on
[item]
coordinates of points uniformly spread inside a sphere or a rectangle
[list_end]

For example:
[example {
    set p [::simulation::random::prng_Normal -1.0 10.0]
}]
produces a new command (whose name is stored in the variable "p") that
generates normally distributed numbers with a mean of -1.0 and a
standard deviation of 10.0.

[section "PROCEDURES"]

The package defines the following public procedures for [emph discrete]
distributions:

[list_begin definitions]

[call [cmd ::simulation::random::prng_Bernoulli] [arg p]]

Create a command (PRNG) that generates numbers with a Bernoulli
distribution: the value is either 1 or 0, with a chance p to be 1

[list_begin arguments]
[arg_def float p] Chance the outcome is 1
[list_end]

[para]

[call [cmd ::simulation::random::prng_Discrete] [arg n]]

Create a command (PRNG) that generates numbers 0 to n-1 with equal
probability.

[list_begin arguments]
[arg_def int n] Number of different values (ranging from 0 to n-1)
[list_end]

[para]

[call [cmd ::simulation::random::prng_Poisson] [arg lambda]]

Create a command (PRNG) that generates numbers according to the Poisson
distribution.

[list_begin arguments]
[arg_def float lambda] Mean number per time interval
[list_end]

[list_end]

The package defines the following public procedures for [emph continuous] distributions:

[list_begin definitions]

[call [cmd ::simulation::random::prng_Uniform] [arg min ] [arg max]]

Create a command (PRNG) that generates uniformly distributed numbers
between "min" and "max".

[list_begin arguments]
[arg_def float min] Minimum number that will be generated
[arg_def float max] Maximum number that will be generated
[list_end]

[para]

[call [cmd ::simulation::random::prng_Triangular] [arg min ] [arg max]]

Create a command (PRNG) that generates triangularly distributed numbers
between "min" and "max". If the argument min is lower than the argument max, then smaller
values have higher probability and vice versa. In the first case the probability
density function is of the form [emph {f(x) = 2(1-x)}] and the other case it is of the form [emph {f(x) = 2x}].

[list_begin arguments]
[arg_def float min] Minimum number that will be generated
[arg_def float max] Maximum number that will be generated
[list_end]

[para]

[call [cmd ::simulation::random::prng_SymmTriangular] [arg min ] [arg max]]

Create a command (PRNG) that generates numbers distributed according to a symmetric triangle
around the mean of "min" and "max".

[list_begin arguments]
[arg_def float min] Minimum number that will be generated
[arg_def float max] Maximum number that will be generated
[list_end]

[para]

[call [cmd ::simulation::random::prng_Exponential] [arg min] [arg mean]]

Create a command (PRNG) that generates exponentially distributed numbers
with a given minimum value and a given mean value.

[list_begin arguments]
[arg_def float min] Minimum number that will be generated
[arg_def float mean] Mean value for the numbers
[list_end]

[para]

[call [cmd ::simulation::random::prng_Normal] [arg mean] [arg stdev]]

Create a command (PRNG) that generates normally distributed numbers
with a given mean value and a given standard deviation.

[list_begin arguments]
[arg_def float mean] Mean value for the numbers
[arg_def float stdev] Standard deviation
[list_end]

[para]

[call [cmd ::simulation::random::prng_Pareto] [arg min] [arg steep]]

Create a command (PRNG) that generates numbers distributed according to
Pareto with a given minimum value and a given distribution steepness.

[list_begin arguments]
[arg_def float min] Minimum number that will be generated
[arg_def float steep] Steepness of the distribution
[list_end]

[para]

[call [cmd ::simulation::random::prng_Gumbel] [arg min] [arg f]]

Create a command (PRNG) that generates numbers distributed according to
Gumbel with a given minimum value and a given scale factor. The
probability density function is:
[example {
     P(v) = exp( -exp(f*(v-min)))
}]

[list_begin arguments]
[arg_def float min] Minimum number that will be generated
[arg_def float f] Scale factor for the values
[list_end]

[para]

[call [cmd ::simulation::random::prng_chiSquared] [arg df]]

Create a command (PRNG) that generates numbers distributed according to
the chi-squared distribution with df degrees of freedom. The mean is 0
and the standard deviation is 1.

[list_begin arguments]
[arg_def float df] Degrees of freedom
[list_end]

[list_end]

The package defines the following public procedures for random point sets:

[list_begin definitions]

[call [cmd ::simulation::random::prng_Disk] [arg rad]]

Create a command (PRNG) that generates (x,y)-coordinates for points
uniformly spread over a disk of given radius.

[list_begin arguments]
[arg_def float rad] Radius of the disk
[list_end]

[para]

[call [cmd ::simulation::random::prng_Sphere] [arg rad]]

Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread over the surface of a sphere of given radius.

[list_begin arguments]
[arg_def float rad] Radius of the disk
[list_end]

[para]

[call [cmd ::simulation::random::prng_Ball] [arg rad]]

Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread within a ball of given radius.

[list_begin arguments]
[arg_def float rad] Radius of the ball
[list_end]

[para]

[call [cmd ::simulation::random::prng_Rectangle] [arg length] [arg width]]

Create a command (PRNG) that generates (x,y)-coordinates for points
uniformly spread over a rectangle.

[list_begin arguments]
[arg_def float length] Length of the rectangle (x-direction)
[arg_def float width] Width of the rectangle (y-direction)
[list_end]

[para]

[call [cmd ::simulation::random::prng_Block] [arg length] [arg width] [arg depth]]

Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread over a block

[list_begin arguments]
[arg_def float length] Length of the block (x-direction)
[arg_def float width] Width of the block (y-direction)
[arg_def float depth] Depth of the block (z-direction)
[list_end]

[list_end]
[manpage_end]
