Adding species or updating chemical mechanism ============================================== To customize the chemical mechanism used in WRF-GC, there are three locations that need to be updated: * **The GEOS-Chem model.** You may be most familiar with this part. You may need to add the desired species, reactions, and processes to GEOS-Chem. * **The WRF-GC coupler.** The coupler needs to be aware of the new species, so it can perform advection and history output for them. Output is always through WRF. * **WRF.** WRF needs to know the names of the species to setup input of ic/bc and output. We outline the relevant steps below, assuming some familiarity with Fortran: GEOS-Chem model --------------- Only changing reactions ^^^^^^^^^^^^^^^^^^^^^^^ Simply edit ``chem/gc/KPP/Standard/standard.eqn`` as you would do within regular GEOS-Chem. You need to rebuild the chemical mechanism code using KPP. After that, simply recompile WRF-GC (``./compile em_real`` at the WRF root directory) and you are good to go. As a reminder, the GEOS-Chem source code is unmodified and resides in ``WRF/chem/gc``. WRF-GC does not use ``Tropchem``. Adding additional code ^^^^^^^^^^^^^^^^^^^^^^^ WRF-GC is based upon GCHP technology by Long et al., 2015 [#f1]_ and Eastham et al., 2018 [#f2]_. The equivalent to ``main.F`` which most GEOS-Chem users are used to is ``chem/gc/GCHP/gigc_chunk_mod.F90``. You may find most of the subroutine calls within the subroutine ``GIGC_Chunk_Run``. We recommend reading ``main.F`` and ``gigc_chunk_mod.F90`` and figuring out where your code should be positioned. If you use this method, and no species are added, all you need to change is within GEOS-Chem and WRF-GC will work seamlessly. And your code will also work for GCHP now! Adding species ^^^^^^^^^^^^^^^ Generally you need to update ``standard.eqn`` (KPP), ``species_database_mod.F90`` within GEOS-Chem. WRF-GC coupler -------------- The species need to be passed to and from WRF at every time step. There are three locations to edit in the WRF-GC coupler, located in ``WRF/chem/wrfgc_convert_state_mod.F``. 1. **Species index declarations**, e.g., .. code-block:: integer :: gi_a3o2, gi_acet, gi_acta ! ... Add the species with a sensible name, e.g., ``gi_newname``. Go to ``WRFGC_IdxSetup``: .. code-block:: gi_a3o2 = IND_('A3O2') gi_acet = IND_('ACET') gi_acta = IND_('ACTA') Add the species you added with the GEOS-Chem name in quotes, e.g., ``gi_newname = IND_('NEWNAME')``. 2. **Passing species from WRF to GEOS-Chem** after advection: .. code-block:: State_Chm%Species(II, JJ, k, gi_acet) = chem(i, k, j, p_acet) * 1.0e-6_fp State_Chm%Species(II, JJ, k, gi_acta) = chem(i, k, j, p_acta) * 1.0e-6_fp Add your species similarly. .. note:: Do not worry about defining ``p_acet``, ``p_acta``, etc. - these are auto-generated by WRF. Remember the loewrcase name of the species, this is the WRF name of the species you added (e.g., ``newname``). We will use it in the next section. 3. **Passing species from GEOS-Chem to WRF** after chemistry: .. code-block:: chem(i, k, j, p_a3o2) = State_Chm%Species(II, JJ, k, gi_a3o2) * 1.0e+6_fp chem(i, k, j, p_acet) = State_Chm%Species(II, JJ, k, gi_acet) * 1.0e+6_fp Add your species similarly. WRF registry ------------- Let WRF know of this species's existence by editing ``WRF/chem/registry.chem``. Search for: .. code-block:: state real a3o2 ikjftb chem 1 - i0{12}rhusdf=(bdy_interp:dt) "a3o2" "A3O2 mixing ratio" "ppmv" state real acet ikjftb chem 1 - i0{12}rhusdf=(bdy_interp:dt) "acet" "ACETONE mixing ratio" "ppmv" Similarly add your species here. **Make sure you search registry.chem to make sure you have not defined a species twice.** A lot of names are reserved for compatibility with WRF-Chem code and we have no control over this. **If a name is already defined you can get away with reusing it directly.** **Every time you update the Registry, you need to completely recompile WRF-GC.** There is no shortcut to this, so make sure your edit of the registry is correct or the compile process will crash very early. Steps: * Update the WRF registry. In the ``chem`` directory, run: ``make install_registry``. * Clean all WRF-GC compiled code. In the ``WRF`` directory, run ``./clean -a``. * Reconfigure WRF. ``./configure -hyb`` (WRF version 3) or ``./configure`` (WRF version 4). This is as if you are reinstalling WRF-GC. * Compile WRF-GC. ``./compile em_real``. .. warning:: Be careful to back up your configuration files. Every WRF-GC recompile **will reset the namelist and configuration files.** .. rubric:: Footnotes .. [#f1] Long, M. S., Yantosca, R., Nielsen, J. E., Keller, C. A., da Silva, A., Sulprizio, M. P., Pawson, S., and Jacob, D. J.: Development of a grid-independent GEOS-Chem chemical transport model (v9-02) as an atmospheric chemistry module for Earth system models, Geosci. Model Dev., 8, 595–602, https://doi.org/10.5194/gmd-8-595-2015, 2015. .. [#f2] Eastham, S. D., Long, M. S., Keller, C. A., Lundgren, E., Yantosca, R. M., Zhuang, J., Li, C., Lee, C. J., Yannetti, M., Auer, B. M., Clune, T. L., Kouatchou, J., Putman, W. M., Thompson, M. A., Trayanov, A. L., Molod, A. M., Martin, R. V., and Jacob, D. J.: GEOS-Chem High Performance (GCHP v11-02c): a next-generation implementation of the GEOS-Chem chemical transport model for massively parallel applications, Geosci. Model Dev., 11, 2941–2953, https://doi.org/10.5194/gmd-11-2941-2018, 2018.