# PDELie — Specification (v0.x)

## Purpose

`pdelie` is a modular system for:

> Empirical Lie-symmetry diagnostics and supportability workflows for PDE data.

It is a **library**, not a project repo.

---

# 1. Scope

## Stable (v0.x)

- uniform rectilinear grids
- Lie point symmetries
- canonical polynomial `GeneratorFamily` parameterizations
- algebraic span and closure diagnostics for supplied polynomial `GeneratorFamily` objects
- runtime-only formula-backed generator records and empirical candidate-validation reports
- frozen invariant, reporting, uniform-translation orbit, and materialized-orbit utilities
- runtime-only downstream discovery bridge/result/workflow reports
- runtime-only split/leakage provenance diagnostics over user-supplied partitions
- narrow `xarray.Dataset` scalar-variable ingestion and readiness reporting that still requires explicit metadata
- synthetic + small benchmark PDEs, currently including Heat, Burgers, normalized short-horizon KdV, frozen scalar 1D Fisher-KPP reaction-diffusion, and frozen scalar 1D constant-coefficient advection-diffusion strong paths

## Experimental

- neural generators
- Python-callable generators and executable formula strings
- weak-form derivatives and weak-form extensions beyond the frozen `v0.8` weak residual report slice and `v0.24` supportability reporting layer
- custom KdV initial conditions, configurable KdV coefficients, general KdV regimes outside the frozen normalized short-horizon path, and weak KdV
- broad dataset adapters, file-based dataset loaders, implicit metadata inference, resampling, and broad Dataset-level ingestion
- broad discovery-backend frameworks, split management, leakage prevention, and heldout-leakage policy
- multidimensional, multivariable, and nonuniform-grid stable expansion
- operator-level symmetry methods
- public multi-generator PDE fitting
- multi-generator invariant charts, finite flows, BCH composition, and multi-parameter orbit atlases

---

# 2. Pipeline

```text
FieldBatch
→ DerivativeBatch
→ ResidualBatch (via ResidualEvaluator)
→ GeneratorFamily
→ InvariantMapSpec
→ VerificationReport
```

 All modules MUST use canonical objects.

---

# 3. Canonical Objects

## FieldBatch

Represents PDE data.

Constraints:
- dims authoritative
- ordering: ("batch", "time", spatial..., "var")
- uniform rectilinear grids only (V0.1 stable slice)
- coords must define domain + centering
- metadata must include BCs, grid type, parameters

---

## DerivativeBatch

Contains derivatives + provenance:
- backend (`spectral_fd` stable in V0.1; `spectral` / `finite` / `weak` reserved)
- smoothing parameters
- boundary assumptions

---

## ResidualEvaluator

Interface:

```text
evaluate(FieldBatch, DerivativeBatch?) → ResidualBatch
```

Defines symmetry target.

---

## ResidualBatch

- residual values
- residual type (analytic / weak / surrogate / operator)
- normalization

---

## GeneratorFamily

- parameterization type
- schema_version (`"0.2"` for canonical `v0.4` family output)
- family-shaped coefficients
- explicit basis_spec
- normalization
- optional generator names
- diagnostics are non-authoritative summaries/provenance

Canonical meaning depends only on:

- schema_version
- parameterization
- coefficients
- basis_spec
- normalization
- optional generator names

`v0.4` direct construction is canonical-only.
Legacy single-generator translation payloads are a narrow `from_dict()` compatibility path only.

Stable `v0.5` runtime artifact note:

- `pdelie.portability` may wrap a canonical `GeneratorFamily` payload in a stable export/import manifest artifact
- the manifest is not a canonical object
- canonical meaning remains only the nested `GeneratorFamily`
- stable `v0.5` manifest validation rejects unknown top-level manifest fields

---

## InvariantMapSpec

- single-generator metadata
- construction method
- parameters
- validity (local/global/unknown)
- inverse availability
- diagnostics

Runtime-only for the stable `v0.3` Milestone 1 slice:

- `InvariantApplier`

---

## VerificationReport

- norm
- epsilon sweep
- held-out evaluation
- classification: exact / approximate / failed

---

# 4. Residual Ontology

Symmetry is always defined relative to a residual.

No symmetry fitting is allowed without a residual.

---

# 5. Identifiability

Generators MUST satisfy:

- normalization (||X|| = 1)
- comparison via span (not coefficients)
- closure diagnostics if multi-generator

---

# 6. Verification Protocol

Every symmetry must be validated using:

- relative L2 norm
- epsilon sweep (logspace 1e-4 → 1e-1)
- held-out initial conditions
- held-out parameter sets

Outputs must include:
- error vs ε curve
- residual error
- classification

---

# 7. Grid Policy

Supported:
- uniform rectilinear grids

Representable but unstable:
- nonuniform rectilinear

Unsupported:
- unstructured meshes

---

# 8. Preprocessing

Preprocessing MUST be logged.

Allowed:
- dtype conversion
- coordinate harmonization
- mild denoising

Restricted:
- normalization
- amplitude scaling
- aggressive smoothing

---

# 9. Serialization

All canonical objects MUST:

- include `schema_version`
- support `.to_dict()` / `.from_dict()`
- be JSON-compatible

---

# 10. Final Rule

If ambiguous:

→ choose the simplest, verifiable implementation