Validation Matrix

Volumential keeps the fast pull-request test suite separate from high-cost accuracy checks. This page records the current validation coverage so kernel, mode, and backend gaps are visible instead of being inferred from individual test names.

Test Tiers

Validation tiers

Tier	How to run	Routine execution	Purpose
Smoke and regression tests	pytest	Pull-request CI and main pushes	Import checks, cache/schema regressions, table-manager behavior, symmetry metadata, selected FMM paths, and reduced example runs.
Long-run tests	pytest --longrun	Developer or dedicated experiment runs	Larger table-generation and quadrature cases that are too expensive for every pull request.
Full-accuracy tests	pytest -m full_accuracy --full-accuracy	CI Full scheduled/manual runs, on a GitHub-hosted CPU; locally on any fp64 device	High-cost direct-reference and split/non-split accuracy checks, and the volume FMM convergence and PDE-residual regressions. CI Full runs them on the PoCL CPU, the two 3D split-versus-nonsplit tests at a reduced size, and fails if any of them is skipped.
Measured evidence	Driver code kept outside this repository, run against a pinned revision of it	Dedicated hosts; never in pull-request CI	Timing, cache, and parameter-sweep evidence. What such a run has to record is Benchmarks and reproducibility.

Current Capability Matrix

Kernel and mode validation status

Area	Dimensions	Modes	Numerics	Current coverage	Remaining gap
Laplace free-space near-field tables	2D, 3D	Volume-source to target nodes; scalar and derivative table entries	Real scalar, derivative signs, symmetry-reduced payloads	Smoke/regression tests cover table construction, cache schema, orbit reconstruction, source/target derivative signs, and direct per-level versus rescaled table comparisons.	Broader nonuniform stress and memory-scaling tests remain performance work rather than correctness coverage.
Helmholtz split reuse	2D, 3D where supported	Volume FMM split and non-split comparisons; 2D directional source paths	Complex-valued scalar outputs and derivative paths	full_accuracy tests compare split outputs against non-split or higher-order references at fixed representative parameters.	Capability reporting is still per-test; unsupported mixed/backend combinations should keep raising explicit errors. Broader parameter ladders remain benchmark coverage rather than full-accuracy CI coverage.
Yukawa split reuse	2D, 3D where supported	Volume FMM split and non-split comparisons; 2D directional source paths	Real scalar outputs and derivative paths	full_accuracy tests cover split/non-split tracking and directional source derivative behavior at fixed representative parameters.	Same backend/mixed-combination policy audit as Helmholtz; broader parameter ladders remain benchmark coverage.
Cahn-Hilliard and other legacy kernels	As implemented by existing specialized tests	Focused compatibility and cache/schema checks	Real scalar paths where currently exposed	Existing regression tests preserve table-manager and legacy cache behavior.	Not yet represented in a unified numerical validation matrix.
Matrix/vector PDE kernel families	Planned	Planned vector/tensor modes	Planned matrix-valued outputs	Tracked by kernel roadmap issues.	Not part of the current M1 validation closure.
Periodic or hybrid boundary paths	Planned or experimental	Periodic-tail and hybrid validation workflows	Kernel-dependent	Tracked separately from free-space validation.	Free-space and periodic rows are not yet a single complete matrix.

CI Partitioning

Pull-request CI runs smoke and regression coverage that should stay bounded in runtime. The scheduled/manual CI Full workflow runs the example jobs and the full_accuracy tests, on the PoCL CPU of a GitHub-hosted runner, so no pull request waits for the full matrix. That job collects the marker explicitly, to catch marker drift and import errors, and fails if any marked test is skipped, so a skipped test is never counted as validation.

When adding a new kernel or derivative mode, update this page in the same pull request that adds tests. A feature should not be marked as fully covered unless there is at least one CI-friendly regression test and, for high-order numerical claims, either a full_accuracy test or a documented benchmark/provenance path.