% $Id: rng.tex,v 1.1 2005/06/09 05:50:42 schnizer Exp $
% 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 class \class{rng} provide the transformation to different probability
distributions and give access to basic properties of random number generators. 

\begin{classdesc}{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}
.

%  or a clone of an existing generator can be created by:
%\begin{verbatim}
%clone_ran0=pygsl.rng.rng(my_ran0)
%\end{verbatim}

\end{classdesc}
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 \class{rng} is determined by the
environment variable \envvar{GSL_RNG_TYPE} or defaults to {\tt rng_mt19937}.

\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: "american"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "pygsl"
%% TeX-parse-self: t
%% End:
