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 [1] and Eastham et al., 2018 [2]. 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.,

integer :: gi_a3o2, gi_acet, gi_acta ! ...

Add the species with a sensible name, e.g., gi_newname.

Go to WRFGC_IdxSetup:

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:

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:

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:

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.

Footnotes

[1]

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.

[2]

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.