VFP-1D Configuration Reference

This document describes how to construct a configuration file for the vfp-1d solver.

Top-Level Structure

solver: vfp-1d

units:
  # Physical unit normalizations

density:
  # Species definitions

grid:
  # Simulation grid parameters

save:
  # Output configuration

mlflow:
  # Experiment tracking

drivers:
  # External drivers

terms:
  # Solver configuration

units

Physical unit normalizations for the simulation.

Field	Type	Description
`laser_wavelength`	string	Laser wavelength with unit, e.g., `"351nm"`
`reference electron temperature`	string	Reference electron temperature with unit, e.g., `"3000eV"`
`reference ion temperature`	string	Reference ion temperature with unit, e.g., `"300eV"`
`reference electron density`	string	Reference electron density with unit, e.g., `"2.275e21/cm^3"`
`Z`	int	Ionization state
`Ion`	string	Ion species label, e.g., `"Au+"`
`logLambda`	string or float	Coulomb logarithm: `"nrl"` (NRL formulary), `"lee-more"` (Lee & More 1984: \(\ln\Lambda = \max[2, \tfrac{1}{2}\ln(1 + b_\max^2/b_\min^2)]\) with Debye-Hückel screening floored at the ion-sphere radius and quantum/classical \(b_\min\)), or a numeric value

Example:

units:
  laser_wavelength: 351nm
  reference electron temperature: 3000eV
  reference ion temperature: 300eV
  reference electron density: 2.275e21/cm^3
  Z: 6
  Ion: Au+
  logLambda: nrl

density

Species and density configuration. Multiple species are supported via keys prefixed with species-.

Field	Type	Description
`quasineutrality`	bool	Whether to enforce quasineutrality

Species Definition

Each species is defined with a key starting with species- (e.g., species-background, species-hote).

Field	Type	Description
`noise_seed`	int	Random seed for noise initialization
`noise_type`	string	`"gaussian"` or `"uniform"`
`noise_val`	float	Amplitude of noise
`v0`	float	Drift velocity (normalized)
`T0`	float	Temperature (normalized to reference temperature)
`m`	float	Super-Gaussian exponent. `2.0` is Maxwellian
`n`	object	Density spatial profile (see Basis Types)
`T`	object	Temperature spatial profile (see Basis Types)

Basis Types

Each of n and T has a basis field that determines the spatial profile.

uniform: Constant profile

n:
  basis: uniform
  baseline: 1.0
  bump_or_trough: bump
  center: 0m
  rise: 1m
  bump_height: 0.0
  width: 1m

sine: Sinusoidal perturbation

T:
  basis: sine
  baseline: 1.0
  amplitude: 1.0e-3
  wavelength: 250um

cosine: Cosine perturbation (useful with reflective BCs where dT/dx=0 at boundaries)

T:
  basis: cosine
  baseline: 1.0
  amplitude: 1.0e-3
  wavelength: 250um

tanh: Hyperbolic tangent profile

T:
  basis: tanh
  baseline: 1.0
  bump_or_trough: bump
  center: 50um
  rise: 5um
  bump_height: 0.1
  width: 20um

file: Tabulated profile from a two-column (coordinate, value) CSV or whitespace-delimited text file. Header rows are skipped automatically; the profile is interpolated onto the grid and clamped to the endpoint values outside the tabulated range. Density values are normalized by units.reference electron density, temperature values by units.reference electron temperature.

n:
  basis: file
  path: /path/to/electrondensity.csv
  units: 1/cm^3          # units of the value column
  coordinate_units: um   # units of the coordinate column (default um)

Ion block (optional)

An optional density.ion block sets a spatially varying ion density and ionization state from a tabulated mass-density profile:

density:
  ion:
    A: 9.0122            # ion mass number (amu)
    mass_density:
      basis: file        # only "file" is supported
      path: /path/to/massdensity.csv
      units: g/cm^3
      coordinate_units: um

This sets \(n_i(x) = \rho(x) / (A \, m_u)\) and \(Z(x) = n_e(x)/n_i(x)\) pointwise. When the block is omitted, \(Z\) is uniform (units.Z) and \(n_i = n_e / Z\).

For atomic mixtures (e.g. fully ionized CD), add a mixture list. The plasma is then represented by a single effective ion species that preserves both quasineutrality (\(Z n_i = n_e\)) and the electron-ion collision rate (\(Z^2 n_i = \sum_i n_i Z_i^2 = Z_\text{eff}\, n_e\)), with \(Z_\text{eff} = \langle Z^2\rangle / \langle Z\rangle\). Set units.Z to \(Z_\text{eff}\) — it is the collisional/transport Z that enters the Epperlein-Haines and SNB coefficients. The mass-density profile is used to cross-check full-ionization quasineutrality (\(\bar{Z}\rho/(A m_u)\) vs \(n_e\)); a warning is printed if they disagree by more than 5%.

density:
  ion:
    A: 6.304                                # mean atomic weight (optional; default sum of fractions * A)
    mixture:
      - { Z: 6, A: 12.011, fraction: 0.4 }  # C
      - { Z: 1, A: 2.0141, fraction: 0.6 }  # D
    mass_density:
      basis: file
      path: /path/to/massdensity.csv
      units: g/cm^3
      coordinate_units: um

grid

Simulation grid parameters. All dimensioned quantities use astropy-style unit strings.

Field	Type	Description
`dt`	string	Timestep with unit, e.g., `"1fs"`
`nv`	int	Number of velocity grid points
`nx`	int	Number of spatial grid cells
`tmin`	string	Start time with unit
`tmax`	string	End time with unit
`vmax`	float	Maximum velocity (normalized to \(c\))
`xmin`	string	Domain minimum x with unit
`xmax`	string	Domain maximum x with unit
`nl`	int	Maximum spherical harmonic order (typically `1`)
`boundary`	string	Spatial boundary condition: `"periodic"` (default) or `"reflective"`
`geometry`	string	Spatial geometry: `"cartesian"` (default) or `"spherical"`

Example:

grid:
  dt: 1fs
  nv: 256
  nx: 32
  tmin: 0.ps
  tmax: 2ps
  vmax: 8.0
  xmin: 0.0um
  xmax: 500um
  nl: 1
  boundary: periodic

Boundary conditions

periodic: Standard periodic wrapping. Suitable for full-wavelength perturbations.
reflective: Zero-flux boundaries. Vector quantities (\(f_{10}\), \(E\)) are zero at domain edges. Scalar quantities (\(f_0\)) use mirror ghost cells. Suitable for half-wavelength (cosine) perturbations where symmetry allows simulating half the domain.

Geometry

cartesian: Planar 1D geometry (default). The spatial coordinate is \(x\).
spherical: Radial 1D geometry with spherical symmetry. The spatial coordinate is the radius \(r\). Requires xmin >= 0 and boundary: reflective (when xmin: 0 the flux through \(r=0\) vanishes by symmetry; xmin > 0 gives an annular domain with a reflecting inner wall; the outer edge is a reflecting wall). Velocity space is unchanged. For \(n_l = 1\) the only modification to the equations is the \(f_0\) advection term becoming a radial divergence,

\[\partial_t f_0 + \frac{v}{3}\frac{1}{r^2}\partial_r \left(r^2 f_{10}\right) = C[f_0], \qquad \partial_t f_{10} + v\, \partial_r f_0 - E\, \partial_v f_0 = C[f_{10}]\]

(the angular coupling term \(\propto (1-\mu^2)/r\) only feeds \(f_2\) into the \(f_{10}\) equation, which is dropped at \(n_l = 1\)). The divergence is discretized in conservative finite-volume form with exact cell volumes \((r_+^3 - r_-^3)/3\).

save

Configures what data to save and at what times.

save:
  fields:
    t:
      tmin: 0.0ps
      tmax: 2.0ps
      nt: 11
  electron:
    t:
      tmin: 0.0ps
      tmax: 2.0ps
      nt: 6

Save Key	Description
`fields`	Fluid moments and electromagnetic fields (\(n\), \(T\), \(U\), \(P\), \(v\), \(q\), \(E\), \(B\))
`electron`	Electron distribution functions (\(f_0\), \(f_{10}\))

Each save key contains a t sub-key with:

Field	Type	Description
`tmin`	string	Start time for saving
`tmax`	string	End time for saving
`nt`	int	Number of save points

mlflow

Experiment tracking configuration.

Field	Type	Description
`experiment`	string	MLflow experiment name
`run`	string	MLflow run name

Example:

mlflow:
  experiment: vfp1d
  run: epperlein-short

drivers

External drivers for heating, cooling, and electromagnetic fields.

drivers:
  ib: {}                    # Inverse Bremsstrahlung heating (optional)
  maxwellian_heating: {}    # Maxwellian heating/cooling (optional)

drivers.ib

Inverse Bremsstrahlung (IB) laser heating. Augments the Fokker-Planck diffusion coefficient \(D\) by \(v_\text{osc}^2 g(v) / (6v)\) where \(g(v) = [1 + (Z^2 n_i / (\omega_0 v^3))^2]^{-1}\) (Ridgers eq 4.39). Drives the distribution toward a Langdon/super-Gaussian shape.

Field	Type	Default	Description
`intensity_1e15_Wcm2`	float	`0.0`	Laser intensity in units of \(10^{15}\) W/cm².
`polarisation`	string or float	`"linear"`	`"linear"` (\(\alpha=1\)), `"circular"` (\(\alpha=1/2\)), or a float in \((0,1]\).

The quiver velocity \(v_\text{osc}^2\) and normalised laser frequency \(\omega_0\) are derived automatically from units.laser_wavelength and units.reference electron temperature:

\[v_\text{osc}^2 = \frac{0.093373}{\alpha} \cdot \frac{I \lambda_0^2}{T_{e0}} \quad \text{(normalised units, } I \text{ in } 10^{15}\text{ W/cm}^2\text{, } \lambda_0 \text{ in } \mu\text{m, } T_{e0} \text{ in keV)}\]

\[\omega_0 = \omega_L / \omega_p = 2\pi c / (\lambda_0 \omega_p)\]

drivers.maxwellian_heating

Maxwellian heating or cooling. Augments \(D\) by \(D_0 v^2\) (Ridgers eq E.2), which changes the temperature while preserving the Maxwellian shape of the distribution.

Field	Type	Default	Description
`D0`	float	`None`	Maxwellian heating/cooling rate (normalised). Positive heats, negative cools.

The heating rate is \(\partial T / \partial t = D_0 / \hat{Z}\) (constant, independent of temperature), where both \(T\) and \(t\) are in normalised units (\(T_0\) and \(1/\omega_p\) respectively). In physical units this corresponds to a volumetric power density \(P/V = n T_0 \omega_p D_0 / \hat{Z}\).

Example:

drivers:
  ib:
    intensity_1e15_Wcm2: 1.0
    polarisation: linear
  # OR for Maxwellian heating:
  # maxwellian_heating:
  #   D0: 0.1

terms

Solver algorithm configuration.

Field	Type	Description
`e_solver`	string	Electric field solver: `"oshun"` or `"ampere"`
`fokker_planck`	object	Fokker-Planck collision operator configuration

e_solver

oshun: Implicit E-field via Taylor expansion of \(J(E)\) (Tzoufras 2013). Recommended for most simulations.
ampere: Explicit Ampere update.

fokker_planck

Configuration for the two collision operators.

fokker_planck.f00

Isotropic (\(f_0\)) collision operator.

Field	Type	Description
`model`	string	Collision model (see below)
`scheme`	string	Differencing scheme: `"central"` or `"chang_cooper"`

Available models:

Model	Description
`CoulombianKernel`	Standard Landau/Rosenbluth operator with kernel \(g(\varepsilon,\varepsilon') = \min(\varepsilon^{3/2}, \varepsilon'^{3/2})\). Default.
`AsymptoticLocal`	Rank-1 kernel \(g(\varepsilon,\varepsilon') = \sqrt{\varepsilon \cdot \varepsilon'}\) from high-velocity limit of linearized collision operator. O(N) computation.
`FastVFP`	Beta-based model with \(D = 1/(2\beta v)\), giving constant drift \(C = 1\). From Bell & Sherlock (2024).

Note: Energy is not conserved for non-Maxwellian distributions with the current Chang-Cooper scheme. A proper Buet weak-form scheme is planned for improved energy conservation.

fokker_planck.flm

Anisotropic (\(f_{lm}\)) collision operator (FLM).

Field	Type	Description
`ee`	bool	Include electron-electron collisions. When `false`, uses \(Z^*\) Epperlein-Haines scaling instead

Example

terms:
  e_solver: oshun
  fokker_planck:
    f00:
      model: CoulombianKernel
      scheme: chang_cooper
    flm:
      ee: true

diagnostics

Optional post-processing diagnostics configuration. The Spitzer-Härm / SNB / kinetic heat-flux comparison always runs during post-processing (it writes plots/fields/heat-flux-comparison.png and binary/heat-flux-comparison.nc, and logs the q_ratio_kinetic_over_sh and q_ratio_snb_over_sh metrics). The diagnostics.snb block tunes the SNB model (Schurtz et al. 2000; the “separated” variant recommended by Brodrick et al. 2017):

Field	Type	Default	Description
`ngroups`	int	`300`	Number of energy groups on the absolute-energy grid \(\varepsilon = v^2/2\) spanning \([0,\ \beta_\text{max}\max(T)]\)
`beta_max`	float	`20.0`	\(\beta = \varepsilon/T\) coverage at the hottest cell (sets the grid’s top energy \(\varepsilon_\text{max} = \beta_\text{max}\max(T)\))
`r`	float	`2.0`	e-e absorption scaling of the group mfp, \(\lambda_g^{ee}/r\)

The energy groups are bands of fixed kinetic energy \(\varepsilon = v^2/2\) (uniform in space), so the multigroup diffusion transports each group at fixed energy — required for the nonlocal preheat to be captured correctly. ngroups needs to be a few hundred because cold cells sample the grid coarsely in \(\beta = \varepsilon/T\); the flux-carrying groups sit at \(\beta \approx 16\), so beta_max \(\gtrsim 20\) keeps them on the grid.

diagnostics:
  snb:
    ngroups: 300
    beta_max: 20.0
    r: 2.0

Complete Examples

Epperlein-Short Heat Transport

See configs/vfp-1d/epp-short.yaml - Epperlein-Short heat transport benchmark with sinusoidal temperature perturbation and multi-species (background + hot electrons).

Hotspot Relaxation

See configs/vfp-1d/hotspot.yaml - Temperature hotspot relaxation with tanh temperature profile.

Spherical Heat Flow from Tabulated Profiles

See configs/vfp-1d/spherical-heatflow.yaml - Radial (spherical) geometry with \(n_e(r)\), \(T_e(r)\), and mass-density profiles loaded from CSV files, set up for a kinetic vs SNB vs Spitzer-Härm heat-flow comparison.