V0.17 Scope - Formula-backed Generator Families#

Summary#

v0.17 is a narrow formula-backed generator interoperability release.

Stable path:

canonical scalar 1D periodic FieldBatch + formula-backed generator candidate -> safe formula metadata/evaluation diagnostics -> empirical configured validation report

This release adds formula-backed runtime records without changing existing polynomial GeneratorFamily semantics.

Stable Scope#

v0.17 adds submodule-only runtime APIs:

  • pdelie.symmetry.FormulaGeneratorFamily

  • pdelie.reporting.summarize_formula_generator_family(...)

  • pdelie.symmetry.validate_symmetry_candidate(...) support for formula-backed candidates

FormulaGeneratorFamily is runtime-only. It is not a new canonical object and does not change canonical GeneratorFamily.

Formula Record#

Frozen record properties:

  • schema_version = "0.1"

  • parameterization = "formula_generator_family"

  • supported variables are exactly t, x, and u

  • supported components are exactly tau, xi, and phi

  • each generator row has a nonempty name

  • each generator row must define all three components

  • optional finite_transform_spec is a canonical InvariantMapSpec payload

  • diagnostics are JSON-compatible provenance only

Formula records support .to_dict() and .from_dict() round trips.

Safe Expression AST#

Formula expressions use a small JSON AST. They are not Python code and are not parsed from arbitrary executable strings.

Supported nodes:

  • const

  • var

  • add

  • mul

  • integer pow

  • sin

  • cos

  • reciprocal

  • metadata-only symbolic_reference

Rational expressions use reciprocal with a fixed denominator floor. Denominator-floor violations are empirical validation failures.

Symbolic references are metadata only. They may be summarized, but they are not evaluated.

Candidate Validation#

validate_symmetry_candidate(...) accepts:

  • FormulaGeneratorFamily objects

  • strict current FormulaGeneratorFamily payload mappings

Formula reports use:

  • summary_schema_version = "0.1"

  • summary_type = "symmetry_candidate_validation"

  • candidate_kind = "formula_generator_family"

Validation behavior:

  • malformed formula records raise typed validation errors

  • well-formed formulas that evaluate to nonfinite values return conclusion = "failed"

  • formulas with finite evaluable components but no finite transform are generally partially_validated

  • symbolic-reference-only formulas are reporting/schema results and do not pretend to evaluate

  • formulas with supported passing finite-transform checks may be validated

  • validated remains empirical configured validation, not a mathematical proof of symmetry

Reporting#

summarize_formula_generator_family(...) returns a JSON-compatible runtime summary with:

  • formula parameterization and schema version

  • variables and component names

  • generator count and names

  • expression node kinds

  • component root-node summaries

  • finite-transform availability

  • symbolic-reference metadata

  • reciprocal denominator floor

  • diagnostics

The helper does not mutate inputs and does not evaluate arbitrary code.

Non-goals#

v0.17 does not add:

  • Python callable generator APIs

  • arbitrary executable formula-string parsing

  • neural generator training

  • learned-generator detector APIs

  • formula-derived finite-flow integration for arbitrary infinitesimal formulas

  • canonical GeneratorFamily schema changes

  • new PDEs

  • stable KS generator/residual/example APIs

  • weak KS

  • broad dataset adapters

  • PDEBench or The Well support

  • multidimensional, multivariable, or nonuniform-grid expansion

  • train/test policy

  • split management

  • operator-facing APIs

  • root pdelie exports

Milestone Status#

  • Milestone 0: COMPLETE - scope freeze

  • Milestone 1: COMPLETE - formula schema and validation semantics freeze

  • Milestone 2: COMPLETE - formula record and reporting implementation

  • Milestone 3: COMPLETE - formula candidate validation

  • Milestone 4: COMPLETE - formula validation example

  • Milestone 5: COMPLETE - API/public-surface audit

  • Milestone 6: COMPLETE - release gate and readiness

Release Gate Expectations#

v0.17 is complete only if:

  • formula records round-trip through strict JSON-compatible payloads

  • invalid formulas raise typed validation errors

  • formula summaries are JSON-compatible and submodule-only

  • formula candidates validate through validate_symmetry_candidate(...)

  • finite formula diagnostics and denominator-floor failures are covered

  • attached supported finite-transform specs reuse existing invariant-map validation

  • existing GeneratorFamily and InvariantMapSpec candidate validation behavior remains unchanged

  • formula validation example emits JSON only

  • no callable, executable-string, neural-detector, KS, weak KS, broad-adapter, operator, split-policy, or root-export surface lands

  • package/readiness docs preserve the v1.0 package-index publishing deferral