examples: adjoint boundary sensitivities + SIMSOPT analytic gradient

.github/actions/run-benchmarks/action.yml

@@ -118,7 +118,7 @@ runs:
         for target in "${TARGETS[@]}"; do
           name="${target##*:}"
           bazel run --config=perf -- "${target}" \
-            --benchmark_min_time=0.2s \
+            --benchmark_min_time=1.0s \
             --benchmark_format=json \
             --benchmark_out="${TMP_DIR}/${name}.json"
         done

.github/workflows/docs.yaml

@@ -66,6 +66,9 @@ jobs:
         uses: actions/upload-pages-artifact@v3
         with:
           path: 'html_docs'
+          name: 'github-pages-${{ github.run_attempt }}'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+        with:
+          artifact_name: 'github-pages-${{ github.run_attempt }}'

.github/workflows/full_validation.yaml

@@ -1,12 +1,17 @@
-name: Full V&V against reference VMEC
+name: V&V against reference VMEC
 
-# Runs the full Verification & Validation suite from proximafusion/vmecpp-validation
-# (all ~219 input configurations against reference Fortran VMEC2000), using the
-# vmecpp version built from this commit rather than the version pinned on PyPI/GitHub.
-# This is a lot more exhaustive (and slower) than the "short" validation that
-# vmecpp-validation itself runs on its own PRs, so it is not run on every push here.
+# Runs the Verification & Validation suite from proximafusion/vmecpp-validation
+# against reference Fortran VMEC2000, using the vmecpp version built from this
+# commit rather than the version pinned on PyPI/GitHub.
+#
+# - On every push to main: a short run (a handful of configs, a few minutes)
+#   so regressions are caught immediately.
+# - On release and on manual request: the full run (all ~219 configurations,
+#   ~8h) -- too expensive to run on every push.
 on:
   workflow_dispatch:
+  release:
+    types: [published]
   push:
     branches:
       - main
@@ -16,11 +21,12 @@ concurrency:
   cancel-in-progress: ${{ github.ref_name != 'main' }}
 
 jobs:
-  full-validation:
-    name: Run full VMEC++ validation
+  validation:
+    name: Run VMEC++ validation
     runs-on: ubuntu-22.04
     # The full parameter scan runs ~219 configurations, each computing a reference
     # wout with Fortran VMEC2000 in Docker plus one with VMEC++: budget generously.
+    # The short run finishes in minutes and won't come close to this limit.
     timeout-minutes: 360
     steps:
       - name: Check out VMEC++
@@ -57,7 +63,13 @@ jobs:
       - name: Install VMEC++ from this commit
         run: python -m pip install ./vmecpp
 
+      - name: Run short validation
+        if: github.event_name == 'push'
+        working-directory: vmecpp-validation
+        run: python validate_vmec.py --short
+
       - name: Run full validation
+        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
         working-directory: vmecpp-validation
         run: python validate_vmec.py
 
@@ -68,3 +80,32 @@ jobs:
           name: vnvresults
           path: vmecpp-validation/vnvresults_*/
           retention-days: 30
+
+  free-boundary-quasr:
+    name: Run QUASR free-boundary tests
+    runs-on: ubuntu-22.04
+    timeout-minutes: 240
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+      - name: Install required packages for Ubuntu
+        run: |
+          sudo apt-get update && sudo apt-get install -y \
+            build-essential cmake libnetcdf-dev liblapack-dev liblapacke-dev libopenmpi-dev \
+            libomp-dev libeigen3-dev nlohmann-json3-dev libhdf5-dev
+      - name: Install package
+        run: python -m pip install -v .[test]
+      - name: Run slow QUASR free-boundary tests
+        run: python -m pytest -m slow tests/test_free_boundary_quasr.py -v -ra
+      - name: Upload QUASR free-boundary artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: quasr-free-boundary-out
+          path: quasr_free_boundary_out/
+          retention-days: 30

.github/workflows/pypi_publish.yml

@@ -73,7 +73,7 @@ jobs:
             "ubuntu:22.04",
             "archlinux/archlinux",
             "debian:12",
-            "debian:testing-20250224",
+            # "debian:testing-20250224", # TODO(jurasic): re-enable when 3.14 support unblocked
             "fedora:41",
           ]
     runs-on: ubuntu-24.04

.gitignore

@@ -17,3 +17,7 @@ bazel-*
 src/vmecpp/cpp/_vmecpp.so
 
 wout_solovev.nc
+
+# generated by tests/test_free_boundary_quasr.py / examples/free_boundary_quasr_cross_sections.py
+tests/data/quasr/coils.quasr*
+quasr_free_boundary_out/

.pre-commit-config.yaml

@@ -21,11 +21,14 @@ repos:
       - id: check-yaml
       - id: debug-statements
       - id: end-of-file-fixer
+        exclude: '^tests/data/quasr/.*\.json$'
       - id: mixed-line-ending
+        exclude: '^tests/data/quasr/.*\.json$'
       - id: name-tests-test
         args: ["--pytest-test-first"]
       - id: requirements-txt-fixer
       - id: trailing-whitespace
+        exclude: '^tests/data/quasr/.*\.json$'
   - repo: https://github.com/pre-commit/mirrors-clang-format
     rev: v20.1.0
     hooks:

README.md

@@ -99,7 +99,7 @@ print(vmec_output.mercier.iota)
 vmec_output.wout.save("wout_w7x.nc")
 ```
 
-All other output files are accessible via members of the `output` object called `threed1_volumetrics`, `jxbout` and `mercier`.
+All other output files are accessible via members of the `vmec_output` object called `threed1_volumetrics`, `jxbout` and `mercier`.
 
 ### With SIMSOPT
 
@@ -152,7 +152,7 @@ Ubuntu 22.04 and 24.04, as well as Debian 12 are officially supported.
 
 1. Install required system packages:
 ```shell
-sudo apt-get install -y build-essential cmake libnetcdf-dev liblapack-dev libomp-dev libhdf5-dev python3-dev
+sudo apt-get install -y build-essential cmake gfortran libnetcdf-dev liblapack-dev libomp-dev libhdf5-dev python3-dev
 ```
 
 2. Install VMEC++ as a Python package (possibly after creating a dedicated virtual environment):
@@ -279,24 +279,24 @@ VMEC++ on a configuration that is very similar to the converged equilibrium.
 ```python
 import vmecpp
 
-input = vmecpp.VmecInput.from_file("w7x.json")
+vmec_input = vmecpp.VmecInput.from_file("w7x.json")
 
 # Base run
-output = vmecpp.run(input)
+vmec_output = vmecpp.run(vmec_input)
 
 # Now let's perturb the plasma boundary a little bit...
-input.rbc[0, 0] *= 0.8
-input.rbc[1, 0] *= 1.2
+vmec_input.rbc[0, 0] *= 0.8
+vmec_input.rbc[1, 0] *= 1.2
 # ...and fix up the multigrid steps: hot-restarted runs only allow a single step
-input.ns_array = input.ns_array[-1:]
-input.ftol_array = input.ftol_array[-1:]
-input.niter_array = input.niter_array[-1:]
+vmec_input.ns_array = vmec_input.ns_array[-1:]
+vmec_input.ftol_array = vmec_input.ftol_array[-1:]
+vmec_input.niter_array = vmec_input.niter_array[-1:]
 
 # We can now run with hot restart:
-# passing the previously obtained output ensures that
+# passing the previously obtained vmec_output ensures that
 # the run starts already close to the equilibrium, so it will take
 # very few iterations to converge this time!
-hot_restarted_output = vmecpp.run(input, restart_from=output)
+hot_restarted_output = vmecpp.run(vmec_input, restart_from=vmec_output)
 ```
 
 ## Full tests and validation against the reference Fortran VMEC v8.52
@@ -328,7 +328,7 @@ VMEC++:
 - supports inputs in the classic INDATA format as well as simpler-to-parse JSON files; it is also simple to construct input objects programmatically in Python
 - employs the same parallelization strategy as Fortran VMEC, but VMEC++ leverages OpenMP for a multi-thread implementation rather than Fortran VMEC's MPI parallelization: as a consequence it cannot parallelize over multiple nodes
 - Uses FFT kernels optimized for small mode numbers [generated using FFTX](https://github.com/spiral-software/fftx) instead of DFT for supported resolutions. They give a 10-20% speedup relative to the DFT counterparts.
-- implements the iteration algorithm of Fortran VMEC 8.52, which sometimes has different convergence behavior from (PAR)VMEC 9.0: some configurations might converge with VMEC++ and not with (PAR)VMEC 9.0, and vice versa
+- implements the iteration algorithm of Fortran VMEC 8.52, which sometimes has different convergence behavior from (PAR)VMEC 9.0: some configurations might converge with VMEC++ and not with (PAR)VMEC 9.0, and vice versa. One deliberate exception: at multigrid grid transitions, the rollback backup of the state vector is taken *after* the radial interpolation of the coarse-grid solution (matching PARVMEC/VMEC2000 since 2017-01-24, "SPH 012417"), not before it as in VMEC 8.52 -- with the 8.52 ordering, the first restart of a stage silently discards the interpolated state and the finer stages effectively re-solve from a cold start
 
 ### Limitations with respect to the Fortran implementations
 - non-stellarator-symmetric terms (`lasym == true`) are not supported yet

benchmarks/test_benchmarks.py

@@ -10,7 +10,10 @@
 
 import subprocess
 import sys
+from collections.abc import Callable
+from importlib import import_module
 from pathlib import Path
+from typing import Any, cast
 
 import pytest
 
@@ -19,6 +22,7 @@
 REPO_ROOT = Path(__file__).parent.parent
 TEST_DATA_DIR = REPO_ROOT / "src" / "vmecpp" / "cpp" / "vmecpp" / "test_data"
 EXAMPLES_DATA_DIR = REPO_ROOT / "examples" / "data"
+sys.path.insert(0, str(EXAMPLES_DATA_DIR.parent))
 
 
 # ---------------------------------------------------------------------------
@@ -165,3 +169,37 @@ def test_bench_free_boundary(benchmark, free_boundary_input, response_table):
         warmup_rounds=1,
     )
     assert result.wout.volume == pytest.approx(0.3075, rel=1e-3)
+
+
+# ---------------------------------------------------------------------------
+# SIMSOPT adjoint gradient benchmarks
+# ---------------------------------------------------------------------------
+
+
+def _gradient_cost(*, analytic):
+    module = import_module("simsopt_vmec_gradient")
+    gradient_cost = cast(Callable[..., Any], module.gradient_cost)
+
+    return gradient_cost(analytic=analytic)
+
+
+def test_bench_simsopt_adjoint_gradient(benchmark):
+    """Track the analytic adjoint gradient cost without timing assertions."""
+    result = benchmark.pedantic(
+        _gradient_cost,
+        kwargs={"analytic": True},
+        rounds=1,
+        warmup_rounds=0,
+    )
+    assert result.force_evals > 0
+
+
+def test_bench_simsopt_finite_difference_gradient(benchmark):
+    """Track the finite-difference reference cost for comparison."""
+    result = benchmark.pedantic(
+        _gradient_cost,
+        kwargs={"analytic": False},
+        rounds=1,
+        warmup_rounds=0,
+    )
+    assert result.force_evals > 0

docs/api/vmecpp.rst

@@ -0,0 +1,15 @@
+vmecpp package
+==============
+
+.. automodule:: vmecpp
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   vmecpp.simsopt_compat

docs/api/vmecpp.simsopt_compat.rst

@@ -0,0 +1,7 @@
+vmecpp.simsopt\_compat module
+=============================
+
+.. automodule:: vmecpp.simsopt_compat
+   :members:
+   :show-inheritance:
+   :undoc-members:

examples/data/README.md

@@ -1,13 +1,13 @@
 # Example input and output files for VMEC++
 
-A few cases are available for testing VMCE++ and experimenting with it:
+A few cases are available for testing VMEC++ and experimenting with it:
 
 1. `cth_like_fixed_bdy.json` - Stellarator case, similar to the Compact Toroidal Hybrid ([CTH](https://www.auburn.edu/cosam/departments/physics/research/plasma_physics/compact_toroidal_hybrid/index.htm)) device
    1. `input.cth_like_fixed_bdy` - Fortran namelist input file to be used with Fortran VMEC
    1. `cth_like_fixed_bdy.json` - JSON input file for VMEC++, derived from `input.cth_like_fixed_bdy` using [`indata2json`](https://github.com/jonathanschilling/indata2json)
    1. `wout_cth_like_fixed_bdy.nc` - NetCDF output file, produced using [`PARVMEC`](https://github.com/ORNL-Fusion/PARVMEC) from `input.cth_like_fixed_bdy`, for testing the loading of a `wout` file using VMEC++'s tooling
 
-1. `input.nfp4_QH_warm_start` - quasi-helically example for use with SIMSOPT
+1. `input.nfp4_QH_warm_start` - quasi-helical example for use with SIMSOPT
 
 1. `solovev` - axisymmetric Tokamak case, similar to the Solov'ev equilibrium used in the [1983 Hirshman & Whitson article](https://doi.org/10.1063/1.864116)
     1. `input.solovev` - Fortran namelist input file for use with Fortran VMEC