Skip to content
This repository was archived by the owner on Aug 12, 2026. It is now read-only.
This repository was archived by the owner on Aug 12, 2026. It is now read-only.

Make simulations reproducible and persistence portable #93

Description

@acgetchell

Summary

Give every stochastic run an explicit, scientifically scoped reproducibility contract and make persisted
triangulations trustworthy across supported platforms.

Determinism applies to state CDT++ owns. It must not perturb the spherical input geometry, replace CGAL's existing
range-insertion behavior, or change foliation repair solely to force one tetrahedralization of degenerate
cospherical points.

Reproducibility contract

On the recorded supported toolchain:

  • A root seed and stable named streams reproduce the tested PCG sequences.
  • The initialization stream reproduces the ordered, pre-CGAL spherical point sequence.
  • Given an identical starting manifold, the transition stream reproduces the tested move/outcome trace, counters,
    and resulting topology.
  • When a seed is omitted, CDT++ generates it once, prints it, and persists it with the output.

A fresh run with the same seed and configuration is not required to reproduce the same final CGAL topology,
post-repair vertex set, simplex counts, or payload bytes. Points on a spherical layer are cospherical, so CGAL may
select different valid tetrahedralizations; foliation repair may then remove different vertices. Output placement
and topology fingerprints make those differences visible without treating them as RNG failure.

Scope

  • Own one persistent random engine or explicit set of derived streams per simulation.
  • Route move selection, shuffling, probability draws, and initial point generation through recorded random state.
  • Define and test stream-consumption boundaries.
  • Record the seed, relevant parameters, version/toolchain, replay limits, state fingerprints, transition trace, and
    integrity metadata with outputs.
  • Replace timestamps that produce invalid Windows filenames.
  • Validate complete serialization, flush, close, parse, causal metadata, and triangulation integrity.
  • Use atomic replacement for payloads and manifests where practical.
  • Keep checkpoints explicitly snapshot-only until mutable RNG and runtime state are serialized and a resume
    interface is supported.

Acceptance criteria

  • Fixed seeds reproduce tested RNG prefixes and the ordered pre-CGAL initialization point sequence on the same
    supported toolchain.
  • Given an identical starting manifold, the same seed and configuration reproduce the tested transition trace,
    counters, and output topology.
  • Tests do not require two independent cospherical CGAL constructions to have matching topology, post-repair
    placement, counts, or serialized bytes.
  • No geometric perturbation or alternate triangulation/repair policy is introduced solely for determinism.
  • Failures and manifests report enough seed, configuration, toolchain, replay-scope, and fingerprint information to
    diagnose a run.
  • Different seeds are covered without probabilistic assertions.
  • Output names are portable across the supported matrix.
  • Truncated, malformed, mismatched, or trailing data fails with diagnostics and never masquerades as valid topology.
  • Persistence behavior, snapshot-only semantics, and cross-platform/toolchain limits are documented.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions