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

Keys

t_final

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

dt

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

vis_steps

  • Required: no
  • Type: int
  • Default: 1

ode_solver

  • Required: no
  • Type: string
  • Default: rk3

resume

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

resume_directory

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

Validation

  • t_final >= 0
  • dt > 0
  • vis_steps > 0
  • ode_solver must currently be rk3

Additional requirements when resume = true

  • resume_directory must exist
  • resume_directory must be a directory
  • resume_directory/gf_out must exist
  • resume_directory/gf_out must be a directory

[grid]

Exists when: always

Keys

mesh_file

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

order

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

Validation

  • mesh_file must exist
  • order >= 0

[vx], [vy], [vz]

Exist when: always

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
  • num must be odd
  • min < max

[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

Keys

display

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

save_dist

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

profile

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

precision

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

Validation

  • precision > 0

[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
  • 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

  • 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

[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

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 = 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

nu0

  • Required: no
  • Default: 10.928693196885557

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 currently be constant
  • nu0 > 0
  • plasma_species must be e
  • neutral_species must be n
  • species e must be present in [components] species

[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

Allowed model values

  • FFT
  • 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, sigma must be Krstic or Janev-Smith
  • plasma_species must be i
  • neutral_species must be n
  • species i must be present in [components] species

[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: should be included when source appears in [components] operators

Keys

type

  • Required: no
  • Default: maxwellian

neutral_species

  • Required: no
  • Default: n

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

  • if [source] exists but source is not enabled in [components] operators, validation fails
  • type must currently be maxwellian
  • neutral_species must be n
  • all referenced profiles must exist and be valid
  • for the current code path, all referenced source profiles must be constant or built-in defaults

[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

alpha

  • Required: no
  • Default: default_u

temperature

  • Required: no
  • Default: default_temperature

ux

  • Required: no
  • Default: default_u

uy

  • Required: no
  • Default: default_u

uz

  • Required: no
  • Default: default_u

specular_coeff

  • Required: no
  • Default: 0.0

Allowed type values

  • maxwellian_channel
  • absorbing
  • specular

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
  • for the current code path, those profiles must be constant or built-in defaults

Implementation notes

Source

The source section accepts density, temperature, ux, uy, and uz, and validation requires all referenced source profiles to be constant or built-in defaults. However, the current BuildSourceOperatorFromConfig implementation only uses density and temperature when constructing the MaxwellianSourceOperator. ux, uy, and uz are parsed and validated but are not currently used by the builder.

Boundaries

For type = maxwellian_channel, the current builder uses alpha, temperature, ux, uy, uz, and specular_coeff. For absorbing and specular, only attrs and type are used by the builder.