.. _troubleshooting-convergence: Convergence Issues ================== This page addresses situations where moments are flagged as "convergence uncertain" or where results appear numerically unstable. .. contents:: On this page :local: :depth: 2 ---- Understanding the "Convergence Uncertain" Flag ----------------------------------------------- When the **Convergence** tab shows a red "uncertain" badge for a moment, it means the backend exhausted all five convergence strategies without confirming the result. The value shown is the raw partial sum — it may or may not be close to the true moment. This does **not** necessarily mean the moment does not exist. It means ToFUL could not confirm convergence within the current settings. ---- Fix 1 — Increase Max Series Terms ----------------------------------- For discrete distributions, the default maximum of 200 terms may not be enough for slowly converging distributions. In the **Advanced** expander, increase **Max series terms** to 400 or 500 and recompute. **When this helps:** Distributions where the PMF decays slowly — for example, Geometric(p=0.05), Negative Binomial with small :math:`p`, or custom PMFs with polynomial decay. **When this does not help:** If the PMF does not decay at all (divergent series), adding more terms makes the sum larger, not more stable. ---- Fix 2 — Increase Calc Precision --------------------------------- A higher **Calc precision** tightens the convergence tolerance, which can trigger acceptance by the term-magnitude test or Wynn ε algorithm when the default tolerance was too loose. Set **Calc precision** to 10–12 and recompute. **When this helps:** When results are very close to converged but just missing the default 1e-12 threshold. ---- Fix 3 — Check Whether the Moment Exists ----------------------------------------- For some distributions, moments of order :math:`r \geq k` are genuinely infinite. Adding more terms or increasing precision will not help. **Symptoms of a non-existent moment:** * The partial sum grows monotonically as more terms are added. * The ratio of consecutive terms is :math:`\geq 1`. * The Convergence tab shows ``ratio-bound`` with "diverge" in the info. **Distributions with non-existent high-order moments:** +-------------------------------+----------------------------------+ | Distribution | Finite moments of order… | +===============================+==================================+ | Cauchy | None (no finite moments at all) | +-------------------------------+----------------------------------+ | Pareto(α) | r < α only | +-------------------------------+----------------------------------+ | Student-t(ν) | r < ν only | +-------------------------------+----------------------------------+ | Lévy(c) | None | +-------------------------------+----------------------------------+ | Log-normal | All orders finite | +-------------------------------+----------------------------------+ | Geometric(p) | All orders finite for p > 0 | +-------------------------------+----------------------------------+ If your distribution has a power-law tail, compute only the moments that are known to exist analytically before comparing with ToFUL. ---- Fix 4 — Reformulate the PMF/PDF --------------------------------- Numerical cancellation can occur when the PMF/PDF involves large intermediate values that nearly cancel. Reformulating in log-space can help. **Example — Poisson with large lambda:** .. code-block:: python # Bug — exp(-50) * 50**x causes underflow for large x (exp(-50) * 50**x) / factorial(x) if x >= 0 else 0 # Fix — use log-space formulation via gamma function exp(-50 + x * log(50) - log(gamma(x+1))) if x >= 0 else 0 The two expressions are mathematically identical but the second avoids the catastrophic underflow of ``exp(-50)``. ---- Fix 5 — Use a Tighter Range ----------------------------- For continuous distributions where the PDF has negligible mass outside a finite interval, use explicit finite bounds rather than infinity. This replaces Gauss-Laguerre or Gauss-Hermite (which assume specific tail behaviour) with standard adaptive Gauss-Kronrod, which adapts freely to the actual integrand shape. **Example — Log-normal distribution on [0, 100] instead of [0, inf]:** A log-normal LN(0,1) has negligible density beyond x=50. Using ``[0, 50]`` instead of ``[0, inf]`` captures 99.9999% of the mass and may integrate more stably. ---- Fix 6 — Switch to mpmath Mode ------------------------------- For distributions where standard float64 arithmetic accumulates too much rounding error, set **Calc precision** to 13 or higher. This triggers mpmath's arbitrary-precision tanh-sinh quadrature for CRVs. Note that for discrete series, increasing precision does not switch to arbitrary-precision arithmetic — it only tightens the tolerance. ---- Diagnosing Slowly Converging Series ------------------------------------- The **Convergence** tab info string contains diagnostic information. Read the method and info for the highest-order moment: .. code-block:: text Method: wynn-epsilon Info: Wynn epsilon converged at column 4: 111.222... Method: partial-sum Info: Convergence uncertain after 500 terms (partial sum=111.1...) If ``wynn-epsilon`` converges but ``partial-sum`` appears for higher-order moments, the higher-order moments need more terms. The Wynn algorithm extracts the limit reliably when partial sums oscillate around it, but for series that are still actively growing, it cannot help. ---- Alternating Series ------------------- If your PMF produces alternating positive and negative values, this is almost certainly a modelling error — probabilities cannot be negative. However, when computing moments (not probabilities), the term :math:`(x-a)^r \cdot P(x)` can alternate in sign for odd :math:`r` and negative-valued :math:`x`. This is expected and the Cohen-Villegas-Zagier algorithm handles it automatically. If the Convergence tab shows ``cohen-villegas-zagier`` for odd-order central moments of a symmetric distribution centred at 0, this is normal correct behaviour (odd central moments of symmetric distributions are 0, and the CVZ algorithm efficiently confirms this). ---- Quick Reference — Which Fix to Try First ------------------------------------------ +---------------------------------------+----------------------------------+ | Symptom | First fix to try | +=======================================+==================================+ | "Convergence uncertain" for all | Increase Max series terms | | moments | | +---------------------------------------+----------------------------------+ | "Convergence uncertain" only for | The moment may not exist; | | high-order moments | check tail behaviour | +---------------------------------------+----------------------------------+ | Sum slightly off from 1.0 | Increase Calc precision to 10 | +---------------------------------------+----------------------------------+ +---------------------------------------+----------------------------------+ | Results look right but method shows | Normal; result is still accurate | | ``partial-sum`` with small deviation | | +---------------------------------------+----------------------------------+ | Moments grow implausibly large | Check for non-existent moments | +---------------------------------------+----------------------------------+ | Results unstable across runs | Increase Calc precision | +---------------------------------------+----------------------------------+ See also -------- * :doc:`common-errors` — error message reference * :doc:`/theory/convergence` — how each method works * :doc:`/user-guide/precision-settings` — precision controls explained