BoundaryConditionSpec — Design Document#

Status: DESIGN-FROZEN in v0.30a; RUNTIME IMPLEMENTED in v0.30b (internal helpers and FieldBatch 0.2 migration). Adapters accept structured nonperiodic specs in v0.30b; nonperiodic derivative and residual backends are deferred to v0.30c.

This document defines the structured representation that will replace the current string-only metadata["boundary_conditions"]["x"] in canonical FieldBatch objects. It is normative for v0.30 proper. The runtime in v0.30a is unchanged.

Motivation#

The current canonical FieldBatch carries boundary information as a free-form string under metadata["boundary_conditions"]["x"]. The only accepted value across the runtime is "periodic", and this is enforced at every consumer site:

  • ingestion: src/pdelie/data/numpy_adapter.py:120-121 rejects everything ≠ "periodic"

  • ingestion: src/pdelie/data/xarray_adapter.py:114-115 rejects the same

  • derivatives: src/pdelie/derivatives/spectral_fd.py:32-33 rejects the same

  • residuals: three sites in src/pdelie/residuals/ enforce periodic-x at runtime — advection_diffusion_1d.py:51-53, reaction_diffusion_1d.py:44-46, kdv_1d.py:32

  • weak residuals: src/pdelie/residuals/weak_1d.py:106-107 enforces the same

  • symmetry: two sites in src/pdelie/symmetry/parameterization/polynomial_translation.py:34-35 and :82-83

  • verification: src/pdelie/verification/finite_transform.py:22-23

Lifting any one of these requires knowing more about the boundary than a string can carry.

Operational problem#

A Dirichlet boundary without the boundary value cannot be used by a one-sided finite-difference stencil to produce a correct derivative at the boundary. A 2nd-order one-sided stencil that must extrapolate the missing boundary point produces O(h) error rather than O(h²). A string label "dirichlet" hides three pieces of information:

  • the boundary value (e.g. u(a) = 0)

  • which side the value applies to (left, right, or both)

  • whether the value is time-dependent

A library that accepts string-only boundary metadata cannot tell whether "dirichlet" means “homogeneous Dirichlet” (boundary value zero), “inhomogeneous Dirichlet with the value embedded in field.values”, or “Dirichlet, value not specified, user error to fit residuals here”. Existing FD libraries (DeepXDE, deal.II, FEniCS) all use typed boundary objects for the same reason.

Why not a wider string set#

Widening to {"periodic", "dirichlet", "neumann", "open"} has the same problem at a different scale. "dirichlet" without a value is still unusable; "open" is ambiguous across PDE communities (outflow, absorbing, Sommerfeld, “finite domain unstated”); and time-dependent boundaries have no expression in a string.

Proposed structured spec#

metadata["boundary_conditions"]["x"] becomes a structured dict:

{
    "type": Literal["periodic", "dirichlet", "neumann", "open_unknown"],
    "left": BoundaryFace | None,
    "right": BoundaryFace | None,
    "specified": bool,
    "time_dependent": bool | None,
    "notes": str | None,
}

BoundaryFace is:

{
    "value": float | None,
    "time_dependent": bool,
    "source": Literal["user_supplied", "default", "inferred_unspecified"],
}

Field semantics#

  • type: the boundary class. The set is closed; new types require a scope freeze.

  • left, right: per-face data. None for the side where the boundary class makes no per-face value meaningful (e.g. "periodic" has no faces; both are None). Required for "dirichlet" and "neumann"; either may be None for one-sided constraints.

  • specified: True iff every face that the boundary class requires has value is not None AND source != "inferred_unspecified". Periodic is always specified=True. open_unknown is always specified=False.

  • time_dependent: top-level convenience flag. True iff any face has time_dependent=True. None for boundary classes where the question doesn’t apply (periodic, open_unknown).

  • notes: free-form string for human-readable context; never load-bearing.

Rename: "open" → "open_unknown"#

In v0.30 the unspecified-finite-domain case is named "open_unknown". The string "open" is intentionally not accepted because it carries different meanings in different PDE communities (outflow, absorbing, Sommerfeld, free-boundary). "open_unknown" makes the meaning explicit: “finite domain, boundary character unstated/unknown to PDELie; treat as needing user attention.”

Legacy compatibility#

v0.30 bumps FieldBatch.SCHEMA_VERSION from "0.1" to "0.2" because the structural change is not a pure widening of accepted values.

FieldBatch.from_dict accepts both "0.1" and "0.2" payloads under a backwards-compatible loader:

  • A "0.2" payload presents boundary_conditions["x"] already in structured form. The loader validates the structure against the spec above.

  • A "0.1" payload presents boundary_conditions["x"] as a string. The loader normalizes:

    • "periodic" → {"type": "periodic", "left": None, "right": None, "specified": True, "time_dependent": None, "notes": None}

    • "dirichlet" → {"type": "dirichlet", "left": {"value": None, "time_dependent": False, "source": "inferred_unspecified"}, "right": {"value": None, "time_dependent": False, "source": "inferred_unspecified"}, "specified": False, "time_dependent": False, "notes": "normalized from legacy 0.1 string"}

    • "neumann" → analogous to "dirichlet"

    • "open" or "open_unknown" → {"type": "open_unknown", "left": None, "right": None, "specified": False, "time_dependent": None, "notes": "normalized from legacy 0.1 string"}

    • any other string → ScopeValidationError

In all "0.1" normalization cases the loader appends one entry to preprocess_log:

{
    "operation": "schema_0_1_to_0_2_boundary_normalization",
    "parameters": {
        "legacy_x_boundary": "<original string>",
        "normalized_specified": <bool>,
    },
}

This preserves provenance; downstream readiness reports can detect the synthetic normalization and warn appropriately.

"0.1" payloads whose boundary classes other than "periodic" are normalized always materialize with "specified": False. The library never invents boundary values.

Readiness signaling#

summarize_field_batch_readiness (in src/pdelie/reporting/summaries.py) gains a new field "boundary_condition_warnings": a list of strings drawn from a frozen vocabulary:

  • "dirichlet_value_unspecified" — type is "dirichlet" but specified is False

  • "neumann_value_unspecified" — analogous for Neumann

  • "open_unknown_boundary" — type is "open_unknown"

  • "boundary_normalized_from_legacy_schema" — provenance recorded in preprocess_log

  • "boundary_time_dependent" — any face has time_dependent=True; v0.30 derivative backends do not support time-dependent BCs

Any non-empty boundary_condition_warnings list downgrades the report’s readiness_label from "ready" to at most "needs_attention". The existing _READINESS_LABELS = frozenset({"ready", "needs_attention", "not_ready"}) vocabulary is sufficient; no new label.

"not_ready" is reserved for hard failures (missing required metadata keys, non-finite values, non-uniform grid). Under-specified boundary conditions are recoverable by the user, so they degrade to "needs_attention", not "not_ready".

Out of scope for v0.30#

The following are deliberately deferred to later releases:

  • time-dependent boundary value tables (Dirichlet/Neumann values that vary with t)

  • mixed / Robin boundaries (αu + β u_x = γ)

  • free-boundary problems (Stefan-type, moving interfaces)

  • vector or tensor boundary conditions (multi-channel data, deferred to v0.34 multi-D/multi-channel scope)

  • 2D and 3D boundary conditions (deferred to v0.34)

  • nonuniform grids (from_numpy currently requires uniform; this does not change in v0.30)

  • time-axis boundary conditions (initial / terminal-time conditions)

The scope of v0.30 is intentionally narrow: structured BC metadata, scalar 1D, uniform grids, time-independent boundary values only.

Validation requirements (for v0.30 proper, not v0.30a)#

When BoundaryConditionSpec lands:

  • FieldBatch.validate() must enforce that metadata["boundary_conditions"]["x"] matches the structured shape exactly (for schema_version == "0.2")

  • FieldBatch.from_dict round-trip: from_dict(d.to_dict()) == d for both "0.1" and "0.2" payloads

  • Strict JSON: json.dumps(field.to_dict(), allow_nan=False) succeeds for any valid FieldBatch

  • All consumers (residuals, derivatives, weak, symmetry, verification) read metadata["boundary_conditions"]["x"]["type"] and not the raw string

  • Adapters (from_numpy, from_xarray, from_xarray_dataset) accept both legacy string inputs (normalized internally) and pre-structured dict inputs

Implementation pointer (for v0.30 proper)#

The most surgical implementation places a new module src/pdelie/contracts/boundary.py (or extends src/pdelie/contracts.py) with:

  • BoundaryConditionSpec dataclass and BoundaryFace dataclass

  • normalize_legacy_x_boundary(value: str) -> BoundaryConditionSpec for the loader path

  • validate_x_boundary(spec: dict | BoundaryConditionSpec) -> BoundaryConditionSpec for ingestion

  • _ALLOWED_X_BOUNDARY_TYPES = frozenset({"periodic", "dirichlet", "neumann", "open_unknown"}) matching the existing frozenset discipline (e.g. _READINESS_LABELS, _CONFIDENCE_LABELS in summaries.py)

The existing JSON-strict helpers (_validate_strict_json_compatible and _json_safe in the reporting layer) handle the serialization of the structured form without modification.