.. _developer-scientific-evidence-matrix:

##########################
Scientific evidence matrix
##########################

:Last reviewed: 25 July 2026

This matrix records why a numerical result is believed, not merely where its
implementation is exercised. ``DIRECT`` means a test derives an expected
value by hand or from a closed form. ``INDEPENDENT`` means a second algorithm
or analytical physical model reaches the same result. ``REGRESSION`` means a
frozen output is useful for detecting change but is not, by itself, evidence
that the value is scientifically correct.

.. list-table:: Central numerical outputs and their independent evidence
   :header-rows: 1
   :widths: 19 25 39 17

   * - Result
     - Implementation
     - Independent evidence
     - Status
   * - Common means, block errors, MSD
     - ``analysis.analysis``
     - Hand-computed running means, one- and two-point block standard errors,
       and the squared-lag MSD in ``test_analysis.py``.
     - DIRECT
   * - MD crossing flux
     - ``flux_analysis``
     - Hand-counted crossings per physical time window in
       ``test_flux_analysis.py``; end-to-end rates are also checked by the
       double-well campaign.
     - DIRECT + INDEPENDENT
   * - TIS/RETIS crossing probability
     - ``path_analysis.analyse_path_ensemble`` and ``match_probabilities``
     - Accepted-path integer ratios and their explicit product in
       ``test_path_analysis.py``.
     - DIRECT
   * - RETIS flux and rate
     - ``path_analysis.retis_flux`` and ``retis_rate``
     - Direct inverse-path-time and product/error-propagation formula checks;
       the method campaign compares the final rate with Kramers--MM theory.
     - DIRECT + INDEPENDENT
   * - WHAM crossing probability and rate
     - ``wham_analysis``
     - Hand-built unweighted and weighted matrices with exact non-zero
       crossing probabilities; single-ensemble agreement with point matching;
       Kramers--MM campaign.
     - DIRECT + INDEPENDENT
   * - REPPTIS local/global probability
     - ``repptis_analysis`` and ``_repptis_state``
     - Raw-column occupancy counts feed both a closed-form recursion and a
       separately constructed Markov matrix in
       ``test_repptis_reference_oracle.py``.
     - INDEPENDENT
   * - REPPTIS MSM probability and MFPT
     - ``repptis_msm``
     - Symmetric-random-walk closed form, a hand-computed three-state MFPT,
       stochastic-matrix invariants, and comparison with the upstream
       implementation.
     - DIRECT + INDEPENDENT
   * - Path weights and transmission coefficient
     - ``path_weights``
     - Equal-weight fixture and explicit ``8 reactive / 10 crossings = 0.8``
       calculation in ``test_path_weights.py``.
     - DIRECT
   * - Interface placement
     - ``interface_placement`` and ``interface_estimation``
     - Exact geometric placement on :math:`p(x)=0.5^x`, plus hand-counted
       binless crossing curves.
     - DIRECT
   * - Permeability
     - ``path_analysis.perm_calculations``
     - Hand-counted :math:`\xi` and :math:`\tau`, explicit permeability
       product, and quadrature error propagation in ``test_path_analysis.py``.
     - DIRECT
   * - Energy/order descriptive reports
     - ``energy_analysis`` and ``order_analysis``
     - Frozen fixture outputs, independently tested common statistics, and the
       shape-one kinetic gamma law checked against
       :math:`2\exp(-2E)` in ``test_energy_analysis.py``.
     - DIRECT
   * - Cross-engine rate equivalence
     - ``examples/validation/engines/water_dimer``
     - Shared-force-field energy gate, direct-MD timescale, and three-engine
       rate comparison documented in :doc:`engine-validation`.
     - INDEPENDENT CAMPAIGN

Scope boundary
==============

The matrix covers numerical results exposed by the analysis reports and
interface tools. Plot layout, file formatting, and training-frame selection
have deterministic functional tests, but are not themselves scientific
estimators and are outside this oracle inventory.