V0.8 Scope Freeze#

Summary#

v0.8 is the first weak-form numerics release for pdelie.

Its purpose is:

add a narrow stable weak residual path for the existing scalar 1D Heat/Burgers regime, with deterministic clean/noisy/coarse robustness comparisons against the current spectral/analytic path, while preserving canonical data and generator-family contracts.

v0.8 is intentionally narrow. It is not a broad numerics, PDE-zoo, or adapter release.

Stable Scope#

Stable v0.8 scope is limited to:

  • pdelie.residuals.evaluate_weak_heat_residual(...)

  • pdelie.residuals.evaluate_weak_burgers_residual(...)

  • window-indexed weak residual reports rather than field-shaped residual arrays

  • canonical scalar 1D uniform periodic FieldBatch inputs only

  • Heat and Burgers only

  • deterministic clean/noisy/coarse robustness comparisons against the current spectral_fd / analytic path

Stable v0.8 release definition:

canonical FieldBatch -> stable weak residual report APIs for Heat/Burgers -> deterministic clean/noisy/coarse robustness comparisons against the current spectral/analytic path

Exact Public API Contracts#

Planned stable public APIs:

  • evaluate_weak_heat_residual(field, *, diffusivity: float | None = None) -> dict[str, Any]

  • evaluate_weak_burgers_residual(field, *, diffusivity: float | None = None) -> dict[str, Any]

These are stable runtime report-style APIs under pdelie.residuals.

Weak Residual Output Family#

Frozen output-family rules:

  • the primary output is a window-indexed report

  • the stable output shape is (batch, time_window, x_window, var)

  • the stable scalar slice keeps var = 1

  • the report is not a field-shaped residual array

  • the exact top-level report keys are:

    • equation

    • equation_form

    • method_family

    • window_residuals

    • time_window_centers

    • x_window_centers

    • normalization

    • diagnostics

  • equation = "heat_1d" or "burgers_1d"

  • equation_form = "nonconservative" for Heat

  • equation_form = "conservative" for Burgers

  • window_residuals has shape (batch, n_time_windows, n_x_windows, 1)

  • time_window_centers and x_window_centers store the physical coordinates of the window-center indices

  • diagnostics includes exactly:

    • strong_form

    • weak_form

    • diffusivity

    • time_window_size

    • x_window_size

    • time_window_stride

    • x_window_stride

    • quadrature

    • test_function

    • periodic_x_wrapping

    • window_counts

    • max_abs_residual

    • l2_residual

Weak Method Family#

Frozen method-family rules:

  • local compact spacetime windows

  • separable polynomial test functions

  • integration by parts shifts derivatives off u where the frozen PDE identity allows

  • the frozen base bump is:

    • beta(s) = (1 - s^2)^2 for |s| <= 1

    • beta(s) = 0 for |s| > 1

  • the frozen bump derivatives are:

    • beta'(s) = -4s(1 - s^2) for |s| <= 1, else 0

    • beta''(s) = -4 + 12s^2 for |s| <= 1, else 0

  • the frozen separable test function is:

    • phi(t, x) = beta(s_t) * beta(s_x)

  • the frozen local coordinates are:

    • s_t = (t - t_c) / h_t

    • s_x = (x_local - x_c_local) / h_x

  • the frozen window sizes are:

    • time window size = 5 grid points

    • x window size = 9 grid points

  • the frozen half-widths are:

    • time half-width = 2 time steps, so h_t = 2 * dt

    • x half-width = 4 x steps, so h_x = 4 * dx

  • local support maps exactly to [-1, 1] in both coordinates

  • the frozen test-function derivatives are:

    • d_t(phi) = (1 / h_t) * beta'(s_t) * beta(s_x)

    • d_x(phi) = (1 / h_x) * beta(s_t) * beta'(s_x)

    • d_xx(phi) = (1 / h_x^2) * beta(s_t) * beta''(s_x)

  • the frozen window geometry is:

    • time stride = 1

    • x stride = 1

    • time windows use full support only and are centered on interior time indices

    • x windows are centered on every x index

    • no time padding, interpolation, or extrapolation is allowed

  • periodic x windows are defined by integer index offsets, not raw coordinate subtraction:

    • x offsets are [-4, -3, ..., 4] * dx

    • sample indices are taken modulo num_points

    • x_window_centers stores the physical coordinate of the center index

    • local x support and derivatives are evaluated from these wrapped index offsets

  • the frozen quadrature is the composite tensor-product trapezoidal rule on the native window grid

  • the frozen normalization is normalization = "none"

  • window_residuals store signed weak residual values, not absolute values

  • the frozen method identifier is method_family = "local_separable_quartic_bump_trapezoid_v1"

v0.8 does not commit to a broad user-configurable weak-form framework.

PDE Identities#

Frozen PDE-identity starting points:

  • Heat starts from u_t - nu u_xx = 0

  • Burgers starts from conservative form u_t + 1/2 (u^2)_x - nu u_xx = 0

  • the frozen Heat weak integrand is -u * d_t(phi) - nu * u * d_xx(phi)

  • the frozen Burgers weak integrand is -u * d_t(phi) - 1/2 * u^2 * d_x(phi) - nu * u * d_xx(phi)

  • the frozen report strings are:

    • Heat:

      • strong_form = "u_t - nu u_xx = 0"

      • weak_form = "-u phi_t - nu u phi_xx"

    • Burgers:

      • strong_form = "u_t + 1/2 (u^2)_x - nu u_xx = 0"

      • weak_form = "-u phi_t - 1/2 u^2 phi_x - nu u phi_xx"

  • boundary terms vanish because:

    • the compact bump vanishes at local time-window endpoints

    • the compact bump vanishes at local x-window endpoints

    • x sampling is periodic and wrapped by index

  • M2 must preserve these signs exactly and must not flip residual orientation

Scope Limits#

Stable v0.8 scope is further limited to:

  • canonical FieldBatch only

  • dims exactly ("batch", "time", "x", "var")

  • uniform time only

  • uniform periodic rectilinear x only

  • finite unmasked values only

  • scalar var only

  • at least 5 time points

  • at least 9 x points

  • diffusivity=None means use field.metadata["parameter_tags"]["nu"]

  • Heat/Burgers only

Explicit Non-goals#

Out of stable v0.8 scope:

  • no stable weak derivative API

  • no stable ResidualBatch / ResidualEvaluator integration

  • no per-term public contribution arrays

  • no stable KdV API

  • no multidimensional expansion

  • no multivariable expansion

  • no nonuniform-grid support

  • no operator-method expansion

  • no adapter expansion

  • no imported-field parity requirement in M1

  • no new canonical object

Benchmark Fixtures#

Frozen v0.8 M1 benchmark fixtures use only the existing native generators and robustness utilities.

Shared base sizes:

  • batch_size = 2

  • num_times = 33

  • num_points = 64

Frozen fixtures:

  • Heat clean:

    • generate_heat_1d_field_batch(seed=8001, batch_size=2, num_times=33, num_points=64)

  • Heat noisy:

    • clean Heat fixture + add_gaussian_noise(std_fraction=1e-3, seed=8002)

  • Heat coarse:

    • clean Heat fixture + subsample_time(stride=2) then subsample_x(stride=2)

  • Burgers clean:

    • generate_burgers_1d_field_batch(seed=8101, batch_size=2, num_times=33, num_points=64)

  • Burgers noisy:

    • clean Burgers fixture + add_gaussian_noise(std_fraction=1e-3, seed=8102)

  • Burgers coarse:

    • clean Burgers fixture + subsample_time(stride=2) then subsample_x(stride=2)

Imported FieldBatch parity is explicitly deferred from M1 to M4.

Frozen v0.8 M4 downstream robustness fixtures are separate from the M1 report-surface fixtures. They benchmark downstream translation fitting and held-out verification, not raw residual magnitudes.

Shared M4 downstream settings:

  • train_batch_size = 4

  • heldout_batch_size = 3

  • num_times = 33

  • num_points = 64

  • noise_std_fraction = 1e-3

  • coarse degradation is exactly:

    • subsample_time(stride=2)

    • then subsample_x(stride=2)

  • the wrong-generator control is fixed to the affine non-translation coefficient row:

    • [0.0, 0.0, 1.0, 0.0]

Frozen M4 Heat fixtures:

  • clean training:

    • generate_heat_1d_field_batch(seed=8401, batch_size=4, num_times=33, num_points=64)

  • clean heldout:

    • generate_heat_1d_field_batch(seed=8402, batch_size=3, num_times=33, num_points=64)

  • noisy training:

    • clean Heat training + add_gaussian_noise(std_fraction=1e-3, seed=8403)

  • noisy heldout:

    • clean Heat heldout + add_gaussian_noise(std_fraction=1e-3, seed=8404)

  • coarse training:

    • clean Heat training + subsample_time(stride=2) then subsample_x(stride=2)

  • coarse heldout:

    • clean Heat heldout + subsample_time(stride=2) then subsample_x(stride=2)

Frozen M4 Burgers fixtures:

  • clean training:

    • generate_burgers_1d_field_batch(seed=8501, batch_size=4, num_times=33, num_points=64)

  • clean heldout:

    • generate_burgers_1d_field_batch(seed=8502, batch_size=3, num_times=33, num_points=64)

  • noisy training:

    • clean Burgers training + add_gaussian_noise(std_fraction=1e-3, seed=8503)

  • noisy heldout:

    • clean Burgers heldout + add_gaussian_noise(std_fraction=1e-3, seed=8504)

  • coarse training:

    • clean Burgers training + subsample_time(stride=2) then subsample_x(stride=2)

  • coarse heldout:

    • clean Burgers heldout + subsample_time(stride=2) then subsample_x(stride=2)

Frozen M4 degraded-data success rule:

  • M4 compares downstream translation recovery and held-out verification, not direct weak-report-vs-strong-residual magnitudes.

  • Clean-data baseline requirements:

    • both the strong path and the weak path must be deterministic on repeated runs for Heat and Burgers

    • both paths must return either:

      • translation coefficients within DEFAULT_TRANSLATION_SPAN_TOLERANCE of the canonical translation reference, or

      • an explicit canonical translation reference fallback

    • both paths must achieve a first-epsilon wrong-vs-fitted median separation ratio of at least 5.0x on clean Heat and clean Burgers

  • Degraded-data robustness requirements:

    • for each PDE separately, at least one degraded condition in {noisy, coarse} must produce a weak-path robustness signal

    • a weak-path robustness signal exists only if the weak path is deterministic on repeated runs and one of the following is true:

      • contract-stability signal:

        • the weak path returns in-tolerance translation coefficients or an explicit canonical translation reference fallback, and

        • the strong path does not

      • separation signal:

        • the weak-path first-epsilon wrong-vs-fitted median separation ratio is at least 1.5x the strong-path ratio, and

        • the weak-path ratio is at least 3.0x

  • M4 does not require the weak path to beat the strong path on every degraded fixture.

  • Imported FieldBatch parity for M4 should reuse these same frozen fixtures after canonical ingestion, not introduce a second benchmark matrix.

Milestones#

Planned v0.8 sequence:

  • Milestone 0 — roadmap reset

  • Milestone 1 — weak semantics freeze

  • Milestone 2 — weak residual report implementation

  • Milestone 3 — optional contract-integration exploration

  • Milestone 4 — robustness comparison layer

  • Milestone 5 — optional KdV stress

  • Milestone 6 — release gate