Random — Random Numbers & Probability Distributions

Overview

The sangi random module has three layers.

• Random engines — RandomEngine with reproducible seeding, plus a fast PRNG (xoshiro256++) and normal generators (Ziggurat, etc.).
• Probability distributions — 30+ continuous and discrete distributions. Each exposes density (pdf) / cumulative (cdf) / quantile (quantile) / moments (mean, variance) and sampling (sample) under a unified interface.
• Quasi-random — Halton / Sobol low-discrepancy sequences, improving Monte-Carlo convergence from $O(1/\sqrt{N})$ toward $O(1/N)$.

The type $T$ may be double/float or multiprecision Float. Sampling takes a standard std::mt19937&.

Build

#include <math/random/random.hpp>          // RandomEngine, Uniform/Normal/MultivariateNormal
#include <math/random/distributions.hpp>   // continuous & discrete distributions (Gamma, Beta, Poisson, ...)
#include <math/random/quasi_random.hpp>    // Halton / Sobol sequences

Header-only; no library to link (linking the sangi_rational static libraries is recommended because random.hpp uses linear algebra).

Random Engines

RandomEngine eng(42);              // seed 42
double u = eng.uniform();          // [0,1)
double x = eng.uniform(2.0, 5.0);  // [2,5)
int d = eng.uniformInt(1, 6);      // dice {1..6}
// The same seed reproduces the same stream (RandomEngine eng2(42); eng2.uniform() == u)

Common Distribution Interface

Each distribution class takes its parameters in the constructor and exposes these common members (discrete distributions provide a mass function pmf(int k) instead of pdf).

NormalDistribution<double> nd(0.0, 1.0);   // standard normal N(0,1)
nd.mean();            // Run output: 0
nd.variance();        // Run output: 1
nd.pdf(0.0);          // Run output: 0.398942280401433   (= 1/sqrt(2π))
nd.cdf(0.0);          // Run output: 0.5
nd.quantile(0.975);   // Run output: 1.95996398612019    (two-sided 95%)

Continuous Distributions

Parameters (common):

UniformDistribution<double> ud(0.0, 1.0);
ud.mean();        // Run output: 0.5
ud.variance();    // Run output: 0.0833333333333333   (= 1/12)
ud.pdf(0.5);      // Run output: 1

ExponentialDistribution<double> ed(2.0);  // rate λ = 2
ed.mean();        // Run output: 0.5
ed.variance();    // Run output: 0.25

Discrete Distributions

PoissonDistribution<double> pd(3.0);
pd.mean();        // Run output: 3
pd.variance();    // Run output: 3

BinomialDistribution<double> bd(10, 0.5);
bd.mean();        // Run output: 5
bd.variance();    // Run output: 2.5
bd.pmf(5);        // Run output: 0.24609375   (= C(10,5)/2^10)

Multivariate & Special Distributions

Quasi-Random Sequences

Quasi-random sequences are highly uniform and improve Monte-Carlo convergence from the $O(1/\sqrt{N})$ of pseudo-random sampling toward $O((\log N)^D / N)$.

Members: next() (next point as std::array<double, Dim>), generate(n) ($n$ points), index(), reset().

HaltonSequence<2> h;     // bases (2, 3)
auto p0 = h.next();      // Run output: (0, 0)
auto p1 = h.next();      // Run output: (0.5, 0.333333333333333)
auto p2 = h.next();      // Run output: (0.25, 0.666666666666667)
auto p3 = h.next();      // Run output: (0.75, 0.111111111111111)

Example

#include <math/random/random.hpp>
#include <math/random/distributions.hpp>
#include <random>
#include <iostream>
using namespace sangi;

int main() {
    // Closed-form (deterministic) values
    NormalDistribution<double> nd(0.0, 1.0);
    std::cout << nd.pdf(0.0) << "\n";       // 0.398942280401433
    std::cout << nd.quantile(0.975) << "\n"; // 1.95996398612019

    // Monte Carlo: sample mean of 100k draws from N(2, 0.5) ≈ 2.0
    std::mt19937 gen(12345);
    NormalDistribution<double> g(2.0, 0.5);
    double s = 0.0;
    for (int i = 0; i < 100000; ++i) s += g.sample(gen);
    std::cout << s / 100000 << "\n";        // ≈ 2.0 (seed dependent)
}

Related Modules

Probability distributions are built on special functions and linear algebra.

• Float — gamma-function family and other special functions used by the distributions
• LinAlg — Cholesky decomposition for the multivariate normal
• Matrix — covariance-matrix representation