VMEX 0.3.0

VMEX 0.3.0

Differentiable, JAX-native VMEC. This release extends the vmex.mirror open/closed magnetic-mirror lane with two new hybrid geometries, promotes the axisymmetric free-boundary mirror to 50 % β, and clears a batch of pre-release QA issues.

Added

• QI–mirror hybrid (Fourier vs B-spline). vmex.mirror.splice_straight_legs cuts a closed magnetic axis at its curvature minima and splices in exactly-straight mirror legs; build_qi_mirror_hybrid returns a solvable setup. The new examples/qi_mirror_hybrid_fourier_vs_bspline.py cuts the nfp = 2 QI axis at its zero-curvature symmetry planes and compares the two axis representations: a global Fourier series rings at the straight↔curved seam and decays only ~1/N, while the local B-spline reproduces the straight mirror cell to machine precision (~1e-12).
• Toroidally rotating ellipse for the stellarator–mirror hybrid. A new section_turns parameter continuously rotates the elliptical cross-section around the closed circuit while the legs keep an exactly straight axis. Two turns lift the traced transform from iota = 0.085 to iota = 0.141 at s = 0.75. section_turns = 0 reproduces the prior geometry exactly. (The rotating-elliptical-section hybrid remains a research candidate — it passes the minor-radius bulk gate but its device-normalized strong force still plateaus on a scoped near-axis defect; the circular-section hybrid is supported.)

Changed

• Axisymmetric free-boundary mirror validated through 50 % β (was 25 %). A size-scaled Krylov span in the Newton-GMRES polish clears the fine-grid restart starvation; on the (ns, nxi, elements, ntheta) = (13, 25, 13, 24) grid every β point from 0 through 50 % converges (≤ 44 Newton-GMRES iterations) with bulk minor-radius force 1.21e-4 → 2.41e-3, far below the 0.05 promotion gate.
• CI timeout headroom for the borderline parity (25 → 35 min) and implicit-gradient (10 → 15 min) jobs.

Fixed

• ESSOS Coils.from_json — track the ESSOS rename (removed Coils_from_json); the --coils CLI path and the two ESSOS coil examples now use the classmethod with a legacy fallback.
• ESSOS Coils.to_mgrid guard — clear VmecInputError instead of an opaque AttributeError on older ESSOS builds.
• tools/fetch_assets.py — repointed at the real vmec_jax_*.tar.gz fixture bundles (the vmex_* names 404-ed).
• Stale lasym-rejection test + docstrings — the implicit lane has supported FD-validated lasym since the 4-family boundary map + traceable readin.f delta rotation landed; retired the obsolete rejection test and corrected the docstrings.

Full changelog: https://github.com/uwplasma/vmex/blob/main/CHANGELOG.md

VMEX 0.2.0

First release under the VMEX name (formerly vmec-jax).

Install: pip install vmex · Docs: https://vmex.readthedocs.io

Highlights

• Renamed vmec_jax → vmex — import vmex, vmex CLI (with vmec alias), and a vmec_jax import shim (DeprecationWarning) for one release. VMEC file conventions (wout_*.nc, boozmn_*.nc, Vmec* classes) unchanged.
• vmex.mirror — open and closed magnetic-mirror equilibria (differentiable, spline-native): fixed-boundary open mirrors (divergence 6.6e-15), free-boundary β scan 0–10% (implicit gradient 1.1e-10 vs reconverged FD), one-call solve_fixed_boundary_from_radius.
• vmex.parallel — concurrent ensembles of independent solves (bit-identical to serial, ~3.3× at 8 workers).
• Optimization — traceable l_grad_b objective and a five-campaign objectives showcase; cold-start single-stage plasma+coil benchmark (vacuum + finite β).
• Speed — NESTOR free-boundary loop fused into jitted lanes; warm solves now beat VMEC2000 on every benchmark row.
• Robustness — typed VmecErrors propagate through the jax.pure_callback boundary; ruff+mypy lint gate in CI.

See CHANGELOG.md for the full list.

v0.1.0

vmec-jax v0.1.0

First 0.1 milestone: a research-grade, differentiable JAX implementation of VMEC,
with VMEC2000 scalar parity and an end-to-end differentiable free boundary.

Highlights

• Differentiable equilibria. Fixed-boundary gradients via the implicit-function-theorem
  adjoint (finite-difference validated to ~1e-6 relative); free-boundary gradients via
  virtual casing.
• True single-stage optimization (new). The free-boundary B·n residual is now
  differentiable in the plasma boundary as well as the coils, so a single
  jax.value_and_grad co-optimizes boundary shape and coils simultaneously — the
  gradient threads through the implicit adjoint (boundary) and virtual casing (coils) at
  once. See examples/single_stage_simultaneous_opt.py.
• Multigrid solver with VMEC2000 scalar parity (energies, aspect ratio, beta, iota,
  pressure, boundary shape), checked in-repo via lightweight golden digests.
• Optimization. QA / QH / QP / QI targets; ESS spectral scaling (single-call, no
  max-mode continuation loop); block-tridiagonal implicit Jacobian; perturbation warm-start
  (3.7× fewer solver iterations).
• Physics. Redl bootstrap current with a self-consistency loop; ballooning stability
  (COBRA); omnigenity / QI residual; gyrokinetic turbulence proxies; a built-in Boozer
  transform.
• Performance. CPU and GPU; persistent XLA compilation cache (on by default);
  memory controls (remat / chunking / donation). Warm fixed-boundary solves are sub-0.1 s.
• Engineering. < 10 MB repo, ~95 % test coverage, SOLVAX-backed structured linear
  algebra, sharded CI, VMEC2000 parity without stored large wout files.

Install

pip install vmec-jax          # PyPI (recommended)
conda install -c conda-forge vmec-jax

Notes

• Free-boundary / virtual-casing features need the optional virtual_casing_jax dependency.
• Python 3.10–3.12.

Golden VMEC2000 parity fixtures v1

VMEC2000 (STELLOPT 9.0, xvmec2000) reference outputs — stdout, threed1, wout_*.nc, timings — for 9 benchmark decks (incl. lasym fixed-boundary and lasym free-boundary). Used by the parity test suite via the fetch helper. sha256: 85b1de372066d1dd0c57b1a9ffb569ccc1276bb67dec81e7bf15a5a943ca05d7

vmec-jax v0.0.18

Highlights

• Retuned the public QA/QH/QP optimization accepted/trial VMEC budgets to reduce default optimization wall time while keeping stricter audit settings documented.
• Preserved compact inactive asymmetric scan velocity state when resuming old fixed-boundary scan payloads, avoiding unnecessary graph and memory expansion.
• Added bounded QI budget-smoke provenance to the research-grade performance/differentiability plan.

Validation

• Ruff and diff checks passed locally for the release bump.
• Focused optimization/scan tests and Sphinx docs passed on the preceding code commits.
• GitHub CI is expected to publish to PyPI from this release.

vmec-jax v0.0.17

Highlights

• Refresh QS optimization budget probe controls for optimizer method, trial-scan policy, SciPy trust-region settings, and target-helicity seed testing.
• Make the QA standalone optimization visibly apply the reviewed target-helicity mode-1 seed so short budget probes escape the zero-transform branch.
• Update optimization documentation and tests to describe the visible seed-conditioning policy and budget-probe knobs.

Validation

• python -m ruff check tools/diagnostics/qs_budget_probe.py examples/optimization/QA_optimization.py tests/test_optimization_examples.py
• JAX_ENABLE_X64=1 python -m pytest -q tests/test_optimization_examples.py -q
• LANG=C.UTF-8 LC_ALL=C.UTF-8 python -m sphinx -W -j auto -b html docs docs/_build/html_release_v0017

vmec-jax v0.0.16

Highlights

• Added compact VMEC2000-style scan runtime controls so fixed-boundary scan runners carry the iteration sequence compactly while FTOL and residual target remain scalar runtime operands.
• Added profile-guided fixed-boundary scan policy documentation and provenance for current-vs-main benchmark threshold classifications.
• Included the recent branch-local free-boundary derivative and coil-optimization validation work from post-v0.0.15 development.
• Kept repository size gates, docs gates, source-health gates, and CI coverage shards aligned for release.

Validation

• Local scan-focused tests: 60 passed.
• Local broader affected slice: 304 passed, 2 warnings.
• Local docs build with warnings as errors: passed.
• Local wheel/sdist build for 0.0.16: passed.
• Local repository size gate: 27.64 MiB tracked, largest tracked file <2 MiB.
• GitHub Actions CI for commit da0c1a31 was running with completed docs/build/smoke/core shards green when this release was created.

Notes

This release is intended as the current public checkpoint for the fixed-boundary performance tranche, branch-local free-boundary derivative work, and release-hygiene updates. Full arbitrary adaptive-branch free-boundary differentiation remains explicitly conservative in the documentation and plan.

vmec-jax v0.0.15

User-visible changes:

• Adds and documents the direct-coil/free-boundary ESSOS lane for single-stage coil-aware workflows.
• Promotes branch-local direct-coil free-boundary derivative validation, including fixed accepted/rejected controller-slot gates and coil-only QS proposal examples with complete solves as acceptance authority.
• Adds the QI minimal-seed NFP1/2/3/4 README panel and lightweight provenance artifacts.
• Improves beginner installation diagnostics, release hygiene, repository-size hygiene, and required CI coverage/runtime splitting.
• Includes Glasser resistive stability diagnostics and Mercier/Glasser derivative validation gates added since v0.0.14.

Validation:

• Local release gate passed with 2793 passed, 23 skipped, 116 deselected, 2 xfailed, and 95.25% coverage at the enforced 95% gate.
• GitHub Actions CI for release-candidate commit 55dde90 passed: console smoke, physics smoke, Python 3.10/3.12 fast tests, py3.11 core/exact/slow-physics coverage shards, docs, wheel/sdist build, parity manifest smoke, and combined coverage gate.
• Bounded VMEC2000 executable gates passed locally for the fast stage trace and LASYM free-boundary smoke rows.

Known limitations:

• Direct-coil free-boundary fields, mgrid interpolation, accepted-boundary replay, and same-branch/fingerprint-gated physical-scalar/vector gates are validated.
• The production adaptive host-controller branch selection is not claimed as fully differentiable through arbitrary branch changes in this release.
• Coil-only QS examples use branch-local derivative proposals and retain complete VMEC solves as the acceptance authority.
• Long DIII-D/VMEC2000 parity refreshes remain optional/manual diagnostics rather than required release gates.

vmec-jax v0.0.14

Release v0.0.14.

Highlights:

• vmec_jax --test now copies the bundled quick-start input with FTOL_ARRAY = 1e-12 for a faster first run, then writes WOUT and plots automatically.
• Package metadata includes matplotlib and booz_xform_jax by default, so quick-start plotting and Boozer workflows work after a normal install.
• Exact replay JVP instrumentation documents GPU accepted-point replay path selection and profile evidence.
• Required local release gate passed with fetched WOUT fixtures: 2354 passed, 20 skipped, 110 deselected, 1 xfailed, 95.09% coverage.
• Current WOUT fixture regression constants are aligned with the assets-20260526-wout-fixtures bundle.

vmec_jax optional WOUT fixtures 2026-05-26

Optional generated/reference WOUT fixtures moved out of git. Restore them with: python tools/fetch_assets.py --bundle wout-fixtures