Skip to content

math: fixing liquid_MarcumQf() returning values outside [0,1] - #470

Open
cthornDSP14 wants to merge 1 commit into
jgaeddert:masterfrom
cthornDSP14:fix-marcumq
Open

cthornDSP14 wants to merge 1 commit into
jgaeddert:masterfrom
cthornDSP14:fix-marcumq

Conversation

@cthornDSP14

@cthornDSP14 cthornDSP14 commented Nov 13, 2026 •

Copy link
Copy Markdown

Problem

liquid_MarcumQf() uses an erfc() approximation. This can return values
anywhere in [0, 2]. The Marcum Q function returns a probability, so this is a problem.

Solution

Q_M(a,b) is the probability that a non-central chi-square variable with
2M degrees of freedom and non-centrality a² exceeds b². This fix computes it
as a Poisson-weighted mixture of central chi-square tail probabilities:

Q_M(a,b) = sum_{j>=0} [exp(-λ) λ^j / j!] * [exp(-x) sum_{i<M+j} x^i / i!]

with λ = a²/2 and x = b²/2.

  • Special cases are handled: Q_M(a,0) = 1, and Q_M(0,b) uses
    its closed form.
  • alpha is limited to 1000 (about 57 dB SNR) to bound run time (~0.2 s);
    the number of terms grows as alpha².
  • NaN arguments raise an error; Q_M(a,inf) = 0.

Tests

  • Re-enabled the three existing MarcumQf checks.
  • Added checks for higher orders, larger arguments, and both special cases.
  • Added checks at the alpha limit and for invalid input.

Related Issues

  • liquid_MarcumQ1f() returns inf/NaN for larger arguments, e.g.
    liquid_MarcumQ1f(10, 9) returns inf.
  • liquid_lnbesselif() overflows to inf for z above ~90.

* previous erfc() approximation returned values outside [0,1]
  (e.g. Q_1(1,2) returned 1.0 instead of 0.269)
* compute as Poisson-weighted mixture of central chi-square terms,
  evaluated in the log domain to avoid overflow for large arguments;
  stop once a bound on the remaining Poisson tail is negligible
  relative to the sum
* validate input (M >= 1, alpha and beta non-negative and not NaN);
  limit alpha to 1000 to bound run time, as the number of terms grows
  as alpha^2
* Q_M(a,inf) = 0
* enables MarcumQf autotest checks; adds higher-order, large-argument,
  alpha-limit, and special-case checks, plus invalid-input checks in
  math_config
@cthornDSP14
cthornDSP14 marked this pull request as ready for review November 14, 2026 01:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant