1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
// Copyright (c) 2025 SpaceCell Enterprises Ltd
// SPDX-License-Identifier: AGPL-3.0-or-later
// Commercial licensing available. See LICENSE and LICENSING.md.
//! # **Statistical Distributions Module** - *Comprehensive Probability Distribution Computing*
//!
//! Advanced statistical distribution kernels providing high-performance probability density
//! functions (PDFs), cumulative distribution functions (CDFs), quantile functions, and
//! random sampling with SIMD acceleration and numerical precision guarantees.
//!
//! ## Distribution Categories
//! - **Univariate distributions**: Complete coverage of common continuous and discrete distributions
//! - **Multivariate distributions**: Multivariate normal, Student-t, Wishart, and advanced distributions
//! - **Parametric families**: Beta, gamma, normal, exponential, and related distribution families
//! - **Discrete distributions**: Binomial, Poisson, geometric, and hypergeometric variants
//!
//! ## Core Statistical Functions
//! Each distribution provides a complete statistical interface:
//! - **Probability density/mass functions**: Optimised PDF/PMF evaluation with numerical stability
//! - **Cumulative distribution functions**: CDF computation with extended precision algorithms
//! - **Quantile functions**: Inverse CDF calculation using robust bracketing and refinement
//! - **Random sampling**: High-quality pseudorandom generation with distributional correctness
//!
//! ## Computational Architecture
//! Distribution calculations employ sophisticated numerical techniques for accuracy and performance:
//! - **SIMD vectorisation**: Hardware-accelerated evaluation of distribution functions
//! - **Rational approximations**: Optimised polynomial and rational function approximations
//! - **Series expansions**: Convergent series with adaptive truncation for transcendental functions
//! - **Numerical integration**: Gauss-Kronrod quadrature for complex distribution functions
//!
//! ## Arrow Integration and Null Handling
//! The module integrates seamlessly with Apache Arrow's memory model and null semantics:
//! - **Null-aware processing**: Efficient handling of missing values with validity bitmasks
//! - **SIMD-accelerated masking**: Vectorised null propagation without conditional branches
//! - **Arrow-compatible layouts**: Direct operation on Arrow array structures
//! - **Memory efficiency**: Zero-copy operations where mathematically valid
//!
//! ### Null Value Philosophy
//! Rather than assume, we choose to recognise inf and NaN as valid float values
//! (consistent with Apache Arrow semantics), leaving it to the user to subsequently
//! treat them as nulls if they wish, given that there are numerical scenarios where
//! they represent information gain. This approach avoids computational overhead in
//! the hot path whilst preserving mathematical correctness for edge cases.
//!
//! ## Numerical Precision and Stability
//! All distribution implementations prioritise numerical accuracy across parameter ranges.
//! See `./tests` for any specific tolerance requirements, where it is measured against Scipy.
//! Whilst these pass on the development machine, platform specific difference may impact your
//! test results, and thus one should keep this in mind when evaluating this library's fit for your use case.
//!
//! ## Disclaimer
//! This implementation is provided on a best-effort basis and is intended for
//! general scientific and engineering use. While every attempt has been made to
//! match the accuracy and behaviour of established libraries such as SciPy, we
//! make no guarantees as to correctness, fitness for any particular purpose, or
//! suitability for uses such as in life-critical, safety-critical, or financial applications.
//!
//! Results may differ from other libraries due to platform, compiler, or implementation
//! differences. Edge cases and special values are handled explicitly for compatibility
//! with SciPy (v1.16) but users are responsible for independently verifying that this
//! function meets their accuracy and reliability requirements.
//!
//! By using these functions, you accept all responsibility for outcomes or decisions
//! based upon its results.
/// # **Shared Distribution Utilities** - *Common Infrastructure for Distribution Computing*
///
/// Foundational utilities, constants, and helper functions shared across all probability
/// distributions, providing consistent numerical methods and sampling infrastructure.
///
/// This module contains the core mathematical building blocks that enable efficient
/// and accurate distribution computation across all statistical functions.
///
/// ## Modules
/// - **`constants`**: Mathematical constants and precomputed values
/// - **`sampler`**: Random number generation and sampling utilities
/// - **`scalar`**: Special functions and mathematical utilities
/// # **Univariate Distributions** - *Single-Variable Probability Distributions*
///
/// Complete collection of univariate probability distributions covering both continuous
/// and discrete families with comprehensive statistical function implementations.
///
/// Each distribution provides PDF/PMF, CDF, quantile functions, and random sampling
/// with SIMD acceleration and numerical precision guarantees.
///
/// ## Distribution Categories
/// - **Continuous**: beta, cauchy, chi-squared, exponential, gamma, laplace, logistic, lognormal, normal, student_t, uniform, weibull
/// - **Discrete**: binomial, discrete_uniform, geometric, hypergeometric, multinomial, neg_binomial, poisson
/// - **Common utilities**: Shared patterns and mathematical building blocks