Skip to content
Projects

Theory toolbox

plasma_plots.theory collects the analytic results that Struphy runs are checked against: dispersion relations and growth rates, plasma parameters, particle orbits, exact solutions, and the properties of the numerics themselves. It is plain numpy, needs neither Struphy nor scipy, and its results plug straight into the plots.

from plasma_plots.theory import (
beams,
collisions,
equilibria,
exact,
kinetic,
magnetron,
negative_ions,
numerics,
orbits,
parameters,
sheaths,
waves,
)

Full signatures are in the theory reference.

  • Arrays: every function takes scalars or numpy arrays that broadcast, and returns arrays (a Python scalar for scalar input).
  • Units: normalized, unless a function says otherwise. Kinetic results use the plasma frequency, the Debye length and v_th = √(T/m). Fluid and MHD results come out in the units of the speeds and wavenumbers you pass. theory.parameters is in SI units, with temperatures in eV.
  • Frequencies are complex, for exp(i(k·x − ωt)): the real part is the frequency, a positive imaginary part a growth rate, a negative one a damping rate. Take .real or .imag to plot one of them.
  • Several branches come as a dict of names to complex frequencies, e.g. {"shear Alfvén": ..., "slow": ..., "fast": ...}.

A theory function goes directly into the plots that compare against theory:

phi.plasma.plot.dispersion(
branches={"kinetic": kinetic.langmuir, "Bohm–Gross": kinetic.bohm_gross}
)
v.plasma.plot.dispersion(
branches=lambda k: waves.mhd_waves(
k, theta=0.3, alfven_speed=1.0, sound_speed=0.5
)
)
spectrum = phi.plasma.analysis.dispersion()
# follow the kinetic branch
traced = spectrum.plasma.analysis.trace_branch(kinetic.langmuir)
# frequencies and their errors
traced.omega.plasma.plot.against_theory(kinetic.langmuir)
# damping rates
rates.plasma.plot.against_theory(lambda k: kinetic.langmuir(k).imag)
T.plasma.plot.profiles(
x="eta1",
reference=lambda x, t: exact.heat_kernel(
x, t, 0.01, width=0.05, center=0.5
),
)
  • branches= takes a dict of labels to functions, or one function that returns a dict of branches. Complex frequencies are drawn by their real part.
  • Struphy’s own struphy.dispersion_relations objects, such as MHDhomogenSlab(), work as branches= too.
  • trace_branch and against_theory compare frequencies (the real part). For growth or damping rates, pass the imaginary part.

A synthetic field of damped Langmuir waves, with the kinetic root and Bohm–Gross drawn over its spectrum. The kinetic curve follows the measured ridge where Bohm–Gross drifts away:

Theory functions as branches of a measured dispersion diagramTheory functions as branches of a measured dispersion diagram

theory.kinetic solves the electrostatic dispersion relation of drifting Maxwellians with the plasma dispersion function Z(ζ). It covers Langmuir waves with their Landau damping, ion-acoustic waves, and the beam-driven instabilities, plus the electromagnetic Weibel instability:

kinetic.langmuir(0.5) # (1.415662−0.153359j): frequency and Landau damping
kinetic.ion_acoustic(k, temperature_ratio=10)
kinetic.bump_on_tail(
k, beam_density=0.1, beam_speed=4.5, beam_thermal_speed=0.5
)
kinetic.two_stream(k, beam_speed=1.0, thermal_speed=0.1)
kinetic.weibel(k, anisotropy=4.0, parallel_thermal_speed=0.1) # k in ω_p/c
# magnetized electron drift (E×B): branches of the cyclotron drift instability
kinetic.electron_cyclotron_drift(0.3, 0.75, 0.197)
# (k, ω) of the fastest growth
kinetic.maximum_growth(kinetic.bump_on_tail, (0.05, 0.5))

For other velocity distributions, describe each species as a kinetic.Maxwellian(density, charge, mass, thermal_speed, drift), and solve kinetic.electrostatic_dielectric(ω, k, species) = 0 with kinetic.solve_dispersion. kinetic.electrostatic_growth(k, species) returns the most unstable root for any such set, e.g. drifting Maxwellians fitted to the moments of a simulation; here electrons drifting through protons (the Buneman instability):

species = (kinetic.Maxwellian(drift=20.0), kinetic.Maxwellian.ions())
kinetic.maximum_growth(
lambda k: kinetic.electrostatic_growth(k, species), (0.02, 0.06)
)

Langmuir frequency and Landau damping rate against Bohm–Gross and the weak-damping formulaLangmuir frequency and Landau damping rate against Bohm–Gross and the weak-damping formula

Growth rates of the bump-on-tail, two-stream and Weibel instabilitiesGrowth rates of the bump-on-tail, two-stream and Weibel instabilities

theory.waves covers the linear waves of Struphy’s fluid and field models:

FunctionModel
light_wave, plasma_light_wave, cavity_modesMaxwell, a cavity, the O-wave cutoff
mhd_waves, magnetosonic_speedsideal MHD at any angle
dissipative_alfvenresistive and viscous MHD
hall_mhd_parallelHall MHD along B: whistler and ion-cyclotron waves
stix, refractive_index, cold_plasma_waves, appleton_hartree, cutoffs, resonances, faraday_rotationcold plasma
drift_wave, hasegawa_wakatanidrift waves
alfven_continuum, slow_continuum, tae_frequencycontinuous spectra and the TAE frequency
# {"shear Alfvén", "slow", "fast"}
waves.mhd_waves(k, theta=np.pi / 4, alfven_speed=1.0, sound_speed=0.6)
plasma = waves.electron_ion(
plasma_frequency=1.0, cyclotron_frequency=0.6, mass_ratio=25
)
waves.cold_plasma_waves(k, np.pi / 4, plasma) # every branch at 45°
waves.cutoffs(plasma), waves.resonances(np.pi / 4, plasma)
waves.faraday_rotation(omega, length, plasma)

The Friedrichs diagram of MHD phase speeds, and the cold-plasma branches at 45°The Friedrichs diagram of MHD phase speeds, and the cold-plasma branches at 45°

The continua follow Struphy’s MhdContinousSpectraCylinder: k∥ = (n + m/q)/R₀. The m and m + 1 continua cross at q = −(m + ½)/n, e.g. q = 1.5 for m = 1, n = −1, at the TAE frequency v_A/(2qR₀). In a torus the toroidal coupling of the two harmonics opens a gap there, where toroidal Alfvén eigenmodes live. The continuous-spectrum plot draws the continua over a measured spectrum.

Hall-MHD branches along B, and two Alfvén continua crossing at the TAE frequencyHall-MHD branches along B, and two Alfvén continua crossing at the TAE frequency

hasegawa_wakatani solves the standard linear Hasegawa–Wakatani equations, ∂(∇²φ)/∂t = α(φ − n) and ∂n/∂t = α(φ − n) − κ ∂φ/∂y, with lengths in ρ_s and time in 1/Ω_i. Check the sign convention against your model before comparing growth rates.

Hasegawa–Wakatani growth rates for three adiabaticitiesHasegawa–Wakatani growth rates for three adiabaticities

theory.parameters gives the standard plasma frequencies, lengths, speeds and dimensionless numbers in SI units, checked against the NRL Plasma Formulary. It also gives the units Struphy normalizes with:

parameters.alfven_speed(field=1.0, density=1e20, mass_number=2) # m/s
parameters.debye_length(density=1e19, temperature=100.0) # m, T in eV
units = parameters.struphy_units(
x=1.0, B=1.0, n=1.0, velocity_scale="alfvén", mass_number=1
)
units["t"], units["v"] # Struphy's time and velocity units
# α, ε, λ, κ of a species
parameters.struphy_equation_parameters(units, charge_number=1, mass_number=1)

struphy_units takes the same arguments as Struphy’s BaseUnits and mirrors Units.derive_units, so normalized results can be converted to physical ones and back.

theory.collisions gives the NRL Coulomb logarithm and collision rates, the Spitzer resistivity, and the Stix slowing down of a fast ion on electrons and ions (SI units, temperatures and energies in eV):

n, te = 1e19, 1e3 # m^-3, eV
collisions.coulomb_logarithm(n, te)
collisions.collision_frequencies(n, te) # dict of nu_e, nu_i, nu_ei in 1/s
collisions.spitzer_resistivity(te, density=n) # ohm m
ec = collisions.critical_energy(te, beam_mass_number=2, ion_mass_number=2)
collisions.slowing_down_time(n, te, 2, energy=80e3, critical_energy_ev=ec)
collisions.beam_stopping_fast_ion(80e3, n, te, 2, ion_mass_number=2, time=0.02)
# pitch evolution of the slowing-down ion, and the shielded beam-driven current
beta = collisions.pitch_scattering_exponent(2, ion_mass_number=2)
collisions.pitch_angle_moments(ec, 80e3, ec, beta) # mean, mean_square, width
collisions.beam_driven_current(
1e20, 1.7, 80e3, n, te, 2, ion_mass_number=2, g=0.3
)

The pitch formulas follow from the Lorentz scattering rate and drag of arXiv:2111.11721 (Eq. D2 to D7), checked against an RK4 integration of the moment equations; the shielding factor is 1 - (Z_b/Z_eff)(1 - G) with Sauter’s L31 (bootstrap_coefficient_l31). The Start-Cordey fit for G is not included because its coefficients could not be confirmed.

The Coulomb logarithm and Spitzer resistivity against temperature, and a deuteron slowing downThe Coulomb logarithm and Spitzer resistivity against temperature, and a deuteron slowing down

theory.orbits has the gyromotion, the E×B and grad-B drifts as 3-vectors, and trapped particles in a large-aspect-ratio tokamak with B = B₀/(1 + ε cos θ). That covers the trapped fraction, the trapped–passing boundary, bounce and transit frequencies, and banana widths:

orbits.gyroradius(perpendicular_speed=1.0, field=1.0)
# B, grad_B: arrays with a last axis of 3
orbits.grad_b_drift(1.0, B, grad_B, charge=1.0, mass=1.0)
orbits.trapped_fraction(0.3)
kappa2 = orbits.trapping_parameter(
orbits.pitch_parameter(0.2, epsilon=0.1), epsilon=0.1
)
orbits.bounce_frequency(
1.0, kappa2, epsilon=0.1, safety_factor=2.0, major_radius=3.0
)

The trapped fraction against ε, and the bounce frequency across the trapped regionThe trapped fraction against ε, and the bounce frequency across the trapped region

theory.magnetron has the crossed-field results used for magnetron spokes, in SI units: the Hull cutoff of planar and coaxial gaps, Brillouin flow, Hall parameter, critical ionisation velocity, E×B speed, and the Simon–Hoh and gradient-drift modes (growth rate and phase velocity), and the lower-hybrid drift / modified two-stream root:

magnetron.hull_cutoff(voltage=300.0, anode_radius=0.06, cathode_radius=0.01)
magnetron.critical_ionisation_velocity(100.0, mass_number=39.948)
k = 2 * 3.14159 / 0.05
magnetron.gradient_drift_phase_velocity(k, 1e4, 0.05, 0.01, 3.0, 39.948)
magnetron.gradient_drift_growth(k, 1e4, 0.05, 0.01, 3.0, 39.948)
magnetron.lower_hybrid_drift(
1326.0, 0.02, 1e17, 10.0, 10.0, -1e4, 0.0, 131.293, 0.0, 3e3
)

The Hull cutoff, the critical ionisation velocity against the E×B drift, and the gradient-drift modeThe Hull cutoff, the critical ionisation velocity against the E×B drift, and the gradient-drift mode

theory.beams has the perveance (A/V^1.5 and the dimensionless generalized one), the Child–Langmuir current through an aperture, KV rms envelopes (closed form in a drift, RK4 with space charge and focusing), thermal beam divergence, the Pierce angle, the Davisson–Calbick aperture lens, the emittance growth of a non-uniform beam from its field energy, and beam attenuation:

beams.child_langmuir_aperture(30e3, 5e-3, 4e-3, mass=parameters.proton_mass)
K = beams.perveance(1.0, 30e3, mass=parameters.proton_mass, kind="generalized")
x, slope = beams.kv_envelope_ode(
np.linspace(0, 2, 5), 2e-3, 0.0, emittance=1e-6, perveance=K
)
beams.emittance_growth_space_charge(0.154, 0.2)
beams.neutral_beam_attenuation(1e19, 1e-20, length=5.0)

A beam envelope with and without space charge, the Child–Langmuir limit of an aperture, and beam attenuationA beam envelope with and without space charge, the Child–Langmuir limit of an aperture, and beam attenuation

theory.exact has exact solutions to verify runs. Most take (x, t) first, so they work as reference= of the profile plots:

FunctionSolution
riemann_euler, sod_shock_tube, star_statethe Euler Riemann problem, including vacuum
dam_breakRitter’s dam break on a dry bed
heat_kerneldiffusion (also of a magnetic field, or of momentum by viscosity)
advected, dalembertadvection and waves
pressureless, pressureless_eulerian, caustic_timepressureless flow and its caustics (Zel’dovich)
sod = exact.sod_shock_tube(x, 0.2) # .density, .velocity, .pressure
rho.plasma.plot.lineout(
x="eta1", t=-1, reference=lambda x, t: exact.sod_shock_tube(x, t).density
)
exact.caustic_time(lambda q: -0.5 * np.sin(q), q) # first shell crossing

The Sod shock tube and a dam breakThe Sod shock tube and a dam break

theory.equilibria has exact equilibria whose force balance ∇p = J × B a MHD code can be checked against. The profile functions take the coordinates first, so a field of the result works as reference=:

FunctionEquilibrium
harris_sheet, harris_drift_speedHarris current sheet B₀ tanh(z/L), n₀ sech²(z/L), with its vector potential
bennett_pinchBennett z-pinch, n₀/(1 + r²/a²)², with μ₀I² = 8πN k(Tₑ + Tᵢ)
solovev, solovev_coefficients, solovev_boundary, solovev_axis, solovev_safety_factor_axisSolov’ev tokamak with a D-shaped boundary (ε, κ, δ), after Cerfon and Freidberg
lundquist_field, taylor_statelinear force-free field J₀, J₁ and the Taylor state
s = equilibria.solovev(
R,
Z,
r0=1.7,
epsilon=0.32,
kappa=1.7,
delta=0.33,
a_param=-0.155,
psi0=0.4,
b0=2.5,
) # .psi, .b_r, .b_z, .pressure
equilibria.harris_sheet(z, 0.01, 1.0, 5.0, 5.0).density
equilibria.solovev_safety_factor_axis(0.32, 1.7, 0.33, -0.155, 0.4, 1.7, 2.5)

The pressure balance of a Harris sheet, a Bennett pinch, the pressure and flux surfaces of a Solov'ev tokamak, and the F–Θ curve of the Taylor stateThe pressure balance of a Harris sheet, a Bennett pinch, the pressure and flux surfaces of a Solov'ev tokamak, and the F–Θ curve of the Taylor state

theory.numerics tells what errors the numerics themselves produce, so a measured drift or frequency error can be judged:

  • the amplification factor, amplitude and phase errors and stability limits of time integrators (explicit and implicit Euler, implicit midpoint, Störmer–Verlet, RK2–RK4)
  • the numerical dispersion of B-spline Galerkin finite elements, as in Struphy’s discrete de Rham complex
numerics.phase_error(omega * dt, "implicit_midpoint") # ≈ −(ωΔt)²/12
# the complex frequency the scheme produces
numerics.numerical_frequency(omega, dt, "rk4")
numerics.stability_limit("rk4") # the largest stable ωΔt, 2√2
# ω of the discrete wave equation
numerics.spline_galerkin_dispersion(k, dx, degree=3)

Phase errors of time integrators, and the numerical dispersion of spline finite elementsPhase errors of time integrators, and the numerical dispersion of spline finite elements

theory.sheaths has the low-pressure and bounded-plasma results, in SI units (m⁻³, eV, V, m): Bohm speed and current, floating potential (with secondary emission), Child–Langmuir and matrix sheath widths, space-charge-limited flow in planar, coaxial and spherical diodes, OML probes and the ion saturation current, ambipolar and Bohm diffusion, Paschen breakdown, and mean free paths.

sheaths.bohm_current_density(1e18, 5.0) # A/m², hydrogen, 5 eV
sheaths.floating_potential(5.0, mass_number=40) # V, argon wall
# planar, any charge and mass; optional injection speed
sheaths.child_langmuir(1e4, 1e-2, mass=parameters.proton_mass)
# coaxial or spherical; tends to child_langmuir as r_a/r_c -> 1
sheaths.langmuir_blodgett(1e3, 5e-3, 1e-3, geometry="cylindrical")

Langmuir–Blodgett against Child–Langmuir flow, Paschen curves, and an OML probe characteristicLangmuir–Blodgett against Child–Langmuir flow, Paschen curves, and an OML probe characteristic

theory.negative_ions has analytic references for H⁻ sources: the detachment and mutual-neutralization cross sections as fitted by Janev, Reiter and Samm (Jül-4105) with their Maxwellian rate coefficients, the Debye length and the Braithwaite–Allen Bohm speed of an electron–H⁻–H⁺ plasma with the H⁻ fraction α = n₋/nₑ and γ = Tₑ/T₋, the survival of an H⁻ beam in H₂ and H gas (through beams.neutral_beam_attenuation), and the current from a surface-production flux. Cross sections are used as printed in the source and are not clipped outside its fit range.

negative_ions.electron_detachment_rate_coefficient(1.0) # m³/s, Tₑ = 1 eV
negative_ions.mutual_neutralization_rate_coefficient(1.0) # m³/s, 1 eV ions
# m/s, α = 1, T₋ = 1 eV
negative_ions.bohm_speed_electronegative(5.0, 1.0, 1.0)
negative_ions.beam_survival_fraction(50e3, h2_density=2.4e18, length=0.5)

The Struphy examples and the analytic results to compare them with:

ExamplesTheory
Langmuir wave dispersion, weak and strong Landau dampingkinetic.langmuir, bohm_gross, landau_damping_weak
Two-stream and bump-on-tail instabilitieskinetic.two_stream, two_stream_cold, bump_on_tail, maximum_growth
Any set of drifting Maxwellianskinetic.electrostatic_growth
Weibel instabilitykinetic.weibel
Electron cyclotron drift instability (MHz spoke-related modes)kinetic.electron_cyclotron_drift
Maxwell light-wave dispersion, cavity resonanceswaves.light_wave, cavity_modes
Cold-plasma oscillation, wave packets, waves along a magnetic fieldwaves.cold_plasma_waves, stix, group_velocity
Ordinary waves and the plasma cutoff, Faraday rotationwaves.plasma_light_wave, cutoffs, faraday_rotation
MHD waves in a slab, shear-Alfvén dispersion, standing shear-Alfvén wavewaves.mhd_waves, magnetosonic_speeds
Resistively damped, viscous and resistive Alfvén waveswaves.dissipative_alfven
Whistler and ion-cyclotron waves in Hall MHDwaves.hall_mhd_parallel
Toroidal shear-Alfvén waveswaves.alfven_continuum, tae_frequency
Hasegawa–Wakatani drift-wave turbulencewaves.hasegawa_wakatani, drift_wave
Gyromotion, grad-B driftorbits.gyrofrequency, gyroradius, grad_b_drift
Guiding-center and Vlasov orbits in a tokamakorbits.trapped_fraction, bounce_frequency, transit_frequency, banana_width
Resistive diffusion of a magnetic fieldexact.heat_kernel (a mode decays as exp(−ηk²t))
Acoustic pulseexact.dalembert
Gas expansion into vacuumexact.riemann_euler (with a vacuum state)
Dam breakexact.dam_break
Zel’dovich caustic, pressureless density transportexact.pressureless, caustic_time, advected
Random and deterministic particle diffusion, SPH velocity diffusionexact.heat_kernel (spread 2Dt)
Incompressible shear relaxationexact.heat_kernel (a shear mode decays as exp(−νk²t))
Structure preservation in time integrationnumerics.amplification_factor, phase_error, numerical_frequency
Every run: physical unitsparameters.struphy_units