Ship Checklist

For each NTX release, research and software lanes should either be closed or explicitly moved to documented future work with a clear reason.

Release Lane Status

There are no unresolved release blockers in the current tree. Items below that say “future work” or “monitor” are deliberately excluded from shipping claims until their benchmark-matrix promotion criteria pass.

Lane

Current Status

Release Rule

Code refactoring

Closed for current release; continue opportunistically

Public facades remain stable while solver, bootstrap-autodiff, profile dataclass, validation artifact-gate, and input/output ownership have been split into smaller internal modules; keep shrinking only with tests and docs.

Repository hygiene

Closed for current release

Current worktree is clean; /Users/rogeriojorge/local/NTX is the canonical checkout and sibling paths should point there instead of carrying stale checkouts.

CI runtime and coverage

Closed; monitor

Maintain >=95% repository-owned coverage, module floors, and a normal CI wall time near 5-10 minutes.

Literature-anchored physics gates

Closed for current release; extend only with artifacts

Current analytical, transfer, and independent-comparison gates pass; future gates must map to scripts, tests, artifacts, and docs.

Fixed-field NTX+NEOPAX closure

Scoped total-current stress gate closed

Keep the passing QA/QH total-current stress gate artifact-backed; do not claim species-current parity or promote a broader default closure unless a physics-derived model preserves this gate and the integrated W7-X raw-branch transfer. No fitted bridge constants.

Multi-CPU and multi-GPU algorithms

Production and strong-scaling maps artifact-backed; monitor

CPU/GPU/device-parallel/multiprocess crossover maps, fixed-workload strong-scaling maps, and prepared-geometry reuse profiles are artifact-backed; promote only algorithms that beat serial batched JAX on the target production workload. Additional healthy GPU nodes and device-memory timelines remain future work.

vmec_jax and booz_xform_jax integration

Closed for first release; broader sensitivities planned

Keep projected-boundary and explicit-relaxed lanes as the promoted differentiable paths; the implicit-equilibrium diagnostic is documented as non-shipping.

SFINCS comparisons

Closed for current release; broader parity future work

Promoted comparison claims are artifact-backed and scoped; additional comparisons must align physics settings and normalizations before promotion.

Documentation

Closed for current release; monitor

Keep docs synchronized with source layout, benchmark matrix, test lanes, performance guidance, examples, and release path.

Implicit-equilibrium derivative lane

Closed as non-shipping diagnostic

Do not promote this path for optimization claims; restore only after Boozer and NTX transport observables match centered finite differences, not just equilibrium volume.

Broader W7-X/QI/omnigenous families

Closed as stress evidence; promotion future work

Keep the VMEC family convergence artifact as reduced NTX stress evidence; add independent-code parity, owned W7-X KJM input coverage, and radial/electric-field ladders before promotion.

PyPI/release automation

Closed for v0.2.0; monitor

PyPI Trusted Publishing published v0.2.0 from release.yml; future releases should keep the same green-CI, tag, artifact-provenance, and PyPI smoke-test path.

Acceptance Criteria

  1. python scripts/test_lane_manifest.py --check passes and every test belongs to exactly one CI lane.

  2. Normal CI lanes remain bounded:

    • core_foundation

    • core_cli_workflows

    • core_io_workflows

    • core_parallel_workflows

    • core_neopax_workflows

    • core_profile_audit_workflow

    • core_profile_basic_workflows

    • core_profile_optimization_workflows

    • core_profile_transport_workflows

    • core_autodiff_uncertainty_workflow

    • core_robust_bootstrap_workflow

    • core_validation

    • integration_examples

    • heavy_examples_profiles

    • heavy_examples_derivatives

    • heavy_examples_boundary

    • heavy_examples_publication

  3. python -m ruff check . and python -m mypy src/ntx pass.

  4. Coverage is >=95% for src/ntx, with weak modules called out explicitly.

  5. python scripts/build_benchmark_matrix.py reports no incomplete active gates.

  6. python scripts/build_manuscript_artifacts.py completes from committed artifacts.

  7. python -m sphinx -b html docs docs/_build/html passes.

  8. python -m build and python -m twine check dist/* pass.

  9. Generated figures and JSON artifacts are reviewed against their owning scripts/tests/docs.

  10. Any lane not closed before release is documented as future work and excluded from release claims.

Current Audit Notes

  • Full split-lane CI coverage is currently above the release threshold at 99.0%.

  • The maintained coverage-report script now accepts both absolute and relative src/ntx/... paths from coverage json, so local and CI module tables are comparable.

  • The validation registry now has additional direct unit coverage.

  • Fast synthetic imported-workflow tests exercise the imported field/database bridge and NTX-to-NEOPAX scan owner without rerunning expensive boundary/equilibrium artifacts in every shard.

  • A fast owned-surface physics gate now checks D11, D31, D33, Onsager residual, and coarse-to-fine angular-grid transfer on the analytic Boozer surface.

  • The committed monoenergetic validation-summary artifact is now a physics gate: the maximum finest plotted N_\xi convergence error over the DKES-style and VMEC surfaces must stay below 2.5e-1, and the example test checks the plotted convergence ladder.

  • A symmetric-limit physics gate now checks zero radial transport and the inverse-collisionality Spitzer parallel-conductivity normalization on a constant-field Boozer surface.

  • A Boozer-coordinate normalization gate now checks J B^2 = B_zeta + iota B_theta, B^theta J = iota, and B^zeta J = 1 on the owned analytic surface before solver coefficients are interpreted.

  • A finite Legendre source-projection gate now checks that the magnetic-drift source occupies only the expected k=0 and k=2 rows and that the parallel-conductivity source occupies only the physical-B k=1 row.

  • A small owned-surface monoenergetic ladder now checks that D11/D31/D13/D33/D33_spitzer move toward the finest small-grid reference as angular and Legendre resolution are increased.

  • A derivative-consistency gate now checks that the hand-coded dD_k/dnu_hat and dD_k/depsi_hat blocks used by the implicit-adjoint path match JAX differentiation of the assembled Legendre-space operator.

  • A profile-control linear-response gate now checks that scalar and radial-basis controls preserve the zero-control identity and exactly follow their prescribed response matrices before profile optimization and UQ workflows use them.

  • A VMEC-JAX boundary-edge transfer gate now checks that traced fixed-boundary Fourier edge arrays are passed into both implicit and explicit equilibrium paths before any boundary-to-output derivative claim is interpreted.

  • A VMEC-JAX to NEOPAX radial-metric transfer gate checks the imported rho = sqrt(s) mesh, axis regularization, volume scale, edge-radius scale, and toroidal-flux normalization before bootstrap-current derivative workflows consume the field.

  • The prepared derivative-path artifact is now a physics gate: the committed custom-VJP derivative path must stay within 1e-4 relative mismatch of direct reverse-mode, while speedup stays a reported performance metric.

  • The committed derivative-geometry artifacts are now physics gates: owned analytic geometry controls, file-backed Boozer/VMEC controls, boundary-projected current derivatives, and explicit-relaxed QA/QH boundary-to-current derivatives must stay within their artifact thresholds. The implicit-equilibrium derivative artifact remains a monitored non-shipping diagnostic because residual contraction and Boozer-space/NTX transport tangent parity still fail.

  • python scripts/test_lane_manifest.py --check passes with split core lanes, 8 integration examples, and 18 opt-in heavy example tests.

  • CI test-shard jobs are bounded by a ten-minute timeout, and subprocess-based parallel smoke tests have explicit subprocess timeouts to prevent silent workflow stalls.

  • The device-parallel profiling script now exposes explicit smoke-profile controls, and CI uses --num-cases 2 --grid 5,5,4 to check serial/device-parallel agreement without rerunning the full profiling workload.

  • python scripts/build_benchmark_matrix.py reports every active benchmark gate complete and keeps the broader geometry/autodiff breadth lanes planned.

  • python -m ruff check ., python -m mypy src/ntx, documentation build, manuscript-artifact build, package build, and twine check pass locally.

  • A clean-venv wheel smoke test passes for ntx --help, python -m ntx --help, and importing GridSpec.

  • Public package metadata no longer exposes Git direct references; optional geometry-coupled workflows document direct upstream installs until those packages are available from standard package indexes.

  • The flat public API remains supported, and namespace-import tests now also require the top-level export list to stay duplicate-free.

  • The repository-side PyPI Trusted Publishing job is present and tag-gated, the GitHub pypi environment exists, and PyPI has a trusted-publisher entry for uwplasma/NTX using release.yml. The v0.2.0 tag release published to PyPI successfully on 2026-04-24.

  • The fixed-field NTX+NEOPAX lane is explicitly scoped as a total-current stress gate. The release claim is the positive W7-X integrated transfer, the fixed-field Redl/SFINCS gate, and the fixed-field NTX+NEOPAX total-current stress result below 1e-1; species-current parity and broader closure transfer remain future work.

  • Manuscript claim artifacts now include the monoenergetic validation-summary convergence gate, the fixed-field Redl/SFINCS gate, and the scoped fixed-field NTX+NEOPAX total-current stress gate, so paper-facing claims match the active physics gates.

  • The finite-beta QA closure lane now has explicit physics-gate separation: same-grid coefficient normalization is a passing gate, while the profile-current observable and species-cancellation scale remain monitored stress diagnostics until same-grid profile-current closure comparisons pass.

  • The finite-beta current-conditioning sidecar now records the stricter coefficient precision needed by the cancellation-dominated net-current observable. The current smoke ladder is still looser than the 1e-1 current-conditioned target. The first production stress-radius rerun and tight-harmonic probe leave the coefficient floor near 2.05e-2; the production six-point radius/collisionality ladder keeps all coefficient differences below 2.07e-2. The corrected Boozer-field path evaluates B00 on normalized radius and converts dB00/d rho with the VMEC minor radius. The closure-quadrature sidecar has zero accepted current-gate passes. The source-channel sidecar reconstructs the same corrected current to roundoff from one-channel solves and localizes the high-order response to mixed density/electric and temperature-gradient drives under the current profile contract. The profile-response sidecar extends that measurement over all committed profile radii and records the response multiplier against Redl collisionality and geometry drivers. The closure-target sidecar now ranks those drivers and records epsilon as the strongest single profile response driver without applying any runtime correction. The radial-interpolation sidecar rebuilds the same database on the exact field radii but the full-profile maximum remains above the 1e-1 current gate. The next required step is a quadrature-converged profile-current/source-response closure on the same finite-beta contract before any finite-beta parity promotion.

  • The finite-beta RHSMode=1 SFINCS-JAX profile-current diagnostic now runs on the same owned VMEC/profile contract as the Redl and NTX+NEOPAX stress audit. The optimized SFINCS-JAX 1.1.0 main-branch refresh completes the three-radius smoke artifact and a 17 x 21 x 12, Nx=5 inner-radius HDF5 output on local CPU. The high-Nxi even/odd pitch-resolution gap is accepted at 1.32e-1 under the 1.5e-1 reduced-closure stress tolerance. The full-collision branch remains a non-shipping feasibility diagnostic.

  • The field-radius-matched source-channel sidecar now repeats the physical RHS decomposition after removing the sparse radial interpolation layer. It reconstructs the corrected current to roundoff and keeps the quadrature-stable X=18, P=18 result as a reduced-closure stress diagnostic.

  • The differentiable bootstrap-current optimization figure is now represented in the benchmark matrix and physics-gate registry as a monitored stress gate: the committed weighted-current gain must stay above the baseline before the manuscript cites that science-case number.

  • The publication figure manifest now includes the file-backed geometry-control derivative audit, and the boundary-forward derivative audit is explicitly marked as a manuscript figure in the benchmark matrix.

  • The geometry-family breadth summary now reads committed analytic, file-backed, boundary-projected, explicit-relaxed, and implicit-equilibrium derivative artifacts into a single publication-ready stress figure; broad W7-X/QI/omnigenous validation remains scoped as future work.

  • The fixed-field closure report is now included in the publication figure manifest and traced back to the fixed-field Redl gate plus the scoped NTX+NEOPAX total-current stress gate in the benchmark matrix.

  • The source-code map is now guarded by a focused test, so future internal ownership splits must update the architecture documentation and CI lane manifest in the same change.

  • The current refactoring pass split bootstrap-current autodiff workflows into common, deterministic, and robust modules, and split profile dataclasses into species, ambipolar-result, control, and transport-result ownership modules while preserving the flat public API and compatibility facades.

  • The current source-ownership pass also split artifact-gate scalar evaluation from finite-beta artifact-gate ownership, finite-beta artifact-gate definitions from the general artifact registry, finite-beta geometry-breadth metadata from the general geometry benchmark matrix, and TOML-run orchestration from suffix-selected NetCDF/NPZ/HDF5 output writing while preserving the public ntx.inputfiles and top-level exports.

  • The current repo-hygiene pass verified every untracked source/artifact file against docs, tests, or benchmark metadata and removed local cache directories.

  • The next valuable coverage work should be opportunistic and physics-driven; coverage is no longer a blocking lane.

  • The expensive boundary/equilibrium artifact reruns remain opt-in through NTX_RUN_HEAVY_BOUNDARY_EXAMPLES=1.

  • The prepared-geometry reuse profile is now a performance software gate: the compiled prepared steady path must remain coefficient-consistent with direct solves, while speedup stays a measured performance claim.

Immediate Next Order

  1. Keep the CI lane manifest and benchmark matrix locked as new tests are added.

  2. Expand owned geometry-family benchmark artifacts only from committed scripts/tests/docs.

  3. Keep release documentation synchronized with the published package state and require green tests, package, and release workflows before the next tag.