Internal Documentation

Documentation for ConvolvedDistributions's internal interface.

Contents

• Internal Documentation
  • Contents
  • Index
  • Internal API

Index

• ConvolvedDistributions._cdf_ad_safe
• ConvolvedDistributions._gamma_cdf
• ConvolvedDistributions._gamma_cdf_value_and_partials
• ConvolvedDistributions._grad_p_a_series
• ConvolvedDistributions._logcdf_ad_safe
• Distributions.cdf
• Distributions.logcdf
• Distributions.logpdf
• Distributions.pdf
• Statistics.mean
• Statistics.std
• Statistics.var

Internal API

ConvolvedDistributions._cdf_ad_safe Function

_cdf_ad_safe(
    dist::Distributions.UnivariateDistribution,
    u::Real
) -> Any

AD-safe cdf(dist, u) companion to _logcdf_ad_safe. Same dispatch idea: route Gamma through _gamma_cdf so the numeric-path optimisations that call cdf(dist, lower) for early termination remain differentiable under reverse-mode AD.

source

ConvolvedDistributions._gamma_cdf Function

_gamma_cdf(k::Real, θ::Real, x::Real) -> Any

AD-safe Gamma CDF, P(k, x/θ).

Primal goes through SpecialFunctions.gamma_inc for every Real subtype it supports (Float64, Float32, BigFloat) — same path the non-AD hot path uses, full accuracy across all z/a regimes. AD coverage is supplied by per-backend extensions:

• ConvolvedDistributionsChainRulesCoreExt defines the reverse-mode rrule and forward-mode frule (analytical partials, primal via gamma_inc).

• ConvolvedDistributionsMooncakeExt lifts both the rrule and frule into Mooncake (reverse and forward mode).

• ConvolvedDistributionsReverseDiffExt lifts the rrule into ReverseDiff.

• ConvolvedDistributionsForwardDiffExt defines Dual methods on _gamma_cdf directly (forward-mode dispatches on argument types, not via ChainRules).

The α-partial that gamma_inc's ChainRule leaves as @not_implemented is supplied by _grad_p_a_series, following the series form Moore (1982) introduced as Algorithm AS 187 and that Stan (grad_reg_inc_gamma) and JAX (igamma_grad_a) both use.

source

ConvolvedDistributions._gamma_cdf_value_and_partials Function

_gamma_cdf_value_and_partials(
    k::Real,
    θ::Real,
    x::Real
) -> NTuple{4, Any}

Primal value and analytical partials (Ω, dk, dθ, dx) for _gamma_cdf. Shared by every per-backend AD extension so the formulas live in one place:

• dx = pdf(Gamma(k, θ), x)

• dθ = -(x/θ) · dx

• dk = _grad_p_a_series(k, x/θ)

The non-positive-x branch returns zeros for the primal and all three partials, matching _gamma_cdf's early-return behaviour.

source

ConvolvedDistributions._grad_p_a_series Function

_grad_p_a_series(a::Real, z::Real; rtol, maxiter) -> Any

Partial of the regularised lower incomplete gamma with respect to the shape parameter — the term SpecialFunctions.gamma_inc leaves as @not_implemented in its ChainRule. Computed by term-by-term differentiation of the Tricomi absolutely-convergent series for P(a, z) = z^a e^{-z} Σ_{n ≥ 0} z^n / Γ(a + n + 1):

with ψ(a + n + 1) = ψ(a + n) + 1 / (a + n) propagated alongside the term recurrence term_{n+1} = term_n · z / (a + n + 1). Used by the reverse-mode rule in ConvolvedDistributionsChainRulesCoreExt and by the forward-mode Dual methods in ConvolvedDistributionsForwardDiffExt.

References

The series + digamma-recurrence form is Moore (1982), "Algorithm AS 187: Derivatives of the Incomplete Gamma Integral", Applied Statistics 31:330-335. The same construction is used by Stan (stan/math/prim/fun/grad_reg_inc_gamma.hpp) and JAX (jax._src.scipy.special.random_gamma_grad / igamma_grad_a) for the shape derivative of the regularised lower incomplete gamma.

source

ConvolvedDistributions._logcdf_ad_safe Function

_logcdf_ad_safe(
    dist::Distributions.UnivariateDistribution,
    u::Real
) -> Any

AD-safe logcdf(dist, u) for use inside differentiable integrands.

Generic dispatch falls through to Distributions.logcdf. The Gamma method routes through _gamma_cdf so its ChainRulesCore.rrule is picked up by reverse-mode AD inside the numeric convolution path; without this, the integrand calls gamma_inc and breaks under every supported AD backend.

source

Distributions.cdf Function

cdf(d::ConvolvedDistributions.Convolved, x::Real) -> Any

Compute the cumulative distribution function.

Uses an analytical convolution when Distributions.convolve applies to all component pairs, otherwise AD-safe numeric quadrature.

See also: logcdf

source

cdf(
    d::ConvolvedDistributions.Convolved,
    x::AbstractVector{<:Real}
) -> Any

Compute the CDF for a vector of evaluation points using a single quadrature solve (the integrand returns a vector).

The batch shares one quadrature window across all points while the scalar path picks a per-point window, so the two paths can differ within quadrature accuracy: batched CDF values agree with the scalar path to ~1e-6, and the derived batched densities to ~1e-3 in the tails of wide batches. Use one path consistently when comparing log densities (see the FAQ).

See also: cdf

source

cdf(d::Difference, z::Real) -> Any

Compute the cumulative distribution function.

Uses the analytic Normal-Normal difference where it applies, otherwise AD-safe numeric quadrature of   .

See also: logcdf

source

Distributions.logcdf Function

logcdf(d::ConvolvedDistributions.Convolved, x::Real) -> Any

Compute the log cumulative distribution function.

See also: cdf

source

logcdf(d::Difference, z::Real) -> Any

Compute the log cumulative distribution function.

See also: cdf

source

Distributions.logpdf Function

logpdf(d::ConvolvedDistributions.Convolved, x::Real) -> Any

Compute the log probability density function.

See also: pdf, logcdf

source

logpdf(
    d::ConvolvedDistributions.Convolved,
    x::AbstractVector{<:Real}
) -> Any

Compute log densities for a vector of points, reusing the batched PDF solve for the numeric path.

The shared quadrature window means batched log densities can differ from the scalar path by up to ~2e-3 in the tails of wide batches (the batched CDF agrees to ~1e-6). Score a model through one path consistently.

See also: logpdf, pdf

source

logpdf(d::Difference, z::Real) -> Any

Compute the log probability density function.

See also: pdf, logcdf

source

Statistics.mean Function

mean(d::ConvolvedDistributions.Convolved) -> Any

Mean of the convolution: the exact sum of the component means.

A Convolved is a sum of independent components, so the mean is . Each component must provide an analytic mean; a component without one errors (there is no numeric fallback).

See also: var, std

source

mean(d::Difference) -> Any

Mean of the difference: the difference of the component means,  .

See also: var, std

source

Distributions.pdf Function

pdf(d::ConvolvedDistributions.Convolved, x::Real) -> Any

Compute the probability density function.

Uses the exact analytical convolved density where Distributions.convolve applies to all component pairs, otherwise the AD-safe numeric density convolution    .

See also: logpdf

source

pdf(
    d::ConvolvedDistributions.Convolved,
    x::AbstractVector{<:Real}
) -> Any

Compute densities for a vector of points using a single quadrature solve (the integrand returns a vector).

See also: pdf

source

pdf(d::Difference, z::Real) -> Any

Compute the probability density function.

Uses the exact analytic Normal-Normal density where it applies, otherwise the AD-safe numeric cross-correlation    .

See also: logpdf

source

Statistics.std Function

std(d::ConvolvedDistributions.Convolved) -> Any

Standard deviation of the convolution, .

See also: var, mean

source

std(d::Difference) -> Any

Standard deviation of the difference, .

See also: var, mean

source

Statistics.var Function

var(d::ConvolvedDistributions.Convolved) -> Any

Variance of the convolution: the exact sum of the component variances.

Independence makes the variance additive, . As for mean, each component must provide an analytic var or the call errors.

See also: mean, std

source

var(d::Difference) -> Any

Variance of the difference: the sum of the component variances,   (independence makes the variance additive even though the means subtract).

See also: mean, std

source