Architecture

Core modules

  • spectraxgk.basis: Hermite and Laguerre basis functions.

  • spectraxgk.gyroaverage: gyroaverage coefficients and polarization helpers.

  • spectraxgk.geometry: analytic s-alpha flux-tube geometry.

  • spectraxgk.terms: term-wise RHS kernels (streaming, mirror, drifts, drive, collisions, fields).

  • spectraxgk.linear: public linear API, field solves, RHS kernels, and integrators that call modular RHS assembly.

  • spectraxgk.linear_cache: geometry-dependent linear cache construction, gyroaverage tables, and collision/hypercollision damping factors.

  • spectraxgk.linear_linked: linked-boundary FFT maps and end-damping profiles for field-aligned linear operators.

  • spectraxgk.linear_moments: Hermite/Laguerre ladder operators, quasineutrality, and gyrokinetic-field variable construction.

  • spectraxgk.linear_params: linear parameter pytrees, term toggles, and validation/coercion helpers.

  • spectraxgk.linear_parallel: gated velocity-parallel linear RHS helpers and disabled-by-default parallel dispatcher.

  • spectraxgk.nonlinear: nonlinear runtime integrators and cached IMEX paths.

  • spectraxgk.nonlinear_diagnostics: sampling and resolved-diagnostic packing helpers used by nonlinear integrators.

  • spectraxgk.nonlinear_helpers: Hermitian/fixed-mode projectors, GX omega masks, collision-split policies, and reusable nonlinear IMEX operator construction.

  • spectraxgk.runtime / spectraxgk.runtime_config: user-facing runtime entrypoints and configuration schema.

  • spectraxgk.runtime_policies: pure runtime selection policies for solver names, scan modes, nonlinear monitored modes, external fields, and step-count inference.

  • spectraxgk.runtime_orchestration: runtime progress/ETA formatting, combined-ky scan batching, and nonlinear restart/checkpoint artifact handoff behind injectable compatibility seams.

  • spectraxgk.benchmark_defaults: normalization constants and Krylov policies for shipped benchmark lanes.

  • spectraxgk.benchmark_helpers: reference data loaders, result containers, and pure benchmark policies.

  • spectraxgk.benchmark_scan: shared scan-window, batching, and fit-signal policies used by benchmark runners.

  • spectraxgk.benchmarks: public benchmark runners and compatibility import surface.

  • spectraxgk.plotting: reusable, publication-ready plotting utilities.

Term-level source mapping

  • streaming, mirror, curvature, grad-B, diamagnetic, collisions, hypercollisions, hyperdiffusion, end damping: src/spectraxgk/terms/linear_terms.py

  • field solves: src/spectraxgk/terms/fields.py

  • nonlinear E×B, flutter, and Bessel-grid transforms: src/spectraxgk/terms/nonlinear.py

  • assembled RHS: src/spectraxgk/terms/assembly.py

For the full operator equations, see Operators And Terms.

Data flow

The linear solve is structured as:

  1. build the spectral grid and geometry

  2. compute gyroaverage coefficients

  3. convert LinearTerms into one canonical TermConfig

  4. solve the field equations for \((\\phi, B_\\parallel, A_\\parallel)\)

  5. build the gyrokinetic variable H

  6. assemble RHS by summing per-term kernels from spectraxgk.terms

  7. advance in time using integrate_linear/diffrax/Krylov with the same RHS

This structure is intentionally modular so that nonlinear terms, collisions, geometry adapters, and electromagnetic extensions can be inserted with minimal refactoring.