V0.31.0 Release Readiness#

Decision#

v0.31.0 is ready as a Git-tag-only release.

Release conclusion:

downstream_discovery_task_bridge

Package Metadata#

  • package version: 0.31.0

  • git tag: v0.31.0 (do not create until explicitly authorized after review)

  • PyPI/TestPyPI: deferred until v1.0 or later

Do not publish to TestPyPI or PyPI for v0.31.0.

Public Surface#

New in v0.31 — downstream discovery task bridge (submodule-only)#

The v0.31 arc adds one narrow scientific delta: a submodule-only downstream discovery task bridge under pdelie.tasks. No root pdelie export is added. The pdelie.residuals.weak_1d PDELie-native weak-derivative path remains available and distinct.

Stable public submodule surfaces:

  • pdelie.tasks.run_pysindy_pde_task — executable PySINDy PDELibrary-backed sparse-discovery task runner (v0.31b1). Periodic scalar 1D only. Layer-1 boundary-condition guard raises PySINDyDiscoveryUnsupportedBoundaryError before any PySINDy call when is_x_periodic(field) is false. Returns a strict-JSON discovery_task_result.

  • pdelie.tasks.summarize_discovery_task_result — strict-JSON payload assembler (v0.31b1). Enforces the 22-key composed schema, records summary_type = "discovery_task_result", summary_schema_version = "0.1", and pysindy_bridge_variant = "periodic_only_v1". Embeds the v0.31b0-frozen backend-native summarize_discovery_result verbatim under underlying_discovery_result.

  • pdelie.tasks.PySINDyDiscoveryUnsupportedBoundaryError — subclass of ScopeValidationError. Raised at the pdelie.tasks.discovery entry when a nonperiodic-x FieldBatch is supplied.

  • pdelie.tasks.inspect_pysindy_weak_pde_library — diagnostic-only wrapper around PySINDy’s WeakPDELibrary (v0.31b2). Two-layer scope guard (periodic-x, uniform x/t grids, batch==1, single var, K-scaled grid-sufficiency floor max(8, 4*K), unsupported PySINDy API). Returns a strict-JSON pdelie_weak_pde_library_diagnostic.

  • pdelie.tasks.summarize_pysindy_weak_pde_library_diagnostic — strict-JSON payload assembler for the diagnostic-only wrapper (v0.31b2). Enforces the 27-key composed schema.

  • pdelie.tasks.WeakPDELibraryDiagnostic — caller-declared, JSON-safe library-configuration dataclass with as_dict() (v0.31b2). Rejects NaN/Inf at construction via _validate_strict_json_compatible.

  • pdelie.examples.run_downstream_discovery_task_bridge_example and CLI python -m pdelie.examples.downstream_discovery_task_bridge (v0.31c) — composed JSON-only demonstration runner. Not a new report schema.

All names above are exposed from pdelie.tasks (or pdelie.examples) as their canonical submodule-only public surface. None appear at the root pdelie namespace.

Discovery task support#

  • input_layout: "scalar_1d_uniform".

  • periodic scalar 1D only.

  • backend: PySINDy PDELibrary (or any caller-configured pysindy.SINDy model per the v0.31b1 adapter loosening).

  • output summary_type: "discovery_task_result".

  • 22-key top-level composed schema.

  • Strict-JSON composition: _validate_strict_json_compatible(payload, name="discovery_task_result summary") invoked exactly once at the final composition boundary.

  • pysindy_bridge_variant = "periodic_only_v1" on every produced TaskResult.

  • Adapter loosening: fit_pysindy_discovery accepts a caller-supplied pysindy_model kwarg (v0.31b1); config != None still raises; the config=None, pysindy_model=None default path is byte-preserved for existing v0.30 callers.

Weak diagnostic support#

  • output summary_type: "pdelie_weak_pde_library_diagnostic".

  • diagnostic_only = True on every produced summary.

  • 27-key top-level composed schema.

  • method_family = "pysindy_weak_pde_library_polynomial_gauss_v1".

  • test_function_family = "pysindy_weak_pde_library_polynomial_bump_v1".

  • quadrature_rule = "pysindy_weak_pde_library_composite_gauss_v1".

  • No WSINDy benchmark claim.

  • No noise-robustness claim.

  • No numerical equivalence with pdelie.residuals.weak_1d. The PDELie-native weak-derivative path remains available and is retained through at least v0.32 close.

  • Two-layer scope guard: nonperiodic-x rejected via PySINDyDiscoveryUnsupportedBoundaryError (reused from v0.31b1); scope violations (dims, var_names, batch, uniform grids, K-scaled grid-sufficiency floor, unsupported PySINDy API) rejected via ScopeValidationError / SchemaValidationError.

Retained from earlier v0.x#

  • Canonical FieldBatch → DerivativeBatch → ResidualBatch → GeneratorFamily → VerificationReport pipeline (frozen since v0.1.x).

  • All v0.30 runtime and reporting surfaces including BoundaryConditionSpec, structured FieldBatch schema 0.2, low-order finite-difference derivative backend, interior-only residual diagnostics, and the ambient supportability report layer.

  • pdelie.residuals.weak_1d behavior — unchanged.

Compatibility Policy#

The v0.31 downstream task bridge is a temporary compatibility surface. It validates against a single narrow PySINDy generation, and its compatibility constraints are all bounded:

  • PySINDy: >=1.7.5,<2 under python_version < '3.12'.

  • scikit-learn: >=1.2.2,<1.3 under python_version < '3.12'.

  • setuptools: <82 under python_version < '3.12' — temporary constraint added by v0.31c1 because pysindy 1.7.5 imports pkg_resources at package init and setuptools 82 removed that module.

  • Python: downstream task support is validated on Python 3.11 only.

The v0.31c1 adversarial matrix confirmed:

  • setuptools 81.0.0: pass end-to-end.

  • setuptools 82.0.0: install succeeds but import pysindy fails with ModuleNotFoundError: No module named 'pkg_resources'.

  • setuptools 83.0.0: same failure mode as 82.

Post-fix rebuilt-wheel verification confirms pip auto-downgrades an ambient setuptools 82/83 to 81 without any user co-install. Fresh-venv baseline: setuptools stays at the bundled 65.5.0, untouched.

Deferred to v0.31.1:

  • PySINDy 2.x support. Four independent 2.x API breaks are documented in docs/design/PYSINDY_COMPATIBILITY_POLICY.md (SINDy kwargs removed; SINDy.fit signature; SINDy.differentiate removed; PDELibrary/WeakPDELibrary kwargs).

  • Python 3.12+ downstream support. The [downstream] extra is marker-scoped to python_version < '3.12'; a user on Python 3.12+ who invokes the task bridge receives a targeted, actionable error message that names the v0.31.1 deferral and states that reinstalling the same extra will not fix the environment.

  • numpy>=2 floor bump. Coordinated with the PySINDy 2.x port.

No hidden manual installation step is required in the documented user path.

Public Example#

The v0.31c JSON-only demonstration runner:

  • Public submodule surface: pdelie.examples.run_downstream_discovery_task_bridge_example.

  • CLI: python -m pdelie.examples.downstream_discovery_task_bridge.

  • Composes both v0.31 paths on one manufactured periodic scalar 1D Heat field (T=64, X=64, K=16, seed=31000).

  • 7-key top-level summary_type = "downstream_discovery_task_bridge_example". NOT a new report schema — the composed wrapper carries the verbatim v0.31b1 discovery_task_result (22 keys) and v0.31b2 pdelie_weak_pde_library_diagnostic (27 keys) as children.

  • Deterministic under the frozen seed via a private _legacy_numpy_rng_seed_scope context manager (v0.31c1). Not thread-safe — PySINDy 1.7.5 uses the legacy np.random global RNG and does not accept a modern Generator.

  • Uses only public submodule APIs (AST-checked in tests/test_v0_31c_downstream_task_bridge_example.py).

Expected xfails ledger#

The v0.31.0 release close retains three declared xfails, each with a non-empty reason and each assigned to a documented follow-up milestone. None represent a genuine failure masked to make the suite green.

Node id

Reason

Strictness

Owner milestone

Planned disposition

tests/test_v0_31b3_pysindy_compatibility_policy.py::test_unsupported_major_pysindy_version_rejected_by_discovery_task_runner

The runtime version guard on run_pysindy_pde_task has not been landed. The test monkeypatches pysindy.__version__ to "999.0.0" and expects a ScopeValidationError; no such guard exists today.

runtime-conditional pytest.xfail(...) inside try/except pytest.fail.Exception: (not decorator strict)

v0.31.1 (PySINDy 2.x port introduces _pysindy_compat._detect_api_generation gate)

KEEP as xfail until v0.31.1 lands the guard

tests/test_v0_31b3_pysindy_compatibility_policy.py::test_unsupported_major_pysindy_version_rejected_by_weak_diagnostic

The same runtime version guard has not been landed on inspect_pysindy_weak_pde_library.

runtime-conditional pytest.xfail(...)

v0.31.1 (PySINDy 2.x port)

KEEP as xfail until v0.31.1

tests/test_v0_31b3_pysindy_compatibility_policy.py::test_discovery_task_backend_version_records_exact_pysindy_and_sklearn

Asks pdelie.tasks.discovery._resolve_backend_version to include scipy for uniformity with the weak diagnostic’s provenance. scipy is currently a nested-value extension, not required for v0.31 release close.

runtime-conditional pytest.xfail(...) on the "scipy" not in backend_version branch

provenance follow-up (v0.31.1 or earlier)

KEEP as xfail until the follow-up lands

Compatibility test / release-close validation#

  • pytest full suite baseline at v0.31.0 close: 1252 passed, 3 skipped, 3 xfailed (v0.31c1 close baseline) → 1253 passed, 3 skipped, 3 xfailed after adding the Python 3.12+ UX test.

  • ruff check . clean.

  • mypy src/pdelie/tasks/ clean.

  • sphinx -b html -W --keep-going docs docs/_build/html clean.

  • python -m build --sdist --wheel produces pdelie-0.31.0.tar.gz and pdelie-0.31.0-py3-none-any.whl.

  • git diff --check clean.

Clean-install smoke matrix:

  • Core-only (Python 3.11, no [downstream]): install passes; task runner raises ImportError naming pdelie[downstream].

  • Downstream (Python 3.11, ambient setuptools>=82): pip auto-downgrades setuptools to 81; run_pysindy_pde_task passes (22-key summary, strict JSON); inspect_pysindy_weak_pde_library passes (27-key summary, diagnostic_only=True, strict JSON); example runner + CLI pass.

  • Downstream (Python 3.11, fresh venv): setuptools stays at the bundled 65.5.0; smoke passes.

  • Python 3.12+ unsupported downstream behavior: targeted ImportError (or ScopeValidationError on the weak path) message names Python 3.12, the v0.31.1 deferral, and states that reinstalling the same extra will not fix the environment. Verified by tests/test_v0_31c1_downstream_packaging_policy.py::test_v0_31_python_312_downstream_missing_extra_message_is_actionable under monkeypatched sys.version_info.

Boundaries / non-goals for v0.31.0#

  • No new discovery backend. PySINDy 1.x only.

  • No new summary type. discovery_task_result (22 keys) and pdelie_weak_pde_library_diagnostic (27 keys) are the entire v0.31 report surface.

  • No WSINDy benchmark claim. The WeakPDELibrary wrapper is diagnostic-only.

  • No noise-robustness claim.

  • No nonperiodic PySINDy discovery. Both task paths raise on nonperiodic-x inputs.

  • No PySINDy 2.x code. Deferred to v0.31.1.

  • No symmetry-method registry, no SymmetryCandidate runtime. Deferred to v0.30.1.

  • No PDEBench / The Well support claim.

  • No multi-channel / 2D widening. Deferred to v0.34+.

  • No new PDE.

  • No root pdelie export added.

  • No package version bump beyond 0.31.0.

  • No PyPI or TestPyPI publication.

Deferred scope confirmed#

  • v0.31.1: PySINDy 2.x migration (four independent API breaks + numpy>=2 floor + Python 3.12+ downstream support + runtime version guard on unsupported pysindy versions).

  • v0.30.1: submodule-only SymmetryMethod registry MVP + SymmetryCandidate wrapper contract freeze.

  • v0.31.5: nonperiodic orbit/action scope decision.

  • v0.32: external dataset readiness cookbooks (no benchmark claim).

  • v0.33: first external symmetry candidate-generator method.

  • v0.34: multi-channel / 2D contract widening scope decision.

  • v0.35: trained-model extraction layer.

  • v1.0: stable public engine + PyPI publish + optional root-entry decision.

Validation checklist#

  • [x] version bump 0.30.0 → 0.31.0 in pyproject.toml and docs/conf.py.

  • [x] release readiness document exists (this file).

  • [x] CHANGELOG.md v0.31.0 entry with the five subsections (Added / Compatibility / Diagnostics / Examples / Boundaries).

  • [x] docs/specs/support_matrix.v0_31.json written as strict JSON with the v0.31 additions.

  • [x] docs/planning/V0_31_DISCOVERY_TASK_BRIDGE_SCOPE.md status → COMPLETE.

  • [x] docs/planning/PLAN.md v0.31.0 release-close record.

  • [x] docs/planning/ROADMAP.md v0.31 moved to completed releases; v0.31c1 marked completed; next active items called out explicitly.

  • [x] docs/specs/API_STABILITY.md v0.31 final stable-surface note.

  • [x] configs/release_gate_manifest.json — "0.31" row extended in place; current_release_gate_job_name renamed to v0_31-release-gate.

  • [x] .github/workflows/ci.yml release-gate job renamed v0_30-release-gate → v0_31-release-gate.

  • [x] tests/test_current_release_gate.py updated to the new job name.

  • [x] Full validation gates pass (pytest / ruff / mypy / sphinx / build / git diff-check).

  • [x] Clean-install smoke matrix (core-only, downstream, ambient setuptools 82/83, Python 3.12+ UX message).

  • [ ] Git tag v0.31.0 — deferred to explicit authorization after review.