Skip to content

v0.8 development plan — cleanup and compatibility removal

  • Status: Draft
  • Target release: v0.8.0
  • Base release: v0.7.0
  • Maintainer: Ivan Yu. Chernyshov
  • Scope decision: 2026-07-22
  • Activation: after verified v0.7.0 tag and PyPI publication
  • Decision: ADR 0006

This draft records work intentionally deferred from the v0.7 finalization cycle. It does not authorize implementation before the v0.7.0 tag and PyPI publication are verified and a v0.8 milestone, issue set, approval date, and Active status are recorded. v0.7.0 intentionally has no GitHub Release or Zenodo record; v0.8.0 is intended to be the next full package, GitHub, and Zenodo archival release.

Intended outcome

v0.8.0 should leave pyvoro2 with one clean forward API, one clean separator inverse API, a navigable test suite, and private Python helpers grouped under an explicit internal package. It is a maintenance release, not a feature release.

At the end of v0.8:

  • new and existing code use pyvoro2.inverse and pyvoro2.inverse.separator, not pyvoro2.powerfit or top-level separator re-exports;
  • deprecated planar result selectors and aliases are gone;
  • compatibility-only reference and characterization assets have been removed or converted into canonical regression tests;
  • tests are organized by subsystem;
  • root private Python helpers live under pyvoro2._internal;
  • v0.7 stable numerical behavior remains unchanged;
  • deferred non-critical audit findings are either fixed or explicitly carried forward with justification.

Required scope

Compatibility removal

Remove the compatibility-only surfaces listed in ADR 0006 and update:

  • package exports and lazy attribute resolution;
  • direct module imports and pickling compatibility decisions;
  • tests and public examples;
  • API reference navigation;
  • distribution-content checks;
  • migration documentation and changelog;
  • architecture and lifecycle inventories.

Judge retention by clean current architecture and usability. Do not preserve an old route solely because a hypothetical caller might still use it.

Test-suite organization

Move the flat tests/ layout into responsibility-based directories. A likely starting structure is:

tests/
├── forward/
│   ├── spatial/
│   └── planar/
├── inverse/
│   └── separator/
├── compatibility/
├── integration/
├── tooling/
├── fuzz/
├── _support.py
└── conftest.py

The final structure may differ after an inventory, but the move should be primarily mechanical. Avoid combining file moves with numerical test rewrites. Shared helpers should live in explicit support modules rather than being imported from conftest.py.

Once v0.7-only compatibility tests are removed, a compatibility/ directory is needed only for still-supported cross-version or raw-output contracts.

Private Python helper organization

Move root private helpers such as _cell_output.py, _domain_geometry.py, _face_shifts3d.py, _inputs.py, _power_input.py, _util.py, and _weight_transforms.py under pyvoro2._internal with responsibility-based names or subpackages where useful.

Do not rename the compiled native extensions _core and _core2d merely for visual symmetry. Preserve lazy native loading and verify source and wheel contents after the move.

Planar private helpers may be reviewed at the same time, but no public pyvoro2.core namespace should be introduced.

Deferred v0.7 audit findings

The initial deferred list includes:

  • narrow overly strong wording around pickle restoration and version independence;
  • exact support and validation expectations for direct TessellationResult(...) construction;
  • external-ID typing versus runtime behavior in separator observations;
  • eager inverse imports caused by v0.7 top-level compatibility exports;
  • release-tool shell-glob portability for twine check;
  • any other non-critical documentation/source mismatch explicitly recorded during v0.7 issue #16 or release qualification.

This list is not permission for unrelated redesign. Each item should be fixed by its smallest coherent change or moved to a named later issue.

Non-goals

v0.8 does not include:

  • prescribed area or volume observations or fitting;
  • mixed separator and cell-measure objectives;
  • new solver families or numerical algorithms;
  • trajectory, repeated-frame, batch, or parallel APIs;
  • site motion, centroid observations, or anisotropic geometry;
  • a public pyvoro2.core namespace;
  • broad source refactoring unrelated to compatibility or private-helper organization.

Validation

The release should demonstrate that cleanup did not alter stable v0.7 behavior:

  • full deterministic and opt-in relevant test groups;
  • canonical forward and separator workflows only;
  • exact public export inventory after removal;
  • clean source editable installation;
  • no-SciPy installation and explicit sparse installation;
  • strict docs, notebook, README, sdist, wheel, and smoke checks;
  • comparison of representative v0.7 numerical outputs before and after internal moves;
  • platform coverage sufficient to protect native lazy-loading changes.

Later feature releases

  • v0.9 introduces prescribed cell areas and volumes.
  • v0.10 introduces the first mixed separator-plus-measure inverse problems.

Neither feature release should be pulled into this cleanup plan.