Configuration Parameters

Simulations require a lot of configuration parameters to be set (e.g. mesh size, what algorithms to use, etc.). In Runko, these are set using runko.Configuration Python class. It can be thought as a Python dictionary but the values are accessed through attribute syntax instead of the dictionary syntax (config.key = value vs. some_dict['key'] = value). If you want to access a value using a string as the key, you can use getattr function.

Different parts of runko take runko.Configuration objects as arguments. Runko will raise an error if a given configuration object does not contain the required parameters. Parameters can also be optional. Missing a optional parameter is not a error, but attempting to use functionality that depends on that parameter will result in an error. This can be annoying if it happens at the end of a large simulation, so make sure to always test your runs on a small scale first.

Constructing runko.Configuration object

runko.Configuration can be constructed completely inline in Python, which is some times useful for 100% self-contained simulation files:

import runko
config = runko.Configuration(None)
config.foo = 42
config.bar = "abc"
# ...

More commonly, the configuration object is constructed from a configuration file by passing the file path to the constructor. The configuration file syntax loosely follows what Python configparser supports by default. In short, there is one key–value pair per line, and the key and value are separated by either : or =. Comments start with either # or ;. Key-value pairs are required to be organized into sections which are marked using [section-name]. However, the sections are completely optional and have no semantic meaning. Starting from Python >= 3.13, sections are made completely optional. A common convention is to have following sections: io, simulation, grid, problem, particles and algorithms.

Here is an example of a configuration file:

[io]
# This is a comment.
; And this too.
foo: 42
bar = "abc"

[simulation]
# ...

And here is an example of how to read it:

import runko
config = runko.Configuration("path/to/config")

# Sometimes it is useful to set other parameters dynamically
# based on other parameters.

config.foobar = config.foo * config.bar

Supported values

Internally, Runko interprets the values from the configuration file as Python literals, and therefore all Python literal data types are supported. However, different parts of Runko expect parameters to be of specific types and will raise an error if the expected type does not match the actual type. For example, if Runko expects an integer parameter, then the value 2.0 will results in an error.

Inspecting configuration from output directory

For each simulation, runko will copy the configuration file to the output directory if it exists. In any case, runko will write a pickled version of the configuration object to the output directory as <output-dir>/config.pkl.

Contents of the pickled configuration object can be inspected using the runko tool:

runko inspect conf <path/to/output/dir>

List of common parameters

As mentioned above, there are different types of parameters in Runko. Some parameters are always required, while others are optional. Additionally, some parameters are not required by any internal Runko machinery but are still useful (e.g. parameters used during the simulation, for post‑processing, or for identifying different simulations). If “used in”-field is empty, the parameter is not actually used by runko, but its use in the project files has become convention.

IO parameters

name	data type	used in	description
io_outdir	str	Simulation	Output directory path (default: runko_outdir). If set to ‘auto’, path is generated by combinging ppc, n_cells_per_skindepth, sigma, n_filter_passes, cfl, theta0 and upstream_gamma.
io_outdir_prefix	str	Simulation	Prefix prepended to io_outdir.
io_outdir_postfix	str	Simulation	Postfix appended to io_outdir.
io_output_interval	int		Interval in laps between outputs.
io_grid_stride	int	emf fields snapshot	Field output stride i.e. downsample factor (default: 1).
io_n_sampled_prtcls	int	pic particle snapshot	Number of particles to sample for particle snapshots (default: 0).
io_n_spectra_bins	int	pic spectra snapshot	Number of bins for particle spectra (default: 200).
io_spectra_umin	float	pic spectra snapshot	Lower u boundary (default: 1e-4).
io_spectra_umax	float	pic spectra snapshot	Upper u boundary (default: 1e3).
io_n_laps_in_timer_stats	int	Simulation	Number of latest laps included in simulation timer statistics (default: all laps).

Simulation parameters

name	data type	used in	description
n_laps	int	Simulation	Total number of time steps.
n_tiles	list[int]	TileGrid	Numer of tiles (sub-domain regions) per dimension.
n_cells_per_tile	list[int]	emf	Grid cells per tile per dimension (dx=dy=dz=1).
cfl	float	emf	Courant number dt/dx; (must be <= 0.5).
qN	float	pic	Charge of Nth particle species in code units (N=0, 1, …).
mN	float	pic	Mass-to-charge magnitude ratio of the Nth particle species (N=0, 1, …).

Miscellaneous parameters

name	data type	used in	description
ppc	int		Macro-particles per cell per species.
sigma	float		Magnetization sigma = B^2/(4*pi*gamma*n*m*c^2).
n_cells_per_skindepth	int		Skin-depth resolution c/omega_p in cells.
n_filter_passes	int		Current smoothing passes per step.
thetaN	float		Temperature of Nth particle species kT/(mc^2).
thetaN_to_thetaM	float		Nth-to-Mth particle species temperature ratio.
upstream_gamma	float		Bulk Lorentz factor of the upstream flow.
b_proj	list[float]		B-field direction cosines.
n_particles	int	weak-scaling plots	Total number of particles in the simulation. Used to calculate push time.

Algorithm parameters

name	data type	used in	description
field_propagator	str	emf	options: ftdt2, stencil
field_propagator_cfl_coeff	float	emf	CFL in field propagator is multiplied by this (default: 1).
particle_pusher	str	pic	options: boris, higuera_cary, faraday
field_interpolator	str	pic	options: binomial2, binomial2_unrolled
current_depositor	str	pic	options: linear_1st, linear_1st_unrolled
domain_decomposition	str	tile_grid	How tiles are divided between MPI ranks. options: hilbert_curve, catepillar_track
catepillar_track_length	int	catepillar_track	FIXME