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 .. math:: k_x(\theta) = k_{x0} - \left(\hat{s}\,\theta - \alpha \sin\theta \right) k_y, and the metric coefficients are .. math:: 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 .. math:: 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 :math:`B^{-2}` factor from the s-alpha magnetic field strength, .. math:: 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 :math:`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 :math:`Z_p = 2\,nperiod-1` and choose ``Nz = ntheta * Zp``, which spans :math:`[-\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 .. math:: \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 .. math:: \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: .. code-block:: bash 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-:math:`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-:math:`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: .. code-block:: bash 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: .. code-block:: bash 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. .. figure:: _static/differentiable_geometry_bridge.png :width: 95% :align: center :alt: Differentiable geometry bridge validation 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: .. code-block:: bash 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. .. figure:: _static/vmec_boozer_parity_matrix.png :width: 95% :align: center :alt: VMEC/Boozer equal-arc parity matrix 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: .. code-block:: python 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.`` 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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.