Spectrax-1D Configuration Reference

This document describes how to construct a configuration file for the spectrax-1d (and hermite-epw-1d) solvers, which implement a Hermite-Fourier spectral Vlasov-Maxwell solver for 1D plasma kinetics.

Top-Level Structure

solver: spectrax-1d      # or hermite-epw-1d for EPW analysis
mlflow: ...
units: ...
physics: ...
grid: ...
drivers: ...
save: ...

physics

Physical parameters for the simulation.

Field	Type	Default	Description
`Lx`	float	—	Domain length in x (normalized)
`Ly`	float	—	Domain length in y (normalized)
`Lz`	float	—	Domain length in z (normalized)
`mi_me`	float	—	Ion-to-electron mass ratio
`qs`	list[float]	—	Species charges `[q_electron, q_ion]`, e.g. `[-1.0, 1.0]`
`alpha_s`	list[float]	—	All-species thermal velocities `[αx_e, αy_e, αz_e, αx_i, αy_i, αz_i]`
`u_s`	list[float]	—	All-species drift velocities (same layout as `alpha_s`)
`Omega_ce_tau`	float	—	Reference cyclotron frequency (electron mass normalized). Species cyclotron frequency is `(q/m) * Omega_ce_tau`.
`nu`	float	—	Hypercollision frequency
`nx`, `ny`, `nz`	int	—	Perturbation mode numbers for initialization
`dn1`	float	—	Density perturbation amplitude
`static_ions`	bool	`false`	Freeze ion distribution (no Lorentz force, no ion current, no free-streaming). Ions retain their initial equilibrium background but do not evolve. Useful for studying pure electron physics (EPW, SRS scattering) at reduced cost.

`static_ions`

When static_ions: true:

Ion distribution Ck_ions is held fixed at its initial (Maxwellian) state
Ion current is excluded from Ampère’s law
Ion free-streaming and collision operators are bypassed (exponential integrator)

Ion dynamics are irrelevant at electron plasma wave (EPW) frequencies because ω_EPW / (k v_{th,i}) ≫ 1. The EPW dispersion is unchanged to within numerical tolerance when this flag is enabled. Static ions is a useful diagnostic and computational shortcut.

grid

Simulation grid and time-integration parameters.

Field	Type	Default	Description
`Nx`, `Ny`, `Nz`	int	—	Number of Fourier modes per spatial dimension
`Nn`, `Nm`, `Np`	int	—	Hermite modes (legacy: same for both species)
`hermite_modes`	dict	—	Per-species Hermite mode counts (see below)
`Ns`	int	`2`	Number of species
`tmax`	float	—	Simulation end time
`dt`	float	—	Timestep (calculated from `tmax/nt` if omitted)
`nt`	int	—	Number of timesteps (calculated from `tmax/dt` if omitted)
`solver`	string	`"Dopri8"`	Diffrax solver name for `"explicit"` integrator (`"Dopri8"`, `"Tsit5"`, etc.)
`adaptive_time_step`	bool	`false`	Adaptive step-size control. For `"explicit"`: PID on the full ODE. For `"exponential"`: PID on the nonlinear term via embedded Lawson-Heun companion.
`integrator`	string	`"exponential"`	Time integrator: `"exponential"` (Lawson-RK4, recommended) or `"explicit"` (plain Runge-Kutta via Diffrax)
`use_shard_map`	bool	`false`	Enable multi-device sharding along Nx

Per-species Hermite modes

Use hermite_modes for independent electron/ion resolution:

grid:
  hermite_modes:
    electrons:
      Nn: 512    # velocity modes in x
      Nm: 1
      Np: 1
    ions:
      Nn: 32
      Nm: 1
      Np: 1

Integrators

explicit (default): Standard Runge-Kutta via Diffrax (e.g., Dopri8). Adaptive time-stepping resolves light waves and free-streaming stiffness.

exponential (Lawson-RK4): Factors out the linear part (free-streaming, Maxwell curls, collision) into exact matrix exponentials, removing CFL stiffness from the linear terms. Supports both fixed and adaptive time-stepping:

adaptive_time_step: false (default) — fixed dt, fastest per-step cost.
adaptive_time_step: true — enables a PIDController (rtol=1e-3, atol=1e-6) using a zero-cost embedded 2nd-order companion (Lawson-Heun). The controller shrinks dt when the nonlinear term (Lorentz force, plasma current) becomes stiff, e.g. for strongly driven EPW. dt in the config sets the initial step; dtmax is automatically set to 2π / (10 * w0) from the highest-frequency driver if present. Use this mode to stabilize strongly driven simulations.

drivers

External electromagnetic field drivers.

drivers:
  ex:                  # drives Ex component
    '0':
      k0: 6.2832       # wavenumber (rad/L)
      w0: 1.104        # frequency (ωpe)
      a0: 1.0e-6       # amplitude
      t_center: 35.0   # pulse center time
      t_width: 30.0    # pulse width
      t_rise: 14.0     # rise/fall time
      x_center: 0.5    # spatial center (normalized)
      x_width: 1000.0  # spatial width (large = uniform)
      x_rise: 0.1
      dw0: 0.0         # frequency detuning
  ey: {}
  ez: {}

density

Stochastic density noise injected into the (0,0,0) Hermite mode each timestep.

density:
  noise:
    enabled: true
    type: uniform        # "uniform" or "normal"
    amplitude: 1.0e-12
    seed: 42
    electrons:
      enabled: true
      amplitude: 1.0e-12
    ions:
      enabled: false

hermite_filter

Hou-Li exponential damping of high Hermite modes (prevents filamentation).

Applies σ(h) = exp(-strength * (h / h_max)^order) to all modes, where h = sqrt(n² + m² + p²) is the Euclidean norm of the mode index triple and h_max = sqrt((Nn-1)² + (Nm-1)² + (Np-1)²) is the norm at the highest-index corner. The highest mode gets exactly exp(-strength); lower modes are progressively less damped.

drivers:
  hermite_filter:
    enabled: true
    strength: 4.0    # filter strength — exp(-strength) is the damping at the highest mode
    order: 4         # filter order (higher = sharper roll-off concentrated near h_max)

save

Quantities to save during the simulation via Diffrax SubSaveAt.

save:
  fields:           # electromagnetic fields Fk in Fourier space
    t:
      tmin: 0.0
      tmax: 200.0
      nt: 801

  hermite:          # full Hermite-Fourier distribution Ck (both species)
    t:
      tmin: 0.0
      tmax: 200.0
      nt: 101

  moments:          # real-space density/velocity/temperature moments
    t:
      tmin: 0.0
      tmax: 200.0
      nt: 201

A default save (scalar diagnostics: EM energy, peak fields, etc.) is always added automatically at every grid timestep.