KPP Standalone

The GEOS-Chem KPP Standalone takes a given set of initial conditions to replicate grid cell chemistry of 3D GEOS-Chem, GCHP, or GEOS-CF runs. It reads an input file generated by the KPP Standalone Interface that generates model output of the full chemical state of the grid cell. The full GEOS-Chem mechanism is run to replicate the chemistry of the specified grid cell.

With contributions from: Obin Sturm (psturm@usc.edu), Michael S Long, Christoph Keller

The KPP Standalone is adapted from a box model used in the following publication: Lin, H., Long, M. S., Sander, R., Sandu, A., Yantosca, R. M., Estrada, L. A., et al. (2023). An adaptive auto-reduction solver for speeding up integration of chemical kinetics in atmospheric chemistry models: Implementation and evaluation in the Kinetic Pre-Processor (KPP) version 3.0.0. Journal of Advances in Modeling Earth Systems, 15, e2022MS003293. https://doi.org/10.1029/2022MS003293

The Kinetic PreProcessor (KPP) files can be modified and the mechanism rebuilt with KPP (see below). Then, the KPP Standalone can be rebuilt with make.

Setting up and running the KPP Standalone

1. Set up with KPP: Use the Kinetic Preprocessor command kpp fullchem.kpp to set up the integrator and related files using the Kinetic Preprocessor.

2. Compile the KPP Standalone: Compile with make to build an executable kpp_standalone.exe. Future options may have an option to compile the standalone when building GEOS-Chem.

3. Run the KPP Standalone: Run the chemistry operator for a single grid cell and print the chemical output with command line arguments e.g. ./kpp_standalone.exe Beijing_L1_20200106_1345.txt output.txt or ./kpp_standalone.exe samples/Beijing_L1_20200106_1345.txt Output_Beijing_L1_20200106_1345.txt. The output file argument is optional, and the standalone can be run without printing output e.g. ./kpp_standalone.exe Beijing_L1_20200106_1345.txt. Batches of grid cells can be called in Python scripts Verify_KPP_Standalone.py or by adjusting the code in kpp_standalone.F90, e.g. in the twilight-zone branch

4. Obtain realistic input files: The KPP Standalone Interface module in GEOS-Chem can be used to sparsely sample chosen grid cells during 3D runs, to get the full chemical state for input to the standalone.

User-modifiable KPP Standalone files

This folder contains the files that define the full-chemistry mechanism (NOx-Ox-VOCs-Br-Cl-I) for GEOS-Chem.

1. kpp_standalone.F90: Driver for the KPP Standalone.

2. kpp_standalone_init.F90: Subroutine to read input generated using the KPP Standalone Interface in 3D runs.

User-modifiable KPP files (taken from KPP/fullchem -- folder for the default GEOS-Chem mechanism)

This folder contains the files that define the full-chemistry mechanism (NOx-Ox-VOCs-Br-Cl-I) for GEOS-Chem.

1. fullchem.kpp: Master KPP specification file.

2. fullchem.eqn: KPP equation file, contains reaction definitoins.

3. fullchem_HetStateFuncs.F90: This module contains functions that initialize the HetChem state object.

4. fullchem_SulfurChemFuncs.F90: This module contains routines that compute rates for SO2 reactions in cloud.

5. fullchem_RateLawFuncs.F90: This module contains functions that compute rates for heterogenous chemistry reactions. This is the so-called "rate law library" for the fullchem mechanism.

6. rateLawUtilFuncs.F90: This module contains several utility functions for heterogeneous chemistry reactions.

7, commonIncludeVars.H: Global variables that are used for all KPP mechanisms. These will be inlined into the KPP-generated gckpp_Global.F90 file.

The following files link to the KPP/stubs folder. These include stub subroutines that are used by other chemical mechanisms. The stubs are needed in order to avoid compilation errors.

1. stub_aciduptake_DustChemFuncs.F90 Stub routines corresponding to the KPP/aciduptake/aciduptake_DustChemFuncs.F90 module,

2. stub_Hg_HetStateFuncs.F90: Stub routines corresponding to the KPP/Hg/Hg_HetStateFuncs.F90 module.

Files generated by KPP

With the exception of the symbolic link gckpp.kpp, and the map file gckpp.map, all files starting with the prefix gckpp_ are generated by KPP. These contain the specifications of the chemical mechanism in efficient source code.

For more information, please see:

1. KPP documentation at: https://kpp.readthedocs.io

2. Guide to Using KPP with GEOS-Chem