V0.12 Scope Freeze#

Summary#

v0.12 is the diagnostics and supportability hardening release for pdelie.

Its purpose is:

harden diagnostics and reporting around generator fitting, verification, and orbit/coverage supportability without adding new numerical scope.

Committed release theme:

existing stable Heat/Burgers/weak-report/KdV/reporting surfaces -> fit and verification diagnostics -> orbit/coverage reporting feasibility -> release supportability

v0.12 does not add a new PDE and does not promote Kuramoto-Sivashinsky runtime APIs. The v0.11 KS evidence remains internal feasibility/no-go evidence.

Motivation From V0.11 KS No-go#

v0.11 added the public order-4 derivative backend extension:

compute_spectral_fd_derivatives(field, *, max_spatial_order=4)

It also evaluated normalized scalar 1D periodic Kuramoto-Sivashinsky internally. The result was useful but not strong enough for public runtime promotion:

  • KS residual feasibility passed with large margin

  • mass drift passed with large margin

  • held-out canonical translation verification passed

  • vertical-slice evidence passed through reference_fallback

  • direct residual-based SVD fitting was out of tolerance

  • direct SVD span distance was around 0.418

  • stable KS generator/residual/example promotion was deferred

The main supportability gap is diagnostic, not PDE coverage:

  • fit diagnostics do not expose full singular values

  • fit diagnostics do not expose condition number

  • epsilon sensitivity is not standardized

  • fallback-backed versus direct-fit evidence needs clearer reporting

  • orbit/coverage diagnostics are not yet reusable library utilities

v0.12 should address those supportability gaps before any further numerical expansion.

Stable Scope#

The stable scope carried into v0.12 remains:

  • canonical FieldBatch, DerivativeBatch, ResidualBatch, GeneratorFamily, InvariantMapSpec, and VerificationReport

  • uniform rectilinear scalar 1D stable paths

  • Heat and Burgers strong-form paths

  • frozen v0.8 weak Heat/Burgers residual report APIs

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

  • frozen v0.10 supportability reporting helpers under pdelie.reporting

  • frozen v0.11 order-4 spectral derivative extension

  • existing polynomial translation fitting and finite-transform verification

The new v0.12 scope is supportability around those existing surfaces:

  • generator-fit diagnostic semantics

  • verification diagnostic semantics

  • reporting helper hardening, if public helper names are frozen in M1/M2

  • internal KS diagnostic sweep reporting, without promotion

  • orbit/coverage diagnostic feasibility, without augmentation APIs in M0

  • API/public-surface audit and compact release-gate coverage

Non-goals#

v0.12 explicitly does not include:

  • a new PDE

  • stable KS generator promotion

  • stable KS residual evaluator promotion

  • stable KS vertical-slice example promotion

  • KS imported parity

  • weak KS

  • weak derivative expansion

  • broad dataset adapters

  • PDEBench or The Well support

  • multidimensional grids

  • nonuniform grids

  • multivariable systems

  • custom KS initial-condition APIs

  • configurable KS coefficient families

  • neural generators

  • operator-facing symmetry work

  • manuscript-specific experiment policy

  • private-paper branch logic

  • private-paper thresholds, tables, figures, or labels

  • public orbit augmentation utilities in M0

  • public reporting helpers in M0

  • root pdelie export expansion unless a later milestone explicitly accepts it

Candidate Public API Policy#

M0 lands no public API.

If v0.12 lands public APIs later, they must be reporting or diagnostic helpers only. Candidate public APIs must be frozen in M1 before implementation in M2 or M4.

Likely allowed API direction:

  • submodule-only helpers under pdelie.reporting

  • JSON-compatible runtime summaries

  • diagnostic reports over existing canonical objects and runtime reports

  • no new canonical object unless a later milestone proves it is necessary

Likely rejected API direction:

  • root pdelie exports

  • stable KS generator/residual APIs

  • broad adapter APIs

  • manuscript-table or figure APIs

  • mutation-heavy augmentation APIs

  • downstream sparse-discovery experiment policy

docs/specs/API_STABILITY.md remains unchanged in M0. It should change only if M2 or M4 actually lands a public reporting/diagnostic API.

M1 Fit and Verification Diagnostic Semantics Freeze#

M1 freezes one future M2 public reporting helper:

pdelie.reporting.summarize_generator_fit_diagnostics(
    generator: GeneratorFamily,
) -> dict[str, Any]

Public helper policy:

  • helper lives under pdelie.reporting only

  • no root pdelie export

  • input is a GeneratorFamily

  • output is a JSON-compatible plain Python dict

  • summary type is generator_fit_diagnostics

  • summary schema version is "0.1"

  • wrong input type raises the existing typed schema validation error in M2

  • helper summarizes existing and future GeneratorFamily.diagnostics

  • helper does not create a canonical object

  • helper does not mutate inputs

Frozen generator-fit diagnostic fields for M2:

  • parameterization

  • fit_mode

  • training_epsilon

  • basis

  • basis_delta_norms

  • design_column_norms

  • singular_values

  • condition_number

  • fit_residual

  • min_delta_basis

  • selected_coefficients

  • svd_coefficients

  • selected_span_distance

  • svd_span_distance

  • reference_fallback_used

  • fallback_reason

  • evidence_label

Diagnostic conventions:

  • condition_number = largest_singular_value / smallest_singular_value

  • if the denominator is zero or nonfinite, report condition_number = None

  • fallback_reason is a stable category string, not prose

  • current stable fallback category remains svd_translation_span_drift

  • evidence_label categories are:

    • direct_svd_in_tolerance

    • direct_svd_out_of_tolerance

    • reference_fallback

    • mixed

    • unavailable

Verification diagnostic semantics:

  • pdelie.reporting.summarize_verification_report(...) remains the verification summary surface

  • M2 may harden top-level verification summary fields for transform, span, and batch-error diagnostics if needed

  • M1 and M2 do not change verification classification rules

  • M1 and M2 do not change finite-transform behavior

M3 internal KS sweep semantics:

  • internal KS sweeps record epsilon, fit mode, fallback status/reason, selected span, SVD span, first verification error, classification, singular values, and condition number

  • sweeps are diagnostic artifacts, not promotion gates

API_STABILITY.md remains unchanged in M1. It should be updated in M2 only if summarize_generator_fit_diagnostics(...) lands as public runtime API.

Milestones#

Milestone 0 - Scope Freeze#

Freeze v0.12 as diagnostics and supportability hardening, add this scope document, reset PLAN.md, and update ROADMAP.md.

M0 is docs-only. It does not change runtime code, tests, package metadata, README, changelog, release readiness, or API stability docs.

Milestone 1 - Fit / Verification Diagnostic Semantics Freeze#

Freeze diagnostic semantics before implementation.

Completed decisions:

  • future M2 helper is pdelie.reporting.summarize_generator_fit_diagnostics(...)

  • helper is submodule-only and returns a JSON-compatible runtime dict

  • summary type is generator_fit_diagnostics

  • summary schema version is "0.1"

  • fit diagnostic fields, condition-number policy, fallback category policy, and evidence labels are frozen above

  • verification keeps summarize_verification_report(...) as its public summary surface

  • M3 KS sweep semantics are diagnostic-only and not promotion gates

Milestone 2 - Diagnostic / Reporting Helper Implementation#

Implement the M1-frozen diagnostics.

Completed implementation:

  • added pdelie.reporting.summarize_generator_fit_diagnostics(...)

  • enriched translation-fit diagnostics with singular values, condition number, design column norms, selected coefficients, selected span distance, and evidence label

  • updated API_STABILITY.md for the new public reporting helper

  • kept fitting coefficient selection unchanged

  • kept existing reporting summary shapes unchanged except for the new helper

  • kept KS public runtime APIs absent

Milestone 3 - Internal KS Diagnostic Sweep Harness#

Keep KS internal and diagnostic-only.

Completed scope:

  • bounded epsilon sweeps

  • selected span distance

  • SVD span distance

  • fallback status and reason

  • first verification error

  • singular values and condition number from the M2 fit diagnostics

  • no promotion gate

Completed sweep matrix:

  • epsilons: 1e-5, 3e-5, 1e-4, 3e-4, 1e-3

  • variants:

    • default

    • lower_amplitude with amplitude=0.04

    • shorter_time with max_time=0.1

Completed diagnosis:

  • all frozen variants concluded fallback_stable_across_epsilons

  • no epsilon or cheap fixture variant recovered direct SVD in-tolerance behavior

  • fallback reason was stable as svd_translation_span_drift

  • residual and verification evidence remained healthy

  • relative L2 drift remained diagnostic-only

  • no public KS generator, residual evaluator, example, imported parity, weak API, or root export landed

Milestone 4 - Orbit / Coverage Diagnostic Feasibility#

Evaluate paper-agnostic orbit and coverage diagnostics.

Completed direction:

  • internal test-only periodic x coverage diagnostics

  • internal test-only finite-transform consistency diagnostics

  • deterministic JSON-compatible summary output

  • no artifact files by default

  • no public API promotion

Completed evidence:

  • half-coverage quarter-shift case covered 32 / 64 points with coverage fraction 0.5

  • full-coverage quarter-shift case covered 64 / 64 points with coverage fraction 1.0

  • 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 was stable under shifts for both fixtures

  • transform provenance recorded invariant_apply and uniform_translation

M4 did not implement private-paper policy, train-augmentation recipes, public orbit/coverage helpers, or API stability entries.

Milestone 5 - API / Public-surface Audit#

Audit API stability and public exports after any M2/M4 helper decisions.

Completed checks:

  • API_STABILITY.md matches actual public helper surface

  • root exports remain narrow

  • KS generator/residual/example APIs remain absent

  • weak KS remains absent

  • broad adapters remain absent

  • M4 orbit/coverage diagnostics remain internal test-only helpers

  • no public augmentation utilities landed

  • API_STABILITY.md required no update in M5

Milestone 6 - Release Gate and Readiness#

Add compact v0_12-release-gate, align release-facing docs and package metadata, and close the direct Git-tag release path.

Release-gate expectations stay representative:

  • current release gate is compact

  • full editable tests cover historical gates

  • package smoke remains small

  • no KS promotion claims

  • no PyPI or TestPyPI publishing before the v1.0 publishing policy is accepted

Milestone 6: COMPLETE.

Completed closeout:

  • package metadata is aligned with 0.12.0

  • release-facing docs are aligned with v0.12.0

  • CI exposes one compact current v0_12-release-gate

  • full editable tests remain the historical gate coverage

  • package smoke remains compact and includes a tiny generator-fit diagnostic summary check

  • API_STABILITY.md remains aligned and required no M6 change

  • M3 internal KS diagnostics and M4 orbit/coverage diagnostics remain internal

Relationship to Downstream Orbit-augmentation Work#

Downstream work has shown that coverage-mediated translation-orbit augmentation can help sparse PDE recovery under localized observations.

The reusable pdelie candidates are the generic mechanics:

  • finite-transform or orbit views over canonical FieldBatch

  • periodic x window coverage diagnostics

  • generic augmentation provenance summaries

  • runtime summaries for residual, fit, verification, and coverage results

  • finite-transform consistency checks

The downstream-only pieces remain outside pdelie:

  • manuscript-specific branch naming

  • sparse-regression policy decisions

  • dataset-specific train/test policy

  • paper-specific thresholds and labels

  • automatic augmentation recipes tuned to one experiment

v0.12 may evaluate reusable diagnostics for this direction. It must not implement private-paper experiment policy.

Release-gate Expectations#

The eventual v0_12-release-gate should be compact and representative. It should not duplicate full diagnostic, reporting, KS, or historical release-gate suites.

Expected release-gate shape:

  • public reporting/diagnostic APIs exist only if frozen and implemented in M2/M4

  • root export boundaries remain intact

  • stable Heat/Burgers/weak-report/KdV surfaces remain importable

  • order-4 derivative API remains documented and available

  • public KS generator/residual/example APIs remain absent

  • no weak KS API appears

  • examples remain JSON-compatible runtime summaries

  • package smoke remains small and avoids KS internal feasibility sweeps

Historical release-gate tests should remain runnable locally and covered by the full editable test suite.

Status#

  • v0.11: COMPLETE as KS feasibility/no-go closeout

  • Milestone 0: COMPLETE

  • Milestone 1: COMPLETE

  • Milestone 2: COMPLETE

  • Milestone 3: COMPLETE

  • Milestone 4: COMPLETE

  • Milestone 5: COMPLETE

  • Milestone 6: COMPLETE