.. |br| raw:: html
.. _kppsa-guide: ############################################################ Use the KPP-Standalone box model to test chemical mechanisms ############################################################ The :program:`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 :program:`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 :cite:t:`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 :option:`fullchem` or :option:`custom` chemistry mechanisms. But we hope to be able to extend this functionality to other mechanisms in the future. .. _kppsa-guide-code: =========== Source code =========== .. _kppsa_guide-code-interface: KPP-Standalone Interface ------------------------ The KPP-Standalone Interface source code is contained in the :file:`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. .. _kppsa-guide-code-boxmodel: KPP-Standalone Box Model ------------------------ The KPP-Standalone Box Model code is contained in the Git repository - https://github.com/geos-chem/KPP-Standalone This is our fork of the - https://github.com/KineticPreProcessor/KPP-Standalone 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: - :file:`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: - :file:`gchp/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem/KPP/standalone`. The :file:`KPP/standalone` folder contains the following files: .. list-table:: :header-rows: 1 * - File - Description * - :file:`Beijing_L1_20190701_0040.txt` - Sample data file based on the GEOS-Chem 14.5.0 fullchem mechanism * - :file:`CMakeLists.txt` - CMake file used to build the KPP-Standalone Box Model executable * - :file:`kpp_standalone.F90` - KPP-Standalone Box Model source code * - :file:`kpp_standalone_init.F90` - Source code to read data files generated by the KPP-Standalone Interface into the KPP-Standalone Box Model * - :file:`python/` - Folder containing Python analysis & plotting scripts * - :file:`README.md` - README file from the KPP-Standalone GitHub repository .. _kppsa-guide-usage: ================== Usage instructions ================== #. Download the `GEOS-Chem Classic `_ or `GCHP `_ source code. |br| |br| #. Navigate to the :literal:`run/` folder and create a run directory: .. code-block:: console $ cd GCClassic/run # If using GEOS-Chem Classic, or $ cd gchp/run # If using GCHP $ ./createRunDir.sh Select the :option:`fullchem` simulation (option :literal:`1`) with any extra option (e.g. :literal:`standard`, :literal:`RRTMG`, etc.). Follow the prompts and provide the necessary information. |br| |br| #. 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 :file:`kpp_standalone`. |br| |br| #. Open the :file:`kpp_standalone_interface.yml` file (located in the run directory) in your favorite editor. The file will look similar to this: .. code-block:: yaml --- # ============================================================================ # 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 :literal:`settings` section: |br| |br| #. Change :literal:`activate: false` to :literal:`activate: true`. This will turn on the KPP-Standalone Interface within GEOS-Chem. By default the Interface is turned off. |br| |br| #. Edit the :literal:`start_output_at` and :literal:`stop_output_at` entries 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 :literal:`2019-01-01 00:00:00` and :literal:`2019-01-02 00:00:00`, edit these entries as shown below: .. code-block:: yaml 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 :literal:`output_directory` setting to specify where the files containing model state will be sent. By default, these files will be placed in the :file:`OutputDir/` folder within the run directory. |br| |br| #. Edit the :literal:`levels` setting to add or remove the model levels at which you wish to archive the GEOS-Chem model state. |br| |br| #. Edit the :literal:`active_cells` section to define the names of sites where the KPP-Standalone Interface will archive the GEOS-Chem model state. The :file:`kpp_standalone_interface.yml` file 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. |br| |br| #. Edit the :literal:`locations` section to add geographical coordinates for each of the :literal:`active_cells` that 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. |br| |br| #. Run your `GEOS-Chem Classic `_ or `GCHP `_ simulation. Make sure that your simulation spans the time interval specified by the :literal:`start_output_at` and :literal:`stop_output_at` fields. |br| |br| #. Once your simulation finishes, navigate to the directory specified by the :literal:`output_directory` field (which in our example is :file:`./OutputDir`) and get a directory listing. .. code-block:: console $ cd OutputDir # Or whatever you specified for output_directory $ ls -1 You should see several files ending in :file:`*.txt`: .. code-block:: console 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 :file:`Beijing_L1_20190701_0040.txt` as an example: .. code-block:: text 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+003 The file header contains metadata about the meteorological conditions present at the site, as well as parameters used by the KPP solver. Species concentrations in :math:`molecules\ cm^{-3}` are listed along with the absolute tolerance value for each species. The number at the top of the header (:literal:`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 :math:`R`) and instantaneous reaction rates (beginning with :math:`A`) follow the species concentrations. These are archived in :math:`molecules\ cm^{-3}\ s^{-1}`. |br| |br| #. 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. .. code-block:: console $ ./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 :file:`kpp_standalone` is 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, :file:`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 :literal:`Hexit` values should be pretty close to each other. Your KPP-Standalone Box Model output should look similar to this: .. code-block:: text 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 :math:`molecules\ cm^{-3}`. The number at the top of the header (:literal:`43`) indicates the number of lines to skip before the data begins. |br| |br| #. 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 `_.