Distributions v0.1.0

Binomial<G>

pub func Binomial<G: RandomGenerator>(
    generator: &var G,
    trials: uint64,
    probability: float64
) -> uint64

The number of successes in trials independent trials each succeeding with probability probability. A probability at or below zero gives zero successes and one at or above one gives every trial, matching Bernoulli's treatment of the same edges. Zero trials give zero. Small counts are summed directly, which is the definition. Large ones are split by a beta draw: the median trial's success probability has a beta distribution, and comparing it to probability says which side the answer falls on and leaves a strictly smaller problem. That halves the count each step, so a binomial over a billion trials costs about thirty draws rather than a billion.

Source

Type parameters

Parameters

Returns: how many of trials succeeded

Poisson<G>

pub func Poisson<G: RandomGenerator>(
    generator: &var G,
    mean: float64
) -> uint64

The number of events in one interval when they arrive independently at the given mean rate. A mean at or below zero gives zero. A small mean uses Knuth's method — multiply uniforms until the product falls below exp(-mean) — which costs about mean draws and is exact. A large mean would cost too many draws that way, and the product would underflow to zero before the loop ended, so the mean is consumed in chunks: a gamma draw of integer shape is the waiting time for that many events, and either it overshoots the interval, in which case the count is a binomial of what is left, or it fits and the remainder carries on.

Source

Type parameters

Parameters

Returns: a draw from the Poisson distribution with that mean

Bernoulli<G>

pub func Bernoulli<G: RandomGenerator>(
    generator: &var G,
    probability: float64
) -> bool

A coin that comes up true with probability probability. A probability at or below zero never comes up true and one at or above one always does, so a caller computing a probability that drifts slightly out of range gets the sensible answer rather than an occasional inversion. The comparison is against a draw in [0, 1), so a probability of exactly zero is impossible rather than merely rare — which is what makes the two ends behave.

Source

Type parameters

Parameters

Returns: true with the given probability

Exponential<G>

pub func Exponential<G: RandomGenerator>(generator: &var G) -> float64

A value from the exponential distribution with rate one. The inverse-transform method: the negated logarithm of a uniform draw. Written on 1 - u rather than on u because NextFloat64 can return exactly zero, whose logarithm is an infinity — so the draw that would produce an infinite sample is instead the one that produces zero, which the distribution does allow. Multiply the result by a mean, or divide by a rate, to scale it.

Source

Type parameters

Parameters

Returns: a draw from the exponential distribution with rate one

ExponentialWithRate<G>

pub func ExponentialWithRate<G: RandomGenerator>(
    generator: &var G,
    rate: float64
) -> float64

A value from the exponential distribution with the given rate. A rate at or below zero has no distribution and gives zero.

Source

Type parameters

Parameters

Returns: a draw from the exponential distribution with that rate

NormalPair<G>

pub func NormalPair<G: RandomGenerator>(
    generator: &var G,
    first: *var float64,
    second: *var float64
)

A pair of independent standard normal values. The Box-Muller transform, which produces two at a time from two uniform draws — so this returns both rather than throwing one away. The radial draw is taken on 1 - u for the same reason as the exponential: the logarithm of an exact zero is an infinity, and the generator will produce an exact zero eventually. The polar form of the transform avoids the trigonometric functions at the cost of rejecting about a fifth of its draws; this uses the direct form, which consumes a fixed two words and is therefore reproducible in a way a rejection loop is not.

Source

Type parameters

Parameters

Normal<G>

pub func Normal<G: RandomGenerator>(generator: &var G) -> float64

A single standard normal value: mean zero, standard deviation one. Discards the second value of the pair. A caller drawing many should use NormalPair and keep both, which halves the work.

Source

Type parameters

Parameters

Returns: a draw from the standard normal distribution

NormalWith<G>

pub func NormalWith<G: RandomGenerator>(
    generator: &var G,
    mean: float64,
    deviation: float64
) -> float64

A normal value with the given mean and standard deviation. A negative standard deviation is reflected rather than refused, since the distribution it describes is the same one; a zero gives the mean exactly.

Source

Type parameters

Parameters

Returns: a draw from the normal distribution with that mean and deviation

DirectMethodLimit

pub const DirectMethodLimit: float64 = 30.0;

Below this the direct methods are cheaper than the reductions, and above it they stop being practical.

Source

Gamma<G>

pub func Gamma<G: RandomGenerator>(
    generator: &var G,
    shape: float64
) -> float64

A value from the gamma distribution with the given shape and unit scale. Marsaglia and Tsang's method: a normal draw squeezed through a cube, which accepts on the first attempt more than ninety-five percent of the time for any shape at or above one. A shape below one is generated from a shape one larger and scaled down, since the density is unbounded at zero there and the squeeze does not hold. A shape at or below zero has no distribution and gives zero.

Source

Type parameters

Parameters

Returns: a draw from the gamma distribution with that shape and scale one

GammaWithScale<G>

pub func GammaWithScale<G: RandomGenerator>(
    generator: &var G,
    shape: float64,
    scale: float64
) -> float64

A value from the gamma distribution with the given shape and scale.

Source

Type parameters

Parameters

Returns: a draw from the gamma distribution with that shape and scale

Beta<G>

pub func Beta<G: RandomGenerator>(
    generator: &var G,
    first: float64,
    second: float64
) -> float64

A value from the beta distribution with the two given shapes, in [0, 1]. Built from two gamma draws, which is the definition rather than an approximation of it. Two shapes that are both zero leave nothing to divide and give a half.

Source

Type parameters

Parameters

Returns: a draw from the beta distribution with those two shape parameters