Scientific Validation

Tests should identify what kind of evidence they provide. Agreement with a previous implementation establishes compatibility; it does not by itself establish physical correctness.

Evidence classes

Evidence	Purpose	Suitable reference
Analytical invariant	Verify definitions and limiting cases	Hand-derived value, conservation law or exactly soluble system
Independent implementation	Detect shared implementation errors	ASE, a direct NumPy expression or another documented program
Legacy parity	Preserve established PQ tool behavior	Output generated by the named legacy executable and input
Kernel parity	Keep optimized and fallback paths equivalent	Direct comparison on identical arrays and parameters
End-to-end behavior	Verify parsing, orchestration and serialization	CLI/API run with versioned fixtures and expected output

Use more than one evidence class for a new scientific method. A reference file produced by the implementation under test is not independent validation.

Reference-data provenance

Store compact, deterministic fixtures under tests/data/<method>/. The test module or a README beside the data must record:

• the program and version that generated the reference;

• the complete source input and relevant options;

• the physical units and column meanings;

• any precision loss caused by text serialization;

• the reason for the selected numerical tolerance.

Do not replace a reference file merely to make a failing test pass. A reference change must be reviewable as either a corrected scientific definition, an intentional compatibility change or a newly generated independent benchmark.

Numerical tolerances

Prefer exact equality for integer counts, field names and deterministic text. For floating-point data, choose rtol and atol from the numerical method, reference precision and expected magnitude. Record relaxed tolerances next to the assertion. Do not use one package-wide tolerance for observables with different scales.

Fast kernels may accumulate values in a different order from NumPy fallbacks. Their parity tolerance should cover the expected floating-point summation difference, not unrelated algorithmic changes.

Test commands

pytest.sh runs the requested tests once with debug runtime type checking and once with release settings:

$ bash pytest.sh tests/analysis/rdf -q
$ bash pytest.sh tests/analysis/msd -q
$ bash pytest.sh tests/analysis/vacf -q

Run the complete suite before review:

$ bash pytest.sh

Documentation figures

Executable figures under docs/source/_plots may use an analytic model or a versioned validation fixture. Their captions must state which one. A schematic must not be presented as simulation output, and a legacy parity fixture must not be described as an independent physical benchmark.