Skip to content

Inputs Reference

All GUERNICA input files use the .cfg extension and are stored in the configs/ directory.

General syntax

  • Input files are INI-style.
  • Sections use [section_name].
  • Entries use key = value.
  • Comments may start with # or ;.
  • Lists such as species, operators, boundaries, and attrs are comma-separated.
  • Booleans may be written as true, false, 1, or 0.

Built-in profile names

The following profile names are always available without defining a [profile:...] section:

  • default_density = 0.0
  • default_temperature = 0.01
  • default_u = 0.0

These built-in defaults are used in many places when a profile reference is omitted.

[time]

Exists when: always

GUERNICA has two run modes. mode = transient advances the solution in physical time with SSP-RK3 until t_final. mode = steady marches in pseudo-time with a locally scaled forward-Euler update until the residual falls below steady_tol or max_iters is reached. See Methods Overview.

Keys

mode

  • Required: no
  • Type: string
  • Default: transient
  • Allowed: transient, steady

dt

  • Required: yes
  • Type: float
  • Default: none
  • In transient mode this is the time step. In steady mode it is the reference pseudo-time step, which is scaled down locally per element and velocity.

t_final

  • Required: yes for mode = transient
  • Type: float
  • Default: 0.0
  • When resuming, this is the additional time to run past the resumed time.

max_iters

  • Required: yes for mode = steady
  • Type: int
  • Default: 0

steady_tol

  • Required: no
  • Type: float
  • Default: 0.0
  • Steady mode only. 0 disables the convergence test, so the run stops at max_iters.

check_every

  • Required: no
  • Type: int
  • Default: 1
  • Steady mode only. How often (in iterations) the convergence test is evaluated.

vis_steps

  • Required: no
  • Type: int
  • Default: 1
  • Output (and, in steady mode, status-line) interval in steps/iterations.

solver

  • Required: no
  • Type: string
  • Default: rk3 for mode = transient, pseudo_euler for mode = steady

resume

  • Required: no
  • Type: bool
  • Default: false

resume_directory

  • Required: no
  • Type: string
  • Default: runs/run

Validation

  • mode must be transient or steady
  • dt > 0
  • vis_steps > 0
  • transient: solver must be rk3, t_final must be present and >= 0
  • steady: solver must be pseudo_euler, max_iters > 0, steady_tol >= 0, check_every > 0

Additional requirements when resume = true

  • resume_directory must exist and be a directory
  • resume_directory/gf_out must exist and be a directory
  • the run being resumed must have written a complete set of distribution slabs (save_dist or save_final_dist)

[grid]

Exists when: always

Keys

mesh_file

  • Required: yes
  • Type: string (path relative to the working directory, e.g. mesh/bernard18.mesh)
  • Default: none

order

  • Required: yes
  • Type: int
  • Default: none

Validation

  • mesh_file must exist
  • order >= 1

[vx], [vy], [vz]

Exist when: always

Each axis is a uniform grid of num points from min to max. An axis with num = 1 has its single node at 0, which is how a 2V problem is set up (usually [vz] num = 1).

Keys

num

  • Required: yes
  • Type: int
  • Default: none

min

  • Required: yes
  • Type: float
  • Default: none

max

  • Required: yes
  • Type: float
  • Default: none

Validation

  • num >= 1 (odd and even counts are both allowed; see Methods Overview for the quadrature used)
  • min < max

[units]

Exists when: optional

Keys

mass_amu

  • Required: no
  • Type: float
  • Default: 1.0
  • Mass of the evolved neutral in amu. It sets the velocity unit v0 = sqrt(e * 1 eV / m) and, through it, the time unit t0 = L0 / v0.

Validation

  • mass_amu > 0
  • charge exchange models Avg, LB and Meier only support mass_amu = 1

[device]

Exists when: optional

Keys

backend

  • Required: no
  • Type: string
  • Default: cpu

Allowed values

  • cpu
  • omp
  • cuda

Validation

  • if present, backend must be one of cpu, omp, or cuda

[output]

Exists when: optional

See Post Processing for what each output contains.

Keys

display

  • Required: no
  • Type: bool
  • Default: true

save_dist

  • Required: no
  • Type: bool
  • Default: false

save_final_dist

  • Required: no
  • Type: bool
  • Default: false

profile

  • Required: no
  • Type: bool
  • Default: false

precision

  • Required: no
  • Type: int
  • Default: 8

track_balance

  • Required: no
  • Type: bool
  • Default: true

operator_timing

  • Required: no
  • Type: bool
  • Default: false
  • Writes a per-operator wall-time table to run.log and operator_timing.txt. It synchronises the device around every operator, so leave it off for production runs.

Validation

  • precision > 0

[plasma_interface]

Exists when: optional. Enables neutral leakage across interior faces between plasma and vacuum element regions (see Boundary Conditions).

Keys

enabled

  • Required: no
  • Type: bool
  • Default: true if the section exists

plasma_attrs

  • Required: yes when enabled
  • Type: comma-separated list of mesh element attributes

vacuum_attrs

  • Required: yes when enabled
  • Type: comma-separated list of mesh element attributes

leakage_fraction

  • Required: no
  • Type: float
  • Default: 0.01

Validation

  • plasma_attrs and vacuum_attrs must be non-empty, valid element attributes, without duplicates, and disjoint
  • at least one interior face must separate a plasma element from a vacuum element
  • leakage_fraction must be finite and > 0
  • species i and e must both be present

[components]

Exists when: simulating more than pure, periodic advection

Keys

species

  • Required: no
  • Type: comma-separated list of strings
  • Default: n

operators

  • Required: no
  • Type: comma-separated list of strings
  • Default: empty list if omitted

boundaries

  • Required: no
  • Type: comma-separated list of strings
  • Default: empty list if omitted

Allowed values

species

  • n
  • e
  • i

Validation:

  • species entries must be unique
  • n must be included

operators

  • ionization
  • recombination
  • charge_exchange
  • source
  • neutral_neutral

Validation:

  • operator entries must be unique

boundaries

Validation:

  • boundary names must be non-empty
  • boundary names must be unique

[e:init], [i:init], [n:init]

Exist when: for each active species in [components] species

Only the neutral n is evolved. [e:init] and [i:init] define the prescribed electron and ion backgrounds (density, temperature, drift) used by the operators; only their profile references matter.

  • If resume = true, [n:init] is skipped during validation.
  • For all init sections, type defaults to maxwellian.

Common profile-reference defaults

Where applicable:

  • density defaults to default_density
  • temperature defaults to default_temperature
  • ux, uy, uz default to default_u

type = maxwellian

Keys

density

  • Required: no
  • Default: default_density

temperature

  • Required: no
  • Default: default_temperature

ux

  • Required: no
  • Default: default_u

uy

  • Required: no
  • Default: default_u

uz

  • Required: no
  • Default: default_u

Validation

  • all referenced profiles must exist and be valid

type = constant_velocity

Keys

density

  • Required: no
  • Default: default_density

Validation

  • referenced density profile must exist and be valid

type = single_velocity

Keys

density

  • Required: no
  • Default: default_density

vx

  • Required: no
  • Default: ([vx].num - 1) / 2

vy

  • Required: no
  • Default: ([vy].num - 1) / 2

vz

  • Required: no
  • Default: ([vz].num - 1) / 2

Validation

  • referenced density profile must exist and be valid
  • 0 <= vx < [vx].num
  • 0 <= vy < [vy].num
  • 0 <= vz < [vz].num

type = bimaxwellian

Keys

density

  • Required: no
  • Default: default_density

temperature

  • Required: no
  • Default: default_temperature

ux

  • Required: no
  • Default: default_u

uy

  • Required: no
  • Default: default_u

uz

  • Required: no
  • Default: default_u

axis

  • Required: no
  • Default: vx

separation

  • Required: no
  • Default: 0.0

Validation

  • all referenced profiles must exist and be valid
  • axis must be vx or vy
  • separation >= 0
  • produces two shifted Maxwellian populations along the specified axis

type = perturbed_maxwellian

A Maxwellian multiplied by a moment-neutral anisotropic factor,

f(x, v) = fM(x, v) * [1 + p(x) * xi(v)]
xi(v)   = [(vx - ux)^2 - (vy - uy)^2] / (2 T)

where p is an ordinary spatial profile. Under the Maxwellian weight xi integrates to zero against 1, v and |v|^2, so the perturbation carries no mass, momentum or energy and a collision operator must damp it without moving any of the five invariants. This is the initial condition of the neutral-neutral verification problem; see configs/bgk_verification.cfg.

Keys

density

  • Required: no
  • Default: default_density

temperature

  • Required: no
  • Default: default_temperature

ux

  • Required: no
  • Default: default_u

uy

  • Required: no
  • Default: default_u

uz

  • Required: no
  • Default: default_u

perturbation

  • Required: yes
  • Default: none
  • The spatial profile p(x) above. It is a signed amplitude, not a magnitude: 1 + p * xi must stay positive, which for a cosine of amplitude eps means keeping eps small compared with one.

Validation

  • all referenced profiles must exist and be valid
  • perturbation must be present and name an existing profile

[profile:<name>]

Exists when: a non-built-in profile reference is used, or whenever you want to define reusable spatial data

Supported profile types

  • constant
  • affine
  • symmetric_sech2
  • rational_linear
  • gaussian
  • radial_component
  • radial_symmetric_sech2
  • radial_affine
  • radial_rational_linear
  • radial_tanh
  • symmetric_sin2
  • cosine
  • cosine_bump
  • file_rectilinear_2d
  • file_boundary_linear_2d (boundary conditions only)

Unless stated otherwise, one-dimensional profiles are functions of the first coordinate x.

type = constant

Keys

value

  • Required: yes
  • Default: none

type = affine

Keys

offset

  • Required: yes
  • Default: none

slope

  • Required: yes
  • Default: none

x0

  • Required: yes
  • Default: none

type = symmetric_sech2

Keys

amplitude

  • Required: yes
  • Default: none

left

  • Required: yes
  • Default: none

right

  • Required: yes
  • Default: none

width

  • Required: yes
  • Default: none

floor

  • Required: yes
  • Default: none

type = rational_linear

Keys

numerator

  • Required: yes
  • Default: none

denominator_slope

  • Required: yes
  • Default: none

denominator_offset

  • Required: yes
  • Default: none

type = gaussian

Keys

amplitude

  • Required: yes
  • Default: none

sigma

  • Required: yes
  • Default: none

x_shift

  • Required: no
  • Default: 0.0

y_shift

  • Required: no
  • Default: 0.0

z_shift

  • Required: no
  • Default: 0.0

Validation

  • sigma > 0

type = cosine

offset + amplitude * cos(2 pi [(x - x0) / wavelength + (y - y0) / wavelength_y]). Without wavelength_y it is a function of the first coordinate only; with it, the wave runs obliquely (used by the exact-solution verification on distorted meshes).

Keys

amplitude

  • Required: yes
  • Default: none

wavelength

  • Required: no
  • Default: 1.0

x0

  • Required: no
  • Default: 0.0

offset

  • Required: no
  • Default: 0.0

wavelength_y

  • Required: no
  • Default: none (no y dependence)

y0

  • Required: no
  • Default: 0.0

Validation

  • wavelength > 0, and wavelength_y > 0 when given
  • amplitude and offset must be finite

type = cosine_bump

amplitude * cos(pi (x - center) / width)^power for |x - center| < width / 2, zero elsewhere: a compactly supported bump in the first coordinate with power - 1 continuous derivatives at its ends. Useful as a spatially varying wall-emission amplitude (alpha) over part of a boundary.

Keys

amplitude

  • Required: yes

center

  • Required: yes

width

  • Required: yes

power

  • Required: no
  • Default: 2

Validation

  • amplitude >= 0, width > 0, power >= 1

type = symmetric_sin2

(A - floor) * exp(-sin^2(pi (x - x0) / L) / sigma) + floor

Keys

A

  • Required: yes

L

  • Required: yes

sigma

  • Required: yes

floor

  • Required: yes

x0

  • Required: no
  • Default: 0.0

Validation

  • L > 0, sigma > 0; A, floor, x0 finite

type = file_rectilinear_2d

Bilinear interpolation of a value tabulated on a rectilinear (x, y) grid read from a text file. The file is whitespace- or comma-separated; the first non-blank line (optionally starting with #) is a header naming the columns, and every (x, y) pair of the tensor grid must appear exactly once. Files used by a run are copied into <run>/profile_files/.

Keys

path

  • Required: yes

value_column

  • Required: yes

x_column

  • Required: no
  • Default: x

y_column

  • Required: no
  • Default: y

interpolation

  • Required: no
  • Default: bilinear (only allowed value)

outside

  • Required: no
  • Default: error (only allowed value): points outside the table are an error

zero_is_outside

  • Required: no
  • Default: false
  • Treat zero-valued table entries as outside the mapped geometry: they are dropped from the bilinear stencil, and a point whose whole stencil is zero is outside.

extrapolate

  • Required: no
  • Default: none
  • nearest returns the nearest nonzero table value for points outside the mapped geometry. Requires zero_is_outside = true.

min

  • Required: no
  • Default: none
  • If given, the result is clamped to at least this value.

type = file_boundary_linear_2d

A profile defined only on boundary faces, for spatially varying wall data in [boundary:<name>]. Each row gives one endpoint of one boundary face; the value is interpolated linearly along the face. Faces are matched to mesh boundary faces by endpoint coordinates, and every face of the boundary must be matched. This type cannot be used for init, source, or recombination profiles.

Keys

path

  • Required: yes

value_column

  • Required: yes

face_column

  • Required: no
  • Default: face (integer face id in the file)

endpoint_column

  • Required: no
  • Default: endpoint (0 or 1)

x_column, y_column

  • Required: no
  • Default: x, y

interpolation

  • Required: no
  • Default: face_linear (only allowed value)

match_tolerance

  • Required: no
  • Default: 1e-8

type = radial_component

Keys

component

  • Required: yes
  • Type: string

offset

  • Required: no
  • Default: 0.0

slope

  • Required: yes
  • Default: none

r0

  • Required: no
  • Default: 0.0

x_center

  • Required: no
  • Default: 0.0

y_center

  • Required: no
  • Default: 0.0

z_center

  • Required: no
  • Default: 0.0

Validation

  • component must be x, y, or z

type = radial_symmetric_sech2

Keys

amplitude

  • Required: yes
  • Default: none

center

  • Required: yes
  • Default: none

width

  • Required: yes
  • Default: none

floor

  • Required: yes
  • Default: none

x_center

  • Required: no
  • Default: 0.0

y_center

  • Required: no
  • Default: 0.0

z_center

  • Required: no
  • Default: 0.0

Validation

  • width > 0

type = radial_affine

Keys

offset

  • Required: yes
  • Default: none

slope

  • Required: yes
  • Default: none

r0

  • Required: yes
  • Default: none

x_center

  • Required: no
  • Default: 0.0

y_center

  • Required: no
  • Default: 0.0

z_center

  • Required: no
  • Default: 0.0

type = radial_rational_linear

Keys

numerator

  • Required: yes
  • Default: none

denominator_slope

  • Required: yes
  • Default: none

denominator_offset

  • Required: yes
  • Default: none

r0

  • Required: yes
  • Default: none

x_center

  • Required: no
  • Default: 0.0

y_center

  • Required: no
  • Default: 0.0

z_center

  • Required: no
  • Default: 0.0

type = radial_tanh

Keys

floor

  • Required: yes
  • Default: none

height

  • Required: yes
  • Default: none

center

  • Required: yes
  • Default: none

width

  • Required: yes
  • Default: none

x_center

  • Required: no
  • Default: 0.0

y_center

  • Required: no
  • Default: 0.0

z_center

  • Required: no
  • Default: 0.0

Validation

  • width != 0

[ionization]

Exists when: should be included when ionization appears in [components] operators

Keys

model

  • Required: no
  • Default: constant
  • Allowed: constant, Voronov

nu0

  • Required: no
  • Default: 10.928693196885557
  • Normalized ionization frequency, used only by model = constant

plasma_species

  • Required: no
  • Default: e

neutral_species

  • Required: no
  • Default: n

Validation

  • if [ionization] exists but ionization is not enabled in [components] operators, validation fails
  • model must be constant or Voronov
  • nu0 > 0
  • plasma_species must be e
  • neutral_species must be n
  • species e must be present in [components] species

[recombination]

Exists when: should be included when recombination appears in [components] operators

Keys

model

  • Required: no
  • Default: Janev1987
  • Allowed: Janev1987, prescribed

neutral_species

  • Required: no
  • Default: n

Keys for model = Janev1987 only:

levels

  • Required: no
  • Default: 1s
  • Allowed: 1s, total

n_max

  • Required: no
  • Default: 500
  • Highest principal quantum number summed when levels = total

electron_species, ion_species

  • Required: no
  • Default: e, i

Keys for model = prescribed only:

rate

  • Required: yes
  • Profile name for the normalized volumetric recombination rate

temperature, ux, uy, uz

  • Required: no
  • Default: default_temperature, default_u
  • Profiles for the Maxwellian of the newly formed atoms

Validation

  • if [recombination] exists but recombination is not enabled, validation fails
  • neutral_species must be n
  • Janev1987: levels must be 1s or total; total requires n_max >= 3; species e and i must be present; rate, temperature, ux, uy, uz are not allowed
  • prescribed: rate is required; all profiles must be valid point profiles; levels, n_max, electron_species, ion_species are not allowed

[charge_exchange]

Exists when: should be included when charge_exchange appears in [components] operators

Keys

model

  • Required: no
  • Default: FFT

sigma

  • Required: no
  • Default: Krstic

plasma_species

  • Required: no
  • Default: i

neutral_species

  • Required: no
  • Default: n

use_fp32

  • Required: no
  • Default: true
  • FFT only. Run the FFTs in single precision.

batch_chunk

  • Required: no
  • Default: 512
  • FFT only. Maximum number of spatial degrees of freedom transformed per batched FFT call; lower it to reduce device memory.

Allowed model values

  • FFT (CUDA builds only)
  • Full
  • LB
  • Avg
  • Meier

Allowed sigma values

  • Krstic
  • Janev-Smith

Validation

  • if [charge_exchange] exists but charge_exchange is not enabled in [components] operators, validation fails
  • model must be one of FFT, Full, LB, Avg, Meier
  • if sigma is explicitly specified, model must be FFT or Full, and sigma must be Krstic or Janev-Smith
  • use_fp32 and batch_chunk may only be given for model = FFT; batch_chunk > 0
  • plasma_species must be i
  • neutral_species must be n
  • species i must be present in [components] species
  • LB, Avg and Meier require [units] mass_amu = 1

[neutral_neutral]

Exists when: should be included when neutral_neutral appears in [components] operators

Keys

model

  • Required: no
  • Default: bgk

nu

  • Required: no
  • Default: 1.0

Validation

  • if [neutral_neutral] exists but neutral_neutral is not enabled in [components] operators, validation fails
  • model must currently be bgk
  • nu > 0

[source]

Exists when: required when source appears in [components] operators

Keys

type

  • Required: no
  • Default: maxwellian

neutral_species

  • Required: no
  • Default: n

flux

  • Required: yes
  • Profile name for the volumetric particle source rate

temperature

  • Required: no
  • Default: default_temperature

ux

  • Required: no
  • Default: default_u

uy

  • Required: no
  • Default: default_u

uz

  • Required: no
  • Default: default_u

Validation

  • if [source] exists but source is not enabled in [components] operators, validation fails
  • flux is required; the old key density is rejected
  • type must currently be maxwellian
  • neutral_species must be n
  • all referenced profiles must exist, be valid, and not be boundary-only profiles

[boundary:<name>]

Exists when: <name> appears in [components] boundaries

Keys

attrs

  • Required: yes
  • Type: comma-separated list of ints
  • Default: none

type

  • Required: yes
  • Type: string
  • Default: none

specular_coeff

  • Required: no
  • Default: 0.0
  • Used by every type except absorbing. Note that type = specular needs specular_coeff = 1.0 to be fully reflecting.

alpha

  • Required: no
  • Default: default_u (i.e. 0)
  • maxwellian_channel only

recycling_coeff

  • Required: no
  • Default: 1.0
  • ion_recycling only

temperature

  • Required: no
  • Default: default_temperature
  • maxwellian_channel and ion_recycling

ux, uy, uz

  • Required: no
  • Default: default_u
  • maxwellian_channel and ion_recycling

Allowed type values

  • absorbing
  • specular
  • maxwellian_channel
  • ion_recycling

Validation

  • the section must exist if the boundary name is listed in [components] boundaries
  • attrs must be non-empty
  • every listed attribute must be a valid mesh boundary attribute
  • a boundary attribute may appear in only one boundary section
  • specular_coeff must satisfy 0 <= specular_coeff <= 1

Additional validation for type = maxwellian_channel

  • alpha, temperature, ux, uy, and uz must resolve to valid profiles. Any profile type is allowed, including file_boundary_linear_2d; non-constant profiles are evaluated at each boundary GLL point.

Additional validation for type = ion_recycling

  • species i must be present
  • recycling_coeff must be finite and >= 0
  • temperature, ux, uy, uz must be constant profiles or built-in defaults