% $Id$
% pygsl/doc/rng.tex

\declaremodule{standard}{pygsl.rng}%
\moduleauthor{Pierre Schnizer}{schnizer@users.sourceforge.net}%
\moduleauthor{Original Author: Achim G\"adke}{achimgaedke@users.sourceforge.net}%

This chapter introduces the random number generator type provided by \module{pygsl}.

\section{Random Number Generators}

All random number generatores are the same python type (PyGSL_rng), but using the
approbriate GSL random generator for generating the random numbers. Use the method
\code{name} to get the name of the rng used internally.

Methods of
this type \pytype{rng} provide the transformation to different probability
distributions and give access to basic properties of random number generators. 
All methods allow to pass one optional integer. Then the method will be evaluated n times and the result
will be returned as an array.

\begin{pytypedesc}{rng}{\texttt{string} typenamme \code{|} \class{rng} r}
  This base class can be instantiated by its name
\begin{verbatim}
import pygsl.rng
my_ran0=pygsl.rng.ran0()
\end{verbatim}
.
\end{pytypedesc}
The type of the allocated generator is given by the method
\begin{methoddesc}{name}{}
  which returns its name as string.
\end{methoddesc}
All generators can be seeded with
\begin{methoddesc}{set}{seed}
  which sets the internal seed according to the positive integer {\tt seed}. Zero as seed
  has a special meaning, please read details in the gsl reference.
\end{methoddesc}
The basic returned number type is integer, these are generated by
\begin{methoddesc}{get}{}
  which returns the next number of the pseudo random sequence.
\end{methoddesc}
All methods support internal sampling; i.e each method has an optional integer. 
If given it will return a sample of the approbriate size.
\begin{methoddesc}{get}{|n}
  will return the next n numbers of the pseudo random sequence.
\end{methoddesc}

Basic information about these numbers can be obtained by
\begin{methoddesc}{max}{}
  maximum number of this sequence and
\end{methoddesc}
\begin{methoddesc}{min}{}
  minimum number of this sequence.
\end{methoddesc}
Implemented uniform probability densities are:
\begin{methoddesc}{uniform}{}
  returns a real number between $[0,1)$.
\end{methoddesc}
\begin{methoddesc}{uniform_pos}{}
  returns a real number between $(0,1)$ --- this excludes 0.
\end{methoddesc}
\begin{methoddesc}{uniform_int}{upper limit}
  returns an integer from 0 to the upper limit (exclusive). If this limit is larger than
  the number of return values of the underlying generator, \exception{pygsl.gsl_Error} is
  raised.
\end{methoddesc}
Furthermore a lot of derived probability densities can be used:
\begin{methoddesc}{gaussian}{sigma}
  gaussian distribution with mean 0 and given sigma \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{gaussian\_ratio\_method}{sigma}
  gaussian distribution with mean 0 and given sigma.  This variate uses the
  Kinderman-Monahan ratio method.  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{ugaussian}{}
  gaussian distribution with unit sigma and mean 0.  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{ugaussian\_ratio\_method}{}
  gaussian distribution with unit sigma and mean 0.  This variate uses the
  Kinderman-Monahan ratio method.  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{gaussian\_tail}{sigma, a}
  upper tail of a Gaussian distribution with standard deviation sigma>0.  \hfill returns
  {\tt float}
\end{methoddesc}
\begin{methoddesc}{ugaussian\_tail}{a}
  upper tail of a Gaussian distribution with unit standard deviation.  \hfill returns {\tt
    float}
\end{methoddesc}
\begin{methoddesc}{bivariate\_gaussian}{sigma\_x, sigma\_y, rho}
  pair of correlated gaussian variates, with mean zero, correlation coefficient rho and
  standard deviations sigma\_x and sigma\_y in the x and y directions \hfill returns~{\tt
    (float,float)}
\end{methoddesc}
\begin{methoddesc}{exponential}{mu}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{laplace}{mu}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{exppow}{mu, a}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{cauchy}{mu}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{rayleigh}{sigma}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{rayleigh\_tail}{a, sigma}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{levy}{mu,a}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{levy_skew}{mu,a,beta}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{gamma}{a, b}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{gamma\_int}{long a}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{flat}{a, b}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{lognormal}{zeta, sigma}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{chisq}{nu}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{fdist}{nu1, nu2}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{tdist}{nu}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{beta}{a, b}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{logistic}{mu}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{pareto}{a, b}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{dir\_2d}{}
  \hfill returns {\tt (float, float)}
\end{methoddesc}
\begin{methoddesc}{dir\_2d\_trig\_method}{}
  \hfill returns {\tt (float, float)}
\end{methoddesc}
\begin{methoddesc}{dir\_3d}{}
  \hfill returns {\tt (float, float, float)}
\end{methoddesc}
\begin{methoddesc}{dir\_nd}{int n}
  \hfill returns {\tt (float, \dots, float)}
\end{methoddesc}
\begin{methoddesc}{weibull}{mu, a}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{gumbel1}{a, b}
  \hfill returns {\tt float}
\end{methoddesc}
\begin{methoddesc}{gumbel2}{}
\end{methoddesc}
\begin{methoddesc}{poisson}{}
\end{methoddesc}
\begin{methoddesc}{bernoulli}{}
\end{methoddesc}
\begin{methoddesc}{binomial}{}
\end{methoddesc}
\begin{methoddesc}{negative\_binomial}{}
\end{methoddesc}
\begin{methoddesc}{pascal}{}
\end{methoddesc}
\begin{methoddesc}{geometric}{}
\end{methoddesc}
\begin{methoddesc}{hypergeometric}{}
\end{methoddesc}
\begin{methoddesc}{logarithmic}{}
\end{methoddesc}
\begin{methoddesc}{landau}{}
\end{methoddesc}
\begin{methoddesc}{erlang}{}
\end{methoddesc}


The different generator classes are created according to the output of
\code{gsl_rng_types_setup()} when the \module{pygsl.rng} is loaded. Here is the list of
children from \class{rng} for gsl-1.2: \newline \class{rng_borosh13}, \class{rng_coveyou},
\class{rng_cmrg}, \class{rng_fishman18}, \class{rng_fishman20}, \class{rng_fishman2x},
\class{rng_gfsr4}, \class{rng_knuthran}, \class{rng_knuthran2}, \class{rng_lecuyer21},
\class{rng_minstd}, \class{rng_mrg}, \class{rng_mt19937}, \class{rng_mt19937_1999},
\class{rng_mt19937_1998}, \class{rng_r250}, \class{rng_ran0}, \class{rng_ran1},
\class{rng_ran2}, \class{rng_ran3}, \class{rng_rand}, \class{rng_rand48},
\class{rng_random128_bsd}, \class{rng_random128_glibc2}, \class{rng_random128_libc5},
\class{rng_random256_bsd}, \class{rng_random256_glibc2}, \class{rng_random256_libc5},
\class{rng_random32_bsd}, \class{rng_random32_glibc2}, \class{rng_random32_libc5},
\class{rng_random64_bsd}, \class{rng_random64_glibc2}, \class{rng_random64_libc5},
\class{rng_random8_bsd}, \class{rng_random8_glibc2}, \class{rng_random8_libc5},
\class{rng_random_bsd}, \class{rng_random_glibc2}, \class{rng_random_libc5},
\class{rng_randu}, \class{rng_ranf}, \class{rng_ranlux}, \class{rng_ranlux389},
\class{rng_ranlxd1}, \class{rng_ranlxd2}, \class{rng_ranlxs0}, \class{rng_ranlxs1},
\class{rng_ranlxs2}, \class{rng_ranmar}, \class{rng_slatec}, \class{rng_taus},
\class{rng_taus2}, \class{rng_taus113}, \class{rng_transputer}, \class{rng_tt800},
\class{rng_uni}, \class{rng_uni32}, \class{rng_vax}, \class{rng_waterman14}, and
\class{rng_zuf}.  
\newline 

The default generator of the \class{rng} defaults to {\tt rng_mt19937} but can be set from the
environment variable \envvar{GSL_RNG_TYPE} using the function \function{rng.env_setup()}.

\section{Probability Density Functions}


\section{Using probability densities with random number generators}


%% Local Variables:
%% mode: LaTeX
%% mode: auto-fill
%% fill-column: 90
%% indent-tabs-mode: nil
%% ispell-dictionary: "british"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "pygsl"
%% TeX-parse-self: t
%% End:
