V0.19 Scope - Stable Advection-Diffusion Strong Path#

Status: COMPLETE

v0.19 is a narrow PDE-expansion release for one stable scalar 1D periodic constant-coefficient advection-diffusion path.

Stable path:

canonical scalar 1D periodic FieldBatch
-> spectral_fd derivatives
-> advection-diffusion residual
-> translation fit/verification
-> vertical-slice summary/example

Summary#

v0.19 adds a deterministic synthetic advection-diffusion generator, a strong-form residual evaluator, and a compact JSON-only vertical-slice example.

Chosen equation:

u_t + c*u_x = nu*u_xx
residual = u_t + c*u_x - nu*u_xx

This release stays inside the existing safe numerical regime:

  • scalar 1D uniform periodic fields

  • synthetic data only

  • default order-2 spectral_fd derivatives

  • polynomial translation generator fitting

  • finite uniform translation verification

  • no root export expansion

Public APIs#

Submodule-only APIs added:

  • pdelie.data.generate_advection_diffusion_1d_field_batch(...)

  • pdelie.residuals.AdvectionDiffusionResidualEvaluator

  • pdelie.examples.run_advection_diffusion_vertical_slice_example(...)

Command example:

python -m pdelie.examples.advection_diffusion_vertical_slice

No root pdelie exports were added.

Frozen Semantics#

Generated fields are canonical FieldBatch objects with:

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

  • scalar variable name u

  • endpoint-excluded uniform periodic x

  • uniformly increasing time

  • finite unmasked values

  • field.metadata["parameter_tags"]["equation"] == "advection_diffusion_constant_coefficient"

  • field.metadata["parameter_tags"]["c"]

  • field.metadata["parameter_tags"]["nu"]

Frozen defaults:

  • batch_size = 5

  • num_times = 65

  • num_points = 64

  • max_time = 0.4

  • advection_speed = 0.75

  • diffusivity = 0.05

  • num_modes = 6

  • amplitude = 0.2

  • domain_length = 2*pi

  • seed = 0

Generator rollout is exact periodic Fourier evolution with multiplier:

exp((-nu*k**2 - 1j*c*k) * t)

The residual evaluator:

  • evaluates u_t + c*u_x - nu*u_xx

  • computes compute_spectral_fd_derivatives(field) when derivatives are omitted

  • requires supplied derivatives to include u_t, u_x, and u_xx

  • accepts finite signed c

  • requires finite positive nu

  • validates scalar 1D periodic finite unmasked fields and the frozen equation tag

Mean drift is diagnostic-only. Periodic constant-coefficient advection-diffusion preserves the mean analytically, while numerical summaries use it only as a smoke diagnostic.

Promotion Evidence#

Frozen vertical-slice configuration:

  • generator seed: 19018

  • train/heldout split: split_batch_train_heldout(field, train_size=2, seed=19019)

  • fit epsilon: 1e-4

Observed evidence:

  • residual max: approximately 5.51e-5

  • residual RMS: approximately 8.44e-6

  • fit mode: svd

  • evidence label: direct_svd_in_tolerance

  • reference fallback: false

  • selected/SVD span distance: approximately 7.87e-4

  • verification classification: exact

  • first held-out verification error: approximately 7.87e-8

This satisfies the promotion gate. No fallback-backed advection-diffusion claim landed.

Non-goals#

v0.19 explicitly does not add:

  • variable-coefficient advection-diffusion

  • reaction-advection-diffusion

  • weak advection-diffusion

  • custom advection-diffusion initial-condition APIs

  • multidimensional or nonuniform-grid ingestion

  • broad PDEBench / The Well adapters

  • time-translation APIs or axis="time" support

  • stable KS data generator, residual evaluator, vertical-slice example, imported parity, weak KS API, or root KS export

  • neural or callable generator APIs

  • operator-facing symmetry APIs

  • train/test split management, heldout-leakage detection, or downstream augmentation policy

  • transformed FieldBatch collections from reporting helpers

  • root export expansion

Milestone Status#

  • Milestone 0: COMPLETE

  • Milestone 1: COMPLETE

  • Milestone 2: COMPLETE

  • Milestone 3: COMPLETE

  • Milestone 4: COMPLETE

  • Milestone 5: COMPLETE

  • Milestone 6: COMPLETE

Release Gate Expectations#

The current explicit CI release gate is v0_19-release-gate.

Required checks before tagging:

  • v0_19-release-gate

  • editable-tests

  • package-smoke

Local validation should include:

  • python -m pytest

  • python -m build --sdist --wheel

  • clean wheel smoke from dist/pdelie-0.19.0-py3-none-any.whl

  • packaged examples, including python -m pdelie.examples.advection_diffusion_vertical_slice

  • git diff --check