V0.12 Release Readiness#

Release Target#

  • package version: 0.12.0

  • git tag: v0.12.0

  • package-index publication: deferred until v1.0 or later

v0.12.0 is a Git-tag-only release. Do not run TestPyPI or PyPI publishing for v0.12.

Done#

  • M0 is complete:

    • v0.12 was frozen as diagnostics and supportability hardening

    • v0.11 was recorded as a completed KS feasibility/no-go release

    • stable KS promotion remained closed as deferred

  • M1 is complete:

    • generator-fit diagnostic semantics were frozen

    • evidence labels and fallback reason categories were fixed

  • M2 is complete:

    • pdelie.reporting.summarize_generator_fit_diagnostics(...) landed as the only public v0.12 API addition

    • fit_translation_generator(...) gained richer diagnostics without changing coefficient selection

    • API_STABILITY.md documents the new reporting helper

  • M3 is complete:

    • internal KS fit diagnostic sweeps confirmed fallback-backed evidence across the frozen epsilon and fixture-variant matrix

    • no public KS API landed

  • M4 is complete:

    • internal orbit/coverage feasibility diagnostics passed on stable Heat and KdV fixtures

    • no public orbit/coverage helper or augmentation utility landed

  • M5 is complete:

    • API stability and public-surface guards confirmed the v0.12 public surface

    • internal M3/M4 helpers remained test-only

  • M6 is complete:

    • package metadata and release-facing docs are aligned with 0.12.0

    • this readiness note is current

    • the compact v0_12-release-gate is the current explicit release-gate CI job

Public API Notes#

New stable runtime API in v0.12:

  • pdelie.reporting.summarize_generator_fit_diagnostics(generator)

The helper returns a JSON-compatible runtime summary of GeneratorFamily fit diagnostics, including:

  • singular values

  • condition number

  • selected coefficients

  • selected span distance

  • SVD coefficients

  • SVD span distance

  • fit mode

  • fallback status and reason

  • evidence label

The helper is submodule-only:

  • import from pdelie.reporting

  • no root pdelie export

  • no new canonical object

  • no fitting algorithm change

  • no promotion gate

Retained stable surfaces include:

  • Heat and Burgers strong paths

  • v0.8 weak Heat/Burgers residual report APIs

  • v0.9 normalized periodic short-horizon KdV strong path

  • v0.10 reporting helpers and nested Heat/KdV example summaries

  • v0.11 order-4 spectral derivative extension

  • structured from_numpy(...) and optional from_xarray(...) ingestion

  • existing discovery, portability, symmetry, and visualization runtime helpers

Internal Diagnostic Evidence#

KS Diagnostic Sweep#

The bounded internal KS sweep remained diagnostic-only. All frozen variants concluded:

fallback_stable_across_epsilons

Default variant evidence:

  • residual max absolute value: 2.276047466221332e-09

  • residual RMS value: 3.450580898077348e-10

  • mass drift: 4.686823294199099e-16

  • relative L2 drift: 0.0070894859776733715 as diagnostic-only

  • condition-number median: 214513.53360977306

  • SVD span-distance median: 0.4178159498317849

  • direct SVD in tolerance: False

  • fallback reason stable: True

  • fallback reason: svd_translation_span_drift

Interpretation:

  • KS residual and canonical held-out verification behavior remain healthy

  • direct residual-based SVD fitting remains out of tolerance

  • stable KS runtime promotion remains deferred

Orbit / Coverage Feasibility#

The internal orbit/coverage feasibility helper remained test-only.

Coverage cases:

  • half-coverage quarter-shift case: 32 / 64 points, coverage fraction 0.5

  • full-coverage quarter-shift case: 64 / 64 points, coverage fraction 1.0

Transform consistency:

  • stable Heat and KdV fixtures preserved dims, coords, var names, metadata, and mask under uniform translations

  • inverse-transform and period-wrap errors remained at floating-point noise levels

  • residual RMS stayed stable under shifts

  • provenance recorded operation == "invariant_apply" and construction_method == "uniform_translation"

Interpretation:

  • paper-agnostic orbit/coverage diagnostics are feasible

  • no public orbit/coverage helper landed

  • no public augmentation utility landed

Explicitly Deferred#

  • new PDE support

  • stable KS data generator

  • stable KS residual evaluator

  • KS vertical-slice example

  • KS imported parity

  • weak KS APIs

  • root pdelie exports for KS runtime APIs

  • public orbit/coverage helpers

  • public augmentation utilities

  • broad dataset adapters

  • PDEBench or The Well support

  • multidimensional, multivariable, or nonuniform-grid support

  • operator-facing APIs

  • manuscript-specific experiment logic

  • PyPI and TestPyPI publication; package-index publishing is deferred to v1.0 or later

CI Expectations#

Before tagging v0.12.0, the release PR should have these CI jobs green:

  • v0_12-release-gate

  • editable-tests

  • package-smoke

Historical release-gate test modules remain runnable locally and are covered by editable-tests.

Local Release Checklist#

Before tagging v0.12.0:

  1. Inspect consistency across:

    • pyproject.toml

    • README.md

    • CHANGELOG.md

    • docs/releases/V0_12_RELEASE_READINESS.md

    • docs/releases/PUBLISHING.md

    • docs/specs/API_STABILITY.md

  2. Run the full test suite:

    • python -m pytest

  3. Build the package:

    • python -m build --sdist --wheel

  4. Install dist/pdelie-0.12.0-py3-none-any.whl into a clean environment and verify:

    • stable root imports

    • pdelie.reporting helper imports from the submodule, including summarize_generator_fit_diagnostics

    • one tiny weak Heat report

    • one tiny KdV strong-path residual

    • one tiny order-4 derivative smoke

    • one tiny generator-fit diagnostic summary

    • root pdelie does not export KS, orbit/coverage, augmentation, or weak KS APIs

  5. Run examples:

    • python -m pdelie.examples.heat_vertical_slice

    • python -m pdelie.examples.kdv_vertical_slice

  6. Run:

    • git diff --check

Direct Final Tag Checklist#

After local checks and CI pass:

  • merge the release PR into main

  • tag the merged main commit as v0.12.0

  • do not publish to TestPyPI

  • do not publish to PyPI

  • record package-index publishing as deferred until v1.0 or later

Final Release View#

v0.12.0 is ready when the local release checklist and the current CI jobs pass.

The stable release claim is intentionally narrow:

existing Heat/Burgers/weak-report/KdV/reporting surfaces -> generator-fit diagnostic summaries -> internal KS diagnostic sweep evidence -> internal orbit/coverage feasibility -> release supportability

M3 internal KS diagnostics and M4 orbit/coverage diagnostics remain internal. The final release view is that no stable KS runtime API is promoted.