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 :doc:`operators`.

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 :math:`(\\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.