Skip to content

Configuration Reference

GENOA uses INI format for configuration files, which allows users to easily modify parameters for different tasks such as mechanism generation, simulation, and training.

Basic Structure

An INI file is divided into sections, each section beginning with a name in square brackets (e.g., [General]). Each section contains key-value pairs defining parameters.

Example Layout

[SectionName]
key1 = value1
key2 = value2

GENOA v3 reads the configuration file to update its internal settings and parameters.

Here is an example of a partial configuration file. Allowed key and acceptable value types are restrained and with expected and default values given in the reference configuration file below.

[action]
build_mechanism = 1

[general]

id_mech = "b1"
prefix  = "U6"
primary_vocs = ["U06000"]

path_workplace = "./test_cases/output/work"
path_sav_mech  = "./test_cases/output/mech"
path_sav_res   = "./test_cases/output/res"

[GECKO-A]
path     = "./vendor/BOXMODEL4GECKO"
namelist = "./test_cases/conditions/U6/simu.nml"

[build_mechanism]
reactionfile = "./test_cases/input/fromGCK/U6_GECKO-A"
reactiontype = "GECKO"
speciesfile  = "./test_cases/input/fromGCK/U6_GECKO-A"
speciestype  = "GECKO"

Available Sections

GENOA v3 currently supports the following sections that are either compulsory or optional depending on the actions specified:

Section Description Notes
[action] Specifies which GENOA functions to perform (e.g., reduction, training, testing, post-processing). Always required.
[general] Defines global and cross-functional options such as mechanism ID, input/output paths, and working directories. Always required.
[GECKO-A] Provides settings related to the GECKO-A box model environment. Required if using GECKO-A data or simulations.
[run_simulation] Contains parameters for box-model or chemical mechanism simulations. Recommended when running evaluation or training.
[threshold_reduction] Settings for threshold-based reduction, including strategies and thresholds for species/reaction pruning. Activated if threshold_reduction = True in [action].
[training] Settings for simulation-based reduction (training), defining simulation conditions, criteria, and iteration parameters. Activated if training = True in [action].
[testing] Settings for mechanism evaluation, including reference data and performance metrics. Activated if testing = True in [action].
[post-processing] Parameters for generating plots, summaries, and statistical analyses after reduction or training. Activated if post_processing = True in [action].

References for configuration options/parameters:

Each configuration file is self-contained and modular. Below are the main roles of key sections:

[action]

Determines which GENOA modules to activate: - build_mechanism = 1: Convert mechanism - run_simulation = 1: Run box-model simulation - threshold_reduction = 1: Perform threshold-based pruning - training = 1: Conduct simulation-based reduction - testing = 1: Evaluate a reduced mechanism - post-processing = 1: Generate comparison plots

[general]

Defines mechanism identifiers, paths, and core options such as: - id_mech and prefix: Used to label mechanisms (e.g., U6T-0) - primary_vocs: List of initial precursors (e.g., U06000) - path_read_mech, path_sav_mech, path_sav_res: Input/output directories

[GECKO-A]

Specifies box-model dependencies: - path: GECKO-A interpreter location - namelist: Simulation namelist file - This section must be consistent with your local GECKO-A installation.

[run_simulation]

Controls numerical integration settings and time-step structure: - start_hour, total_t, delta_t, and dates set simulation timeline. - path_init_cond defines which condition folder (e.g., 1conds) to use.

[threshold_reduction]

Implements rule-based removal of species and reactions using physical and empirical thresholds. Example parameters (from 5_threshold_reduction.ini):

Parameter Example Description
svoc 1E-5 atm Upper volatility limit (semi-volatile)
nvoc_tree 1E-10 atm Lower volatility cutoff
pyield 0.01 Product yield threshold
bratio 1E-4 Minimum branching ratio retained
generation 12 Maximum carbon generation retained

[training]

Controls iterative simulation-based reduction.

Parameter Example Description
training_parameter_table 6_training_parameters.csv Links to stage-specific reduction options
npara, ncpu 1 Parallel cores used
tlim 600 Time limit per reduction cycle (s)
group_order_mode gen_prop Species grouping and ordering rule
pretesting_path conditions/U6/2conds Evaluation conditions between iterations
stop_at_eave, stop_at_emax 0.5 / 0.99 Error thresholds for termination

Parameter Table from 6_training_parameters.csv

Stage Strategy Description Example Values
rm Remove minor species Filters low-impact compounds threshold=1E-3
rs Remove sparse reactions Prunes weak links branching ratio < 1E-4
da Dependency analysis Tracks interdependencies coupling depth=2
jp Join pathways Merges near-equivalent nodes similarity > 0.9
lp Local pruning Eliminates redundant branches iteration=3
rp Refinement pass Tightens accuracy criteria NMAE limit=0.05

Each stage corresponds to a reduction strategy applied sequentially during training.

[testing]

Defines evaluation metrics for a mechanism vs. reference. Results include normalized mean absolute errors (NMAE) for O3, NO, NO2, and SOA mass.

[post-processing]

Produces plots of volatility distributions, reaction pathways, and error comparisons.

Reference configuration files

References for configuration options/parameters: