Use the KPP-Standalone box model to test chemical mechanisms
The KPP-Standalone Box Model takes a given set of initial conditions to replicate grid cell chemistry of 3D GEOS-Chem, GCHP, or GEOS-CF simulations. 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.
The KPP-Standalone Box Model can be a useful tool for debugging chemical mechanisms or validating new chemistry reactions before adding them to an existing GEOS-Chem mechanism.
The current KPP-Standalone has been adapted from a box model used in Lin et al. [2023]. The GEOS-Chem Support Team has implemented the KPP-Standalone Box Model and KPP-Standalone Interface into GEOS-Chem 14.5.1 and later versions.
Note
The KPP-Standalone Box Model is currently compatible with the
fullchem or custom chemistry mechanisms. But we
hope to be able to extend this functionality to other
mechanisms in the future.
Source code
KPP-Standalone Interface
The KPP-Standalone Interface source code is contained in the
GeosCore/kppsa_interface_mod.F90 module in the
GEOS-Chem “science codebase” repository. The Interface
code is used to archive the GEOS-Chem model state (at the locations
and times that you choose) for input into the KPP-Standalone Box
Model.
KPP-Standalone Box Model
The KPP-Standalone Box Model code is contained in the Git repository
This is our fork of the
repository, which is maintained by the Kinetic PreProcessor developers.
When you clone the GEOS-Chem Classic source code, the KPP-Standalone Box Model code will be copied into this folder:
GCClassic/src/GEOS-Chem/KPP/standalone
Or if you clone the GCHP source code, the KPP-Standalone Box Model code will be copied into this folder:
gchp/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem/KPP/standalone.
The KPP/standalone folder contains the following files:
File |
Description |
|---|---|
|
Sample data file based on the GEOS-Chem 14.5.0 fullchem mechanism |
|
CMake file used to build the KPP-Standalone Box Model executable |
|
KPP-Standalone Box Model source code |
|
Source code to read data files generated by the KPP-Standalone Interface into the KPP-Standalone Box Model |
|
Folder containing Python analysis & plotting scripts |
|
README file from the KPP-Standalone GitHub repository |
Usage instructions
Download the GEOS-Chem Classic or GCHP source code.
Navigate to the
run/folder and create a run directory:$ cd GCClassic/run # If using GEOS-Chem Classic, or $ cd gchp/run # If using GCHP $ ./createRunDir.sh
Select the
fullchemsimulation (option1) with any extra option (e.g.standard,RRTMG, etc.). Follow the prompts and provide the necessary information.
Navigate to the run directory and compile the GEOS-Chem Classic or GCHP source code. The KPP-Standalone Box Model code will be compiled to an executable named
kpp_standalone.
Open the
kpp_standalone_interface.ymlfile (located in the run directory) in your favorite editor. The file will look similar to this:--- # ============================================================================ # Configuration file for KPP standalone interface # # This file specifies at which locations we will archive the model # state so that we can initialize KPP standalone box model simulations. # ============================================================================ # ------------------------------------ # General settngs # ------------------------------------ settings: activate: false # Main on/off switch start_output_at: [19000101, 000000] # Save model state for KPP standalone stop_output_at: [21000101, 000000] # ... if between these 2 datetimes output_directory: "./OutputDir/" # This directory should already exist levels: # Model levels to archive - 1 - 2 # ... etc. other levels not shown ... # ------------------------------------ # Where to archive model state? # ------------------------------------ active_cells: - Alert - Amazon - AtlanticOcean - Beijing # ... etc. other active_cells not shown ... # ------------------------------------ # Active cell geographic coordinates # ------------------------------------ locations: Alert: latitude: 82.5 longitude: -62.3 Amazon: latitude: -3.4653 longitude: -62.2159 AtlanticOcean: latitude: 34.707874 longitude: -41.574755 Beijing: latitude: 39.9042 longitude: 116.4074 # ... etc. other locations not shown ...
Edit the following entries under the
settingssection:
Change
activate: falsetoactivate: true. This will turn on the KPP-Standalone Interface within GEOS-Chem. By default the Interface is turned off.
Edit the
start_output_atandstop_output_atentries to specify the time interval when the KPP-Standalone Interface will run. The KPP-Standalone Interface will archive the GEOS-Chem model state to disk at each chemistry timestep that occurs within the specified interval.Attention
We recommend that you only archive model state to disk for the time interval that you need. By default, the model state will be archived to disk at every chemistry timestep, which can cause your simulation to run much more slowly than normal.
For example, if you wish to archive model state to disk only between
2019-01-01 00:00:00and2019-01-02 00:00:00, edit these entries as shown below:start_output_at: [20190101, 000000] # Save model state for KPP standalone stop_output_at: [20190102, 000000] # ... if between these 2 datetimes
If you wish, change the
output_directorysetting to specify where the files containing model state will be sent. By default, these files will be placed in theOutputDir/folder within the run directory.
Edit the
levelssetting to add or remove the model levels at which you wish to archive the GEOS-Chem model state.
Edit the
active_cellssection to define the names of sites where the KPP-Standalone Interface will archive the GEOS-Chem model state. Thekpp_standalone_interface.ymlfile ships with several pre-defined active cells. You may keep these, remove them, and/or add new active cells as you please. The ordering of the active cell names does not matter.
Edit the
locationssection to add geographical coordinates for each of theactive_cellsthat have been specified above. The ordering of the locations does not matter, but you must make sure that each active cell has a corresponding geographic location defined.
Run your GEOS-Chem Classic or GCHP simulation. Make sure that your simulation spans the time interval specified by the
start_output_atandstop_output_atfields.
Once your simulation finishes, navigate to the directory specified by the
output_directoryfield (which in our example is./OutputDir) and get a directory listing.$ cd OutputDir # Or whatever you specified for output_directory $ ls -1
You should see several files ending in
*.txt:Alert_L1_20190701_0000.txt Alert_L1_20190701_0020.txt Alert_L1_20190701_0040.txt Alert_L2_20190701_0000.txt Alert_L2_20190701_0020.txt Alert_L2_20190701_0040.txt ... Amazon_L1_20190701_0000.txt Amazon_L1_20190701_0020.txt Amazon_L1_20190701_0040.txt Amazon_L2_20190701_0000.txt Amazon_L2_20190701_0020.txt Amazon_L2_20190701_0040.txt ... AtlanticOcean_L1_20190701_0000.txt AtlanticOcean_L1_20190701_0020.txt AtlanticOcean_L1_20190701_0040.txt AtlanticOcean_L2_20190701_0000.txt AtlanticOcean_L2_20190701_0020.txt AtlanticOcean_L2_20190701_0040.txt ... Beijing_L1_20190701_0000.txt Beijing_L1_20190701_0020.txt Beijing_L1_20190701_0040.txt Beijing_L2_20190701_0000.txt Beijing_L2_20190701_0020.txt Beijing_L2_20190701_0040.txt ... ... etc. for other sites & times ...
These files represent the GEOS-Chem model state at each active cell, model level, date and time. The format of these files is shown below (using the
Beijing_L1_20190701_0040.txtas an example:60 ============================================================================ KPP Standalone Atmospheric Chemical State File Description: This file contains model output of the atmospheric chemical state as simulated by the GEOS-Chem chemistry module in a 3D setting. Each grid cell represents the chemical state of an individual location, suitable for input into a separate KPP Standalone program which will replicate the chemical evolution of that grid cell for mechanism analysis. Note that the KPP Standalone will only use concentrations, rate constants, and KPP-specific fields. All other fields are for reference. The first line contains the number of lines in this header. If wanting to use this output for other analysis, a Python class to read these fields is available by request, contact Obin Sturm (psturm@usc.edu). Generated by the GEOS-Chem Model (https://geos-chem.org/) Using the KPP Standalone Interface github.com/GEOS-ESM/geos-chem/tree/feature/psturm/kpp_standalone_interface With contributions from: Obin Sturm (psturm@usc.edu) Christoph Keller Michael Long Sam Silva Meteorological and general grid cell metadata Location: Beijing Timestamp: 2019/07/01 00:40 Longitude (degrees): 115.0000 Latitude (degrees): 38.0000 GEOS-Chem Vertical Level: 1 Pressure (hPa): 947.7906 Temperature (K): 300.29 Dry air density (molec/cm3): 0.2273E+20 Water vapor mixing ratio (vol H2O/vol dry air): 0.9784E-02 Cloud fraction: 0.0000E+00 Cosine of solar zenith angle: 0.6833E+00 KPP Integrator-specific parameters Init KPP Timestep (seconds): 41.0561 Exit KPP Timestep (seconds): 92.6195 Chemistry operator timestep (seconds): 1200.0000 Number of internal timesteps: 15 ICNTRL integrator options used: 1 0 4 0 0 0 1 0 0 0 0 0 0 345 -1 0 0 0 0 0 RCNTRL integrator options used: 0.000000 0.000000 41.056066 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000050 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 CSV data of full chemical state, including species concentrations, rate constants (R) and instantaneous reaction rates (A). All concentration units are in molec/cm3 and rates in molec/cm3/s. ============================================================================ Name, Value, Absolute Tolerance CH2I2, 5.5790359988082701E+003, 1.00E-02 CH2IBr, 4.3058653390896252E+004, 1.00E-02 CH2ICl, 5.5586468566915649E+005, 1.00E-02 AERI, 1.0841371359954113E+007, 1.00E-02 AONITA, 1.0756986064207199E+009, 1.00E-02 ... R1 1, 3.9000149380783678E-020 R2, 1.9670377782305400E-007 R3, 1.6079592890328128E-008 R4, 7.2351790708373721E-022 ... A1, 4.6780159996820985E+003 A2, 4.6780159996820985E+003 A3, 4.6780159996820976E+003 A4, 5.1949221122605059E+003The file header contains metadata about the meteorological conditions present at the site, as well as parameters used by the KPP solver. Species concentrations in \(molecules\ cm^{-3}\) are listed along with the absolute tolerance value for each species. The number at the top of the header (
60) indicates the number of lines to skip before the data begins. Data is saved to comma-separated variable (CSV) format.Reaction rate constants (beginning with \(R\)) and instantaneous reaction rates (beginning with \(A\)) follow the species concentrations. These are archived in \(molecules\ cm^{-3}\ s^{-1}\).
Run the KPP-Standalone Box Model for each of the active cells, model levels, dates, and times where the GEOS-Chem model state has been archived.
$ ./kpp_standalone Beijing_L1_20190701_0040.txt Beijing_L1_20190701_0040.log Processing sample: input/Beijing_L1_20190701_0040.txt Number of internal timesteps (from 3D run): 15 Number of internal timesteps ( standalone): 15 Hexit (from 3D run): 92.62 Hexit ( standalone): 92.62
The first argument to
kpp_standaloneis the file containing the GEOS-Chem model state for a given active cell, level, date, and time.The second argument is the log file (in our example,
Beijing_L1_20190701_0040.log) containing the output of the KPP-Standalone Box Model. The log file will also be printed in CSV format.The KPP-Standalone Box Model will print some statistics to the screen (aka “standard output” or “stdout”). Ideally the
Hexitvalues should be pretty close to each other.Your KPP-Standalone Box Model output should look similar to this:
43 =============================================================================== KPP Standalone Output This file contains the concentrations of all the chemical species in a single grid cell of a GEOS-Chem 3D run as replicated by the KPP Standalone. Concentrations before and after the operator timestep are in CSV format, below. Generated by the GEOS-Chem KPP Standalone: https://github.com/KineticPreProcessor/KPP-Standalone Input file used: Beijing_L1_20190701_0040.txt Meteorological and general grid cell metadata Location: Beijing Timestamp: 2019/07/01 00:40 Longitude (degrees): 115.0000 Latitude (degrees): 38.0000 GEOS-Chem Vertical Level: 1 Pressure (hPa): 947.7906 Temperature (K): 300.29 Dry air density (molec/cm3): 0.2273E+20 Water vapor mixing ratio (vol H2O/vol dry air): 0.9784E-02 Cloud fraction: 0.0000E+00 Cosine of solar zenith angle: 0.6833E+00 KPP Integrator-specific parameters Init KPP Timestep (seconds): 41.0561 Exit KPP Timestep (seconds): 92.6195 Chemistry operator timestep (seconds): 1200.0000 Number of internal timesteps: 15 ICNTRL integrator options used: 1 0 4 0 0 0 1 0 0 0 0 0 0 345 -1 0 0 0 0 0 RCNTRL integrator options used: 0.000000 0.000000 41.056066 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000050 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 =============================================================================== Species Name,Initial Concentration (molec/cm3),Final Concentration (molec/cm3) CH2I2, 5.5790359988082701E+003, 2.8781775861340213E+000 CH2IBr, 4.3058653390896252E+004, 2.9971817468639663E+004 CH2ICl, 5.5586468566915649E+005, 5.0135868815135013E+005 AERI, 1.0841371359954113E+007, 1.0896017942806700E+007 AONITA, 1.0756986064207199E+009, 1.0756986064207199E+009 BUTDI, 2.0521956658716797E+010, 2.0526479192010277E+010 ...The header contains the same information as the corresponding input file containing model state archived from GEOS-Chem. The initial and final concentrations for each species are printed in \(molecules\ cm^{-3}\). The number at the top of the header (
43) indicates the number of lines to skip before the data begins.
As of this writing (December 2024) we are working on Python plotting codes to better visualize KPP-Standalone Box Model output. These will ship as part of the GCPy package.