.. _api-core:

core.py — Computational Backend
=================================

The ``core`` module contains all numerical computation for ToFUL.
The frontend (``app.py``) calls the public functions at the bottom of
this module; it imports nothing from SciPy or NumPy directly.

.. contents:: On this page
   :local:
   :depth: 2

----

Architecture
------------

.. code-block:: text

   toful_parser.py
       └── normalise_for_eval()    ← clean user input
       └── build_safe_dict()       ← eval namespace

   core.py
       ├── _build_safe_dict()      ← canonical eval namespace
       ├── _cached_compile()       ← AST compiled once per expression
       ├── _eval_scalar()          ← scalar evaluation
       ├── _eval_array()           ← vectorised NumPy evaluation
       │
       ├── Convergence cascade (discrete)
       │   ├── _wynn_epsilon()
       │   ├── _aitken_delta2()
       │   ├── _cohen_villegas_zagier()
       │   └── _sum_series_with_acceleration()
       │
       ├── Quadrature (continuous)
       │   ├── _gauss_laguerre_integrate()
       │   ├── _gauss_hermite_integrate()
       │   ├── _mpmath_integrate()
       │   └── _quadrature_integrate()   ← dispatch
       │
       ├── Symbolic path
       │   └── _try_sympy_moment()
       │
       ├── Validation
       │   ├── validate_drv_probabilities()   ← public
       │   └── validate_crv_pdf()             ← public
       │
       ├── Moment computation
       │   ├── _compute_drv_moment()
       │   ├── _compute_crv_moment()
       │   └── compute_moments_parallel()     ← public
       │
       ├── Statistical summary
       │   └── compute_statistical_summary()  ← public
       │
       └── Range parsing
           ├── parse_range_input()            ← public
           └── parse_continuous_bound()       ← public

----

Data Classes
------------

.. autoclass:: core.SeriesPattern
   :members:
   :undoc-members:

.. autoclass:: core.SeriesAnalysis
   :members:
   :undoc-members:

.. autoclass:: core.ValidationResult
   :members:
   :undoc-members:

.. autoclass:: core.MomentResult
   :members:
   :undoc-members:

.. autoclass:: core.StatisticalSummary
   :members:
   :undoc-members:

----

Public API
----------

Validation
~~~~~~~~~~

.. autofunction:: core.validate_drv_probabilities

.. autofunction:: core.validate_crv_pdf

Moment Computation
~~~~~~~~~~~~~~~~~~

.. autofunction:: core.compute_moments_parallel

Statistical Summary
~~~~~~~~~~~~~~~~~~~

.. autofunction:: core.compute_statistical_summary

Range Parsing
~~~~~~~~~~~~~

.. autofunction:: core.parse_range_input

.. autofunction:: core.parse_continuous_bound

Utilities
~~~~~~~~~

.. autofunction:: core.to_subscript

.. autofunction:: core.detect_series_pattern

.. autofunction:: core.generate_extended_series

----

Convergence Algorithm Reference
--------------------------------

The following internal functions implement the convergence acceleration
cascade. They are not part of the public API but are documented here
for contributors and advanced users.

``_wynn_epsilon(partial_sums)``
   Wynn ε-algorithm. Builds a recursive epsilon-table from the
   list of partial sums and returns the best limit estimate from
   the even-column diagonal.

   Returns ``(estimate, converged, info_string)``.

``_aitken_delta2(s0, s1, s2)``
   Aitken Δ² three-point extrapolation. Returns the extrapolated
   limit from three consecutive partial sums.

``_cohen_villegas_zagier(expr_str, n_terms)``
   Cohen-Villegas-Zagier algorithm for alternating series.
   Computes near-machine-precision estimate in exactly ``n_terms``
   evaluations.

   Returns ``(estimate, True, info_string)``.

``_sum_series_with_acceleration(expr_str, x_values, r, a, tol)``
   Main discrete summation engine. Evaluates ``Σ (x-a)^r · f(x)``
   over ``x_values`` and applies the full convergence cascade.

   Returns a :class:`~core.SeriesAnalysis` instance.

----

Quadrature Reference
--------------------

``_gauss_laguerre_integrate(func, n=64)``
   Gauss-Laguerre quadrature for :math:`\int_0^\infty f(x)\,dx`.
   Uses 64 nodes. Returns ``(estimate, error_estimate)``.

``_gauss_hermite_integrate(func, n=64)``
   Gauss-Hermite quadrature for :math:`\int_{-\infty}^{\infty} f(x)\,dx`.
   Uses 64 nodes. Returns ``(estimate, error_estimate)``.

``_mpmath_integrate(func, lower, upper, precision)``
   mpmath tanh-sinh (double-exponential) quadrature.
   Active when Calc precision ≥ 13.
   Returns ``(estimate, error_estimate, "mpmath-tanh-sinh")``.

``_quadrature_integrate(func, lower, upper, precision, ...)``
   Dispatch function. Selects the best quadrature method based on
   domain and precision, cross-checks results, returns
   ``(value, error, method_name)``.

----

Configuration Constants
------------------------

.. code-block:: python

   _MPMATH_THRESHOLD = 12    # Calc precision above which mpmath activates
   _MAX_SERIES_TERMS = 500   # Hard cap on infinite-series truncation
   _CONVERGENCE_TOL  = 1e-12 # Default convergence tolerance
   _GAUSS_NODES      = 64    # Gauss-Laguerre / Hermite quadrature nodes

----

Legacy Compatibility
--------------------

The following classes and function from the original codebase are
retained as thin shims over the new API. New code should use the
public functions above directly.

.. autoclass:: core.InfiniteSeriesHandler
   :members:

.. autoclass:: core.EnhancedProbabilityValidator
   :members:

.. autoclass:: core.EnhancedMomentCalculator
   :members:

.. autofunction:: core.rth_moment

See also
--------

* :doc:`toful-parser` — input normalisation API
* :doc:`/theory/convergence` — the mathematics behind each method