Note

This page renders committed notebook outputs. The Read the Docs build does not execute notebook code.

External and formula-backed symmetry candidates#

Current surface: V0.29.

Purpose#

Main interoperability tutorial: validate candidate objects and strict payloads produced by external methods without training those methods in PDELie.

What you will learn#

  • candidate_kind differences for GeneratorFamily, InvariantMapSpec, and FormulaGeneratorFamily.

  • How validated, partially_validated, and failed are configured empirical conclusions.

  • Why formula records use a safe JSON AST rather than executable strings.

  • Why callable and neural generator APIs remain deferred.

Required extras#

Core install is enough.

Expected runtime#

Under 1 minute.

Out of scope#

No detector training, no callable descriptors, no neural generators, no mathematical proof claim, no downstream acceptance policy.

These notebooks are tutorials, not API contracts. Example outputs are runtime summaries, not canonical paper artifacts.

[1]:

from pathlib import Path
import sys

ROOT = Path.cwd()
if not (ROOT / "pyproject.toml").exists():
    ROOT = ROOT.parent
if str(ROOT) not in sys.path:
    sys.path.insert(0, str(ROOT))
import numpy as np

from notebooks._tutorial_utils import confidence_card, print_cards, pretty_json
from pdelie import GeneratorFamily, InvariantMapSpec
from pdelie.data import generate_heat_1d_field_batch
from pdelie.reporting import summarize_formula_generator_family, summarize_generator_fit_diagnostics
from pdelie.residuals import HeatResidualEvaluator
from pdelie.symmetry import FormulaGeneratorFamily, fit_translation_generator, validate_symmetry_candidate

DOMAIN_LENGTH = 2.0 * np.pi
CONFIG = {"fit_epsilon": 1e-4, "finite_shift": DOMAIN_LENGTH / 8.0}
CONFIG

[1]:

{'fit_epsilon': 0.0001, 'finite_shift': 0.7853981633974483}

1. Build one field and four candidate styles#

[2]:

field = generate_heat_1d_field_batch(batch_size=3, num_times=17, num_points=64, seed=670)
evaluator = HeatResidualEvaluator()
fitted = fit_translation_generator(field, evaluator, epsilon=CONFIG["fit_epsilon"])
spec = InvariantMapSpec(
    generator_metadata=fitted.to_dict(),
    construction_method="uniform_translation",
    parameters={"axis": "x", "shift": CONFIG["finite_shift"]},
    domain_validity="global",
    inverse_available=True,
    diagnostics={},
)
formula = FormulaGeneratorFamily(
    formula_generators=[
        {
            "name": "formula_translation",
            "components": {
                "tau": {"node": "const", "value": 0.0},
                "xi": {"node": "const", "value": 1.0},
                "phi": {"node": "const", "value": 0.0},
            },
        }
    ],
    finite_transform_spec=spec.to_dict(),
)
failed = GeneratorFamily(
    parameterization=fitted.parameterization,
    coefficients=np.asarray([[0.0, 0.0, 1.0, 0.0]], dtype=float),
    basis_spec=fitted.basis_spec,
    normalization=fitted.normalization,
    diagnostics={},
)
print(pretty_json(summarize_formula_generator_family(formula), max_chars=2500))

{
  "component_names": [
    "tau",
    "xi",
    "phi"
  ],
  "component_nodes": {
    "phi": [
      "const"
    ],
    "tau": [
      "const"
    ],
    "xi": [
      "const"
    ]
  },
  "diagnostics": {},
  "finite_transform_available": true,
  "finite_transform_construction_method": "uniform_translation",
  "formula_kinds": {
    "const": 3
  },
  "generator_count": 1,
  "generator_names": [
    "formula_translation"
  ],
  "parameterization": "formula_generator_family",
  "reciprocal_denominator_floor": 1e-12,
  "schema_version": "0.1",
  "summary_schema_version": "0.1",
  "summary_type": "formula_generator_family",
  "symbolic_references": [],
  "variables": [
    "t",
    "x",
    "u"
  ]
}

2. Validate candidates and compare conclusions#

[3]:

candidates = {
    "fitted_generator": fitted,
    "invariant_map_payload": spec.to_dict(),
    "formula_generator": formula,
    "failed_wrong_span": failed,
}
reports = {
    name: validate_symmetry_candidate(
        field,
        candidate,
        residual_evaluator=evaluator,
        source_candidate_id=name,
    )
    for name, candidate in candidates.items()
}
fit_summary = summarize_generator_fit_diagnostics(fitted)
cards = [
    confidence_card(
        label=name,
        fit=fit_summary if name == "fitted_generator" else None,
        validation=report,
    )
    for name, report in reports.items()
]
print_cards(cards)

[
  {
    "candidate_kind": "generator_family",
    "condition_number": 96906.51946806097,
    "evidence_label": "direct_svd_in_tolerance",
    "fit_mode": "svd",
    "label": "fitted_generator",
    "reference_fallback_used": false,
    "selected_span_distance": 3.0007521409568434e-05,
    "singular_value_count": 4,
    "svd_span_distance": 3.0007521409568434e-05,
    "validation_conclusion": "validated"
  },
  {
    "candidate_kind": "invariant_map_spec",
    "label": "invariant_map_payload",
    "validation_conclusion": "validated"
  },
  {
    "candidate_kind": "formula_generator_family",
    "label": "formula_generator",
    "validation_conclusion": "validated"
  },
  {
    "candidate_kind": "generator_family",
    "label": "failed_wrong_span",
    "validation_conclusion": "failed"
  }
]

3. A validation report is a configured empirical report#

validated is not a theorem. It means configured checks passed under this field, evaluator, epsilons, reference, and thresholds.

[4]:

print(pretty_json({
    name: {
        "candidate_kind": report["candidate_kind"],
        "conclusion": report["conclusion"],
        "configured_checks": report["configured_validation_checks"],
    }
    for name, report in reports.items()
}, max_chars=5000))

{
  "failed_wrong_span": {
    "candidate_kind": "generator_family",
    "conclusion": "failed",
    "configured_checks": [
      "schema",
      "finite_transform_verification"
    ]
  },
  "fitted_generator": {
    "candidate_kind": "generator_family",
    "conclusion": "validated",
    "configured_checks": [
      "schema",
      "finite_transform_verification"
    ]
  },
  "formula_generator": {
    "candidate_kind": "formula_generator_family",
    "conclusion": "validated",
    "configured_checks": [
      "schema",
      "formula_evaluation_diagnostics",
      "finite_transform_schema",
      "finite_transform_residual_stability",
      "finite_transform_inverse_consistency"
    ]
  },
  "invariant_map_payload": {
    "candidate_kind": "invariant_map_spec",
    "conclusion": "validated",
    "configured_checks": [
      "schema",
      "residual_stability",
      "inverse_consistency"
    ]
  }
}

Recap#

PDELie can validate structured candidates from external methods without training those methods or accepting executable generator code.

Common pitfalls#

  • Reading validated as a theorem instead of configured empirical validation.

  • Treating partially_validated as downstream acceptance.

  • Passing callable or neural generator objects; those are deliberately out of scope.

  • Hiding candidate kind differences in a single scalar score.

Extension ideas#

  • Validate candidates exported from your own method as strict payload mappings.

  • Add source candidate IDs that trace back to external experiment logs.

  • Compare formula-only candidates against candidates with supported finite-transform specs.

What to read/run next#

Run 08_downstream_task_template.ipynb to connect validation reports to downstream inputs.