Skip to content
uwplasmaPublic

About

Gyrokinetic Spectral Solver of Plasma Turbulence

Resources

Contributing

Security policy

Stars

7 stars

Watchers

0 watching

Forks

Repository files navigation

GKX

Release PyPI CI Coverage License: MIT Python Docs

GKX is a JAX gyrokinetic solver for tokamak and stellarator flux tubes. It reads a VMEC or VMEX equilibrium, or builds an analytic Miller or s-alpha geometry, and computes linear stability and nonlinear turbulence in a Hermite-Laguerre velocity basis. The whole path, equilibrium included, is differentiable on CPUs and GPUs.

Comparison across gyrokinetic codes

Growth rate, real frequency and growth-rate deviation from GKX for GKX, GX, GS2 and stella: Cyclone with adiabatic and kinetic electrons, a finite-beta scan, and W7-X

Wall time of one linear k_y at 1% growth-rate accuracy and of the nonlinear Cyclone run to t = 400 for GKX, GX, GS2 and stella, with hardware and heat flux

Nonlinear Cyclone heat flux against time for GKX, GX, GS2 and stella

GKX, GX, GS2 and stella solve the same Cyclone and W7-X flux-tube problems in GX units: linear growth rate and frequency, wall time, and the nonlinear Cyclone heat flux. Redraw the figures with python docs/figures/four_code_comparison.py, which reads docs/figures/four_code_comparison.json. The GKX runs use the decks in benchmarks/cases; the GX, GS2 and stella runs need those codes installed. Resolutions, hardware and caveats are in the validation guide.

Install and first run

pip install gkx
gkx

Python 3.10+. The wheel installs CPU JAX; for GPUs add an accelerator JAX wheel (JAX install guide). gkx with no arguments runs a linear Cyclone case and prints its growth rate gamma and real frequency omega. The tutorial walks through the runs in examples/, from this one to a stellarator optimization.

Run a case

gkx wout_circular_tokamak.nc --estimate   # size the grid, explain it, exit
gkx wout_circular_tokamak.nc              # nonlinear ITG run to saturation
gkx plot wout_circular_tokamak/gkx.out.nc # replot a saved bundle
gkx examples/01_linear_tokamak/case.toml --plot  # any TOML deck; --plot opens the figures

A run stops when heat flux, field energy and free energy are stationary, or reports that it did not. It writes figures, a restartable NetCDF bundle and the resolved deck that reproduces it.

import gkx

case = gkx.load("examples/01_linear_tokamak/case.toml")
result = gkx.solve(case, ky_target=0.3, Nl=case.run.Nl, Nm=case.run.Nm)
print(result.gamma, result.omega)

Every deck key, with type and default, is listed in inputs; examples/reference_inputs holds decks that set every key at its default.

Defaults

Choice Default
Velocity space Hermite-Laguerre (Nl, Nm); kinetic electrons get per-species counts
Collisions linearized Landau
Nonlinear stepper auto: lawson-rk4-pi or rk4-pi; imex-ark3 for kinetic electrons at beta <= 3e-4
Linear solver auto: time integration, then the certified eigensolver (banded shift-invert, else Arnoldi); krylov runs the eigensolver directly
End damping one rate on every route, 30 thermal transits across the end layer
ky layout half, the non-negative rows
Precision float32; JAX_ENABLE_X64=true for float64

Guidance says what to set for kinetic electrons and electromagnetic runs, and how to check it.

Collision operators

collision_operator in [time] selects the model; nu sets the collision frequency for all of them (operators).

  • landau (default): the linearized Landau operator, exact in the drift-kinetic limit. Use it unless a comparison calls for another model.
  • sugama: Landau test part with momentum- and energy-restoring field part, self-adjoint between unlike species and temperatures. Use it to compare with codes that use this model.
  • improved_sugama: sugama with the exact Landau heat-flux and friction terms; it tracks landau at high collisionality.
  • lenard_bernstein: conserving Lenard-Bernstein/Dougherty relaxation, the cheapest model. It captures collisional damping qualitatively, not the Landau operator.
  • coulomb_finite_kperp: tabulated gyrokinetic Coulomb operator with finite k_perp, for one species.

Collisional trapped-electron mode growth rate against collisionality for the GKX landau, sugama, improved_sugama and lenard_bernstein operators, GS2 and stella, and its reduction relative to the collisionless rate

Collisional trapped-electron mode at k_y rho_i = 0.3 on the benchmarks/cases/tem_collisional.toml deck. At (Nl, Nm) = (4, 8) the four operators lie within 4% of one another; GKX is not converged there. Redraw with python docs/figures/collision_operators.py.

Left: GKX landau collisional trapped-electron mode growth rate against velocity-space size, with GS2 and stella. Right: zonal-flow damping of the four GKX operators against the Xiao-Catto-Molvig formula

The collisional growth rate of landau converges to 0.2587 +- 0.0006, 3% below GS2 (0.2666) and 0.5% above stella's Fokker-Planck test part (0.2575 at its second grid); the ratio to the collisionless rate is 0.73 +- 0.02 against GS2's 0.736. The zonal flow relaxes to 0.006 of its initial value for every operator, against 0.0051 from the formula, which the decay rate matches to about 10% only below a neoclassical collisionality of 0.3, at the finest resolution (validation).

Derivatives and optimization

Eigenvalue derivatives use dλ/dp = wᴴ(dA/dp)v / (wᴴv) with residual, overlap and conditioning checks. Nonlinear heat-flux derivatives use a checkpointed discrete adjoint over a finite post-saturation window. Compare these derivatives with finite differences across perturbation sizes and window lengths; assess a design change with independent long simulations (nonlinear autodiff).

VMEX composes its equilibrium derivative with GKX objectives in stellarator shape optimization; the optimization example combines heat flux with equilibrium constraints. Quasilinear flux requires calibration and held-out nonlinear validation before it supports an absolute transport prediction (quasilinear, stellarator optimization).

Saturated ITG turbulence on a Cyclone flux tube, shown as a perpendicular cut and as the field-aligned tube

Saturated ITG turbulence on a Cyclone flux tube (full-rate movie).

Documentation and development

Documentation: gkx.readthedocs.io. Start with the tutorial and the guidance; validation and cross-code protocols are in validation, performance and parallel execution in performance and parallelization.

git clone https://github.com/uwplasma/GKX
cd GKX
pip install -e ".[dev]"
pytest -n 4

CI requires 95% combined line and branch coverage plus the physics, convergence, comparison, differentiability and performance gates (CONTRIBUTING.md). Cite GKX with CITATION.cff. MIT license; see LICENSE.

About

Gyrokinetic Spectral Solver of Plasma Turbulence

Resources

Contributing

Security policy

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages