Skip to content

Inputs & Outputs

This page describes what GUERNICA requires to run (inputs) and what it writes to disk (outputs). Build instructions and deployment are documented elsewhere.

Inputs

Configuration file: input.cfg

GUERNICA is configured via a key–value input file (typically input.cfg). This file controls the mesh, DG order, velocity-space discretization, enabled physics operators, runtime parameters and output cadence.

Note

The input interface is intentionally lightweight at present. Future extensions are expected to include explicit plasma profile inputs and more flexible specification of neutral initial conditions.

Configuration-space geometry (mesh/)

The configuration-space geometry is defined by a mesh file, typically stored under the mesh/ directory.

  • GUERNICA relies on MFEM for mesh handling and DG discretization.
  • Any mesh format supported by MFEM may be used.

  • In practice, GUERNICA commonly uses:

  • MFEM-native .mesh files

  • Gmsh .msh files

The mesh may be one- or two-dimensional and may be nonuniform, with refinement near material boundaries or recycling regions.

Implementation in GUERNICA

  • Mesh loading and DG space construction are handled through MFEM.
  • Mesh setup occurs in guernica.cxx.

Spatial discretization

The spatial discretization order is set by:

  • order: polynomial degree \(p\) of the DG basis

Details of the DG formulation, numerical fluxes and partial assembly are described in the Numerics section.

Velocity-space grid (DVM)

Velocity space is discretized using the discrete velocity method (DVM) on a uniform Cartesian grid in three velocity dimensions.

User-defined inputs include:

  • num_vel_x, num_vel_y, num_vel_z: number of discrete velocities
  • vxmin/vxmax, vymin/vymax, vzmin/vzmax: velocity bounds

The velocity domain is chosen large enough to capture the support of the neutral distribution function, typically extending several thermal speeds from the bulk flow.

Macroscopic moments and collision operators are evaluated using Simpson–Cotes quadrature on this uniform grid.

Implementation in GUERNICA

  • Velocity grids and quadrature weights are constructed in VelocityIntegrate.
  • The same quadrature is used consistently for moment evaluation and collision operators.

Plasma background fields

Plasma quantities are treated as externally prescribed fields and are assumed fixed in time.

Required plasma inputs include: - electron density \(n_e(\mathbf{x})\) - ion density \(n_i(\mathbf{x})\) - electron temperature \(T_e(\mathbf{x})\) - ion temperature \(T_i(\mathbf{x})\) - ion flow velocity \(\mathbf{u}_i(\mathbf{x})\)

Note

Plasma background fields are currently hard coded in the solver and are not specified through the input file. Support for externally provided plasma profiles is planned for future revisions.

Implementation in GUERNICA

  • Plasma quantities enter the solver through the ionization and charge exchange operators.
  • Coupling to the plasma background is orchestrated in guernica.cxx.

Atomic physics models

GUERNICA requires atomic physics data describing plasma–neutral interactions, including:

  • Maxwellian-averaged ionization rate coefficients
  • charge-exchange cross sections as functions of relative speed

The charge exchange model is selected via input parameters and may trade accuracy for performance.

Implementation in GUERNICA

  • Ionization: IonizationOperator

  • Charge exchange:

    • ChargeExchangeOperator (1V)
    • ChargeExchangeFull
    • ChargeExchangeMeier
    • ChargeExchangeFFT

Initial conditions (problem)

The problem parameter selects a predefined initial condition for the neutral distribution function.

Note

The problem parameter controls initial conditions only. Plasma background fields are not affected by this setting.

This mechanism is primarily intended for verification and benchmark problems.

Inflow boundary sources (inflow)

The inflow parameter enables predefined source boundary conditions that inject neutrals into the domain.

Supported values:

  • 0 : no inflow source
  • 1 : inflow source for the 1X1V test case
  • 2 : inflow source for the 1X3V Bernard benchmark case

These inflow sources are implemented as boundary source terms and are primarily used for validation and benchmarking.

Runtime and control parameters

Additional input parameters include:

  • t_final : final simulation time
  • dt : time step size
  • vis_steps : output cadence (every N time steps)
  • precision : numerical precision used when writing output files
  • device : execution backend (e.g. cpu, cuda)
  • display : runtime logging and progress output

Warning

The parameter ode_solver_type is deprecated and has no effect. GUERNICA currently uses SSP–RK3 internally.

Outputs

GUERNICA writes MFEM-compatible output files intended for post-processing, visualization and verification.

Mesh snapshot

A copy of the mesh is written for reference:

  • ex9.mesh

Field outputs (gf_out/)

Most simulation outputs are written to the gf_out/ directory as MFEM GridFunction files (.gf).

Neutral macroscopic moments

The primary outputs are macroscopic moments of the neutral distribution function:

  • neutral density
  • momentum density components
  • total energy density

These quantities are used for diagnostics, validation against Monte Carlo solvers and eventual coupling back to plasma simulations.

Typical files include:

  • rho-<step>.gf
  • rho_ux-<step>.gf
  • rho_uy-<step>.gf
  • rho_uz-<step>.gf
  • E-<step>.gf

Implementation in GUERNICA

  • Velocity moments are computed in VelocityIntegrate.
  • Layout conversion for output uses LayoutOperator.

Neutral distribution function (conditional)

In some cases, GUERNICA writes the full neutral distribution function sampled at discrete velocities as DG fields.

Note

Output of the full neutral distribution function is not currently controlled through the input file. It is written automatically in certain cases, including:

  • simulations with vDim != 3
  • two-dimensional configuration-space simulations

This behavior exists for convenience during development and validation and may be replaced by an explicit input option in the future.

Because of its size, output of the full distribution function is typically restricted to reduced-dimension test cases.

BGK diagnostics (when enabled)

When the BGK operator is active, GUERNICA writes additional diagnostics tracking conserved quantities and entropy:

  • moment.gf

This file includes the time evolution of mass, momentum components, total energy and kinetic entropy and is primarily used for verification studies.

Layout and data movement for output

Internally, GUERNICA stores the neutral distribution function in an element-major memory layout for performance reasons. For each configuration- space element, all discrete velocity values are stored contiguously, with element-local DG degrees of freedom as the innermost index.

To produce MFEM-native output fields, controlled data movement is used:

  • Scatter: extract a single velocity slab from the element-major distribution function into an MFEM GridFunction
  • Gather: inject an MFEM GridFunction back into the element-major distribution function at a specified velocity index

Implementation in GUERNICA

  • Scatter/gather operations are implemented in LayoutOperator.
  • This design preserves efficient element-local kernels while allowing standard MFEM output and visualization.

Note

Several runtime behaviors described here—such as distribution function output and plasma background specification—are currently implicit in the code and may be exposed as explicit input options in future revisions.