.. highlight:: lua

.. include:: <isogrk1.txt>
.. include:: <isotech.txt>

:mod:`rnd` -- Random Number Distributions
=========================================

.. module:: rnd

This chapter describes functions for generating random variates and
computing their probability distributions.  Samples from the
distributions described in this chapter can be obtained using any of
the random number generators in the library as an underlying source of
randomness.

In the simplest cases a non-uniform distribution can be obtained
analytically from the uniform distribution of a random number
generator by applying an appropriate transformation.  This method uses
one call to the random number generator.  More complicated
distributions are created by the "acceptance-rejection" method, which
compares the desired distribution against a distribution which is
similar and known analytically.  This usually requires several samples
from the generator.

The library also provides cumulative distribution functions and
inverse cumulative distribution functions, sometimes referred to as
quantile functions.  The cumulative distribution functions and their
inverses are computed separately for the upper and lower tails of the
distribution, allowing full accuracy to be retained for small results. See the chapter :ref:`cdf-section` for more details.

.. _rnd_gaussian:

.. function:: gaussian(r [, sigma])

     This function returns a Gaussian random variate, with mean zero and
     standard deviation 'sigma'.  The probability distribution for
     Gaussian random variates is,

     .. math::
          p(x) dx = {1 \over \sqrt{2 \pi \sigma^2}} \exp (-x^2 / 2\sigma^2) dx

     for x in the range -\ |infin| to +\ |infin| .  Use the transformation z =
     |mgr| + x on the numbers returned by 'gsl_ran_gaussian' to obtain a
     Gaussian distribution with mean |mgr|.  This function uses the
     Box-Mueller algorithm which requires two calls to the random
     number generator R.

.. _rnd_exponential:

.. function:: exponential(r [, mu])

     This function returns a random variate from the exponential
     distribution with mean 'mu'. The distribution is,

     .. math::
          p(x) dx = {1 \over \mu} \exp(-x/\mu) dx

     for x >= 0.

.. _rnd_chisq:

.. function:: chisq(r [, nu])

   The chi-squared distribution arises in statistics.  If Y\ :sub:`i` are n
   independent gaussian random variates with unit variance then the
   sum-of-squares,

   .. math::
     X_i = \sum_i Y_i^2

   has a chi-squared distribution with n degrees of freedom.

   This function returns a random variate from the chi-squared
   distribution with |ngr| degrees of freedom. The distribution function
   is,

   .. math::
        p(x) dx = {1 \over 2 \Gamma(\nu/2) } (x/2)^{\nu/2 - 1} \exp(-x/2) dx

   for x >= 0.

.. _rnd_laplace:

.. function:: laplace(r [, a])

     This function returns a random variate from the Laplace
     distribution with width ``a``.  The distribution is,

     .. math::
          p(x) dx = {1 \over 2 a}  \exp(-|x/a|) dx

     for -\ |infin| < x < +\ |infin|.

.. _rnd_tdist:

.. function:: tdist(r [, nu])
   
   The t-distribution arises in statistics.  If Y\ :sub:`1` has a
   normal distribution and Y\ :sub:`2` has a chi-squared distribution
   with \nu degrees of freedom then the ratio,

   .. math::
     X = { Y_1 \over \sqrt{Y_2 / \nu} }

   has a t-distribution t(x; |ngr|) with |ngr| degrees of freedom.

   This function returns a random variate from the t-distribution.
   The distribution function is,

   .. math::
          p(x) dx = {\Gamma((\nu + 1)/2) \over \sqrt{\pi \nu} \Gamma(\nu/2)}
             (1 + x^2/\nu)^{-(\nu + 1)/2} dx

   for -\ |infin| < x < +\ |infin|.

.. _rnd_cauchy:

.. function:: cauchy(r [, a])

     This function returns a random variate from the Cauchy
     distribution with scale parameter A.  The probability distribution
     for Cauchy random variates is,

     .. math::
          p(x) dx = {1 \over a\pi (1 + (x/a)^2) } dx

     for x in the range - |infin| to + |infin| .  The Cauchy distribution is
     also known as the Lorentz distribution.

.. _rnd_rayleigh:

.. function:: rayleigh(r [, sigma])

     This function returns a random variate from the Rayleigh
     distribution with scale parameter |sgr|.  The distribution is,

     .. math::
          p(x) dx = {x \over \sigma^2} \exp(- x^2/(2 \sigma^2)) dx

     for x > 0.

.. _rnd_fdist:

.. function:: fdist(r, nu1, nu2)

   The F-distribution arises in statistics.  If Y\ :sub:`1` and Y\
   :sub:`2` are chi-squared deviates with |ngr| :sub:`1` and 
   |ngr|\ :sub:`2` degrees of freedom then the ratio,

   .. math::
     X = { (Y_1 / \nu_1) \over (Y_2 / \nu_2) }

   has an F-distribution F(x; |ngr|\ :sub:`1`, |ngr|\ :sub:`2`).

   This function returns a random variate from the F-distribution with
   degrees of freedom |ngr|\ :sub:`1` and |ngr|\ :sub:`2`. The
   distribution function is,

   .. math::
          p(x) dx =
             { \Gamma((\nu_1 + \nu_2)/2)
                  \over \Gamma(\nu_1/2) \Gamma(\nu_2/2) }
             \nu_1^{\nu_1/2} \nu_2^{\nu_2/2}
             x^{\nu_1/2 - 1} (\nu_2 + \nu_1 x)^{-\nu_1/2 -\nu_2/2}

   for x >= 0.

.. _rnd_gamma:

.. function:: gamma(r, a, b)

   This function returns a random variate from the gamma
   distribution. The distribution function is,

   .. math::
          p(x) dx = {1 \over \Gamma(a) b^a} x^{a-1} e^{-x/b} dx

   for x > 0.

   The gamma distribution with an integer parameter a is known as the
   Erlang distribution. The variates are computed using the
   Marsaglia-Tsang fast gamma method.

.. _rnd_beta:

.. function:: beta(r, a, b)

    This function returns a random variate from the beta
    distribution. The distribution function is,

    .. math::
        p(x) dx = {\Gamma(a+b) \over \Gamma(a) \Gamma(b)} x^{a-1} (1-x)^{b-1} dx

    for 0 <= x <= 1.

.. _rnd_gaussian_tail:

.. function:: gaussian_tail(r, a, sigma)

   This function provides random variates from the upper tail of a
   Gaussian distribution with standard deviation sigma. The values
   returned are larger than the lower limit a, which must be
   positive. The method is based on Marsaglia's famous
   rectangle-wedge-tail algorithm (Ann. Math. Stat. 32, 894–899
   (1961)), with this aspect explained in Knuth, v2, 3rd ed, p139,586
   (exercise 11).

   The probability distribution for Gaussian tail random variates is,

   .. math::
          p(x) dx = {1 \over N(a;\sigma) \sqrt{2 \pi \sigma^2}}
          \exp \left(- \frac{x^2}{2 \sigma^2}\right) dx

   for x > a where N(a; |sgr|) is the normalization constant,

   .. math::
          N(a; \sigma) = (1/2) \textrm{erfc}(a / \sqrt{2 \sigma^2}).

.. _rnd_exppow:

.. function:: exppow(r, a, b)

   This function returns a random variate from the exponential power
   distribution with scale parameter a and exponent b. The
   distribution is,

   .. math::
          p(x) dx = {1 \over 2 a \Gamma(1+1/b)} \exp(-|x/a|^b) dx

   for x >= 0. For b = 1 this reduces to the Laplace distribution. For
   b = 2 it has the same form as a gaussian distribution, but with
   :math:`a = \sqrt{2} \sigma`.

.. _rnd_lognormal:

.. function:: lognormal(r, zeta, sigma)

   This function returns a random variate from the lognormal
   distribution. The distribution function is,

   .. math::
          p(x) dx = {1 \over x \sqrt{2 \pi \sigma^2} } 
          \exp(-(\ln(x) - \zeta)^2/2 \sigma^2) dx

   for x > 0.

.. _rnd_binomial:

.. function:: binomial(r, p, n)

   This function returns a random integer from the binomial
   distribution, the number of successes in n independent trials with
   probability p. The probability distribution for binomial variates
   is,

   .. math::
          p(k) = {n! \over k! (n-k)! } p^k (1-p)^{n-k}

   for 0 <= k <= n.

.. _rnd_poisson:

.. function:: poisson(r [, mu])

   This function returns a random integer from the Poisson
   distribution with mean mu. The probability distribution for Poisson
   variates is,

   .. math::
          p(k) = {\mu^k \over k!} \exp(-\mu)

   for k >= 0.
