Abstract per-family continuous distribution. More...

#include "Distribution.h"

Inheritance diagram for provsql::Distribution:

Public Member Functions
virtual	~Distribution ()=default
virtual bool	meanIsAffine () const
	Whether `mean()` is an affine function of the raw parameters (p1, p2) – i.e.
virtual bool	isDiscrete () const
	Whether the family is discrete (integer-valued), so a point event `X` `=` `c` carries positive mass.
virtual DistSupport	support () const =0
	Natural support interval of X.
virtual bool	integrationRange (double &lo, double &hi) const =0
	Finite window [lo, hi] covering essentially all of X's mass, for numerical quadrature.
virtual std::pair< double, double >	plotRange (double trunc_lo, double trunc_hi) const =0
	Plot x-window given optional truncation bounds (±infinity means "unbounded on that side"); used by the SVG curve renderer.
virtual double	sample (std::mt19937_64 &rng) const =0
	Draw one sample using the shared MC generator.
virtual std::optional< double >	quantile (double p) const
	Inverse CDF \(Q(p) = F^{-1}(p)\) for \(p \in (0, 1)\).
virtual std::optional< double >	truncatedRawMoment (double lo, double hi, unsigned k) const
	Closed-form raw moment \(E[X^k \mid lo < X < hi]\) of the distribution truncated to [lo, hi] (±infinity for a semi-infinite side).
virtual std::optional< std::vector< double > >	sampleTruncated (std::mt19937_64 &rng, double lo, double hi, unsigned n) const
	Draw `n` rejection-free samples of X conditioned on `lo` < X < hi (±infinity for a semi-infinite side).
virtual std::optional< double >	iidOrderStatMean (std::size_t n, bool isMax) const
	Closed-form mean of the max / min of `n` i.i.d.
virtual std::unique_ptr< Distribution >	affine (double a, double b) const =0
	Closed-form location-scale transform `a·X` `+` `b` within the family.
std::unique_ptr< Distribution >	scale (double c) const
	Closed-form `c·X` (affine with no offset).
std::unique_ptr< Distribution >	negate () const
	Closed-form `-X` (affine with coefficient -1).
virtual std::string	serialise () const =0
	The on-disk `gate_rv` `extra` text encoding (e.g.
virtual std::optional< double >	asDirac () const
	The point-mass value when the parameters make the distribution degenerate (a Dirac), `std::nullopt` for a proper distribution.
Identity (parameters, for the i.i.d. equality test)
virtual const DistributionFamily &	family () const =0
	The family's interned registry descriptor.
virtual double	p1 () const =0
virtual double	p2 () const =0
Closed-form moments
virtual double	mean () const =0
	E[X].
virtual double	variance () const =0
	Var(X).
virtual double	rawMoment (unsigned k) const =0
	E[X^k].
Density / distribution
virtual double	pdf (double x) const =0
	f(x); NaN if the family declines
virtual double	cdf (double x) const =0
	F(x); NaN if the family declines.

Detailed Description

Abstract per-family continuous distribution.

Concrete subclasses (Normal / Uniform / Exponential / Erlang / Gamma) hold the two parameters and implement the family-specific closed forms. The methods below are the family-local ones (pairwise closure / comparison rules live in separate registries, not here).

Definition at line 48 of file Distribution.h.

Constructor & Destructor Documentation

◆ ~Distribution()

virtual provsql::Distribution::~Distribution ( )

virtualdefault

Member Function Documentation

◆ affine()

virtual std::unique_ptr< Distribution > provsql::Distribution::affine	(	double	a,
		double	b ) const

pure virtual

Closed-form location-scale transform a·X + b within the family.

Returns the transformed distribution when the family is closed under these coefficients, nullptr when it is not: Exponential / Erlang decline a <= 0 (the support flips) and any non-zero offset (a shifted Erlang leaves the family); every family declines a == 0 (a Dirac is not in-family – the constant-fold path is responsible for pure constants).

Here is the caller graph for this function:

◆ asDirac()

virtual std::optional< double > provsql::Distribution::asDirac ( ) const

inlinevirtual

The point-mass value when the parameters make the distribution degenerate (a Dirac), std::nullopt for a proper distribution.

Only Normal reports one (σ == 0, e.g. after an underflowing scale fold); the simplifier collapses such a result to a plain constant. Families whose degenerate forms are still sampled as-is (Uniform(a, a)) do not report.

Definition at line 238 of file Distribution.h.

◆ cdf()

virtual double provsql::Distribution::cdf ( double x ) const

pure virtual

F(x); NaN if the family declines.

Here is the caller graph for this function:

◆ family()

virtual const DistributionFamily & provsql::Distribution::family ( ) const

pure virtual

The family's interned registry descriptor.

One instance per family, so &family() (or comparing family().name) is family identity.

Here is the caller graph for this function:

◆ iidOrderStatMean()

virtual std::optional< double > provsql::Distribution::iidOrderStatMean	(	std::size_t	n,
		bool	isMax ) const

inlinevirtual

Closed-form mean of the max / min of n i.i.d.

copies of X.

Uniform(a, b): E[max] = a + (b-a)·n/(n+1), E[min] = a + (b-a)/(n+1).
Exponential(λ): E[min] = 1/(nλ), E[max] = H_n/λ (harmonic number), for λ > 0.

std::nullopt when the family has no elementary order-statistic mean (Normal, Erlang – those need the 1-D layer-cake quadrature) or the parameters are degenerate, so the caller falls back to quadrature / Monte Carlo.

Definition at line 192 of file Distribution.h.

◆ integrationRange()

virtual bool provsql::Distribution::integrationRange	(	double &	lo,
		double &	hi ) const

pure virtual

Finite window [lo, hi] covering essentially all of X's mass, for numerical quadrature.

Returns false (leaving lo / hi untouched) when the parameters are degenerate.

Here is the caller graph for this function:

◆ isDiscrete()

virtual bool provsql::Distribution::isDiscrete ( ) const

inlinevirtual

Whether the family is discrete (integer-valued), so a point event X = c carries positive mass.

Default false (continuous). The discrete families (Poisson, Binomial) override to true. It is the authoritative, per-family signal – not inferred – that a point observation / conditioning event on a leaf of this family is feasible (a continuous point event is measure-zero, so it is only meaningful as a likelihood weight, never as a rejection interval). pdf() already returns the pmf for a discrete family, so the density-weight path needs no special case beyond this classification.

Definition at line 102 of file Distribution.h.

◆ mean()

virtual double provsql::Distribution::mean ( ) const

pure virtual

E[X].

◆ meanIsAffine()

virtual bool provsql::Distribution::meanIsAffine ( ) const

inlinevirtual

Whether mean() is an affine function of the raw parameters (p1, p2) – i.e.

mean = c0 + c1·p1 + c2·p2.

Default false. A family whose mean is a linear combination of its parameters (Normal μ, Uniform (a+b)/2, inverse-Gaussian μ) overrides to true. This is the authoritative signal the latent- variable evaluator uses to keep the expectation of a compound (token- parameterised) leaf EXACT: when the mean is affine, \(E[X] = E[\mathrm{mean}(\theta)] = \mathrm{mean}(E[\theta])\) by linearity of expectation (no independence assumption), so the evaluator recurses into the parameter wires instead of falling back to Monte Carlo. Families with a nonlinear mean (Exponential 1/λ, Gamma k/λ, ...) keep the default and decline.

Definition at line 87 of file Distribution.h.

◆ negate()

std::unique_ptr< Distribution > provsql::Distribution::negate ( ) const

inline

Closed-form -X (affine with coefficient -1).

Definition at line 217 of file Distribution.h.

Here is the call graph for this function:

◆ p1()

virtual double provsql::Distribution::p1 ( ) const

pure virtual

Implemented in provsql::BaseDistribution.

◆ p2()

virtual double provsql::Distribution::p2 ( ) const

pure virtual

Implemented in provsql::BaseDistribution.

◆ pdf()

virtual double provsql::Distribution::pdf ( double x ) const

pure virtual

f(x); NaN if the family declines

◆ plotRange()

virtual std::pair< double, double > provsql::Distribution::plotRange	(	double	trunc_lo,
		double	trunc_hi ) const

pure virtual

Plot x-window given optional truncation bounds (±infinity means "unbounded on that side"); used by the SVG curve renderer.

◆ quantile()

virtual std::optional< double > provsql::Distribution::quantile ( double p ) const

inlinevirtual

Inverse CDF \(Q(p) = F^{-1}(p)\) for \(p \in (0, 1)\).

std::nullopt when the family has no elementary inverse CDF (Erlang), so "unsupported" cannot be silently consumed – callers branch on availability explicitly. Normal uses the Beasley-Springer-Moro rational approximation (~1e-7 accuracy, ample for sampling); Uniform / Exponential invert exactly. Behaviour at the endpoints is the family's (BSM diverges; clamp p strictly inside (0, 1) before calling).

Definition at line 141 of file Distribution.h.

◆ rawMoment()

virtual double provsql::Distribution::rawMoment ( unsigned k ) const

pure virtual

E[X^k].

◆ sample()

virtual double provsql::Distribution::sample ( std::mt19937_64 & rng ) const

pure virtual

Draw one sample using the shared MC generator.

◆ sampleTruncated()

virtual std::optional< std::vector< double > > provsql::Distribution::sampleTruncated	(	std::mt19937_64 &	rng,
		double	lo,
		double	hi,
		unsigned	n ) const

inlinevirtual

Draw n rejection-free samples of X conditioned on lo < X < hi (±infinity for a semi-infinite side).

Each family uses its own exact scheme (interval intersection for Uniform, memorylessness / stable inverse-CDF for Exponential, inverse-CDF transform for Normal). std::nullopt when the family has no scheme (Erlang: needs the inverse regularised incomplete gamma) or the truncation is degenerate / parameters invalid, so the caller's MC-rejection fallback can emit its usual diagnostics.

Definition at line 173 of file Distribution.h.

◆ scale()

std::unique_ptr< Distribution > provsql::Distribution::scale ( double c ) const

inline

Closed-form c·X (affine with no offset).

Definition at line 212 of file Distribution.h.

Here is the call graph for this function:

◆ serialise()

virtual std::string provsql::Distribution::serialise ( ) const

pure virtual

The on-disk gate_rv extra text encoding (e.g.

"normal:2.5,0.5"), inverse of parse_distribution_spec.

◆ support()

virtual DistSupport provsql::Distribution::support ( ) const

pure virtual

Natural support interval of X.

◆ truncatedRawMoment()

virtual std::optional< double > provsql::Distribution::truncatedRawMoment	(	double	lo,
		double	hi,
		unsigned	k ) const

inlinevirtual

Closed-form raw moment \(E[X^k \mid lo < X < hi]\) of the distribution truncated to [lo, hi] (±infinity for a semi-infinite side).

std::nullopt when the family has no closed form (Erlang: needs the regularised lower incomplete gamma) or the truncation is degenerate (mass below a numerical floor), so the caller falls through to MC rejection. k is at least 1 (the caller short-circuits k = 0).

Definition at line 156 of file Distribution.h.

◆ variance()

virtual double provsql::Distribution::variance ( ) const

pure virtual

Var(X).

The documentation for this class was generated from the following file:

/home/pierre/git/software/provsql/src/distributions/Distribution.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Distribution()

Member Function Documentation

◆ affine()

◆ asDirac()

◆ cdf()

◆ family()

◆ iidOrderStatMean()

◆ integrationRange()

◆ isDiscrete()

◆ mean()

◆ meanIsAffine()

◆ negate()

◆ p1()

◆ p2()

◆ pdf()

◆ plotRange()

◆ quantile()

◆ rawMoment()

◆ sample()

◆ sampleTruncated()

◆ scale()

◆ serialise()

◆ support()

◆ truncatedRawMoment()

◆ variance()