V0.4 Scope#

Summary#

v0.4 is the first Lie-algebra span, symbolic reporting, algebra diagnostics, and visual inspection release for PDELie.

It does not:

  • introduce a new numerical regime

  • add weak-form methods

  • add operator methods

  • add neural generators as stable API

  • add broad dataset adapters

  • add a stable 2D PDE pipeline

  • add stable multi-generator PDE fitting

Instead, it asks a narrower and more important question:

Can PDELie represent, normalize, compare, diagnose, and visually inspect a small polynomial Lie-generator family under controlled stable conditions?

v0.4 is therefore the first generator-family and algebra-inspection release, not the first weak-form, operator, or broad downstream release.

Stable Scope#

  • uniform rectilinear grids only

  • synthetic PDE data only

  • polynomial Lie point generators only

  • Heat/Burgers stable paths remain regression-protected

  • multi-generator GeneratorFamily representation

  • symbolic generator normalization and display

  • span comparison diagnostics

  • Lie bracket / closure diagnostics

  • minimal optional visualization

  • no new stable canonical object unless absolutely necessary

Stable canonical objects#

Stable in v0.4:

  • FieldBatch

  • DerivativeBatch

  • ResidualBatch

  • ResidualEvaluator

  • GeneratorFamily

  • InvariantMapSpec

  • VerificationReport

Runtime-only, not canonical:

  • symbolic rendering helpers

  • optional basis simplification helpers

  • span-diagnostics helpers

  • closure-diagnostics helpers

  • visualization helpers

  • existing InvariantApplier

  • existing downstream bridge helpers

GeneratorFamily Contract#

Canonical core#

Canonical meaning depends only on:

  • schema_version

  • parameterization

  • coefficients

  • basis_spec

  • normalization

  • optional generator_names

diagnostics is optional and non-authoritative.

Rule:

  • GeneratorFamily stores enough information to reproduce analysis reports

  • symbolic/span/closure/viz helpers compute runtime reports

  • attached diagnostics are summaries or provenance, not the contract itself

Schema policy#

  • schema_version is an object-schema epoch, not a package version

  • GeneratorFamily.schema_version = "0.2" means “post-family-semantics GeneratorFamily”

  • other canonical objects may remain at "0.1" until their schemas actually change

  • schema versions advance independently per canonical object family as needed

Canonical family form#

Canonical v0.4 output must always be:

  • schema_version = "0.2"

  • coefficients.shape == (num_generators, num_coefficients_per_generator)

  • explicit basis_spec

Required basis_spec fields:

  • variables

  • component_names

  • basis_terms

  • component_ordering

  • term_ordering

  • layout

Freeze:

  • layout = "component_major"

Freeze one concrete example:

{
  "variables": ["t", "x", "u"],
  "component_names": ["tau", "xi", "phi"],
  "basis_terms": [
    {"label": "1", "powers": [0, 0, 0]},
    {"label": "t", "powers": [1, 0, 0]},
    {"label": "x", "powers": [0, 1, 0]},
    {"label": "u", "powers": [0, 0, 1]}
  ],
  "component_ordering": ["tau", "xi", "phi"],
  "term_ordering": ["1", "t", "x", "u"],
  "layout": "component_major"
}

Coefficient interpretation rule:

  • for each generator row

  • iterate component_names in order

  • within each component, iterate basis_terms in order

  • each scalar coefficient multiplies that component-term pair

Legacy compatibility and canonical serialization#

  • direct construction without basis_spec is invalid in v0.4

  • legacy 0.1 single-generator translation payloads remain accepted only via GeneratorFamily.from_dict()

  • legacy payloads without basis_spec are accepted only when they match the frozen translation parameterization

  • those payloads are upgraded in memory to canonical 0.2 family form

  • to_dict() always emits canonical 0.2 output

  • canonical output always includes explicit basis_spec

  • missing basis_spec outside the explicit legacy translation case is a typed validation error

  • round-trip tests must cover:

    • legacy input -> canonical in-memory form -> canonical output

    • canonical input -> canonical output

Frozen canonical translation compatibility target:

{
  "schema_version": "0.2",
  "parameterization": "polynomial_translation_affine",
  "coefficients": [[1.0, 0.0, 0.0, 0.0]],
  "basis_spec": {
    "variables": ["t", "x", "u"],
    "component_names": ["xi"],
    "basis_terms": [
      {"label": "1", "powers": [0, 0, 0]},
      {"label": "t", "powers": [1, 0, 0]},
      {"label": "x", "powers": [0, 1, 0]},
      {"label": "u", "powers": [0, 0, 1]}
    ],
    "component_ordering": ["xi"],
    "term_ordering": ["1", "t", "x", "u"],
    "layout": "component_major"
  },
  "normalization": "l2_unit"
}

Normalization And Reports#

Numerical vs display normalization#

Numerical normalization:

  • canonical meaning only

  • default row-wise l2_unit

  • used for fitting/comparison/diagnostics

Display normalization:

  • runtime-only

  • default anchor

  • never mutates canonical coefficients

  • used only for human-readable output

Symbolic display promise#

  • deterministic symbolic display for the given basis

  • no promise of canonical algebra-basis recovery

  • span equivalence remains primary

  • optional runtime-only sparse/anchor basis simplification helper may try to find a nicer displayed basis

  • simplification is heuristic and not part of stable equivalence semantics

Span And Closure Diagnostics#

Span diagnostics policy#

Primary metric:

  • principal angles

Paired derived metric:

  • projection residual

Comparison precondition:

  • compared families must have structurally equivalent basis_spec semantics

Freeze one default inner-product policy:

  • normalized variable domain

  • default algebraic-fixture domain [-1, 1]^n

  • PDE-associated variables are affine-mapped to [-1, 1]

  • uniform component weights after normalization

Preferred computation mode:

  • exact polynomial inner product for the current algebraic/runtime polynomial scope

Deferred later work:

  • field-aware scaling for PDE-associated learned spans

  • deterministic sampled fallback modes for broader comparison settings

Required core span report fields:

  • inner_product

  • evaluation_mode

  • domain

  • component_weights

  • reference_rank

  • candidate_rank

  • comparison_rank

  • principal_angles_radians

  • projection_residual

  • conditioning

Additional runtime diagnostic fields may be included, but are not frozen in v0.4 Milestone 3 unless promoted later.

Closure / structure-constant policy#

Preferred mode:

  • exact polynomial Lie brackets for the current monomial algebraic/runtime polynomial scope

Fallback mode:

  • deterministic sampled/projection closure only when exact mode is unavailable or explicitly forced

Exact-mode policy:

  • closure diagnostics use raw vector-field brackets

  • exact brackets may use an internal expanded polynomial representation when bracket monomials leave the stored family basis

  • that expanded bracket representation is runtime-only and not a canonical object or stable basis contract

  • projected brackets determine reported structure constants and closure diagnostics

  • exact mode is available only for the current monomial basis-term encoding; richer or noncanonical term encodings must reject exact mode or downgrade to fallback

Interpretation rule:

  • symmetry_algebra_diagnostics means closure diagnostics on a family with supplied symmetry-validity evidence

  • it does not claim a full family symmetry proof or full per-generator coverage in v0.4

  • symmetry_algebra_diagnostics requires non-empty supplied verification evidence whose classifications are all exact or approximate

  • otherwise the label is vector_field_algebra_diagnostics

  • closure is interpretive support, never primary evidence

  • finite-flow validity, residual validity, and held-out verification remain primary

Required core closure report fields:

  • interpretation_label

  • verification_classifications

  • inner_product

  • computation_mode

  • domain

  • component_weights

  • component_targets

  • family_rank

  • structure_constants

  • closure

  • antisymmetry

  • jacobi

  • conditioning

Controlled Targets#

Freeze two target classes:

  • algebraic family fixtures with exact known coefficients and brackets

  • regression protection on existing Heat/Burgers stable paths

Allowed algebraic fixtures:

  • translation-style

  • scaling-style

  • mixed affine

  • rotation-style for symbolic/span/bracket tests only

Rotation-style fixtures must be coefficient-level algebra fixtures, not PDE/data fixtures.

Frozen Milestones#

Milestone 1 — GeneratorFamily representation semantics#

Status: Complete

  • freeze family-shaped GeneratorFamily

  • add required basis_spec

  • freeze canonical serialization and migration policy

  • no symbolic display

  • no fitting

  • no visualization

Milestone 2 — Symbolic normalization and display#

Status: Complete

  • deterministic symbolic rendering

  • runtime-only display normalization

  • optional SymPy output

  • no heuristic basis simplification helper in the completed M2 slice

Milestone 3 — Span diagnostics#

Status: Complete

  • principal angles

  • projection residual

  • frozen inner-product policy

  • controlled algebraic fixtures

Milestone 4 — Closure diagnostics#

Status: Complete

  • exact polynomial Lie brackets where supported

  • deterministic fallback where needed and kept minimal

  • structure constants

  • closure / antisymmetry / Jacobi diagnostics

  • verification-aware interpretation labels

Milestone 5 — Minimal visualization#

Status: Complete

  • optional [viz] extra only

  • visualization consumes existing canonical objects and runtime reports only

  • no visualization-specific contracts

  • coefficient-bar renderer for GeneratorFamily

  • symbolic summary renderer using the frozen M2 symbolic display

  • verification-curve renderer for VerificationReport

  • span-diagnostics renderer for the frozen M3 report shape

  • closure-diagnostics renderer for the frozen M4 report shape

  • no transformed-field plots, rollout heatmaps, animation, or interactive backends

  • explicitly deferrable first if M1–M4 take longer than expected

Milestone 6 — Algebra-span release gate#

Status: Complete

  • one focused pytest release-gate module over the already-implemented M1–M5 behavior

  • one dedicated CI visibility job running only that release-gate module

  • migration / canonical serialization checks for the translation slice

  • symbolic determinism checks for canonical and legacy-upgraded translation families

  • tolerant span reproducibility checks on representative exact multi-rank fixtures

  • tolerant closure reproducibility checks on representative nontrivial closed fixtures

  • compact Heat/Burgers stable translation regression checks

  • optional-viz smoke tests using a non-interactive backend with figure cleanup

  • no downstream or SymPy behavior in the gate itself

  • the CI job may still use the standard .[test] environment; this milestone does not claim total optional-dependency isolation

  • the dedicated CI job supplements, and does not replace, the full editable/full-suite job

Release Gate#

v0.4 is releasable only if:

  • Heat and Burgers still pass unchanged

  • GeneratorFamily backward compatibility is preserved for the current translation slice

  • canonical family serialization is stable and tested

  • symbolic rendering is deterministic for a given basis

  • span diagnostics are reproducible under the frozen inner-product policy

  • closure diagnostics are reproducible and condition-aware

  • release-gate numeric assertions use tolerant checks for floating outputs

  • visualization remains optional and outside the core install

  • visualization smoke does not require an interactive/display backend and closes figures cleanly

  • no weak-form, operator, neural, broad-adapter, or manuscript-facing feature is required

Explicit Non-goals#

  • weak-form methods

  • operator methods

  • neural generators as stable API

  • representative-loss or research-loss code

  • broad dataset adapters

  • broad downstream benchmark expansion

  • stable 2D PDE fitting or data pipeline

  • stable multi-generator PDE fitting

  • full algebra-basis canonicalization as a stable promise

  • polished plotting library

  • paper-specific or manuscript-facing logic