Geometry

S-alpha flux-tube model

We start with a simple analytic geometry based on the s-alpha model, which is widely used for Cyclone base case benchmarks. The field-aligned perpendicular wave number is

\[k_x(\theta) = k_{x0} - \left(\hat{s}\,\theta - \alpha \sin\theta \right) k_y,\]

and the metric coefficients are

\[g_{ds2} = 1 + \left(\hat{s}\,\theta - \alpha \sin\theta\right)^2,\quad g_{ds21} = -\hat{s}\left(\hat{s}\,\theta - \alpha \sin\theta\right),\quad g_{ds22} = \hat{s}^2.\]

The perpendicular wave number is then

\[k_\perp^2(\theta) = k_y \left(k_y g_{ds2} + 2 k_x g_{ds21} \right) + k_x^2 g_{ds22},\]

with an additional \(B^{-2}\) factor from the s-alpha magnetic field strength,

\[B(\theta) = \frac{1}{1 + \epsilon \cos\theta}.\]

Parameters

The geometry is specified by:

• q: safety factor

• s_hat: magnetic shear

• epsilon: inverse aspect ratio

• R0: reference major radius

• B0: reference magnetic field

• drift_scale: drift normalization (1.0 is the tracked default; 2.0 selects the alternate doubled-drift convention)

Field-aligned grid parameters

For direct comparison with published Cyclone base case benchmarks, GridConfig exposes field-aligned grid inputs:

• y0 sets the minimum binormal wave number via \(k_y \rho = 1/y_0\). Internally this maps to Ly = 2\pi y0 so that the FFT grid spacing matches.

• ntheta and nperiod (or zp) control the parallel grid. We set \(Z_p = 2\,nperiod-1\) and choose Nz = ntheta * Zp, which spans \([-\pi Z_p, \pi Z_p)\).

Curvature and grad-B drift

The magnetic drift frequency used in the linear operator follows the standard s-alpha form

\[\omega_d(\theta) = k_y \left(\mathcal{C}_v + \mathcal{C}_g\right) + k_x \left(\mathcal{C}_v^0 + \mathcal{C}_g^0\right),\]

with

\[\mathcal{C}_v = \mathcal{C}_g = \frac{\cos\theta + (\hat{s}\,\theta - \alpha \sin\theta)\sin\theta}{R_0}, \qquad \mathcal{C}_v^0 = \mathcal{C}_g^0 = -\frac{\hat{s}\sin\theta}{R_0}.\]

These parameters will be extended to VMEC/DESC geometry once the linear solver is validated against Cyclone benchmarks.

Slab Model

SPECTRAX-GK now also exposes GX’s slab geometry contract directly with geometry.model = "slab". This is the correct backend for GX’s secondary and cETG benchmarks; it is not an s-alpha approximation.

The slab overrides follow the audited GX implementation:

• bmag = 1 and bgrad = 0

• cvdrift = gbdrift = cvdrift0 = gbdrift0 = 0

• gradpar = 1 by default, or 1/z0 when geometry.z0 > 0

• the metric still uses the supplied s_hat unless geometry.zero_shat = true

• with zero_shat = true, the slab metric becomes gds2 = 1, gds21 = 0, gds22 = 1 and the effective solver shear is zero

That contract is now locked by unit tests so future secondary/cETG work is built on the same geometry semantics GX uses. It does not mean both benchmarks are solved already: secondary is a geometry-plus-runtime parity problem, while GX’s cETG benchmark is a dedicated collisional reduced model with its own solver/RHS path. The slab backend is the correct prerequisite for both, but only secondary sits on the generic-runtime parity path today.

Geometry Data Contract

The linear cache now accepts either:

• the analytic SAlphaGeometry model, or

• a sampled FluxTubeGeometryData contract.

FluxTubeGeometryData stores the solver-ready profiles on a specific theta grid:

• bmag and bgrad,

• gradpar,

• metric coefficients (gds2, gds21, gds22),

• curvature / grad-B drift coefficients (cv, gb, cv0, gb0),

• geometry metadata such as q, s_hat, R0, and the kperp2_bmag / bessel_bmag_power switches.

This is the insertion point for future VMEC/DESC or GX-imported field-line geometry. The helper sample_flux_tube_geometry converts the analytic s-alpha model into the same contract, and ensure_flux_tube_geometry_data normalizes analytic and sampled inputs onto one solver-facing representation.

The sampled geometry contract is now a JAX pytree and is accepted by the linear cache, runtime initial-condition builder, RHS assembly entry points, nonlinear config runner, and reference-compatible volume-weight diagnostics. That means upcoming VMEC or imported field-line geometry can be threaded into more of the codebase without rebuilding solver-specific side paths.

The contract also preserves explicit jacobian and grho profiles when they are available from imported geometry. The helper load_gx_geometry_netcdf reads both GX full-output NetCDF files with Geometry/Grids groups and root-level GX eik.nc geometry files from the VMEC workflow. That is the intended short path to the GX W7-X examples: import the sampled field-line geometry first, prove solver/diagnostic parity on that contract, and only then add a native VMEC path that generates the same contract inside SPECTRAX-GK.

Runtime and executable paths can now construct that bridge directly from config with geometry.model = "gx-netcdf" and geometry.geometry_file = "external_geometry.nc". Analytic s-alpha remains the default with geometry.model = "s-alpha". For slab cases use geometry.model = "slab" with optional geometry.z0 and geometry.zero_shat controls. In practice an imported geometry file can be either a GX *.out.nc file or a GX/VMEC-generated *.eik.nc file such as the W7-X examples in the GX benchmark tree. Root-level *.eik.nc files are no longer assumed to be closed-interval grids: the importer now infers whether the terminal theta point is present from the periodic endpoint content of the geometry profiles, so both VMEC-style closed grids and GX Miller’s already-open *.eiknc.nc grids are mapped onto the correct solver contract. For imported geometry, the runtime now also adopts the file’s theta extent, twist-shift jtwist/x0 defaults for both linked and fix aspect boundaries, and kxfac metadata so the flux-tube grid is built from the same field-line domain GX used to generate the file. The same importer is also exposed under the aliases geometry.model = "gx-eik", "vmec-eik", and "desc-eik" so configs can reflect the provenance of a root-level *.eik.nc file without changing the solver-facing geometry contract. The linear KBM benchmark entry point now uses the same geometry builder, so the benchmark audit harness can exercise imported sampled geometry through run_kbm_linear instead of only through the runtime wrappers. Regression coverage now runs that benchmark path explicitly for both "vmec-eik" and "desc-eik" aliases, so imported W7-X-style geometry is checked through both runtime and benchmark entry points. The test suite now locks both root-level contracts explicitly:

• imported VMEC/DESC closed-interval *.eik.nc files must preserve theta_scale/nfp metadata and trim the terminal theta point consistently when mapped onto the solver’s open field-line grid, and

• imported GX Miller *.eiknc.nc files must stay on their already-open theta grid without a spurious terminal-point trim.

With the corrected imported-VMEC contract, that imported-geometry bridge now also reproduces the GX W7-X linear ITG t=2 reference on the same sampled field line over the tracked ky range. The refreshed scan in docs/_static/w7x_linear_t2_scan.csv shows mean relative gamma errors of about 2.3% to 3.5% and mean relative omega errors of about 0.02% to 0.27% across ky = 0.1 through 0.8.

That same imported contract now has a first-class nonlinear runtime workflow: examples/nonlinear/non-axisymmetric/w7x_nonlinear_imported_geometry.py and examples/nonlinear/non-axisymmetric/runtime_w7x_nonlinear_imported_geometry.toml mirror the GX nonlinear W7-X adiabatic-electron setup while keeping the geometry source explicitly tied to a VMEC/DESC *.eik.nc field-line file.

SPECTRAX-GK now also supports a direct VMEC runtime bridge with geometry.model = "vmec". This path uses the existing compatibility helper to produce an imported *.eik.nc file and then re-enters the same imported-geometry contract described above. The bridge is cached by input content and VMEC file timestamp when SPECTRAX chooses the output path itself. If the user supplies an explicit geometry_file target, the runtime now regenerates that file instead of silently reusing whatever stale *.eik.nc may already be present there. That keeps the native JAX geometry contract centered on FluxTubeGeometryData while preserving reproducible imported-geometry workflows. For VMEC fix aspect cases, the bridge now leaves x0 unset when calling GX so the helper chooses the same cut that GX would choose from y0 and the geometry itself. SPECTRAX no longer back-solves x0 = Lx/(2 pi) into the helper input, which was generating the wrong HSX/W7-X *.eik.nc files. When booz_xform_jax is not installed into the active environment, point SPECTRAX at it through BOOZ_XFORM_JAX_PATH or SPECTRAX_BOOZ_XFORM_JAX_PATH. The internal backend is preferred. A legacy booz_xform install is only needed as fallback compatibility for older helper environments. Differentiable VMEC/Boozer transport-gradient audits require a booz_xform_jax checkout at or after upstream commit 1d5e8c. That revision replaces inactive zero-mode Fourier divisions by safe denominators in the JAX Boozer transform so reverse-mode cotangents through w spectrum reconstruction remain finite. Older checkouts can produce finite values but non-finite gradients and must not be used for promoted transport-gradient claims. The first differentiable-geometry bridge is now explicit in spectraxgk.geometry.differentiable. Use discover_differentiable_geometry_backends() to audit optional vmec_jax / booz_xform_jax availability and flux_tube_geometry_from_mapping(...) to validate an in-memory, solver-ready field-line geometry bundle before passing it into the existing FluxTubeGeometryData contract. This is a real contract boundary, not a proxy equilibrium: the upstream differentiable pipeline must still supply the sampled theta, bmag, gradpar, metric, drift, Jacobian, and grho arrays. The bridge is tracer-safe: finite-value checks are kept on host inputs, while JAX-traced arrays can flow through flux_tube_geometry_from_mapping(..., validate_finite=False) so geometry observables, inverse-design objectives, and covariance estimates can be differentiated.

The release validation artifact is generated by:

JAX_ENABLE_X64=1 PYTHONPATH=src \
  python examples/theory_and_demos/differentiable_geometry_bridge.py

It writes docs/_static/differentiable_geometry_bridge.png and docs/_static/differentiable_geometry_bridge.json. The JSON records vmec_jax and booz_xform_jax API availability, autodiff-vs-finite difference sensitivity errors, inverse-design convergence, local UQ covariance diagnostics, and seven optional real-backend derivative gates: a vmec_jax boundary-aspect check, a vmec_jax metric-tensor check through vmec_jax.geom.eval_geom, a stellarator VMEC field-line tensor check through vmec_jax.geom plus vmec_jax.vmec_bcovar, a direct VMEC tensor-derived flux-tube mapping check, a tiny booz_xform_jax Boozer-spectrum check, a bounded Boozer-spectrum-to-flux-tube mapping check, and a real vmec_jax VMECState to booz_xform_jax to SPECTRAX-GK field-line geometry check. The metric-tensor gate currently has max absolute AD-vs-finite-difference error about 5.9e-8 and max relative error about 1.3e-7. The field-line tensor gate uses the non-axisymmetric nfp4_QH_warm_start fixture and checks |B| ripple plus sampled VMEC metric observables before any reduced SPECTRAX-GK metric/drift closure is applied; its current max absolute AD-vs-finite-difference error is about 2.1e-3 and max relative error is about 2.4e-5. The direct VMEC flux-tube gate inverts the sampled VMEC metric tensor, derives gds*, gradpar, Jacobian, grho, and a local grad-\(B\) drift closure, and checks the resulting solver-ready geometry observables; the current max relative AD-vs-finite-difference error is about 1.3e-4 on the nfp4_QH_warm_start fixture. The same artifact now also records a bounded VMEC/EIK array-parity audit for that direct tensor path. That audit currently keeps the full production gate open because the direct tensor path still uses a VMEC-coordinate/equal-theta sampling and local grad-\(B\) closure. The same report now also runs a JAX-native vmec_jax -> booz_xform_jax Boozer equal-arc core audit. On the tracked nfp4_QH_warm_start fixture, that audit matches the imported convention for bmag, the solver Jacobian, gradpar, q, and s_hat with worst normalized/scalar errors 4.5e-3 and 2.4e-3; the derivative-like bgrad check is recorded separately and is 2.3e-2. The same JAX-native path now reconstructs the zero-beta Boozer metric profiles gds2, gds21, gds22, and grho with worst normalized mismatch 3.45e-2 and the loaded-convention zero-beta drift profiles cvdrift, gbdrift, cvdrift0, and gbdrift0 with worst normalized mismatch 3.50e-2. The remaining promotion gap is finite-beta and broader production-runtime drift parity beyond the tracked zero-beta equal-arc fixtures, not the Boozer equal-arc field-line or zero-beta metric/drift normalization on the tracked fixture. The Boozer gates evaluate the JAX-native Boozer |B| spectrum along a field line, build the FluxTubeGeometryData input mapping, and compare geometry-observable sensitivities against central finite differences. In the current artifact the VMEC-state path has max absolute AD-vs-finite-difference error about 5.8e-7 and max relative error about 1.4e-8 for the tracked geometry observables.

The reusable API entry point for this workflow is geometry_inverse_design_report(mapping_fn, initial_params, target_observables, ...): it runs a bounded Gauss-Newton inverse design on selected solver-ready geometry observables, checks the final sensitivity Jacobian against central finite differences, and records local covariance diagnostics. High-fidelity vmec_jax / booz_xform_jax optimization examples should use the same contract once their in-memory field-line mapping is available.

The bridge validates more than array shapes. Host-side mappings must contain finite scalar metadata such as q, R0, B0, and theta_scale, must provide at least one theta sample, and must use a positive integer nfp. JAX-traced mappings can still be passed with validate_finite=False so autodiff transforms do not attempt host NumPy checks during tracing. The finite-difference utilities used by these gates also reject non-positive step sizes, and the inverse-design covariance block records rank and conditioning before any optimization result is promoted from local sensitivity evidence to a transport-design claim. Each geometry AD/finite-difference gate now also records a compact conditioning block alongside the raw Jacobians. That block includes finite flags for the AD and finite-difference Jacobians, singular values, numerical rank, condition number, AD row/column norms, per-parameter finite-difference step scaling, and the observable/parameter location of the worst absolute and relative AD/FD mismatch. This metadata is intentionally separate from the pass tolerance: a derivative can agree with finite differences and still be a poor optimization direction if the sensitivity map is nearly rank deficient or if the finite-difference step is not well scaled to the chosen VMEC coefficient. Research artifacts should quote both the derivative error and this conditioning metadata before treating a VMEC/Boozer bridge row as optimization-ready.

Growth-rate transport-gradient audits also need an eigenbranch-locality check. The public helper solver_linear_operator_matrix_from_geometry(geometry, ...) materializes the same SPECTRAX-GK linear operator used by solver_growth_rate_from_geometry(...). The report vmec_jax_transport_growth_branch_locality_report_from_states(base, plus, minus, ...) then compares the dominant-growth finite-difference slope against the slope of the eigenvalue nearest to the base dominant eigenvalue for every configured surface, field line, and k_y sample. If the independently selected max-growth branch switches, or if the base branch is under-isolated, the report fails closed and labels the row before any transport-gradient optimization claim is admitted. The boundary-chain executable exposes the same check via:

PYTHONPATH=src:tools:$VMEC_JAX_ROOT \
  python tools/probe_vmec_jax_boundary_chain.py \
    --input path/to/input.final \
    --out-json tools_out/vmec_boundary_chain_probe.json \
    --index 28 --step 2e-5 \
    --transport-kind growth \
    --include-growth-branch-locality

This branch-locality block is a diagnostic admission gate. Passing it does not by itself promote nonlinear turbulent-flux optimization; it only says that the linear growth finite-difference stencil is measuring the local branch assumed by the implicit left/right eigenvalue derivative. When this block is present in a boundary-chain probe, build_boundary_chain_collection_summary(...) carries growth_branch_locality_checked, growth_branch_locality_passed, and the branch-locality classification into each collection row. The projected-update policy still fails closed on the stricter VMEC exact-FD/frozen-axis consistency gate; branch locality only localizes the failure mechanism and prevents a VMEC-convention issue from being misdiagnosed as a SPECTRAX eigenbranch switch. For projected transport line searches, boundary_chain_accepted_parameter_indices and projected_line_search_input_manifest accept require_growth_branch_locality=True to exclude any coefficient whose explicit branch-locality check is missing or failed. The default remains backward compatible because older boundary-chain collections did not contain this optional block. Assemble several probe JSON files into the collection consumed by the projected writer with:

python tools/build_vmec_jax_boundary_chain_collection.py \
  --probe-json tools_out/latest_vmec_stack/boundary_chain_zs13_h2e5_branch_locality.json \
               tools_out/latest_vmec_stack/boundary_chain_rc14_h2e5_branch_locality.json \
  --out-json tools_out/latest_vmec_stack/boundary_chain_growth_collection.json

The reusable low-level entry point is observable_gradient_validation_report(observable_fn, params, ...). It flattens arbitrary geometry or objective observables, compares JAX AD Jacobians with central finite differences, records absolute and relative error tables, checks a tangent direction, adds finite flags, and applies an explicit rank/condition-number gate. Its payload is strict JSON compatible: nonfinite diagnostic numbers are written as null while the corresponding finite flag and failure reason remain explicit. geometry_sensitivity_report is a thin FluxTubeGeometryData wrapper around the same helper.

For vmec_jax and booz_xform_jax this remains a bridge contract, not a claim that SPECTRAX-GK has run a full optimization. The upstream JAX pipeline must first produce the sampled solver-ready field-line arrays accepted by flux_tube_geometry_from_mapping. Passing the reusable AD/finite-difference gate proves local differentiability and conditioning of the supplied observables; production stellarator optimization still requires the VMEC/Boozer array parity, solver-objective gradient, and nonlinear transport gates described below.

Differentiable geometry bridge validation. The panel checks boundary-control sensitivities, geometry-observable Jacobians, a two-parameter inverse design, and local UQ covariance at the in-memory flux-tube contract boundary. When vmec_jax is available, the panel/JSON also includes a real VMEC boundary-aspect derivative check and sampled VMEC metric-tensor derivative check, plus a real VMEC field-line tensor check for a non-axisymmetric fixture, a direct VMEC tensor-derived flux-tube mapping check, and a Boozer equal-arc core/metric parity check against the imported VMEC/EIK geometry; when booz_xform_jax is available, it runs a bounded JAX-native Boozer spectral transform, samples that spectrum onto a field-line flux-tube mapping, checks both autodiff derivative paths against central finite differences, and, when both optional backends are available, starts from a real vmec_jax VMECState before converting through booz_xform_jax into the SPECTRAX-GK field-line contract.

Multi-Equilibrium Boozer Parity Matrix

The single-fixture bridge artifact is complemented by a replayable multi-equilibrium matrix:

JAX_ENABLE_X64=1 PYTHONPATH=src \
  python tools/build_vmec_boozer_parity_matrix.py

It writes docs/_static/vmec_boozer_parity_matrix.{png,pdf,json,csv}. The builder enforces mboz,nboz >= 21 before calling the real optional backend path, because the QI drift gate is under-resolved at lower Boozer mode counts. The JSON now includes a sample_set_provenance block and the CSV includes a sample_set_id column so each bounded row is identified by case_name, ntheta, mboz, and nboz. That provenance block also records that the builder does not launch external VMEC solves; input-only QI variants remain explicitly artifact-limited until a bundled wout reference exists. The tracked matrix covers the nfp4_QH_warm_start, nfp3_QI_fixed_resolution_final, and shaped_tokamak_pressure examples. At mboz=nboz=21 the current regenerated artifact passes all matrix rows. The fixed-resolution QI case passes the loaded-convention drift subgate with mismatch about 7.13e-2 against an 8e-2 release tolerance after fixing the Boozer half-mesh radial-index convention. The evaluated QI robustness variants at ntheta=8 and ntheta=16 also pass. The broader QI seed campaign is still artifact-limited because three input-only QI seeds have no bundled wout references, and none of this is broad random-seed nonlinear QI transport validation or QI optimization. Finite-beta drift parity, solver-objective geometry gradients beyond the tracked reduced gates, and nonlinear transport optimization remain explicitly scoped as follow-up work.

VMEC/Boozer equal-arc parity matrix. Each cell reports the absolute mismatch for one subgate, while the color shows mismatch divided by the relevant tolerance. The matrix is generated from the actual optional vmec_jax and booz_xform_jax bridge path and rejects Boozer mode counts below 21.

The next implementation step is to extend the same equal-arc path to finite-beta/production-runtime curvature and drift reconstruction, then replace the reduced estimator-gradient checks with converged transport-gradient and broader optimized-equilibrium audits beyond the selected QA candidate.

In-memory differentiable geometry API

Differentiable stellarator optimization must stay on the in-memory path:

from spectraxgk import flux_tube_geometry_from_vmec_boozer_state

geom = flux_tube_geometry_from_vmec_boozer_state(
    state,
    static,
    indata,
    wout,
    surface_index=surface_index,
    alpha=0.0,
    ntheta=32,
    mboz=21,
    nboz=21,
)

This public wrapper converts a solved vmec_jax state through booz_xform_jax and returns the existing SPECTRAX-GK FluxTubeGeometryData solver contract. The path is VMECState -> BoozXformInputs -> Boozer coefficients -> FluxTubeGeometryData and does not write or reload *.eik.nc files. The file-backed VMEC/EIK route remains the right runtime import path for ordinary examples, but it is not the path to use for end-to-end differentiable optimization.

The current wrapper is a production API boundary, not a new physics claim. It inherits the same mboz,nboz >= 21 and equal-arc parity requirements as the VMEC/Boozer gates. Full stellarator-optimization claims still require multi-surface/multi-field-line objective gates and nonlinear heat-flux audits of optimized equilibria.

The lightweight readiness tests mirror that claim boundary. The parity-matrix tests reject mboz,nboz < 21 and assert that a passed equal-arc matrix is still tagged as not_full_transport_gradient_claim. The gradient-holdout tests require the mode21_vmec_boozer_state source scope, mboz,nboz >= 21, and explicitly track the nonlinear-window estimator objectives as a reduced differentiability gate rather than a production nonlinear-optimization gate.

For release claims, the differentiable-geometry lane is closed only for artifact-passing zero-beta equal-arc parity rows and reduced AD/finite-difference objectives. The fixed-resolution QI row and evaluated QI ntheta variants now pass, but production nonlinear heat-flux optimization is still open. The active publication wording must keep these levels separate: the current bridge starts at real vmec_jax state coefficients and reaches SPECTRAX-GK solver observables, but it has not yet validated converged nonlinear turbulence gradients, broad QI transport behavior, or nonlinear audits of optimized equilibria. The VMEC bridge now also expands environment variables in geometry.vmec_file. The shipped portable runtime TOMLs now point to relative wout_*.nc paths under examples/vmec. Generate those WOUT files locally from the bundled vmec_jax input decks with examples/vmec/generate_wouts.sh or a single vmec_jax input.<case> command. Environment variables and --vmec-file remain useful for machine-specific validation equilibria, but they are no longer required for the bundled demos. For future validation-lane selection, the external vmec_jax example-data portfolio can be inventoried without copying those VMEC files into this repository:

VMEC_JAX_ROOT=/path/to/vmec_jax
python tools/plot_vmec_jax_equilibrium_inventory.py \
  --data-dir "$VMEC_JAX_ROOT/examples/data" \
  --out docs/_static/vmec_jax_equilibrium_inventory.png

This writes docs/_static/vmec_jax_equilibrium_inventory.{png,pdf,json}. The artifact is an equilibrium-selection aid only. It excludes VMEC files with degenerate reference-scale metadata from the recommended follow-up list, but it still does not validate quasilinear transport until each selected VMEC equilibrium also has matched linear and nonlinear SPECTRAX-GK runs and physics gates. The first bounded smoke checks have finite stable linear branches for Li383, nfp4 QH, CTH-like, and shaped-tokamak fixtures from vmec_jax/examples/data; those checks only validate the runtime geometry and quasilinear-feature plumbing, not nonlinear transport. The nonlinear W7-X and HSX startup audits now confirm that this VMEC runtime path reproduces GX startup g_state and phi to roundoff when the generated *.eik.nc is rebuilt from the same VMEC input. The late-time W7-X diagnostic-state audit now also matches GX on the exact dumped nonlinear state once the comparison tool reconstructs the compressed real-FFT positive-ky dump grid directly from diag_state_ky_t*.bin. The tracked exact-state panel docs/_static/w7x_exact_state_audit.png records a maximum finite pointwise relative error of 4.62e-5 under the explicit 1e-4 convention gate, with late scalar diagnostics below 1.8e-7. That closes the remaining imported-geometry diagnostic-contract gap for nonlinear VMEC cases: startup, phi, kperp2, fluxfac, Wg, Wphi, and heat flux all agree on the same GX state. The follow-on exact-state linear audit on that same W7-X dump now also matches GX to roundoff. The remaining operator-level fixes were:

• treat boundary = "fix aspect" and "continuous drifts" as GX linked twist-and-shift boundaries in the linear cache, and

• include the GX collision-conservation correction on top of the Lenard-Bernstein damping term.

With those in place, the imported VMEC/eik bridge, the late-time linear RHS, and the late-time nonlinear E x B diagnostics all agree with GX on the same dumped stellarator state. The final nonlinear W7-X free-run mismatch then collapsed once the runtime de-alias mask matched GX exactly: the two-thirds cutoff must be strict (< 1/3), not inclusive. With that correction, the tracked stock-GX W7-X t = 200 VMEC runtime rerun also passes the native late-window comparison, so the shipped nonlinear W7-X example is now closed at startup, exact-state, and long-horizon levels.

Tokamak Miller geometry now follows the same imported-geometry bridge pattern. With geometry.model = "miller", SPECTRAX-GK shells out to the existing Miller helper, generates the matching root-level *.eiknc.nc file, and then re-enters the same imported-geometry contract described above. This keeps the Miller lane geometry-honest without introducing a second hand-maintained Miller implementation in the runtime path. On the tracked Cyclone Miller parameters, the generated *.eiknc.nc file matches the clean GX grouped Geometry arrays to roundoff in the main metric and drift profiles. With the root-level open/closed theta inference corrected, the clean-mainline Cyclone Miller late-state audit also now closes on the exact dumped GX state: kperp2, fluxfac, phi, Wg, Wphi, and heat flux all match to roundoff on the same nonlinear state.

Two user-facing entry points now exercise that bridge:

• tools/generate_gx_vmec_eik.py --config ... generates a compatible *.eik.nc file from a SPECTRAX runtime TOML.

• tools/generate_gx_miller_eik.py --config ... generates a compatible Miller *.eiknc.nc file from a SPECTRAX runtime TOML.

• examples/nonlinear/non-axisymmetric/hsx_nonlinear_vmec_geometry.py and examples/nonlinear/non-axisymmetric/runtime_hsx_nonlinear_vmec_geometry.toml run a nonlinear adiabatic-electron ITG case on the bundled QHS VMEC input deck after its wout_NuhrenbergZille_1988_QHS.nc file is generated with vmec_jax. They still accept --vmec-file for exact HSX validation WOUTs while letting SPECTRAX generate and reuse the field-line geometry automatically.

VMEC and Miller runtime examples

VMEC-driven stellarator runs:

cd examples/vmec
vmec_jax input.nfp3_QI_fixed_resolution_final
cd ../..
spectrax-gk run-runtime-nonlinear \
  --config examples/nonlinear/non-axisymmetric/runtime_w7x_nonlinear_vmec_geometry.toml \
  --steps 200 \
  --out tools_out/w7x_vmec.out.nc

cd examples/vmec
vmec_jax input.NuhrenbergZille_1988_QHS
cd ../..
spectrax-gk run-runtime-nonlinear \
  --config examples/nonlinear/non-axisymmetric/runtime_hsx_nonlinear_vmec_geometry.toml \
  --steps 200 \
  --out tools_out/hsx_vmec.out.nc

Miller geometry runs:

spectrax-gk run-runtime-nonlinear \
  --config examples/nonlinear/axisymmetric/runtime_cyclone_nonlinear_miller.toml \
  --steps 200 \
  --out tools_out/cyclone_miller.out.nc

Imported geometry currently bypasses analytic twist-shift reconstruction and uses the provided grid as-is. That keeps the GX-import bridge honest while the native VMEC path is still being generalized.