mixle.stats.univariate.continuous.nakagami module¶

Nakagami distribution – the amplitude/envelope law of Nakagami-m fading.

A positive-support family for signal envelopes (wireless/radar/sonar fading, also reliability and hydrology). With shape m >= 1/2 and spread omega = E[X^2] > 0,

f(x; m, omega) = 2 m^m / (Gamma(m) omega^m) * x^(2m-1) * exp(-m x^2 / omega), x > 0,

so X^2 ~ Gamma(m, omega/m); m = 1/2 is the half-normal and m = 1 the Rayleigh. The CDF is the regularized lower incomplete gamma, it samples exactly via a Gamma draw, and it has a clean closed-form method-of-moments fit: omega = E[X^2] and m = E[X^2]^2 / Var[X^2].

Reference: Nakagami, “The m-distribution – a general formula of intensity distribution of rapid fading”, in Statistical Methods in Radio Wave Propagation (1960).

class NakagamiDistribution(m, omega, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Nakagami distribution with shape m >= 1/2 and spread omega = E[X^2] > 0.

Parameters:

m (float)
omega (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at x.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at x, including the exact limit at zero.

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded array of observations.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]: Describe backend support for generated Nakagami kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for Nakagami distributions.

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row Nakagami power sums in accumulator order (count, sum x^2, sum x^4).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, m, omega, engine)[source]

Engine-neutral Nakagami log-density with the exact limit at zero.

Parameters:

x (Any)
m (Any)
omega (Any)
engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Stacked Nakagami parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[NakagamiDistribution])
engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Nakagami log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Stacked Nakagami power sums (count, sum x^2, sum x^4) using engine-resident arrays.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, Any, Any]

cdf(x)[source]

Cumulative distribution function P(X <= x) = P(m, m x^2 / omega) (0 for x <= 0).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean (Gamma(m+1/2)/Gamma(m)) sqrt(omega/m).

Return type:: float

variance()[source]

Variance omega - mean^2 (since E[X^2] = omega).

Return type:: float

entropy()[source]

Differential entropy m + lgamma(m) + (1/2 - m) psi(m) + (1/2) log(omega/m) - log(2).

Derived via the entropy of a monotone transform: X = sqrt(Y) with Y = X^2 ~ Gamma(m, omega/m) (Nakagami, ‘The m-distribution’, 1960), so h(X) = h(Y) - log(2) - E[log X] = h(Y) - log(2) - (1/2)(E[log Y]) and both h(Y) and E[log Y] are standard Gamma-distribution identities. Reduces exactly to the Rayleigh entropy at m = 1.

Return type:: float

sampler(seed=None)[source]

Return a sampler (X = sqrt(Gamma(m, omega/m))).

Parameters:: seed (int | None)
Return type:: NakagamiSampler

estimator(pseudo_count=None)[source]

Return a closed-form method-of-moments estimator.

Parameters:: pseudo_count (float | None)
Return type:: NakagamiEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (the raw value).

Return type:: NakagamiDataEncoder

class NakagamiSampler(dist, seed=None)[source]

Bases: DistributionSampler

Draw X = sqrt(G) with G ~ Gamma(shape=m, scale=omega/m) (so X^2 ~ Gamma(m, omega/m)).

Parameters:

dist (NakagamiDistribution)
seed (int | None)

sample(size=None, *, batched=True)[source]

Draw one sample or an array of iid samples.

Parameters:

size (int | None)
batched (bool)

Return type:

float | ndarray

class NakagamiAccumulator(name=None, keys=None)[source]

Bases: SquaredPowerSumTrack, SequenceEncodableStatisticAccumulator

Accumulate the weighted power sums (count, sum x^2, sum x^4) for the moment fit.

The whole accumulator is SquaredPowerSumTrack – shape, validation and the conditioning-gated shift-anchored track on y = x**2, which is the quantity this family’s M-step differences. It is shared with the Rician family, whose accumulator was character-for- character the same; the duplicate-body gate caught the pair and de-duplicating it is what keeps a fix landing on one from missing the other.

Parameters:

name (str | None)
keys (str | None)

acc_to_encoder()[source]

Return the encoder used by this accumulator.

Return type:: NakagamiDataEncoder

class NakagamiAccumulatorFactory(name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for NakagamiAccumulator.

Parameters:

name (str | None)
keys (str | None)

make()[source]

Create a fresh Nakagami accumulator.

Return type:: NakagamiAccumulator

class NakagamiEstimator(pseudo_count=None, suff_stat=None, m_min=0.5, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator: omega = E[X^2], m = E[X^2]^2 / Var[X^2] (clamped m >= 1/2).

Var[X^2] comes from the shift-anchored moment track whenever the accumulated statistics carry that payload (see NakagamiAccumulator). The shape is the reciprocal of the relative spread of X^2, so the raw E[X^4] - E[X^2]^2 form loses about eps * m: measured against exact rational arithmetic, 2.0e-10 relative at m=1e6, 2.6e-8 at 1e8 and 2.6e-6 at 1e10, now 2.0e-10, 4.7e-16 and 1.0e-13. With a plain raw tuple the historical path is used bit-identically, and estimate warns rather than returning a shape it cannot stand behind.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
m_min (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for Nakagami power-sum statistics.

Return type:: NakagamiAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate shape and spread from weighted second and fourth moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

NakagamiDistribution

class NakagamiDataEncoder[source]

Bases: DataSequenceEncoder

Encode observations as a float array.

seq_encode(x)[source]

Encode observations as a floating-point array, admitting finite rows outside the support.

A negative value is scored -inf by NakagamiDistribution.seq_log_density() (and by the scalar path), so a mixture whose other component owns it can encode the whole batch (P02-F03). Refusing it here made Mixture[Gaussian, Nakagami] unencodable (Q01-F02). The accumulator still refuses a negative row that carries weight. Non-finite values stay refused.

Parameters:: x (Sequence[float])
Return type:: ndarray