Repository navigation
Publish deterministic C++ reference fixtures for Rust comparison #94
Description
Activity
Repository review follow-up for the verification plan:
- Add exact invalid-
alphaboundary cases rather than relying only on broad valid ranges. - Test Metropolis detailed balance and forward/reverse proposal probabilities independently of production counters.
- Replace broad random action checks with deterministic fixtures whose expected geometry and action deltas are independently derived.
- For every move rejection/failure class, compare a canonical pre/post representation to prove topology, metadata, geometry, and caches are unchanged.
These are specific test gaps under the existing P0/P1 regression and deterministic-oracle scope.
- Add exact invalid-
Scientific-correctness follow-up (2026-07-24)
This is the active tracker for the remaining findings. #106 is complete and specifically owns the Pachner-move combinatorics; #92 is complete and owns the repaired Metropolis/action implementation. The items below are the independent-oracle, tolerance, and statistical verification work already in scope for #94.
1. Replace the empirical spherical population estimator with a derived, monotone contract
Current behavior in
expected_points_per_timeslice()uses piecewise factors0.4,0.2,0.15, and0.1. Those factors are empirical, and the thresholds introduce nonphysical discontinuities. For example, at four timeslices, increasing the request from 999 to 1000 simplices reduces the base layer estimate from 99 to 50 points. In repeated independent process runs with the current spherical generator, the actual tetrahedron range changed from 4222–4249 for 999 requested simplices to 2072–2088 for 1000 requested simplices. That effect is far larger than the observed CGAL run-to-run variation.The citation in the source currently overstates what Dwyer supplies. Dwyer proves an expected-complexity result for points drawn independently and uniformly from the interior of a ball. In three dimensions the asymptotic expected tetrahedron count is
E[N3] ~ (24 pi^2 / 35) n ~= 6.768 n.That is a useful reference baseline, but it is not a hard upper bound and it does not directly model CDT++ input: this generator places points on nested cospherical layers and then removes causally invalid vertices.
References:
- M. Dwyer, Higher-dimensional Voronoi diagrams in linear expected time.
- A later derivation records the 3D constant explicitly in Section 4.1 of Duménil, 2022.
- The general 3D worst-case bound is
N3 <= (n^2 - 3n - 2) / 2, as summarized in Three-dimensional Delaunay triangulation. This follows the upper-bound theorem and is distinct from the Dwyer expectation.
The generator does have one exact relationship that should be the starting point. For a positive base population
p, initial radiusr0, spacingdr, andTlayers, the number of input vertices isV_input(p) = sum(i = 0..T-1, floor(p * (r0 + i * dr))).The estimator should therefore separate three contracts:
- exact and overflow-safe input-population calculation;
- the rigorous quadratic tetrahedron bound for safety/preflight checks, not preallocation or an expected result;
- a calibrated monotone estimate for the expected post-repair tetrahedron count, with declared uncertainty bands appropriate to CGAL randomness and the layered input distribution.
A reasonable implementation path is to measure
N3(p, T, r0, dr)over a predeclared parameter grid and multiple independent processes, fit or otherwise derive a monotone calibration, and validate it out of sample. A bracketed corrective retry may be considered if the initialization cost is acceptable. Exact topology counts must not be the oracle for randomized CGAL construction.Local exploratory evidence from 12 independent process runs per case:
Requested N3 / timeslices Observed N3 range Mean Sample SD 24 / 3 1–1 1.00 0.00 64 / 3 22–28 24.00 1.76 640 / 4 2646–2691 2679.17 12.28 6400 / 7 27472–27480 27476.08 2.50 999 / 4 4222–4249 4238.17 9.10 1000 / 4 2072–2088 2081.67 6.12 Acceptance evidence should include monotonicity across former thresholds, overflow/boundary cases, calibration residuals on held-out inputs, and tolerance bands declared before final samples are examined.
2. Add nonzero-action Metropolis-Hastings acceptance oracles
The direct acceptance test currently constructs
Metropolis_3withk = lambda = 0, so it verifies the Hastings factor but not the action sign, exponential, or clamp. Add hand-computed fixtures formin(1, q_reverse / q_forward * exp(S_current - S_proposed))covering a probability strictly between zero and one, clamping above one, inverse-direction behavior, and a numerically extreme delta. The expected value must be computed independently of the production action helper.
3. Derive quantity-specific action tolerances
The staged tests improve independence by adding closed-form reference calculations, but the alpha=1 generalized-versus-rounded comparison still uses the repository-wide one-percent
TOLERANCE. Replace that with a bound derived from the rounded coefficients and the actual simplex counts. Geometry/radius checks, rounded published coefficients, generalized transcendental formulas, and MPFR round-off should not share one tolerance. Record absolute and relative components per quantity.4. Calibrate the raw-site uniformity test statistically
The current five-bin test makes 50,000 draws, expects 10,000 per bin, and allows plus/minus 1,000. A bin has standard deviation
sqrt(50000 * 0.2 * 0.8) ~= 89.4, so the current envelope is about 11.2 standard deviations and has little power. Use a predeclared goodness-of-fit statistic or a justified simultaneous binomial bound, while keeping deterministic boundary tests separate from distributional evidence. Do not require identical raw counts across standard-library implementations.5. Clarify the alpha=-1 action contract
The documentation writes the alpha=-1 expression with an explicit imaginary unit, while the API returns a real MPFR value and the test treats it as a real coefficient. State whether the function returns the coefficient of
i, a Wick-rotated real action, or another convention; then align the name, documentation, and independent oracle with that choice.PR relationship
The currently staged multithreading implementation can remain one commit/PR as requested. It should primarily reference #88. The independent S3 action oracles already staged are partial #94 evidence; the unresolved items above remain tracked here and should not be folded into #88 merely because the population estimator was encountered while checking parallel initialization bounds.
- changed the title
[-]Build the definitive C++ verification suite and Rust comparison fixtures[/-][+]Publish deterministic C++ reference fixtures for Rust comparison[/+]on Jul 24, 2026 - added a commit that references this issue
on Jul 25, 2026 - added a commit that references this issue
on Jul 26, 2026
Current v1.0.0 plan (2026-07-24)
Starts after: #88 and the completed scientific/reproducibility audits. Blocks: #98 and #104.
This issue publishes the bounded behavior-level oracle needed by the archival release and by
causal-triangulations. It consolidates completed correctness work into small deterministic fixtures, language-neutral schemas, declared numerical tolerances, complete manifests, and independently checkable expected results.It is not a new implementation-refactor tracker or a comprehensive statistical/performance research program.
Summary
Publish a compact, versioned set of deterministic CDT++ reference fixtures and results that a Rust implementation can consume without copying C++ implementation logic.
CDT++ is an independent reference implementation, not presumed ground truth. A discrepancy is an investigation target until the scientific contract or one of the implementations explains it.
Required deliverables
Comparison rules
Exact fields
Canonical topology, incidence and adjacency, foliation and time labels, simplex types, f-vectors, move legality, integer count deltas, and deterministic accept/reject decisions must agree exactly.
Numerical fields
Coordinates, Regge actions and deltas, probabilities, and observables use named tolerances justified per quantity. A repository-wide percentage is not a generic scientific oracle.
Transition fixtures
Fixtures provide the proposed move, site, and acceptance variate explicitly. This permits comparison of proposal preparation, action delta, and accept/reject behavior without requiring identical RNG engines, allocation behavior, or container iteration order.
Randomized CGAL quantities
Randomized construction results use declared tolerance or statistical bands rather than exact simplex counts. Dwyer’s distribution-specific expected-complexity results and general three-dimensional worst-case bounds are cited only for their valid roles.
The spherical population estimator must be documented as an estimator rather than an exact topology oracle. Its supported domain must be monotone and overflow-safe, but an extensive new calibration study is not a v1.0.0 release requirement.
Action convention
Independent nonzero-action fixtures must verify the Metropolis-Hastings action sign, exponential factor, reverse/forward proposal factor, probability clamping, and numerically extreme deltas. The
alpha = -1action convention must be named consistently in the API, documentation, and reference results.Non-goals and deferred research
The following are valuable Praxis or
causal-triangulationscomparison work, but are not CDT++ v1.0.0 release blockers:Acceptance criteria