# DistributionExt

URL: https://stochastic.rust-dd.com/docs/concepts/distribution-ext

> Closed-form pdf, cdf, characteristic function and moments for 33 of the 37 distribution types — a missing closed form panics, never returns zero.

Closed-form analytics for every distribution that has them.

`DistributionExt` is `f64`-only (not generic over `T`), and every method
defaults to a `type_name`-annotated `unimplemented!()` — a distribution
overrides only the methods it has a closed form for:

```rust
// Signature sketch. Every method below is a *provided* method whose default
// body is a `type_name`-annotated `unimplemented!()`; the bodies are elided
// here. See `stochastic-rs-distributions/src/traits/distribution.rs`.
pub trait DistributionExt {
  fn characteristic_function(&self, t: f64) -> Complex64;
  fn pdf(&self, x: f64) -> f64;
  fn cdf(&self, x: f64) -> f64;
  fn inv_cdf(&self, p: f64) -> f64;
  fn mean(&self) -> f64;
  fn median(&self) -> f64;
  fn mode(&self) -> f64;
  fn variance(&self) -> f64;
  fn skewness(&self) -> f64;
  fn kurtosis(&self) -> f64;
  fn entropy(&self) -> f64;
  fn moment_generating_function(&self, t: f64) -> f64;
}
```

## Coverage

**33 of the 37** distribution types implement `DistributionExt`. The four
that do not are `SimdDirichlet` and `SimdWishart` (vector- and
matrix-valued draws, with their own inherent `pdf` / `log_pdf`),
`SimdNonCentralChiSquared` (its noncentrality is supplied per draw; it backs
the exact CIR transition density) and `ComplexDistribution` (a composition
utility that pairs two distributions as the parts of a complex draw).

Implementing the trait does not mean every method has a closed form.
`SimdGed`, `SimdSkellam` and the four `truncated` wrappers override only
`pdf` / `cdf`, and nine types — `SimdAlphaStable`, `SimdBeta`,
`SimdHypergeometric`, `SimdInverseGauss`, `SimdNormalInverseGauss`,
`SimdVarianceGamma`, `SimdGig`, `SimdGeneralizedHyperbolic` and
`SimdTemperedStable` — carry a named no-closed-form `unimplemented!()` on
specific methods. `cargo doc -p stochastic-rs-distributions` renders exactly
which methods each type overrides.

## Default behaviour: panic, never zero

Project rule: an unimplemented moment **panics** with a helpful
message including the type name, never silently returns 0. This was a
deliberate choice after a v1.x bug where a silent-zero kurtosis caused
a downstream calibration to converge on garbage. Reproduced below (the
crate's own equivalent helper is private):

```rust title="tests/doctest_concepts_unimplemented_moment.rs"
// docs: concepts/distribution-ext#default-behaviour-panic-never-zero
//! Backs the "default behaviour: panic, never zero" example on the
//! DistributionExt concept page. Reproduces the doc's helper verbatim
//! (the crate's own equivalent is private) and proves it panics with the
//! documented message instead of silently returning a number.

fn unimplemented_moment<T>() -> ! {
  let name = std::any::type_name::<T>();
  unimplemented!("moment not implemented for {name}")
}

#[test]
#[should_panic(expected = "moment not implemented for f64")]
fn unimplemented_moment_panics_with_type_name() {
  unimplemented_moment::<f64>();
}
```

If you hit such a panic, you have two options:

1. Use a different distribution if the moment is non-essential.
2. Open an issue / PR — the `feedback_implementation.md` rule says
   we follow papers exactly, so closed forms get added with a citation.

## Why no `statrs::distribution::*`

The library deliberately writes closed forms from scratch in
`stochastic-rs-distributions`, never delegating to `statrs`. Reasons:

1. **Generic precision**. `statrs` is `f64`-only. We need `f32`
   support for GPU + memory-bound bulk sampling.
2. **No-allocation guarantees**. `statrs` allocates in some cdfs; the
   bulk samplers in this library cannot afford that.
3. **Audit trail**. Every formula in this crate is anchored to a paper
   citation, with a comparison test against the paper's numerical
   tables. `statrs`'s implementations are competent but lack that
   audit trail.

See the per-distribution pages under
[Distributions](/docs/distributions) for the formulas, tests, and
references.

