.. _user-guide-discrete:

Discrete Random Variables
==========================

A **discrete random variable** (DRV) takes values from a countable set —
either finite (like a die roll) or infinite (like the number of coin flips
before the first head). ToFUL computes moments for both cases.

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

----

Defining a Discrete Distribution
----------------------------------

A discrete distribution is defined by two inputs:

1. **Support** — the set of possible values :math:`\{x_1, x_2, \ldots\}`
2. **PMF** — the probability mass function :math:`P(X = x)`

The PMF must satisfy:

.. math::

   P(X = x) \geq 0 \quad \text{for all } x

.. math::

   \sum_{x} P(X = x) = 1

ToFUL validates both conditions automatically before computing anything.

----

Finite Support
--------------

Enter a comma-separated list of values in the **Range** field:

.. code-block:: text

   1,2,3,4,5,6

Then enter a PMF that sums to 1 over those values:

.. code-block:: python

   # Fair six-sided die
   1/6

   # Non-uniform discrete distribution
   0.1 if x == 1 else 0.2 if x == 2 else 0.3 if x == 3 else 0.2 if x == 4 else 0.1 if x == 5 else 0.1

For finite support, ToFUL evaluates the PMF at each value exactly and
sums directly — no approximation involved.

----

Infinite Support
----------------

End the range input with ``...`` to signal an infinite series:

.. code-block:: text

   0,1,2,3,...

ToFUL detects the sequence pattern (arithmetic or geometric) and generates
values up to the maximum terms setting (default 200, adjustable to 500 in
**Advanced**).

**Pattern detection examples:**

+---------------------------+------------------+------------------------------+
| Range input               | Pattern detected | Extended as                  |
+===========================+==================+==============================+
| ``0,1,2,3,...``           | Arithmetic (d=1) | 0, 1, 2, 3, 4, …             |
+---------------------------+------------------+------------------------------+
| ``1,3,5,7,...``           | Arithmetic (d=2) | 1, 3, 5, 7, 9, …             |
+---------------------------+------------------+------------------------------+
| ``1,2,4,8,...``           | Geometric (r=2)  | 1, 2, 4, 8, 16, …            |
+---------------------------+------------------+------------------------------+
| ``1,3,9,27,...``          | Geometric (r=3)  | 1, 3, 9, 27, 81, …           |
+---------------------------+------------------+------------------------------+

.. note::

   For distributions whose PMF decays quickly (e.g. Geometric with large
   :math:`p`, Poisson with small :math:`\lambda`), 200 terms captures
   effectively all probability mass and the results are highly accurate.
   For heavy-tailed distributions, increase **Max series terms** in Advanced
   settings.

----

Convergence Acceleration for Infinite Series
--------------------------------------------

When computing moments over infinite support, ToFUL does not simply sum
the first N terms and stop. It applies a cascade of convergence
accelerators in order:

1. **Term magnitude** — if the last 10 terms are all smaller than the
   tolerance, the partial sum is accepted as converged.

2. **Wynn ε-algorithm** — extracts a limit estimate from the full sequence
   of partial sums via a recursive epsilon-table. Effective for a wide
   class of converging series.

3. **Aitken Δ²** — a lightweight three-point extrapolation, cross-checked
   against the current partial sum.

4. **Cohen-Villegas-Zagier** — optimal for alternating series; achieves
   near-machine-precision in exactly N evaluations.

5. **Geometric ratio-bound** — estimates the tail as a geometric series
   and adds it to the partial sum.

The **Convergence** tab shows which method fired for each moment order.

----

PMF Validation
--------------

Before moments are computed, ToFUL validates the PMF:

* Evaluates the function at every support value using vectorised NumPy.
* Checks that no probability is negative.
* Applies the convergence cascade to estimate the total probability mass.
* Reports the sum and the convergence method used.

If validation fails, a detailed error is shown including the computed
sum and the deviation from 1.

----

Common Discrete Distributions
------------------------------

The following table shows how to enter standard distributions.

.. list-table::
   :header-rows: 1
   :widths: 22 25 53

   * - Distribution
     - Range
     - PMF expression
   * - Bernoulli(p=0.4)
     - ``0,1``
     - ``0.4 if x == 1 else 0.6``
   * - Binomial(n=5, p=0.3)
     - ``0,1,2,3,4,5``
     - ``(factorial(5)/(factorial(x)*factorial(5-x))) * 0.3**x * 0.7**(5-x)``
   * - Geometric(p=0.3)
     - ``0,1,2,3,...``
     - ``0.3 * (0.7 ** x) if x >= 0 else 0``
   * - Geometric(p=0.3) †
     - ``1,2,3,4,...``
     - ``0.3 * (0.7 ** (x-1)) if x >= 1 else 0``
   * - Poisson(λ=3)
     - ``0,1,2,3,...``
     - ``(exp(-3) * 3**x) / factorial(x) if x >= 0 else 0``
   * - Negative Binomial(r=2, p=0.4)
     - ``0,1,2,3,...``
     - ``(factorial(x+1)/(factorial(x)*factorial(1))) * 0.4**2 * 0.6**x if x >= 0 else 0``

† The Geometric distribution has two common parameterisations — number of
failures before the first success (support starting at 0) and number of
trials until the first success (support starting at 1).

----

Tips for Discrete Distributions
---------------------------------

* Use ``factorial(n)`` only for integer arguments. For non-integer
  generalisation, use ``gamma(n+1)``.
* The PMF guard ``if x >= 0 else 0`` is good practice — it prevents
  stray negative evaluations from contaminating the sum.
* For Binomial distributions, compute ``factorial`` of small integers
  only. For large :math:`n`, reformulate using ``gamma``.
* Increase **Calc precision** to 10–12 for distributions with very small
  probabilities (e.g. Poisson with small :math:`\lambda` and large
  support).

See also
--------

* :doc:`/examples/discrete-distributions` — full worked examples
* :doc:`/theory/convergence` — how convergence acceleration works
* :doc:`/user-guide/interpreting-results` — understanding the output tabs