Quickstart

Install

pip install spectraxgk

or install the development checkout:

git clone https://github.com/uwplasma/SPECTRAX-GK
cd SPECTRAX-GK
pip install -e .

Executable demo

spectraxgk
spectrax-gk
spectraxgk examples/linear/axisymmetric/cyclone.toml
spectraxgk run-runtime-linear --config examples/linear/axisymmetric/runtime_cyclone.toml --out tools_out/cyclone_runtime
spectraxgk run-runtime-nonlinear --config examples/nonlinear/axisymmetric/runtime_cyclone_nonlinear.toml --steps 50 --out tools_out/cyclone_nonlinear.out.nc
spectraxgk --plot tools_out/cyclone_nonlinear.out.nc
spectraxgk --plot spectraxgk_default_linear.summary.json

Running spectraxgk with no TOML launches a short Cyclone initial-value linear demo, prints live progress with elapsed time and ETA, and writes the artifacts in the current directory:

  • spectraxgk_default_linear.toml: the input file that reproduces the run

  • spectraxgk_default_linear.summary.json

  • spectraxgk_default_linear.timeseries.csv

  • spectraxgk_default_linear.eigenfunction.csv

  • spectraxgk_default_linear.png

The plot is the standard two-panel linear quickstart view: the log-scale |\phi|^2 time history with fitted (\gamma, \omega) on the left, and the normalized real/imaginary eigenfunction on the right. To rerun the same numerical case explicitly:

spectraxgk run-linear --config spectraxgk_default_linear.toml --progress

When progress output is enabled (for example on a TTY or with the explicit progress flags), the executable prints live status lines with step/time progress, wall elapsed time, and an estimated wall-clock time remaining. Long adaptive nonlinear runs also report chunk-level elapsed/ETA updates at the runtime layer.

When --out is provided for runtime-configured single-point runs, the executable writes a JSON summary plus sidecar time-series/state artifacts using the supplied path as a prefix.

If the nonlinear target ends in .out.nc or another .nc suffix, the runtime writes a restartable NetCDF bundle instead:

  • *.out.nc: diagnostic history, geometry, and input metadata

  • *.big.nc: final fields and moments in spectral and real-space layouts

  • *.restart.nc: restart state for continuation runs

The same artifact prefix can be stored in the runtime TOML itself:

[output]
path = "tools_out/cyclone_runtime"

To make the run restart-aware, add the restart controls directly to the TOML:

[time]
nstep_restart = 100

[output]
path = "tools_out/cyclone_runtime.out.nc"
restart_if_exists = true
save_for_restart = true
append_on_restart = true

Rerunning the same nonlinear command then resumes from the saved *.restart.nc checkpoint and appends the continued history to *.out.nc.

Plot diagnostics directly from the output:

spectraxgk --plot tools_out/cyclone_nonlinear.out.nc
spectraxgk --plot spectraxgk_default_linear.summary.json

Self-contained VMEC geometry

The VMEC-backed examples are prefilled with relative wout_*.nc paths. The repository ships small vmec_jax input decks, not large generated WOUT files. Generate the needed equilibria locally, then run the TOMLs directly:

pip install vmec-jax
cd examples/vmec
vmec_jax input.circular_tokamak
vmec_jax input.NuhrenbergZille_1988_QHS
vmec_jax input.nfp3_QI_fixed_resolution_final
cd ../..

spectraxgk run --config examples/linear/axisymmetric/runtime_circular_vmec_linear.toml
spectraxgk run --config examples/linear/non-axisymmetric/runtime_hsx_linear_quasilinear.toml
spectraxgk run --config examples/linear/non-axisymmetric/runtime_w7x_linear_quasilinear_vmec.toml

The bundled QHS/QI/QA decks are self-contained demonstrators. Exact machine-specific HSX or W7-X validation should use the same TOMLs with --vmec-file pointing to the corresponding benchmark wout_*.nc.

Geometry path overrides

The executable can still override geometry paths without editing the TOML. These command-line paths are resolved from the shell’s current working directory, while paths written in the TOML remain resolved from the TOML location. Use --vmec-file when the runtime config already uses a VMEC-backed geometry model:

spectrax-gk run \
  --config examples/nonlinear/non-axisymmetric/runtime_hsx_nonlinear_vmec_geometry.toml \
  --vmec-file /absolute/or/relative/wout_machine_specific.nc \
  --out tools_out/hsx_vmec_run

Use --geometry-file only for advanced imported-geometry configs that already use model = "vmec-eik", model = "gx-eik", or model = "gx-netcdf". This is not needed for the shipped VMEC examples:

spectrax-gk run \
  --config external_imported_geometry_case.toml \
  --geometry-file /absolute/or/relative/external_geometry.eik.nc \
  --out tools_out/imported_run

--geometry-file only replaces [geometry].geometry_file; it does not switch model = "vmec" into imported-geometry mode. For model = "vmec", geometry_file remains the generated *.eik.nc target/cache path.

Python demo

from spectraxgk import load_cyclone_reference, run_cyclone_linear

ref = load_cyclone_reference()
result = run_cyclone_linear(ky_target=0.3, method="rk4")

print(result.gamma, result.omega)

Run from TOML

python examples/utilities/runtime_from_toml.py --config examples/linear/axisymmetric/cyclone.toml

Figure generation

PYTHONPATH=src python tools/make_benchmark_atlas.py