Skip to content

Test Cases

Explore the GENOA v3 test cases that demonstrate the complete GENOA workflow, from mechanism conversion to reduction and evaluation.

At a glance

GENOA test cases illustrate the key functionalities of the GENOA framework for reducing and evaluating fully explicit atmospheric chemical mechanisms derived from GECKO-A. Each case represents one or more stages of the workflow:

  • Mechanism conversion
  • 0-D box-model simulation
  • Threshold-based reduction
  • Simulation-based reduction (training)
  • Mechanism evaluation (testing)
  • Post-processing and visualization

The examples are based on a six-generation 1-hexene GECKO-A mechanism (U6), providing small but representative cases that can be executed locally or on HPC systems.

All required input files are included in the repository under the test_cases/ directory. The folder layout is described below.

Folder layout

The folder structure for the test cases is as follows:

  • conditions/: Contains example simulation conditions and namelist files for the GECKO-A box model.
  • config/: Contains configuration files (.ini) for each test case, which can be modified as needed.
  • input/: Contains input files, including GECKO-A mechanisms, converted mechanisms, and reference simulation results.
  • output/: This folder will be created during execution to store generated mechanisms, results, and plots.
  • work/: Temporary files generated during execution.

The detailed folder structure is:

test_cases/
├── conditions/                # Example simulation conditions for the GECKO-A box model
│   └── U6/
│       ├── 1conds/            # Folder for each condition set (each can contain one or more condition files)
│       ├── 2conds/
│       ├── 4conds/
│       └── simu.nml           # Example basic namelist file for GECKO-A box model simulations
│
├── config/                    # Configuration files for all test cases
│   ├── 1_build.ini
│   ├── 2_build_run.ini
│   ├── 3_run.ini
│   ├── 4_run_compare.ini
│   ├── 5_threshold_reduction.ini
│   ├── 6_training.ini
│   ├── 6_training_parameters.csv
│   ├── 7_testing.ini
│   ├── 8_reductions.ini
│   ├── 9_postprocess.ini
│   ├── config_reference.ini       # Reference file for general configuration options
│   └── parameter_reference.csv    # Reference table for simulation-based reduction parameters
│
├── input/                    # Example mechanisms and reference results
│   ├── fromGCK/              # Original GECKO-A mechanisms
│   │   └── U6_GECKO-A/
│   ├── mech/                 # Converted and reduced mechanisms
│   │   ├── U6O/              # Reference (parsed but unreduced)
│   │   ├── U6R/              # Threshold-reduced
│   │   ├── U6T-0/            # Simulation-reduced (first cycle)
│   │   └── U6T-2/            # Simulation-reduced (third cycle)
│   └── res/                  # Reference and generated simulation results
│       ├── Results_U6O/
│       ├── Results_U6R/
│       ├── Results_U6T-0/
│       └── Results_U6T-2/
│
└── output/                   # Holder for outputs

Test case summary

ID Description Key Inputs Expected Outputs Notes
1 Parse a GECKO-A mechanism: (1) remove species and reactions not derived from precursors (non-basic reactions), (2) merge reactions sharing the same reactants and kinetic types, and (3) add tracer species to track pollutant loss and formation. GECKO-A raw mechanism U6_GECKO-A; basic species list basic_species.txt Parsed mechanism U6b1 in output/mech/ Large mechanisms may require significant time and memory to parse.
2 Parse and run a GENOA-reduced mechanism using the GECKO-A box model coupled to GENOA. Mechanism U6T-0; simulation inputs: conditions 1conds, namelist simu.nml Parsed mechanism U6b2; box-model results in output/res/Results_U6b2 When multiple actions are enabled in one configuration file, they are executed sequentially in the order listed.
3 Run a GECKO-A box-model simulation for a given mechanism. Same inputs as test case 2 Simulation results Results_U6T-0 All output files are stored in the results folder, organized by condition name and time index (e.g., simple.T0 for the first time setting). You can rerun simulations manually using the generated namelist.
4 Run simulations and compare results with a reference mechanism (error analysis). Reduced mechanism U6T-1; reference results ./test_cases/input/res/Results_U6O; simulation settings as in test case 2 Error file error_sml_U6R.dat; results Results_U6R Reference results must be generated in advance using the same or similar simulation settings for a meaningful comparison.
5 Perform threshold-based reduction using multiple strategies and thresholds. Reduction settings in the config file; starting and reference mechanism U6O; reference results Results_U6O; simulation settings as in test case 2 Reduced mechanism U6r1; results Results_U6r1; error log mech/error_threshold_reduction_U6O_r1.dat Comment or uncomment strategies in the configuration file to enable or disable them, and adjust thresholds as needed.
6 Run simulation-based reduction (training). Training settings in config and parameters.csv; mechanisms U6O (reference) and U6T-0 (starting point); reference results Results_U6O; training and validation conditions 1conds, 2conds Folder mech/t_mechs/ containing all reduction-related files (e.g., reduced mechanisms *_sav/, training log record_r2.txt, grouping and ordering files, pretest results pretest_PTST.txt) Reduction cycle numbering starts from 0. Training is time- and memory-intensive; multiprocessing is recommended for large mechanisms.
7 Evaluate a reduced mechanism against a reference. Tested mechanism U6T-0; reference U6O; simulation settings as in test case 2, with conditions 4conds Testing log mech/error_testing_U6O_test.dat; results for reference (ref) and tested (test) mechanisms in output/work/testing/ To save time, precomputed reference results can be reused as input for later evaluations.
8 Run a full reduction workflow — threshold-based (U6O -> U6tbr), simulation-based (U6tbr -> U6sbr, 10 min limit), and evaluation (U6sbr vs U6O). Similar to test cases 5–7; reference/starting mechanism U6O Similar outputs to test cases 5–7: reduced mechanisms in U6sbr and tbr_mechs/, error records (e.g., error_threshold_reduction_U6O_tbr.dat and error_testing_U6O_tst.dat), simulation results Results_U6tbr/ Demonstrates the complete reduction workflow in a single run. Commenting out the tlim option allows full simulation-based reduction (can be very time-consuming).
9 Postprocess mechanisms and simulation results. Postprocessing configuration; mechanisms and results from previous runs Plots and CSV outputs in output/post/U6_ppb/: flowcharts in flowchart/, reduction-process visualization rdc_T_1_log_wprt.png, condition-specific plots (e.g., simple.T0), error comparisons (if activated), and log postprocess.log See Postprocessing Gallery for available plots and details.

How to run

To run any test case, use:

  • From the GENOA root directory: 

    python3 -m genoa ./test_cases/config/<config_file.ini>
    Example: 
    python3 -m genoa ./test_cases/config/1_build.ini

  • If GENOA is installed as a package (see Installation Instructions), you can simply run: 

    genoa ./test_cases/config/<config_file.ini>
    Example: 
    genoa ./test_cases/config/1_build.ini

  • For time-consuming runs (e.g., reductions), use background mode:

    nohup python3 src/genoa.py ./test_cases/config/8_reductions.ini > 8.log 2>&1 &
    or 
    nohup genoa ./test_cases/config/8_reductions.ini > 8.log 2>&1 &
    Either command will run the test case in the background. and redirect output to 8.log.

After execution, a log file is generated in runtime/logs/ for each run, containing error and warning messages by default. If the file is empty, it means the run completed without any errors or warnings.

Notes for new users

  • See the Installation Guide for setup instructions.

  • For any action involving box-model simulations, ensure the box model is properly compiled before running GENOA.
    GENOA can automatically compile the box model if the executable is not found (using the command specified in the configuration file), but manual compilation is recommended to verify all dependencies are correctly installed.

  • Each test case is self-contained, with all required input files under test_cases/input/.
    Output files are generated in the output/ directory during execution.

  • Configuration files (.ini) for each test case are stored in test_cases/config/.
    Review the file headers and inline comments for guidance; parameters can be adjusted as needed.

  • Refer to the Configuration Reference for a full list of configurable options.
    Note that using the same runid will overwrite previous outputs—assign unique run IDs for separate runs when needed.