Historical V0.15+ Strategy#

Historical strategy note, superseded by ../ROADMAP.md. Some forward-looking version numbers in this file are intentionally stale and should be read as historical planning context, not current scope.

V0.15+ Strategy#

This document records the staged post-v0.14 direction. It is a strategy note, not an active scope freeze and not an API contract.

The active execution record remains PLAN.md. Stable contracts remain in docs/specs/API_STABILITY.md only after APIs land.

Summary#

After v0.14, the highest-ROI path has been to move from read-only invariant diagnostics toward conservative user-facing data utilities, then external symmetry-candidate validation, then formula-backed generator support, then carefully scoped PDE expansion.

After v0.23, the next planned path is to consider a weak-form supportability reset before more difficult axes such as broader KdV/KS, multi-generator fitting, broad adapters, multidimensional/nonuniform grids, and time-translation actions.

Staged sequence:

  • v0.15: materialized uniform translation orbit batches

  • v0.16: external symmetry-candidate interop and validation

  • v0.17: formula-backed generator families

  • v0.18: stable Fisher-KPP reaction-diffusion strong path

  • v0.19: stable advection-diffusion strong path

  • v0.20: unified generator confidence reports

  • v0.21: external data readiness reports

  • v0.22: downstream discovery contracts

  • v0.23: split/leakage provenance diagnostics

  • v0.24: completed weak-form supportability reset

  • v0.25: completed KdV scope decision; public KdV remains frozen

  • v0.26: completed KS revisit decision; public KS remains deferred

  • v0.26b: planned KS promotion decision, only after a separate scope freeze

  • v0.27: planned multi-generator feasibility

  • v0.28: planned data ecosystem feasibility

  • v0.29: planned grid-domain feasibility

  • v0.30: planned orbit/action scope decision

  • v0.31: planned v1.0 readiness hardening

PDELie should remain a reusable library and validation/reporting substrate. It should not become a neural symmetry-detector training framework.

V0.15 - Materialized Uniform Translation Orbit Batches#

Completed theme:

promote the first conservative user-facing data utility for materializing finite uniform translation orbits from canonical FieldBatch inputs.

Implemented API direction:

pdelie.invariants.build_uniform_translation_orbit_batch(
    field,
    *,
    shifts,
    keep_source_index=True,
    keep_shift_index=True,
    copy=True,
)

build_uniform_translation_orbit_batch(...) is the selected public name because it says the helper returns a batch-oriented data product. The completed scope freeze belongs in V0_15_SCOPE.md.

Completed semantics:

  • augmentation appends along the batch dimension

  • output ordering is deterministic and preserves duplicate shifts

  • source indices and shift indices are recorded as provenance/report metadata

  • duplicate shifts are preserved rather than deduplicated

  • masks are transformed and concatenated consistently with existing InvariantApplier behavior

  • preprocess logs append one orbit-materialization entry

  • output metadata records group/action parameters, normalized shifts, and duplicate-shift policy

  • no train/test policy is applied

  • no split management or heldout-leakage detection is attempted

  • source IDs may be recorded, but the helper does not manage experimental partitions

Return-shape policy:

  • use OrbitBatchResult(field, report) as an explicit structured return

  • avoid a silent FieldBatch-only return because users need source/shift provenance

  • avoid returning transformed fields inside a JSON report

Explicit non-goals:

  • no sparse-discovery branch policy

  • no train/heldout split management

  • no paper-specific augmentation recipe

  • no time translation

  • no new PDE

  • no root exports unless separately accepted

This would be useful beyond PDELie itself: users could feed the materialized orbit batch into PySINDy, a neural solver, PDE-FIND-style code, or their own model while keeping provenance explicit.

V0.16 - External Symmetry-candidate Interop#

Completed theme:

validate external symmetry candidates without training the detectors that produced them.

Implemented API direction:

pdelie.symmetry.validate_symmetry_candidate(
    field,
    candidate,
    *,
    residual_evaluator,
    reference_generator=None,
    finite_transform_epsilons=None,
    source_candidate_id=None,
) -> dict[str, Any]

External methods may provide in v0.16:

  • an existing GeneratorFamily

  • a canonical GeneratorFamily payload mapping

  • an existing InvariantMapSpec

  • a canonical InvariantMapSpec payload mapping

PDELie validates candidates using:

  • finite-transform verification where applicable

  • residual preservation for supported invariant-map specs

  • span or closure diagnostics when applicable

  • provenance checks

  • verification summaries

Design boundary:

  • this is detector interop, not sparse-discovery reporting

  • this is validation/reporting, not neural-generator training

  • learned-generator methods may slot in by exporting candidates, but PDELie does not train those models

  • callable descriptors and learned-generator APIs remain deferred beyond v0.17

This keeps PDELie compatible with learned-generator or Lie-algebra-aware methods without becoming a neural symmetry-discovery framework.

V0.17 - Formula-backed Generator Families#

Completed theme:

support richer generator descriptions without jumping directly to neural generator classes.

Implemented API direction:

pdelie.symmetry.FormulaGeneratorFamily
pdelie.reporting.summarize_formula_generator_family(...)
pdelie.symmetry.validate_symmetry_candidate(..., candidate=FormulaGeneratorFamily(...), ...)

The completed first phase focuses on formula-backed runtime records for:

  • affine generators

  • trigonometric generators

  • rational or simple analytic forms

  • externally supplied symbolic references

Completed semantics:

  • JSON-compatible formula metadata and strict payload round trips

  • safe JSON AST expressions rather than executable strings

  • finite formula-evaluation diagnostics on canonical scalar 1D periodic fields

  • optional finite-transform validation through attached InvariantMapSpec payloads

  • symbolic references as metadata-only expressions

  • compatibility with existing symmetry-candidate validation reports

Callable or external executable generators remain deferred and should be treated as less stable unless paired with diagnostic reports.

Later learned-generator interop should still work through accepted outputs only. PDELie should validate such outputs; it should not train learned generators.

Selected design for v0.17:

  • FormulaGeneratorFamily is a runtime-only structured record

  • it is not a canonical object

  • it does not change existing polynomial GeneratorFamily semantics

The completed scope freeze belongs in V0_17_SCOPE.md.

V0.18 And V0.19 Completed PDE Expansion#

v0.18 completed the first scoped PDE expansion by adding the stable scalar 1D periodic Fisher-KPP reaction-diffusion strong path.

v0.19 completed the second scoped PDE expansion:

add one safe transport-plus-diffusion PDE under the same scalar 1D periodic order-2 derivative regime.

Completed stable path:

canonical scalar 1D periodic FieldBatch
-> spectral_fd u_t/u_x/u_xx
-> constant-coefficient advection-diffusion residual
-> translation fit/verification
-> vertical-slice example

Frozen equation:

u_t + c*u_x = nu*u_xx
residual = u_t + c*u_x - nu*u_xx

Deferred after v0.19:

  • variable coefficients

  • reaction-advection-diffusion

  • weak advection-diffusion

  • nonperiodic boundaries

  • custom initial-condition APIs

  • multidimensional grids

  • nonuniform grids

Like v0.18, v0.19 shipped only because direct residual-based fitting evidence was in tolerance.

V0.20 - Unified Generator Confidence Reports#

Completed theme:

promote the notebook confidence-card pattern into a public supportability/reporting helper.

Implemented scope:

  • residual health summaries

  • fit conditioning and singular-value summaries

  • selected/SVD span evidence

  • finite-transform verification summaries

  • candidate-validation conclusions

  • orbit/coverage/consistency diagnostics

  • configured threshold interpretation

  • categorical confidence labels and component statuses

Explicit boundaries:

  • no transformed FieldBatch collections from reporting helpers

  • no train/test policy

  • no downstream success policy

  • no mathematical-proof claim

  • no scalar confidence score

V0.21 - External Data Readiness Reports#

Completed theme:

make user-owned scalar 1D periodic data safer to bring into the stable runtime before broad adapters land.

Implemented scope:

  • stronger FieldBatch audit reports

  • coordinate and grid diagnostics

  • metadata completeness diagnostics

  • finite-value, mask, scalar-var, and shape diagnostics

  • residual-evaluator compatibility preflight

  • conservative metadata suggestions for explicit, low-risk cases

Deferred:

  • xarray.Dataset support

  • file-based dataset loaders

  • PDEBench and The Well adapters

  • multidimensional or nonuniform-grid ingestion

V0.22 - Downstream Discovery Contracts#

Completed theme:

standardize downstream discovery reporting without becoming a full experiment-policy framework.

Implemented scope:

  • downstream discovery bridge-output summaries

  • backend-neutral discovery result summaries

  • optional feature-keyed recovery summaries

  • downstream discovery workflow summaries

  • recovery and provenance summary reports

  • orbit-materialization provenance checks

  • paper-agnostic downstream templates

Deferred:

  • general discovery-backend framework

  • manuscript thresholds

  • automatic experiment policy

  • backend lock-in beyond thin adapters

V0.23 - Split/Leakage Provenance Diagnostics#

Completed theme:

reduce orbit-materialization misuse by reporting provenance risks across user-supplied partitions.

Completed scope:

  • user-supplied partition diagnostics

  • source/shift overlap reports

  • identity-shift overlap reports

  • downstream workflow integration

Explicit boundaries:

  • no train/test split management

  • no automatic split generation

  • no leakage prevention

  • no downstream augmentation policy

  • no benchmark success criteria

V0.24 - Weak-Form Supportability Reset#

Planned theme:

decide whether weak derivatives and broader weak-form methods can be promoted beyond the frozen v0.8 weak residual report slice.

Candidate scope:

  • weak derivative backend feasibility

  • broader weak-form residual contracts

  • weak reaction-diffusion feasibility

  • noisy/coarse-data supportability diagnostics

Deferred unless separately proven:

  • weak KdV APIs

  • weak KS APIs

  • broad weak-form superiority claims

V0.25 - KdV Scope Decision#

Status: completed. The decision is to keep public KdV frozen.

Planned theme:

decide whether KdV should remain frozen or expand beyond normalized periodic short-horizon support.

Candidate decisions:

  • custom KdV initial conditions

  • configurable KdV coefficients

  • general KdV support outside the frozen normalized periodic short-horizon regime

  • weak KdV APIs

Acceptable outcome:

  • keep KdV frozen and document why if the broader regime is not supportable.

Completed outcome:

  • current normalized scalar 1D periodic short-horizon KdV strong path remains stable

  • custom KdV initial conditions remain deferred

  • configurable KdV coefficients remain deferred

  • general KdV support outside the frozen normalized periodic short-horizon regime remains deferred

  • weak KdV remains deferred

V0.26 - KS Revisit Decision#

Completed theme:

revisit the v0.11/v0.12 KS no-go with confidence diagnostics, without promoting public KS runtime APIs in the same release.

Completed decision:

  • current_no_go_reference_fallback

Follow-up:

  • v0.26b is reserved for the actual KS promotion release if a separate scope freeze accepts future direct-SVD/no-fallback evidence.

Deferred in v0.26:

  • public KS data generator

  • public KS residual evaluator

  • KS vertical-slice example

  • KS imported parity

  • weak KS API

  • root KS export

V0.26b - KS Promotion Decision#

Planned theme:

decide whether the KS direct-SVD/no-fallback evidence is stable enough to promote a narrow public KS runtime surface.

Default stance:

  • no root KS export

  • no weak KS

  • no residual-only KS public API

  • no public KS path unless direct residual-based fitting evidence remains stable under a separate scope freeze

V0.27 - Multi-Generator Feasibility#

Planned theme:

test whether the single-generator-centered runtime can support stable multi-generator workflows.

Candidate scope:

  • stable multi-generator PDE fitting feasibility

  • multi-generator invariant machinery feasibility

  • closure/span/verification interactions for fitted families

Boundary:

  • this is high-risk core machinery and should not be mixed with a PDE, adapter, or weak-form release.

V0.28 - Data Ecosystem Feasibility#

Planned theme:

decide whether external data ecosystem support can widen without weakening canonical contracts.

Candidate scope:

  • xarray.Dataset support

  • file-based dataset loaders

  • narrow adapter feasibility

  • metadata inference expansion

Deferred unless scope is frozen:

  • PDEBench / The Well as stable APIs

  • broad adapter framework

  • implicit alias-based loaders

V0.29 - Grid-Domain Feasibility#

Planned theme:

evaluate multidimensional and nonuniform-grid ingestion as a contract change.

Candidate scope:

  • multidimensional ingestion feasibility

  • nonuniform-grid ingestion feasibility

  • resampling/reporting decisions

  • derivative/residual compatibility diagnostics for unsupported grids

Default stance:

  • unsupported until a dedicated scope freeze proves the contracts.

V0.30 - Orbit/Action Scope Decision#

Planned theme:

decide whether invariant actions should expand beyond frozen uniform spatial translation materialization.

Candidate scope:

  • public orbit-view builders beyond the frozen materialized uniform translation orbit batch helper

  • transformed FieldBatch collection policy for explicit data/invariant APIs

  • time-translation APIs

  • axis="time" support

Boundary:

  • reporting helpers remain report-only

  • transformed collections must not be returned from reporting helpers

V0.31 - V1.0 Readiness Hardening#

Planned theme:

freeze the public engine before v1.0.

Candidate scope:

  • public/private API audit

  • root export policy audit

  • deprecation policy

  • package publishing plan

  • docs and notebook consistency audit

  • release-gate consolidation

  • support matrix for stable PDEs, grids, residuals, candidate types, and downstream paths

Relationship To V1.0#

These releases should move PDELie toward v1.0 by improving supportability, provenance, interoperability, and scoped numerical coverage before freezing the public contract.

The preferred sequence is:

  1. materialize finite translation orbits safely

  2. validate external symmetry candidates

  3. represent non-polynomial formulas

  4. widen stable PDE coverage one axis at a time

  5. consolidate confidence reporting

  6. harden external data and downstream reporting

  7. decide weak/KdV/KS/multi-generator/grid boundaries explicitly

  8. run a dedicated v1.0 readiness hardening release

Package-index publishing, broad adapters, and stable v1 API commitments remain deferred until a dedicated v1.0 readiness milestone.