Complete pyQSC_JAX refactor with pyQSC parity and plasma–coil field jets

[rogeriojorge]

Summary

Complete foundational refactor of pyQSC_JAX into an immutable,
autodifferentiable near-axis stellarator library while preserving the ESSOS
pyqsc_jax.near_axis.near_axis contract.

The branch now includes:

• general Fourier-axis geometry and converged implicitly differentiated
  first-order solves;
• complete finite-pressure/current r2, r3 boundary/shear support, field
  gradient/Hessian, Mercier, singular-radius, and Maxwell diagnostics;
• target-iota inverse solves, continuation, dense B20 diagnostics, exact B2c
  elimination, criteria, and branch-aware axis optimization;
• the surface-free plasma/external 3+5+7 field jet from the audited
  derivation, with a mandatory formal radius and asymptotic metadata;
• fast VMEC boundary export with a diagnosed cylindrical-angle inversion;
• an optional differentiable VMEX bridge for radial iota, quasisymmetry,
  magnetic well, energy, volume, and aspect ratio;
• screened public-database stellarators, direct 3D plotting, executable
  examples, publication figures, documentation, CI, and packaging.

Final integration hardening

• VMEC export records its angle-inversion tolerance and convergence state,
  validates finite positive radii, and refuses to write an invalid boundary.
• The VMEX bridge applies the same guard. Concrete failures raise; invalid
  traced candidates receive nonfinite boundary coefficients rather than a
  silently different equilibrium.
• A live finite-pressure, exactly zero-current VMEC regression uses public
  QA database ID 139524, a nonplanar axis with RMS torsion
  1.189 1/m.
• VMEX examples are explicitly opt-in (PYQSC_RUN_VMEX=1), so an installed
  VMEX does not unexpectedly turn the ordinary example matrix into a
  multi-minute equilibrium run.
• Paired ESSOS PR
  uwplasma/ESSOS#46 now uses
  finite-pressure, exactly zero-current database stellarator ID 52521 for
  both stage-two and single-stage demonstrations; I2 is not a single-stage
  design variable.

Screened showcase

The README gallery uses public Wisconsin stellarator-database QA
139524, QH
3, B20-refinement seed
57409, and
large-clearance case
107579.

• QA ID 139524 has helicity zero, |iota| = 0.355, finite pressure,
  exactly I2 = 0, nonzero torsion, and passes the configurable Curvo
  criteria with the requested QA |iota| >= 0.3 gate.
• The other displayed cases pass the same screen with |iota| >= 0.4.
• The staged eight-mode refinement of ID 57409 has
  |iota| = 2.964, r_singularity = 0.249 m, and weighted B20 residual
  1.2743e-10 at nphi=121, stable through nphi=481.
• The finite-beta showcase has finite p2, exactly I2 = 0,
  |iota| = 2.809, RMS torsion 0.979 1/m, and 14.04% angular variation
  in the pressure-driven plasma-field norm.
• The pressure-only plasma contribution at formal radius a = 0.15 m is
  reported honestly as about 0.19%. The former 30% finite-current,
  tokamak-like showcase was removed; current-driven physics remains supported
  and tested, but it is not used in user-facing finite-beta examples.

Validation

• Final PR matrix on dcacea2: all required GitHub checks pass on macOS and
  Ubuntu with Python 3.12/3.14, including docs, package, Codecov, frozen
  contracts, clean ESSOS, and live current-main VMEX. The only skipped job is
  the intentionally schedule/manual-only upstream-head smoke.
• Complete local matrix: 296 passed, with 4 intentional live-integration
  skips; the branch-coverage run measured 98.75% lines and
  95.898% branches.
• VMEC/VMEX-focused matrix: 52 passed, with only the two local-VMEC
  opt-in skips.
• Local VMEC2000: frozen plus vacuum and finite-pressure/zero-current live
  cases pass. The finite-pressure case has signed on-axis-iota error
  0.02143% and maximum force residual 9.97e-12.
• Live VMEX 0.3.0/current-main at commit 2a40d756: 2 passed, covering
  vacuum and finite-beta/zero-current radial iota, QS, magnetic well, and
  implicit boundary/pressure gradients.
• Paired ESSOS slice at da66774: 13 passed, including both optimization
  scripts in clean subprocesses; field, gradient, and Hessian blocks all
  decrease in stage-two and single-stage runs.
• Independent nphi=121 comparison to audited pyQSC commit cd75359:
  maximum scalar delta 8.02e-12, geometry/sigma delta 3.40e-14, and r2
  array delta 1.11e-11.
• Ruff clean; warning-as-error Sphinx HTML and doctest builds pass.
• Wheel and sdist pass twine check; independent clean installs pass physics,
  VMEC-boundary, and pip check smokes.
• Fourteen tutorials and ten publication scripts execute from clean working
  directories; the headline README figures were visually inspected.

Architecture and release state

Core runtime dependencies remain unpinned jax and solvax; plotting and
VMEX are optional. pyQSC_JAX has no ESSOS dependency. The legacy mutable class
is a thin adapter around immutable pytrees, with no import-time JAX
configuration or mutable global physics state.

This remains a draft review PR. TestPyPI/PyPI trusted-publisher setup,
maintainer approval and merge, release-version/date metadata, and Zenodo DOI
creation are external release gates. No release tag is proposed here.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️