Skip to content

0017 — Functional stabilization precedes 1.0 and later inverse families

Context

ADR 0006 correctly separated the feature-free v0.8 cleanup from future inverse features, but its provisional sequence placed prescribed cell measures in v0.9 and mixed fitting in v0.10.

A later code-first capability review and downstream planning exposed a more important pre-1.0 need. pyvoro2 is intended to serve application packages such as chemvoro, where ordinary workloads include weighted molecular geometries, periodic crystals, and repeated independent simulation frames. The current forward and periodic APIs still contain wrapper-level restrictions and representation-sensitive behaviors that are reasonable to correct before a stable release. v0.9 is also the last inexpensive point for deliberate public API refinement based on real downstream use.

The existing separator inverse layer is already the principal inverse functionality needed by that downstream use. Its fixed-observation inner solve has an exact/convex mathematical contract, while realization-aware active-set refinement is an empirical outer algorithm. Calling the entire realization-aware workflow experimental indefinitely would conflate algorithmic convergence guarantees with API stability: an iterative method can have a stable supported input/result/status contract while still returning cycles, iteration limits, infeasibility, or numerical failure for some inputs.

Prescribed cell measures and mixed observation families are valuable, but they are not required to make the existing package a credible 1.0 dependency.

Decision

The post-v0.8 sequence is changed as follows:

  1. v0.9 is functional/API stabilization and downstream readiness. It may make deliberate documented pre-1.0 API changes and remove artificial forward/periodic restrictions that materially affect intended downstream workflows. It does not add a new inverse observation family merely to fill the version.
  2. The normal realization-aware separator inverse workflow is a v0.9 stabilization target. By the end of v0.9, ordinary downstream callers should not need an API labelled experimental to perform the supported "points + separator observations -> fitted weighted tessellation" workflow. Stable public semantics do not imply a universal convergence theorem for the empirical outer refinement. Advanced research/path internals may remain provisional when the normal high-level contract does not depend on them.
  3. Documentation is stabilized in three ordered passes during v0.9: factual alignment with the final API and capability boundaries; content and information-architecture improvement; then visual/navigation improvement and possible documentation-stack replacement.
  4. 1.0 follows v0.9 and stabilizes the existing forward, periodic, and separator-inverse core. Prescribed-measure and mixed inverse solvers are not gates for 1.0.
  5. v1.1 targets prescribed cell measures. The solver family remains shared with the existing inverse architecture rather than being introduced as an unrelated utility.
  6. v1.2 targets mixed separator-plus-measure fitting. Built-in per-row, per-site, and block-scaling needs should be understood before freezing any generic public observation-block protocol.
  7. The roadmap records potentially valuable wrapper, periodic, inverse, and post-1.0 workstreams so they are not lost. Concrete issue grouping and exact release acceptance criteria are intentionally deferred to later development plans and GitHub issue design.

This decision does not change v0.8 scope or reopen completed v0.8 work.

Consequences

  • The accepted v0.8 technical-maintenance decision remains intact; only its old post-v0.8 feature ordering is superseded.
  • v0.9 becomes the main opportunity to qualify and, where justified, refine the public API before the stronger 1.0 compatibility commitment.
  • Downstream chemistry-facing validation is evidence for API readiness without moving chemistry-specific models or structure parsing into pyvoro2.
  • Molecule, crystal, and repeated-frame use does not by itself imply a persistent trajectory/container API; independent frame computation is enough for the pre-1.0 contract unless profiling establishes a separate need.
  • The realization-aware separator algorithm can remain explicitly described as empirical and non-universally-convergent while its supported public workflow is promoted out of the experimental lifecycle category.
  • Prescribed-measure and mixed research work no longer delay the stable 1.0 release.
  • Documentation technology is not selected before the factual API and content architecture are stable.

Decisions intentionally left open

This record does not silently settle two package/backend policies identified by the capability review. They require explicit maintainer confirmation during v0.9/1.0 planning:

  • whether pyvoro2 should commit to one repository and one distribution through 1.0, with post-1.0 reassessment only under concrete triggers;
  • whether pyvoro2 should formally adopt a no-persistent-functional-Voro++-fork policy, including the exact treatment of narrowly carried correctness or upstream-backport patches.

Until those decisions are accepted separately, the roadmap records them as questions to confirm rather than assumptions.

Alternatives considered

Keep prescribed measures in v0.9 and mixed fitting in v0.10

Rejected. Those features are scientifically useful but are not the limiting factor for the immediate downstream package. Adding them before correcting avoidable forward/periodic friction would spend the remaining pre-1.0 API freedom on the wrong priority.

Add v0.9 functional stabilization, then still require v0.10/v0.11 inverse features before 1.0

Rejected. A stable release can be based on the already substantial forward and separator-inverse functionality once it is validated by real downstream use. There is no architectural reason for a second observation family to be a 1.0 gate.

Keep the realization-aware separator workflow experimental through 1.0

Rejected as a blanket policy. Lack of a universal outer-loop convergence theorem is a scientific limitation to document, not by itself a reason to deny stable API status to the package's main downstream inverse workflow. Stable status must instead be earned through clear supported inputs, inspectable termination, consistent final-state semantics, tests, and downstream use.