# V0.5 Scope ## Summary `v0.5` is the first **generator-family portability and external-family compatibility** release for PDELie. It does **not** introduce a new numerical regime. It does **not** make weak-form methods, operator methods, neural generators, or broad dataset adapters part of the stable library. It does **not** commit to a broad PDE benchmark zoo. Instead, it asks: > Can learned or externally supplied polynomial Lie generator families be exported, imported, validated, inspected, and used in controlled downstream workflows without losing their semantics? `v0.5` is therefore a portability release, not a broader numerics or PDE-zoo release. Prediction-facing utility remains deferred unless it is narrowed later with a precise fixed task. --- ## Stable Scope Stable scope for `v0.5`: - uniform rectilinear grids only - synthetic PDE data only - polynomial Lie point generator families only - Heat/Burgers stable paths remain regression-protected - generator-family export/import manifest - external-family validation and compatibility - controlled portability benchmark - current symbolic/span/closure/viz helpers remain available - no new stable canonical object unless absolutely necessary Gated / feasibility-only: - KdV feasibility as a higher-derivative stress test Deferred: - stable KdV release path unless feasibility passes - prediction-facing utility task unless explicitly narrowed - weak-form methods - operator methods - broad numerics expansion beyond the current stable regime - broad adapters - broad PDE zoo --- ## Core User Story `v0.5` should support four forms of generator-family input: 1. an in-memory canonical `GeneratorFamily` 2. a canonical `GeneratorFamily.to_dict()` payload 3. a `pdelie.generator_family_export` manifest containing a canonical generator family 4. the existing narrow legacy `0.1` translation payload via the already-defined compatibility path Unsupported in stable `v0.5`: - arbitrary symbolic generator strings - arbitrary handwritten equations without `basis_spec` - non-polynomial generators - neural generators - unsupported component or basis conventions - stable multi-generator PDE fitting --- ## Export Manifest Policy The export manifest is a **stable artifact schema**, not a new canonical object. Required fields: - `manifest_schema_version` - `manifest_type` - `generator_family` Optional fields: - `pdelie_version` - `symbolic` - `diagnostics` - `provenance` - downstream compatibility hints Top-level manifest field policy in stable `v0.5`: - required fields must exist - known optional fields may exist - unknown top-level manifest fields are rejected The mathematical content of the manifest is the canonical `GeneratorFamily`. Symbolic summaries, span diagnostics, closure diagnostics, visualization hints, and provenance are optional metadata. They are not canonical meaning. Stable `v0.5` scope is the manifest schema plus runtime dict-level export/import over JSON-compatible payloads. Dedicated JSON file read/write is not required for stable M1 scope. Users may serialize manifests with the standard-library `json` module. Thin file helpers may be added later without changing manifest semantics. --- ## KdV Policy KdV is a candidate stable PDE path, but it is not automatically part of the `v0.5` stable release. KdV first enters as a **feasibility milestone**. It may be promoted only if: - spectral third-derivative accuracy tests pass on clean periodic functions - synthetic KdV data generation is reproducible - a KdV residual evaluator gives near-zero residual on trusted data - no redesign of `FieldBatch`, `DerivativeBatch`, or residual ontology is required - Heat/Burgers regressions remain unchanged If KdV fails this feasibility gate, it moves to `v0.6+`. Weak-form methods are not required for the clean synthetic feasibility pass, but they remain the likely long-term route for noisy/high-derivative PDE discovery. --- ## Prediction Utility Policy Prediction utility is not committed as stable `v0.5` scope unless narrowed later. If included later, it must be defined as: - a fixed lightweight predictor - a fixed input representation - a fixed target metric - a fixed comparison against raw / canonicalized / nuisance features - no neural operators - no broad forecasting framework Until that is frozen, prediction utility remains `v0.6+` planning. --- ## Frozen Milestones ### Milestone 1 — Generator-family export/import manifest **Status:** Complete - define manifest schema - export canonical `GeneratorFamily` - import/validate manifest - no new canonical object unless unavoidable ### Milestone 2 — External-family compatibility **Status:** Complete - validate externally supplied canonical generator families - support runtime dict/object ingestion - run symbolic/span/closure/viz helpers on imported families - typed failures for unsupported families ### Milestone 3 — Portability benchmark **Status:** Complete Compare: - in-memory family - canonical payload normalized through `coerce_generator_family(...)` - exported/imported manifest family normalized through `coerce_generator_family(...)` - nuisance / malformed control The goal is semantic preservation after export/import, not a repeat of the `v0.3` downstream benchmark. Legacy `0.1` translation compatibility remains a narrow smoke path only, not a first-class benchmark branch. ### Milestone 4 — KdV feasibility **Status:** Complete / gated - spectral third-derivative stress tests - synthetic KdV data feasibility - KdV residual feasibility - short-horizon conservation sanity - promotion decision: stable path or defer to `v0.6+` M4 remains tests-first and feasibility-only: - no stable KdV API yet - no root exports - no broad numerics expansion - no prediction/downstream broadening Current kickoff outcome: - normalized periodic KdV feasibility passes in the tests-first slice - stable KdV promotion remains deferred to the release gate ### Milestone 5 — V0.5 release gate **Status:** Complete - compact, high-signal release-gate aggregation only - manifest export/import stability on representative canonical families - coercion and frozen input-form stability on representative external-family inputs - portability benchmark reproducibility on a representative slice - Heat/Burgers regression protection on a representative slice - KdV feasibility outcome explicitly recorded as: - feasibility proven in tests-first scope - stable promotion deferred - no stable KdV API in `v0.5` - no new public API - no new canonical object - no new numerics work - no prediction/downstream expansion Current outcome: - the `v0.5` release gate is complete - the compact release-gate aggregation slice passes - KdV feasibility is recorded as passed in the tests-first slice - KdV remains non-stable in `v0.5` with no stable KdV API added --- ## Release Gate `v0.5` is releasable only if: - Heat/Burgers stable paths still pass unchanged - generator-family manifests export/import deterministically - external canonical families can be validated and inspected - malformed or unsupported external families fail with typed errors - portability benchmark shows no semantic drift between in-memory and imported families - KdV feasibility outcome is explicitly recorded while no stable KdV surface is added in `v0.5` - no weak-form, operator, neural, broad-adapter, or manuscript-facing feature is required --- ## Explicit Non-goals - weak-form methods - operator symmetry - neural generators as stable API - representative-loss or research-loss code - broad dataset adapters - broad PDE zoo - stable wave-equation pipeline - stable KdV path without feasibility gate - vague prediction utility - arbitrary symbolic-string import - paper-specific or manuscript-facing logic