Skip to content

Architecture Map

High-level flow

At a high level, GUERNICA advances a neutral distribution function \(f_n(\mathbf{x}, \mathbf{v}, t)\) using:

  • Disonctinous Galerkin (DG) in configuration space \(\mathbf{x}\)
  • Discrete Velocity Method (DVM) in \(\mathbf{v}\)
  • a collection of operators (advection, charge exchange, ionization, BGK) combined into the RHS

Conceptually:

  1. Build mesh + DG finite element space (in \(\mathbf{x}\))
  2. Define velocity grid \(\{\mathbf{v}_{i}\}_{i=1}^{N_v}\)
  3. Store one DG field per velocity point (or an equivalent packed layout)
  4. Evaluate the RHS as a sum of operators
  5. Advance in time

State representation (what is the “unknown”?)

The unknown is the neutral distribution \(f_n \equiv f\) sampled on:

  • DG basis functions in \(\mathbf{x}\)
  • discrete velocity grid points in \(\mathbf{v}\)

A useful mental model is:

  • For each velocity index \(i\), there is a DG field \(f_i(\mathbf{x}, t)\)
  • The full state is \(\{ f_i \}_{i=1}^{N_v}\)

Notes on layout

Implementation may store this either as:

  • a vector of GridFunctions (one per velocity), or
  • a packed array with an explicit layout (e.g., element-major with a velocity “slab” dimension)

Implementation in GUERNICA

Main driver

  • guernica.cxx

Layout

  • LayoutOperator.hxx / LayoutOperator.cxx — element-major storage, plus scatter/gather to MFEM-style velocity-major views

Velocity grid + moments

  • VelocityIntegrate.hxx / VelocityIntegrate.cxx — moment integrals (density, momentum, temperature), other velocity-space reductions

Operators (model terms → code units)

GUERNICA’s RHS is organized as a sum of operators. At the documentation level we treat each as a module:

  • Advection (DG in \(\mathbf{x}\))
  • Charge exchange
  • Ionization
  • BGK / ES-BGK (neutral-neutral model collisions)

Each operator typically:

  • consumes the current state \(f\)
  • may require background plasma inputs (e.g., \(n_i, \mathbf{u}_i, T_i\))
  • produces a contribution to \(\partial f / \partial t\)

Implementation in GUERNICA

Advection (DG in configuration space)

  • DG_Advection.hxx / DG_Advection.cxx — 1D advection (mostly partial assembly)
  • DG_Advection2D.hxx / DG_Advection2D.cxx — 2D advection (PA / matrix-free with sum factorization)

Charge exchange

  • ChargeExchangeOperator.hxx / ChargeExchangeOperator.cxx — 1V CX (simple test case)
  • ChargeExchangeFull.hxx / ChargeExchangeFull.cxx — 3V CX (direct numerical integration)
  • ChargeExchangeMeier.hxx / ChargeExchangeMeier.cxx — 3V CX (Meier approximation)
  • ChargeExchangeFFT.hxx / ChargeExchangeFFT.cxx — 3V CX (FFT-based)

Ionization

  • IonizationOperator.hxx / IonizationOperator.cxx — 3V ionization

Neutral-neutral model collisions

  • BGKOperator.hxx / BGKOperator.cxx — BGK neutral-neutral collisions

Sources

  • MaxwellianSourceOperator.hxx / MaxwellianSourceOperator.cxx — inject Maxwellian source terms

Operator summation

  • SumTDep.hxx / SumTDep.cxx — combines multiple time-dependent operators into one RHS

Time integration

GUERNICA can be understood in two modes:

Time-dependent

Advance: \( \frac{\partial f}{\partial t} = \mathcal{R}(f) \) using explicit time integration, where \(\mathcal{R}\) is the sum of operator contributions.

Implementation in GUERNICA

Time stepping / evolution

  • guernica.cxx — sets up the RHS and advances in time (via MFEM ODE solver or your stepping logic)

RHS assembly

  • SumTDep.hxx / SumTDep.cxx — the place where “RHS = advection + CX + ionization + BGK + sources” becomes concrete

Inputs and outputs

Typical inputs:

  • geometry / mesh
  • velocity grid definition
  • plasma background fields (\(n_i, \mathbf{u}_i, T_i\)) and reaction rates / cross sections
  • boundary conditions and sources

Typical outputs:

  • neutral moments: density, momentum/flow, temperature, reaction source terms
  • saved fields for \(f_i(\mathbf{x})\) (optional / heavy)

Implementation in GUERNICA

Input

  • InputConfig.hxx / InputConfig.cxx — reads/validates runtime parameters

Outputs

  • VelocityIntegrate.hxx / VelocityIntegrate.cxx — computes moments for output/coupling
  • LayoutOperator.hxx / LayoutOperator.cxx — converts between element-major storage and MFEM-friendly views for writing/visualization
  • guernica.cxx — orchestrates file output (fields, moments, diagnostics)