V0.9 Scope Freeze#

Summary#

v0.9 is the stable normalized periodic KdV strong-path release for pdelie.

Its purpose is:

promote the existing tests-first KdV feasibility slice into a narrow stable runtime path for normalized, periodic, short-horizon KdV data.

Stable release definition:

canonical scalar 1D uniform periodic FieldBatch -> spectral_fd with u_xxx -> normalized KdV residual evaluator -> translation fit/verification

v0.9 is not general KdV support. It is a controlled strong-form path for the existing scalar 1D periodic regime.

Stable Scope#

Stable v0.9 scope is limited to:

compute_spectral_fd_derivatives(..., max_spatial_order=...) through spatial order 3
pdelie.data.generate_kdv_1d_field_batch(...)
pdelie.residuals.KdVResidualEvaluator
canonical scalar 1D uniform periodic FieldBatch inputs
normalized periodic KdV only
short-horizon synthetic KdV generation under the frozen default regime
translation fitting and held-out verification through the existing polynomial translation stack

Stable v0.9 does not add root exports. The new runtime APIs live under their existing submodules.

Exact Public API Contracts#

Derivatives#

Planned stable derivative API:

compute_spectral_fd_derivatives(
    field: FieldBatch,
    *,
    max_spatial_order: int = 2,
) -> DerivativeBatch

Frozen order behavior:

max_spatial_order=1 emits derivative keys u_t and u_x
max_spatial_order=2 emits exactly the existing default derivative keys u_t, u_x, and u_xx
max_spatial_order=3 emits u_t, u_x, u_xx, and u_xxx
unsupported orders raise ScopeValidationError

Backward-compatibility rule:

default max_spatial_order=2 preserves the v0.8 derivative arrays and stable behavior
default config and diagnostics should remain unchanged unless implementation requires a documented versioned addition

KdV Data#

Planned stable generator API:

generate_kdv_1d_field_batch(
    *,
    batch_size: int = 2,
    num_times: int = 17,
    num_points: int = 64,
    max_time: float = 0.03,
    num_modes: int = 3,
    amplitude: float = 0.08,
    seed: int = 0,
    num_substeps: int = 8,
    domain_length: float = 2 * pi,
) -> FieldBatch

Frozen generator policy:

no dtype parameter in v0.9
no custom initial conditions in v0.9
generated data uses dims ("batch", "time", "x", "var")
generated data uses var_names = ["u"]
generated metadata includes parameter_tags = {"equation": "kdv_normalized"}
generated metadata keeps periodic x, cartesian coordinates, rectilinear grid type, and uniform grid regularity

KdV Residual#

Planned stable residual evaluator API:

KdVResidualEvaluator().evaluate(
    field: FieldBatch,
    derivatives: DerivativeBatch | None = None,
) -> ResidualBatch

Frozen residual contract:

equation: u_t + 6*u*u_x + u_xxx = 0
residual form: u_t + 6*u*u_x + u_xxx
if derivatives are omitted, the evaluator computes compute_spectral_fd_derivatives(field, max_spatial_order=3)
if derivatives are supplied, the evaluator requires u_t, u_x, and u_xxx
output uses ResidualBatch(definition_type="analytic", normalization="none")
diagnostics include equation, backend, max_abs_residual, and rms_residual

The definition_type="analytic" label means formula-defined strong-form residual using numerical derivatives, matching the existing Heat/Burgers residual convention. It does not mean an exact closed-form solution residual.

KdV Equation and Numerical Regime#

Frozen KdV equation:

u_t + 6*u*u_x + u_xxx = 0

Frozen stable regime:

normalized coefficient form only
scalar u only
one spatial dimension x
uniform periodic rectilinear grid
short time horizon
synthetic Fourier-mode initial conditions generated by the runtime generator
spectral spatial derivatives
finite-difference time derivative

The stable numerical guarantee covers the frozen default short-horizon regime and the release-gate fixtures. Accepted parameters outside the release-guaranteed regime may produce valid FieldBatch objects, but they are not promised to satisfy release-gate numerical thresholds.

Generator Parameter Validation#

The KdV generator must reject invalid parameters with typed validation errors.

Frozen validation rules:

batch_size must be a positive integer
num_times must be an integer with num_times >= 3
num_points must be an integer with num_points >= 16
max_time must be finite and positive
num_modes must be an integer with num_modes >= 1
num_modes <= floor(num_points / 3)
amplitude must be finite and nonnegative
seed must be an integer
num_substeps must be a positive integer
domain_length must be finite and positive

Frozen release-guaranteed regime:

default generator parameters
max_time <= 0.03
amplitude <= 0.08
num_modes <= 3
num_substeps >= 8
num_points >= 64
num_times >= 17

The function may accept parameters outside the release-guaranteed regime if they pass validation. Those accepted-outside-guarantee parameters are user-risk in v0.9.

Release Fixtures and Thresholds#

Frozen KdV vertical-slice fixture:

generator seed: 9001
batch_size = 5
train_size = 2
train/heldout split seed: 9002
all other generator settings use the frozen defaults

Frozen release-gate thresholds:

KdV residual max absolute value < 1e-2
KdV residual RMS value < 2e-3
translation span distance <= 5e-2
first-epsilon held-out verification error < 1e-4
held-out verification classification is not failed
mass drift <= 1e-8
relative L2 drift <= 5e-3

These thresholds gate the stable release fixture. They are not general mathematical guarantees for arbitrary accepted KdV generator parameters.

Scope Limits#