++ed by:
SALVA MOOCOW DEMIAN SAPER SHLOMIF

16 PAUSE users
10 non-PAUSE users.

Chris Marshall
and 1 contributors

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);
   # or
   $rng = PDL::GSL::RNG->new('taus')->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

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);

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);

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_gaussian

Fills output piddle with random values from Gaussian distribution with mean zero and standard deviation $sigma.

Usage:

 $piddle = $rng->ran_gaussian($sigma,[list of integers = output piddle dims]);
 $rng->ran_gaussian($sigma, $output_piddle);

Example:

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

ran_gaussian_var

This method is similar to ran_gaussian except that it takes the parameters of the distribution as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_gaussian_var($sigma_piddle);
   $rng->ran_gaussian_var($sigma_piddle, $output_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_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_poisson

Fills output piddle by with random integer values from the Poisson distribution with mean $mu.

Usage:

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

ran_poisson_var

Similar to ran_poisson except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_poisson_var($mu_piddle);

ran_additive_poisson

Add Poisson noise of given $mu 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_bernoulli

Fills output piddle with random values 0 or 1, the result of a Bernoulli trial with probability $p.

Usage:

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

ran_bernoulli_var

Similar to ran_bernoulli except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_bernoulli_var($p_piddle);

ran_beta

Fills output piddle with random variates from the beta distribution with parameters $a and $b.

Usage:

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

ran_beta_var

Similar to ran_beta except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_beta_var($a_piddle, $b_piddle);

ran_binomial

Fills output piddle with random integer values from the binomial distribution, the number of successes in $n independent trials with probability $p.

Usage:

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

ran_binomial_var

Similar to ran_binomial except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_binomial_var($p_piddle, $n_piddle);

ran_cauchy

Fills output piddle with random variates from the Cauchy distribution with scale parameter $a.

Usage:

   $piddle = $rng->ran_cauchy($a,[list of integers = output piddle dims]);
   $rng->ran_cauchy($a,$output_piddle);

ran_cauchy_var

Similar to ran_cauchy except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_cauchy_var($a_piddle);

ran_chisq

Fills output piddle with random variates from the chi-squared distribution with $nu degrees of freedom.

Usage:

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

ran_chisq_var

Similar to ran_chisq except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_chisq_var($nu_piddle);

ran_exponential

Fills output piddle with random variates from the exponential distribution with mean $mu.

Usage:

   $piddle = $rng->ran_exponential($mu,[list of integers = output piddle dims]);
   $rng->ran_exponential($mu,$output_piddle);

ran_exponential_var

Similar to ran_exponential except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_exponential_var($mu_piddle);

ran_exppow

Fills output piddle with random variates from the exponential power distribution with scale parameter $a and exponent $b.

Usage:

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

ran_exppow_var

Similar to ran_exppow except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_exppow_var($mu_piddle, $a_piddle);

ran_fdist

Fills output piddle with random variates from the F-distribution with degrees of freedom $nu1 and $nu2.

Usage:

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

ran_fdist_var

Similar to ran_fdist except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_fdist_var($nu1_piddle, $nu2_piddle);

ran_flat

Fills output piddle with random variates from the flat (uniform) distribution from $a to $b.

Usage:

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

ran_flat_var

Similar to ran_flat except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_flat_var($a_piddle, $b_piddle);

ran_gamma

Fills output piddle with random variates from the gamma distribution.

Usage:

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

ran_gamma_var

Similar to ran_gamma except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_gamma_var($a_piddle, $b_piddle);

ran_geometric

Fills output piddle with random integer values from the geometric distribution, the number of independent trials with probability $p until the first success.

Usage:

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

ran_geometric_var

Similar to ran_geometric except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_geometric_var($p_piddle);

ran_gumbel1

Fills output piddle with random variates from the Type-1 Gumbel distribution.

Usage:

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

ran_gumbel1_var

Similar to ran_gumbel1 except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_gumbel1_var($a_piddle, $b_piddle);

ran_gumbel2

Fills output piddle with random variates from the Type-2 Gumbel distribution.

Usage:

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

ran_gumbel2_var

Similar to ran_gumbel2 except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_gumbel2_var($a_piddle, $b_piddle);

ran_hypergeometric

Fills output piddle with random integer values from the hypergeometric distribution. If a population contains $n1 elements of type 1 and $n2 elements of type 2 then the hypergeometric distribution gives the probability of obtaining $x elements of type 1 in $t samples from the population without replacement.

Usage:

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

ran_hypergeometric_var

Similar to ran_hypergeometric except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_hypergeometric_var($n1_piddle, $n2_piddle, $t_piddle);

ran_laplace

Fills output piddle with random variates from the Laplace distribution with width $a.

Usage:

   $piddle = $rng->ran_laplace($a,[list of integers = output piddle dims]);
   $rng->ran_laplace($a,$output_piddle);

ran_laplace_var

Similar to ran_laplace except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_laplace_var($a_piddle);

ran_levy

Fills output piddle with random variates from the Levy symmetric stable distribution with scale $c and exponent $alpha.

Usage:

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

ran_levy_var

Similar to ran_levy except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_levy_var($mu_piddle, $a_piddle);

ran_logarithmic

Fills output piddle with random integer values from the logarithmic distribution.

Usage:

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

ran_logarithmic_var

Similar to ran_logarithmic except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_logarithmic_var($p_piddle);

ran_logistic

Fills output piddle with random random variates from the logistic distribution.

Usage:

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

ran_logistic_var

Similar to ran_logistic except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_logistic_var($m_piddle);

ran_lognormal

Fills output piddle with random variates from the lognormal distribution with parameters $mu (location) and $sigma (scale).

Usage:

   $piddle = $rng->ran_lognormal($mu,$sigma,[list of integers = output piddle dims]);
   $rng->ran_lognormal($mu,$sigma,$output_piddle);

ran_lognormal_var

Similar to ran_lognormal except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_lognormal_var($mu_piddle, $sigma_piddle);

ran_negative_binomial

Fills output piddle with random integer values from the negative binomial distribution, the number of failures occurring before $n successes in independent trials with probability $p of success. Note that $n is not required to be an integer.

Usage:

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

ran_negative_binomial_var

Similar to ran_negative_binomial except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_negative_binomial_var($p_piddle, $n_piddle);

ran_pareto

Fills output piddle with random variates from the Pareto distribution of order $a and scale $b.

Usage:

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

ran_pareto_var

Similar to ran_pareto except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_pareto_var($a_piddle, $b_piddle);

ran_pascal

Fills output piddle with random integer values from the Pascal distribution. The Pascal distribution is simply a negative binomial distribution (see ran_negative_binomial) with an integer value of $n.

Usage:

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

ran_pascal_var

Similar to ran_pascal except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_pascal_var($p_piddle, $n_piddle);

ran_rayleigh

Fills output piddle with random variates from the Rayleigh distribution with scale parameter $sigma.

Usage:

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

ran_rayleigh_var

Similar to ran_rayleigh except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_rayleigh_var($sigma_piddle);

ran_rayleigh_tail

Fills output piddle with random variates from the tail of the Rayleigh distribution with scale parameter $sigma and a lower limit of $a.

Usage:

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

ran_rayleigh_tail_var

Similar to ran_rayleigh_tail except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_rayleigh_tail_var($a_piddle, $sigma_piddle);

ran_tdist

Fills output piddle with random variates from the t-distribution (AKA Student's t-distribution) with $nu degrees of freedom.

Usage:

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

ran_tdist_var

Similar to ran_tdist except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_tdist_var($nu_piddle);

ran_ugaussian_tail

Fills output piddle with random variates from the upper tail of a Gaussian distribution with standard deviation = 1 (AKA unit Gaussian distribution).

Usage:

   $piddle = $rng->ran_ugaussian_tail($tail,[list of integers = output piddle dims]);
   $rng->ran_ugaussian_tail($tail,$output_piddle);

ran_ugaussian_tail_var

Similar to ran_ugaussian_tail except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_ugaussian_tail_var($tail_piddle);

ran_weibull

Fills output piddle with random variates from the Weibull distribution.

Usage:

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

ran_weibull_var

Similar to ran_weibull except that it takes the distribution parameters as a piddle and returns a piddle of equal dimensions.

Usage:

   $piddle = $rng->ran_weibull_var($mu_piddle, $a_piddle);

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_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.