Provided by: pdl_2.007-2build1_amd64 bug

NAME

       PDL::GSL::RNG - PDL interface to RNG and randist routines in GSL

DESCRIPTION

       This is an interface to the rng and randist packages present in the GNU Scientific
       Library.

SYNOPSIS

          use PDL;
          use PDL::GSL::RNG;

          $rng = PDL::GSL::RNG->new('taus');

          $rng->set_seed(time());

          $a=zeroes(5,5,5)

          $rng->get_uniform($a); # inplace

          $b=$rng->get_uniform(3,4,5); # creates new pdl

FUNCTIONS

   new()
       The new method initializes a new instance of the RNG.

       The avaible RNGs are: coveyou cmrg fishman18 fishman20 fishman2x gfsr4 knuthran knuthran2
       knuthran2002 lecuyer21 minstd mrg mt19937 mt19937_1999 mt19937_1998 r250 ran0 ran1 ran2
       ran3 rand rand48 random128_bsd random128_glibc2 random128_libc5 random256_bsd
       random256_glibc2 random256_libc5 random32_bsd random32_glibc2 random32_libc5 random64_bsd
       random64_glibc2 random64_libc5 random8_bsd random8_glibc2 random8_libc5 random_bsd
       random_glibc2 random_libc5 randu ranf ranlux ranlux389 ranlxd1 ranlxd2 ranlxs0 ranlxs1
       ranlxs2 ranmar slatec taus taus2 taus113 transputer tt800 uni uni32 vax waterman14 zuf
       default The last one (default) uses the enviroment variable GSL_RNG_TYPE. Note that only a
       few of these rngs are recommended for general use. Please check the GSL documentation for
       more information.

       Usage:

          $blessed_ref = PDL::GSL::RNG->new($RNG_name);

       Example:

          $rng = PDL::GSL::RNG->new('taus');

   set_seed();
       Sets the RNG seed.

       Usage:

          $rng->set_seed($integer);

       Example:

          $rng->set_seed(666);

   min()
       Return the minimum value generable by this RNG.

       Usage:

          $integer = $rng->min();

       Example:

          $min = $rng->min(); $max = $rng->max();

   max()
       Return the maximum value generable by the RNG.

       Usage:

          $integer = $rng->max();

       Example:

          $min = $rng->min(); $max = $rng->max();

   name()
       Returns the name of the RNG.

       Usage:

          $string = $rng->name();

       Example:

          $name = $rng->name();

   get_uniform()
       This function creates a piddle with given dimensions or accept an existing piddle and
       fills it. get_uniform() returns values 0<=x<1,

       Usage:

          $piddle = $rng->get_uniform($list_of_integers)
          $rng->get_uniform($piddle);

       Example:

          $a = zeroes 5,6; $max=100;
          $o = $rng->get_uniform(10,10); $rng->get_uniform($a);

   get_uniform_pos()
       This function creates a piddle with given dimensions or accept an existing piddle and
       fills it. get_uniform_pos() returns values 0<x<1,

       Usage:

          $piddle = $rng->get_uniform_pos($list_of_integers)
          $rng->get_uniform_pos($piddle);

       Example:

          $a = zeroes 5,6;
          $o = $rng->get_uniform_pos(10,10); $rng->get_uniform_pos($a);

   get()
       This function creates a piddle with given dimensions or accept an existing piddle and
       fills it. get() returns integer values beetween a minimum and a maximum specific to evry
       RNG.

       Usage:

          $piddle = $rng->get($list_of_integers)
          $rng->get($piddle);

       Example:

          $a = zeroes 5,6;
          $o = $rng->get(10,10); $rng->get($a);

   get_int()
       This function creates a piddle with given dimensions or accept an existing piddle and
       fills it. get_int() returns integer values beetween 0 and $max.

       Usage:

          $piddle = $rng->get($max, $list_of_integers)
          $rng->get($max, $piddle);

       Example:

          $a = zeroes 5,6; $max=100;
          $o = $rng->get(10,10); $rng->get($a);

   ran_gaussian()
       These functions return random deviates from given distribution.

       The general form is

         ran_[distrib](args)

       where distrib can be any of the ones shown below.

       They accept the parameters of the distribution and a specification of where to put output.
       This spec can be in form of list of integers that specify the dimensions of the ouput
       piddle or an existing piddle that will be filled with values inplace.

       Usage:

          # gaussian dist
          $piddle = $rng->ran_gaussian($sigma,[list of integers]);
          $rng->ran_gaussian($sigma,$piddle);

          # gaussian tail
          $piddle = $rng->ran_ugaussian_tail($tail,[list of integers]);
          $rng->ran_ugaussian_tail($tail,$piddle);

          # exponential dist
          $piddle = $rng->ran_exponential($mu,[list of integers]);
          $rng->ran_exponential($mu,$piddle);

          # laplacian dist
          $piddle = $rng->ran_laplace($mu,[list of integers]);
          $rng->ran_laplace($mu,$piddle);

          $piddle = $rng->ran_exppow($mu,$a,[list of integers]);
          $rng->ran_exppow($mu,$a,$piddle);

          $piddle = $rng->ran_cauchy($mu,[list of integers]);
          $rng->ran_cauchy($mu,$piddle);

          $piddle = $rng->ran_rayleigh($sigma,[list of integers]);
          $rng->ran_rayleigh($sigma,$piddle);

          $piddle = $rng->ran_rayleigh_tail($a,$sigma,[list of integers]);
          $rng->ran_rayleigh_tail($a,$sigma,$piddle);

          $piddle = $rng->ran_levy($mu,$a,[list of integers]);
          $rng->ran_levy($mu,$a,$piddle);

          $piddle = $rng->ran_gamma($a,$b,[list of integers]);
          $rng->ran_gamma($a,$b,$piddle);

          $piddle = $rng->ran_flat($a,$b,[list of integers]);
          $rng->ran_flat($a,$b,$piddle);

          $piddle = $rng->ran_lognormal($zeta, $sigma,[list of integers]);
          $rng->ran_lognormal($zeta, $sigma,$piddle);

          $piddle = $rng->ran_chisq($nu,[list of integers]);
          $rng->ran_chisq($nu,$piddle);

          $piddle = $rng->ran_fdist($nu1, $nu2,[list of integers]);
          $rng->ran_fdist($nu1, $nu2,$piddle);

          $piddle = $rng->ran_tdist($nu,[list of integers]);
          $rng->ran_tdist($nu,$piddle);

          $piddle = $rng->ran_beta($a,$b,[list of integers]);
          $rng->ran_beta($a,$b,$piddle);

          $piddle = $rng->ran_logistic($m,[list of integers]u)
          $rng->ran_logistic($m,$piddleu)

          $piddle = $rng->ran_pareto($a,$b,[list of integers]);
          $rng->ran_pareto($a,$b,$piddle);

          $piddle = $rng->ran_weibull($mu,$a,[list of integers]);
          $rng->ran_weibull($mu,$a,$piddle);

          $piddle = $rng->ran_gumbel1($a,$b,[list of integers]);
          $rng->ran_gumbel1($a,$b,$piddle);

          $piddle = $rng->ran_gumbel2($a,$b,[list of integers]);
          $rng->ran_gumbel2($a,$b,$piddle);

          $piddle = $rng->ran_poisson($mu,[list of integers]);
          $rng->ran_poisson($mu,$piddle);

          $piddle = $rng->ran_bernoulli($p,[list of integers]);
          $rng->ran_bernoulli($p,$piddle);

          $piddle = $rng->ran_binomial($p,$n,[list of integers]);
          $rng->ran_binomial($p,$n,$piddle);

          $piddle = $rng->ran_negative_binomial($p,$n,[list of integers]);
          $rng->ran_negative_binomial($p,$n,$piddle);

          $piddle = $rng->ran_pascal($p,$n,[list of integers]);
          $rng->ran_pascal($p,$n,$piddle);

          $piddle = $rng->ran_geometric($p,[list of integers]);
          $rng->ran_geometric($p,$piddle);

          $piddle = $rng->ran_hypergeometric($n1, $n2, $t,[list of integers]);
          $rng->ran_hypergeometric($n1, $n2, $t,$piddle);

          $piddle = $rng->ran_logarithmic($p,[list of integers]);
          $rng->ran_logarithmic($p,$piddle);

       Example:

         $o = $rng->ran_gaussian($sigma,10,10);
         $rng->ran_gaussian($sigma,$a);

   ran_gaussian_var()
       This method is similar to ran_[distrib]() except that it takes the parameters of the
       distribution as a piddle and returns a piddle of equal dimensions. Of course, you can use
       the same set of distributions as in the previous method (see also the ran_gaussian entry
       above).

       Usage:

          $piddle = $rng->ran_[distribution]_var($distr_parameters_list,$piddle_dim_list);
          $rng->ran_[distribution]_var($distr_parameters_list,$piddle);

       Example:

          $sigma_pdl = rvals zeroes 11,11;
          $o = $rng->ran_gaussian_var($sigma_pdl);

   ran_additive_gaussian()
       Add Gaussian noise of given sigma to a piddle.

       Usage:

          $rng->ran_additive_gaussian($sigma,$piddle);

       Example:

          $rng->ran_additive_gaussian(1,$image);

   ran_additive_poisson()
       Add Poisson noise of given sigma to a piddle.

       Usage:

          $rng->ran_additive_poisson($mu,$piddle);

       Example:

          $rng->ran_additive_poisson(1,$image);

   ran_feed_poisson()
       This method simulates shot noise, taking the values of piddle as values for mu to be fed
       in the poissonian RNG.

       Usage:

          $rng->ran_feed_poisson($piddle);

       Example:

          $rng->ran_feed_poisson($image);

   ran_bivariate_gaussian()
       Generates $n bivariate gaussian random deviates.

       Usage:

          $piddle = $rng->ran_bivariate_gaussian($sigma_x,$sigma_y,$rho,$n);

       Example:

          $o = $rng->ran_bivariate_gaussian(1,2,0.5,1000);

   ran_dir()
       Returns $n random vectors in $ndim dimensions.

       Usage:

          $piddle = $rng->ran_dir($ndim,$n);

       Example:

          $o = $rng->ran_dir($ndim,$n);

   ran_discrete_preproc()
       This method returns a handle that must be used when calling ran_discrete(). You specify
       the probability of the integer number that are returned by ran_discrete().

       Usage:

          $discrete_dist_handle = $rng->ran_discrete_preproc($double_piddle_prob);

       Example:

          $prob = pdl [0.1,0.3,0.6];
          $ddh = $rng->ran_discrete_preproc($prob);
          $o = $rng->ran_discrete($discrete_dist_handle,100);

   ran_discrete()
       Is used to get the desired samples once a proper handle has been enstablished (see
       ran_discrete_preproc()).

       Usage:

          $piddle = $rng->ran_discrete($discrete_dist_handle,$num);

       Example:

          $prob = pdl [0.1,0.3,0.6];
          $ddh = $rng->ran_discrete_preproc($prob);
          $o = $rng->ran_discrete($discrete_dist_handle,100);

   ran_shuffle()
       Shuffles values in piddle

       Usage:

          $rng->ran_shuffle($piddle);

   ran_shuffle_vec()
       Shuffles values in piddle

       Usage:

          $rng->ran_shuffle_vec(@vec);

   ran_choose()
       Chooses values from $inpiddle to $outpiddle.

       Usage:

          $rng->ran_choose($inpiddle,$outpiddle);

   ran_choose_vec()
       Chooses $n values from @vec.

       Usage:

          @choosen = $rng->ran_choose_vec($n,@vec);

   ran_ver()
       Returns a piddle with $n values generated by the Verhulst map from $x0 and paramater $r.

       Usage:

          $rng->ran_ver($x0, $r, $n);

   ran_caos()
       Returns values from Verhuls map with $r=4.0 and randomly choosen $x0. The values are
       scaled by $m.

       Usage:

          $rng->ran_caos($m,$n);

BUGS

       Feedback is welcome. Log bugs in the PDL bug database (the database is always linked from
       <http://pdl.perl.org/>).

SEE ALSO

       PDL

       The GSL documentation is online at <http://www.gnu.org/software/gsl/manual/html_node/>

AUTHOR

       This file copyright (C) 1999 Christian Pellegrin <chri@infis.univ.trieste.it> Docs mangled
       by C. Soeller. All rights reserved. There is no warranty. You are allowed to redistribute
       this software / documentation under certain conditions. For details, see the file COPYING
       in the PDL distribution. If this file is separated from the PDL distribution, the
       copyright notice should be included in the file.

       The GSL RNG and randist modules were written by James Theiler.