README

NAME

Math::Libgsl::RandomDistribution - An interface to libgsl, the Gnu Scientific Library - Random Number Distributions

SYNOPSIS

use Math::Libgsl::Random;
use Math::Libgsl::RandomDistribution;

my Math::Libgsl::Random $r .= new;
say poisson($r, 3) for ^10;

DESCRIPTION

Math::Libgsl::RandomDistribution is an interface to the Random Number Distributions section of libgsl, the Gnu Scientific Library.

gaussian(Math::Libgsl::Random sigma --> Num)

This function returns a Gaussian random variate, with mean zero and standard deviation $sigma.

gaussian-pdf(Num() sigma --> Num)

This function computes the probability density at sigma.

gaussian-ziggurat(Math::Libgsl::Random sigma --> Num)

gaussian-ratio-method(Math::Libgsl::Random sigma --> Num)

This function computes a Gaussian random variate using the alternative Marsaglia-Tsang ziggurat and Kinderman-Monahan-Leva ratio methods.

ugaussian(Math::Libgsl::Random $r --> Num)

ugaussian-pdf(Num() $x --> Num)

ugaussian-ratio-method(Math::Libgsl::Random $r --> Num)

These functions compute results for the unit Gaussian distribution. They are equivalent to the functions above with $sigma = 1.

gaussian-P(Num() sigma --> Num)

gaussian-Q(Num() sigma --> Num)

gaussian-Pinv(Num() sigma --> Num)

gaussian-Qinv(Num() sigma --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses.

ugaussian-P(Num() $x --> Num)

ugaussian-Q(Num() $x --> Num)

ugaussian-Pinv(Num() $P --> Num)

ugaussian-Qinv(Num() $Q --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the unit Gaussian distribution.

gaussian-tail(Math::Libgsl::Random a where * > 0, Num() $sigma --> Num)

This function provides random variates from the upper tail of a Gaussian distribution with standard deviation $sigma.

gaussian-tail-pdf(Num() a where * > 0, Num() $sigma --> Num)

This function computes the probability density p(x) at sigma and lower limit $a.

ugaussian-tail(Math::Libgsl::Random a where * > 0 --> Num)

ugaussian-tail-pdf(Num() a where * > 0 --> Num)

These functions compute results for the tail of a unit Gaussian distribution.

bivariate-gaussian(Math::Libgsl::Random sigma-x, Num() rho where -1 < * < 1 --> List)

This function generates a pair of correlated Gaussian variates, with mean zero, correlation coefficient sigma_x and $sigma_y. The function returns two Num values: the Gauusian correlates along the x and y directions.

bivariate-gaussian-pdf(Num() y, Num() sigma-y, Num() $rho where -1 < * < 1 --> Num)

This function computes the probability density p(x, y) at (y) for a bivariate Gaussian distribution with standard deviations sigma_y and correlation coefficient $rho.

multivariate-gaussian(Math::Libgsl::Random mu, Math::Libgsl::Matrix L.matrix.size1 == L.matrix.size1 == $mu.vector.size } --> Math::Libgsl::Vector)

This function generates a random vector satisfying the k-dimensional multivariate Gaussian distribution with mean μ and variance-covariance matrix Σ. On input, the k-vector μ is given in L, as output from Math::Libgsl::LinearAlgebra::cholesky-decomp(). The function returns the random vector as a Math::Libgsl::Vector object.

multivariate-gaussian-pdf(Math::Libgsl::Vector mu where *.vector.size == L where { L.matrix.size2 && mu.vector.size } --> Num)

multivariate-gaussian-log-pdf(Math::Libgsl::Vector mu where *.vector.size == L where { L.matrix.size2 && mu.vector.size } --> Num)

These functions compute p(x) or log p(x) at the point mu and variance-covariance matrix specified by its Cholesky factor $L.

multivariate-gaussian-mean(Math::Libgsl::Matrix $X --> Math::Libgsl::Vector)

Given a set of n samples Xⱼ from a k-dimensional multivariate Gaussian distribution, this function computes the maximum likelihood estimate of the mean of the distribution. The function returns the maximum likelihood estimate as a Math::Libgsl::Vector object.

multivariate-gaussian-vcov(Math::Libgsl::Matrix $X --> Math::Libgsl::Matrix)

Given a set of n samples Xⱼ from a k-dimensional multivariate Gaussian distribution, this function computes the maximum likelihood estimate of the variance-covariance matrix of the distribution. The function returns the maximum likelihood estimate of the variance-covariance matrix as a Math::Libgsl::Matrix object.

exponential(Math::Libgsl::Random mu --> Num)

This function returns a random variate from the exponential distribution with mean $mu.

exponential-pdf(Num() mu --> Num)

This function computes the probability density p(x) at mu.

exponential-P(Num() mu --> Num)

exponential-Q(Num() mu --> Num)

exponential-Pinv(Num() mu --> Num)

exponential-Qinv(Num() mu --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the exponential distribution with mean $mu.

laplace(Math::Libgsl::Random a --> Num)

This function returns a random variate from the Laplace distribution with width $a.

laplace-pdf(Num() a --> Num)

This function computes the probability density p(x) at a.

laplace-P(Num() a --> Num)

laplace-Q(Num() a --> Num)

laplace-Pinv(Num() a --> Num)

laplace-Qinv(Num() a --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the Laplace distribution with width $a.

exppow(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the exponential power distribution with scale parameter b.

exppow-pdf(Num() a, Num() $b --> Num)

This function computes the probability density p(x) at a and exponent $b.

exppow-P(Num() a, Num() $b --> Num)

exppow-Q(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) for the exponential power distribution with parameters b.

cauchy(Math::Libgsl::Random a --> Num)

This function returns a random variate from the Cauchy distribution with scale parameter $a.

cauchy-pdf(Num() a --> Num)

This function computes the probability density p(x) at a.

cauchy-P(Num() a --> Num)

cauchy-Q(Num() a --> Num)

cauchy-Pinv(Num() a --> Num)

cauchy-Qinv(Num() a --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the Cauchy distribution with scale parameter $a.

rayleigh(Math::Libgsl::Random sigma --> Num)

This function returns a random variate from the Rayleigh distribution with scale parameter $sigma.

rayleigh-pdf(Num() sigma --> Num)

This function computes the probability density p(x) at sigma.

rayleigh-P(Num() sigma --> Num)

rayleigh-Q(Num() sigma --> Num)

rayleigh-Pinv(Num() sigma --> Num)

rayleigh-Qinv(Num() sigma --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the Rayleigh distribution with scale parameter $sigma.

rayleigh-tail(Math::Libgsl::Random a, Num() $sigma --> Num)

This function returns a random variate from the tail of the Rayleigh distribution with scale parameter a.

rayleigh-tail-pdf(Num() a, Num() $sigma --> Num)

This function computes the probability density p(x) at sigma and lower limit $a.

landau(Math::Libgsl::Random $r --> Num)

This function returns a random variate from the Landau distribution.

landau-pdf(Num() $x --> Num)

This function computes the probability density p(x) at $x for the Landau distribution.

levy(Math::Libgsl::Random c, Num() $alpha where 0 < * ≤ 2 --> Num)

This function returns a random variate from the Levy symmetric stable distribution with scale alpha.

levy-skew(Math::Libgsl::Random c, Num() beta --> Num)

This function returns a random variate from the Levy skew stable distribution with scale alpha and skewness parameter $beta.

gamma(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the gamma distribution.

gamma-knuth(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a gamma variate using the algorithms from Knuth.

gamma-pdf(Num() a, Num() $b --> Num)

This function computes the probability density p(x) at a and $b.

gamma-P(Num() a, Num() $b --> Num)

gamma-Q(Num() a, Num() $b --> Num)

gamma-Pinv(Num() a, Num() $b --> Num)

gamma-Qinv(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the gamma distribution with parameters b.

flat(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the flat (uniform) distribution from b.

flat-pdf(Num() a, Num() $b --> Num)

This function computes the probability density p(x) at a to $b.

flat-P(Num() a, Num() $b --> Num)

flat-Q(Num() a, Num() $b --> Num)

flat-Pinv(Num() a, Num() $b --> Num)

flat-Qinv(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for a uniform distribution from b.

lognormal(Math::Libgsl::Random zeta, Num() $sigma --> Num)

This function returns a random variate from the lognormal distribution.

lognormal-pdf(Num() zeta, Num() $sigma --> Num)

This function computes the probability density p(x) at zeta and $sigma.

lognormal-P(Num() zeta, Num() $sigma --> Num)

lognormal-Q(Num() zeta, Num() $sigma --> Num)

lognormal-Pinv(Num() zeta, Num() $sigma --> Num)

lognormal-Qinv(Num() zeta, Num() $sigma --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the lognormal distribution with parameters sigma.

chisq(Math::Libgsl::Random nu --> Num)

This function returns a random variate from the chi-squared distribution with $nu degrees of freedom.

chisq-pdf(Num() nu --> Num)

This function computes the probability density p(x) at nu degrees of freedom.

chisq-P(Num() nu --> Num)

chisq-Q(Num() nu --> Num)

chisq-Pinv(Num() nu --> Num)

chisq-Qinv(Num() nu --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the chi-squared distribution with $nu degrees of freedom.

fdist(Math::Libgsl::Random nu1, Num() $nu2 --> Num)

This function returns a random variate from the F-distribution with degrees of freedom nu2.

fdist-pdf(Num() nu1, Num() $nu2 --> Num)

This function computes the probability density p(x) at nu1 and $nu2 degrees of freedom.

fdist-P(Num() nu1, Num() $nu2 --> Num)

fdist-Q(Num() nu1, Num() $nu2 --> Num)

fdist-Pinv(Num() nu1, Num() $nu2 --> Num)

fdist-Qinv(Num() nu1, Num() $nu2 --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the F-distribution with nu2 degrees of freedom.

tdist(Math::Libgsl::Random nu --> Num)

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

tdist-pdf(Num() nu --> Num)

This function computes the probability density p(x) at nu degrees of freedom.

tdist-P(Num() nu --> Num)

tdist-Q(Num() nu --> Num)

tdist-Pinv(Num() nu --> Num)

tdist-Qinv(Num() nu --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the t-distribution with $nu degrees of freedom.

beta(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the beta distribution.

beta-pdf(Num() a, Num() $b --> Num)

This function computes the probability density p(x) at a and $b.

beta-P(Num() a, Num() $b --> Num)

beta-Q(Num() a, Num() $b --> Num)

beta-Pinv(Num() a, Num() $b --> Num)

beta-Qinv(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the beta distribution with parameters b.

logistic(Math::Libgsl::Random a --> Num)

This function returns a random variate from the logistic distribution.

logistic-pdf(Num() a --> Num)

This function computes the probability density p(x) at a.

logistic-P(Num() a --> Num)

logistic-Q(Num() a --> Num)

logistic-Pinv(Num() a --> Num)

logistic-Qinv(Num() a --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the logistic distribution with scale parameter $a.

pareto(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the Pareto distribution of order b.

pareto-pdf(Num() a, Num() x ≥ $b } --> Num)

This function computes the probability density p(x) at a and scale $b.

pareto-P(Num() a, Num() x ≥ $b } --> Num)

pareto-Q(Num() a, Num() x ≥ $b } --> Num)

pareto-Pinv(Num() a, Num() $b --> Num)

pareto-Qinv(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the Pareto distribution with exponent b.

d2dir(Math::Libgsl::Random $r --> List)

d2dir-trig-method(Math::Libgsl::Random $r --> List)

This function returns a random direction vector v = (x, y) in two dimensions. The return value is a List of two Num(s): the x and y components of the 2D vector.

d3dir(Math::Libgsl::Random $r --> List)

This function returns a random direction vector v = (x, y, z) in three dimensions. The return value is a List of three Num(s): the x, y, and z components of the 3D vector.

dndir(Math::Libgsl::Random n --> List)

This function returns a random direction vector v = (x 1 , x 2 , . . . , x n ) in n Num(s): the components of the n-D vector.

weibull(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the Weibull distribution.

weibull-pdf(Num() x ≥ 0, Num() b --> Num)

This function computes the probability density p(x) at a and exponent $b.

weibull-P(Num() x ≥ 0, Num() b --> Num)

weibull-Q(Num() x ≥ 0, Num() b --> Num)

weibull-Pinv(Num() a, Num() $b --> Num)

weibull-Qinv(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the Weibull distribution with scale b.

gumbel1(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the Type-1 Gumbel distribution.

gumbel1-pdf(Num() a, Num() $b --> Num)

This function computes the probability density p(x) at a and $b.

gumbel1-P(Num() a, Num() $b --> Num)

gumbel1-Q(Num() a, Num() $b --> Num)

gumbel1-Pinv(Num() a, Num() $b --> Num)

gumbel1-Qinv(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the Type-1 Gumbel distribution with parameters b.

gumbel2(Math::Libgsl::Random a, Num() $b --> Num)

This function returns a random variate from the Type-2 Gumbel distribution.

gumbel2-pdf(Num() a, Num() $b --> Num)

This function computes the probability density p(x) at a and $b.

gumbel2-P(Num() a, Num() $b --> Num)

gumbel2-Q(Num() a, Num() $b --> Num)

gumbel2-Pinv(Num() a, Num() $b --> Num)

gumbel2-Qinv(Num() a, Num() $b --> Num)

These functions compute the cumulative distribution functions P(x), Q(x) and their inverses for the Type-2 Gumbel distribution with parameters b.

dirichlet(Math::Libgsl::Random K, @alpha where *.all > 0 --> List)

This function returns an array of K random variates as a List of Num(s) from a Dirichlet distribution of order K-1.

dirichlet-pdf(Int $K, @alpha where _.all > 0, @theta where _.all ≥ 0 --> Num)

This function computes the probability density p(θ₁, …, θₖ) at theta[K] for a Dirichlet distribution with parameters alpha[K].

dirichlet-lnpdf(Int $K, @alpha where _.all > 0, @theta where _.all ≥ 0 --> Num)

This function computes the logarithm of the probability density p(θ₁, …, θₖ) at theta[K] for a Dirichlet distribution with parameters alpha[K].

poisson(Math::Libgsl::Random mu --> UInt)

This function returns a random integer from the Poisson distribution with mean $mu.

poisson-pdf(UInt mu --> Num)

This function computes the probability p(k) of obtaining mu.

poisson-P(UInt mu --> Num)

poisson-Q(UInt mu --> Num)

These functions compute the cumulative distribution functions P(k), Q(k) for the Poisson distribution with parameter $mu.

bernoulli(Math::Libgsl::Random p --> Int)

This function returns either 0 or 1, the result of a Bernoulli trial with probability $p.

bernoulli-pdf(UInt p --> Num)

This function computes the probability p(k) of obtaining p.

binomial(Math::Libgsl::Random p, UInt $n --> Int)

This function returns a random integer from the binomial distribution, the number of successes in p.

binomial-pdf(UInt p, UInt k --> Num)

This function computes the probability p(k) of obtaining p and $n.

binomial-P(UInt p, UInt k --> Num)

binomial-Q(UInt p, UInt k --> Num)

These functions compute the cumulative distribution functions P (k), Q(k) for the binomial distribution with parameters n.

multinomial(Math::Libgsl::Random K, UInt $N, *@p where { @p.all ~~ Numeric } --> List)

This function returns a random sample from the multinomial distribution formed by $N trials from an underlying distribution p[K] as a List of UInt(s).

multinomial-pdf(Int $K, @p where { @p.all Numeric }, *@n where { @n.all UInt } --> Num)

This function computes the probability P(n₁, n₂, …, nₖ) of sampling n[K] from a multinomial distribution with parameters p[K].

multinomial-lnpdf(Int $K, @p where { @p.all Numeric }, *@n where { @n.all UInt } --> Num)

This function computes the logarithm of the probability P(n₁, n₂, …, nₖ) for the multinomial distribution with parameters p[K].

negative-binomial(Math::Libgsl::Random p, Num() $n --> UInt)

This function returns a random integer from the negative binomial distribution.

negative-binomial-pdf(UInt p, Num() $n --> Num)

This function computes the probability p(k) of obtaining p and $n.

negative-binomial-P(UInt p, Num() $n --> Num)

negative-binomial-Q(UInt p, Num() $n --> Num)

These functions compute the cumulative distribution functions P(k), Q(k) for the negative binomial distribution with parameters n.

pascal(Math::Libgsl::Random p, UInt $n --> UInt)

This function returns a random integer from the Pascal distribution.

pascal-pdf(UInt p, UInt $n --> Num)

This function computes the probability p(k) of obtaining p and $n.

pascal-P(UInt p, UInt $n --> Num)

pascal-Q(UInt p, UInt $n --> Num)

These functions compute the cumulative distribution functions P(k), Q(k) for the Pascal distribution with parameters n.

geometric(Math::Libgsl::Random p --> UInt)

This function returns a random integer from the geometric distribution, the number of independent trials with probability $p until the first success.

geometric-pdf(UInt p --> Num)

This function computes the probability p(k) of obtaining p.

geometric-P(UInt p --> Num)

geometric-Q(UInt p --> Num)

These functions compute the cumulative distribution functions P(k), Q(k) for the geometric distribution with parameter $p.

hypergeometric(Math::Libgsl::Random n1, UInt t --> UInt)

This function returns a random integer from the hypergeometric distribution.

hypergeometric-pdf(UInt n1, UInt t --> Num)

This function computes the probability p(k) of obtaining n1, t.

hypergeometric-P(UInt n1, UInt t --> Num)

hypergeometric-Q(UInt n1, UInt t --> Num)

These functions compute the cumulative distribution functions P(k), Q(k) for the hypergeometric distribution with parameters n2 and $t.

logarithmic(Math::Libgsl::Random p --> UInt)

This function returns a random integer from the logarithmic distribution.

logarithmic-pdf(UInt p --> Num)

This function computes the probability p(k) of obtaining p.

wishart(Math::Libgsl::Random n, Math::Libgsl::Matrix L.matrix.size1 == n ≤ $L.matrix.size1 - 1 } --> Math::Libgsl::Matrix)

This function returns a random symmetric p-by-p matrix from the Wishart distribution as a Math::Libgsl::Matrix object.

wishart-pdf(Math::Libgsl::Matrix X.matrix.size1 == L-X where { L-X.matrix.size2 }, Num() X.matrix.size1 - 1, Math::Libgsl::Matrix L.matrix.size1 == X.matrix.size1 == L-X.matrix.size1 == $L.matrix.size1 } --> Num)

wishart-log-pdf(Math::Libgsl::Matrix X.matrix.size1 == L-X where { L-X.matrix.size2 }, Num() X.matrix.size1 - 1, Math::Libgsl::Matrix L.matrix.size1 == X.matrix.size1 == L-X.matrix.size1 == $L.matrix.size1 } --> Num)

These functions return p(X) or log p(X) for the p-by-p matrix L-X. The degrees of freedom is given by L.

shuffle(Math::Libgsl::Random $r, @base --> List)

This function randomly shuffles the order of the elements of the array @base and returns them as a List.

choose(Math::Libgsl::Random k, @src where *.elems ≥ $k --> List)

This function returns the list of $k objects taken randomly from the elements of the array @src.

sample(Math::Libgsl::Random k, @src --> List)

This function is like choose() but samples $k items from the original array of n items @src with replacement, so the same object can appear more than once in the output.

Class Math::Libgsl::RandomDistribution::Discrete

This probability distribution needs a lookup table for the discrete random number generator, so it's implemented as a class, which hides the implementation details.

use Math::Libgsl::RandomDistribution;
use Math::Libgsl::Random;

my Int $size = 3;
my @probability = .59, .4, .01;
my Math::Libgsl::Random $r .= new;
my Math::Libgsl::RandomDistribution::Discrete $d .= new: :$size, :@probability;

say "Using probability values: { $d.probability }";
say $d.discrete($r) for ^10;

say $d.discrete-pdf(2);

new(Int() :$size, :@probability where *.all > 0)

Creates the lookup table for the discrete random number generator. The array @probability contains the probabilities of the discrete events.

discrete(Math::Libgsl::Random $r --> Int)

This method returns one discrete random number.

discrete-pdf(Int $k --> Num)

This method returns the probability P[k] of observing the variable $k.

C Library Documentation

For more details on libgsl see https://www.gnu.org/software/gsl/. The excellent C Library manual is available here https://www.gnu.org/software/gsl/doc/html/index.html, or here https://www.gnu.org/software/gsl/doc/latex/gsl-ref.pdf in PDF format.

Prerequisites

This module requires the libgsl library to be installed. Please follow the instructions below based on your platform:

Debian Linux and Ubuntu 20.04+

sudo apt install libgsl23 libgsl-dev libgslcblas0

That command will install libgslcblas0 as well, since it's used by the GSL.

Ubuntu 18.04

libgsl23 and libgslcblas0 have a missing symbol on Ubuntu 18.04. I solved the issue installing the Debian Buster version of those three libraries:

Installation

To install it using zef (a module management tool):

$ zef install Math::Libgsl::RandomDistribution

AUTHOR

Fernando Santagata [email protected]

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.