FlexChem

From Geos-chem
Revision as of 21:41, 11 August 2016 by Lizzie Lundgren (Talk | contribs) (Milestones)

Jump to: navigation, search

On this page we provide information about the FlexChem chemical solver, which was introduced in GEOS-Chem v11-01g.

Overview

The clean and flexible reimplementation of the Kinetic PreProcessor package (aka KPP)—known as FlexChem—is nearing full integration into GEOS-Chem. Most of the remaining FlexChem development work will focus on replacing legacy infrastructure—which prevents GEOS-Chem from operating efficiently in high-performance computing (HPC) environments—with newer, more efficient algorithms.

Check back soon for the latest information!

--Bob Yantosca (talk) 19:58, 19 May 2016 (UTC)

Milestones

The following table shows several milestones that were achieved in the FlexChem implementation, development, as well as ongoing development tasks.

Task Developer Status
Add FlexChem into v11-01c Mike Long Completed 14 Dec 2015
Enable the “tropchem” mechanism Mike Long Completed 14 Dec 2015
Restore the OH and HO2 diagnostics (ND43) Melissa Sulprizio Completed 18 Dec 2015
Remove CSPEC array and replaced with State_Chm%Species Melissa Sulprizio Completed 22 Dec 2015
Enable a temporary workaround for family tracers (ISOPN, MMN) Mike Long Completed 25 Jan 2016
Enable FAST-JX photochemistry Mike Long Completed 25 Jan 2016
Enable the "benchmark" chemistry mechanism Melissa Sulprizio Completed 29 Jan 2016
Fix HBr and HOBr hetchem rates for the "tropchem" mechanism Melissa Sulprizio Completed 04 Feb 2016
Fix unit conversions for heterogeneous chemistry Mike Long Completed 18 Feb 2016
Restore the broken J-value diagnostic (ND22) Melissa Sulprizio Completed 15 Mar 2016
Parallelize the main KPP driver loop; fixed other minor issues Bob Yantosca Completed 30 Mar 2016
Enable the SOA and SOA-SVPOA mechanisms Lizzie Lundgren Completed 01 Apr 2016
Add more parallelization fixes Bob Yantosca Completed 18 Apr 2016
Merge FlexChem with v11-01f Melissa Sulprizio Completed 20 Apr 2016
Add KPP repository to Bitbucket (https://bitbucket.org/gcst/kpp) Mike Long Completed 19 Apr 2016
Create new gckpp* files from the updated KPP solver package Melissa Sulprizio Completed 22 Apr 2016
Enable the UCX mechanism Melissa Sulprizio Completed 26 Apr 2016
Introduce a new prod/loss diagnostic into the KPP solver package Mike Long Completed 29 Apr 2016
Fix various other bugs and cleaned up some leftover things Melissa Sulprizio Completed 04 May 2016
Complete unit tests and 1-month benchmarks for the tropchem, benchmark, UCX, SOA, and SOA-SVPOA simulations Melissa Sulprizio
Lizzie Lundgren
Completed 05 May 2016
Remove tracer indices of Rn, Pb, Be, Hg, and POPs simulations from tracerid_mod.F. (This paves the way for us to retire tracerid_mod.F.) Bob Yantosca Completed 02 May 2016
Add a fast species name lookup algorithm Bob Yantosca Code is in place as of 04 May 2016, but has not been implemented throughout GEOS-Chem yet.
Store the unique list of GEOS-Chem species in the GEOS-Chem species database object. (In other words, we combine the list of advected tracers with the list of KPP chemical species and remove duplicate entries). Bob Yantosca Completed 09 May 2016
Store the indices of each species in the KPP chemical reaction matrix in the GEOS-Chem species database object. Bob Yantosca Completed 09 May 2016
Merge FlexChem with other v11-01g updates Bob Yantosca Completed 17 May 2016
Remove family tracer fields of the Input_Opt object, namely : TRACER_N_CONST, TRACER_CONST, TRACER_COEFF, ID_EMITTED. These were only used by SMVGEAR and are now obsolete. Bob Yantosca Completed 18 May 2016
Create mapping vectors in the State_Chm object to store the ID numbers of species that are advected, dry-deposited, wet-deposited, and/or included in the KPP chemical mechanism Bob Yantosca Completed 19 May 2016
Remove all 1-D loop indexing variables (JLOOP, KLOOP, KTLOOP, JLOP, IXSAVE, IYSAVE, IZSAVE) that were used by SMVGEAR Melissa Sulprizio Completed 19 May 2016
Remove SMVGEAR input files (globchem.dat, mglob.dat) and associated subroutines (readchem.F, reader.F) Melissa Sulprizio Completed 30 Jun 2016
Remove tracerid_mod.F and related tracer ID flags (IDTxxxx, IDxxxx) from GEOS-Chem. GCST
  • Completed 24 Jun 2016
  • Validated 27 Jun 2016
Use the GEOS-Chem species database to retrieve species index from species name GCST
  • Completed 24 Jun 2016
  • Validated 27 Jun 2016
Remove tracers from restart files and read/write restart file species only Lizzie Lundgren
  • Completed 12 Jul 2016
Create unit conversion routines for species that mimic existing routines for tracers or convert to/from molecules/cm3 Lizzie Lundgren
  • Completed 25 Jul 2016
Add State_Chm variable to track species units throughout GEOS-Chem (State_Chm%Spc_Units) Lizzie Lundgren
  • Completed 25 Jul 2016
Remove the remaining family tracers (ISOPN, MMN, CFCX, HCFCX). Henceforth, FlexChem will only work with individual species. Melissa Sulprizio
  • Completed 28 Jul 2016
  • Validated 01 Aug 2016
Move the non-advected species initial unit conversion of background values from init_flexchem (called during chemistry) to read_gc_restart (called during restart file read) Lizzie Lundgren
  • Completed 4 Aug 2016
Store species background concentrations values previously stored in globchem.dat in the species database Lizzie Lundgren
  • Completed 11 Aug 2016
Attach the new KPP prod/loss output to the GEOS-Chem prod/loss diagnostic Melissa Sulprizio
  • Completed 11 Aug 2016
  • Validated 11 Aug 2016
Remove State_Chm%Tracers and use species concentrations in State_Chm%Species instead GCST In progress
Update the GEOS-Chem Makefiles so that a fresh version of KPP will be built (using a custom chemical mechanism that you specify) each time GEOS-Chem is compiled. GCST TBD
Validate FlexChem with additional debugging, unit testing, and benchmarking GCST TBD
Update GEOS-Chem documentation and user manual for v11-01 GCST TBD

--Lizzie Lundgren (talk) 21:41, 11 August 2016 (UTC)

Adding chemical mechanisms in FlexChem

KPP source code

The KPP source code for FlexChem is currently available as a Git repository on Bitbucket. It can be obtained using:

git clone https://bitbucket.org/gcst/kpp

Once you have KPP on your system, you will need to build it:

cd kpp/kpp-2.2.3_01
make clean
make

If the build completed successfully, you should see the executable kpp in the kpp/kpp-2.2.3_01/bin/ directory. Next, add KPP to your PATH. For bash users, add the following lines the ~/.bashrc file:

export PATH=$PATH:/PATH_TO_KPP/KPP/kpp-2.2.3_01/bin/
export KPP_HOME=/PATH_TO_KPP/KPP/kpp-2.2.3_01

--Melissa Sulprizio (talk) 21:18, 10 August 2016 (UTC)

Building a custom chemical mechanism

GEOS-Chem v11-01g has five pre-built chemical mechanisms: standard, tropchem, SOA, SOA-SVPOA, and UCX. These mechanisms are described on our GEOS-Chem chemistry mechanisms wiki page.

GEOS-Chem will eventually include the option to create a custom chemistry mechanism and automatically build that mechanism with KPP when GEOS-Chem is compiled. For now, users still need to build custom chemistry mechanisms manually. The KPP Git repository includes the following files:

 geos2kpp_parser.pl
 gckpp.kpp
 rename_f90.sh
 copy_gckpp.sh

These files can be used to build a custom chemistry mechanisms with KPP. Follow these steps:

  1. The geos2kpp_parser.pl script can be used to create globchem.eqn, globchem.spc, and globchem.def files from a globchem.dat file. You may also choose to start from the preexisting globchem.eqn, globchem.spc, and globchem.def files found in the KPP subdirectories of the GEOS-Chem source code (e.g. Code.v11-01/KPP/Standard/).
  2. If needed, edit globchem.eqn to add/modify reactions for your mechanism and edit globchem.spc to add/modify species to your mechanism. Put the final globchem.* files in the same directory as the gckpp.kpp file.
  3. Execute KPP using kpp gckpp.kpp. This will create the necessary gckpp_*.f90 files.
  4. Run rename_f90.sh to rename gckpp_*.f90 to gckpp_*.F90.
  5. Open copy_gckpp.sh and modify the lines for codedir. Save and run copy_gckpp.sh. This will copy the gckpp_*.F90 files to codedir/Custom.
  6. Compile GEOS-Chem for the new mechanism by including CHEM=Custom in your make command.

--Melissa Sulprizio (talk) 21:18, 10 August 2016 (UTC)

Production & loss diagnostic

Mike Long implemented prod/loss structure parsing in the KPP source code. This option can be turned on by adding the line #FLUX on to the gckpp.kpp file. For example:

  #INTEGRATOR rosenbrock
  #LANGUAGE Fortran90
  #DRIVER none
  #HESSIAN off
  #MEX off
  #STOICMAT off
  #FLUX on
  
  #INCLUDE globchem.spc
  #INCLUDE globchem.eqn

For the FLUX option to work properly, MEX and HESSIAN must be turned off as shown above.

When changing any of the settings in gckpp.kpp, the chemistry mechanism will need to be rebuilt with KPP as described above.

The pre-built chemistry mechanisms (Standard, Tropchem, SOA, SOA-SVPOA, and UCX) were built with the FLUX option turned on. The prod/loss rates from KPP can be saved out in GEOS-Chem via the ND65 diagnostic.

--Melissa Sulprizio (talk) 21:18, 10 August 2016 (UTC)

Inefficiencies in prod/loss code

The current implementation of the prod/loss diagnostic output in KPP is somewhat inefficient. The code is set up so that KPP calculates the prod/loss of ALL species, even though a user may only want prod/loss rates for a few species. This likely adds considerable memory overhead because KPP has NREAC additional species to track. Making this code more efficient is a task for future development.

--Melissa Sulprizio (talk) 21:18, 10 August 2016 (UTC)

Comparing KPP and SMVGEAR prod/loss output

During the implementation of FlexChem in GEOS-Chem v11-01g, KPP's new prod/loss diagnostics were validated against SMVGEAR's prod/loss diagnostics. We list the prod/loss rates [molec/cm3/s] for several families after a 20-minute run below:

Family Name v11-01f
(SMVGEAR)
v11-01g
(KPP)
POX 666.15 194722.60
LOX 15410.74 208939.00
PCO 5623.75 5610.81
LCO 9129.74 8771.62
PBrOx 5703.22 58242.10
PBry 2.04 74904.60
LBry 1.96E-04 74902.59

The differences in the prod/loss rates returned by SMVGEAR versus KPP are large for most of the families. Examination of the prod/loss code revealed that SMVGEAR is missing many of the reactions that KPP is flagging for inclusion in the prod/loss rate calculations. For example, the reactions that KPP uses for calculating PBrOx in the tropchem mechanism are listed below:

* HBr + OH --> RR240 + Br + H2O
  2 BrO --> RR241 + 2 Br + O2
  BrO + NO --> RR243 + Br + NO2
* Br2 + OH --> RR245 + HOBr + Br
  BrO + OH --> RR246 + Br + HO2
* CHBr3 + OH --> RR255 + 3 Br
* CH2Br2 + OH --> RR256 + 2 Br
* CH3Br + OH --> RR257 + Br
* Br2 --> RR382 + 2 Br
  BrO --> RR383 + Br + O3
* HOBr --> RR384 + Br + OH
* BrNO3 --> RR385 + Br + NO3
* BrNO2 --> RR387 + Br + NO2
* CHBr3 --> RR388 + 3 Br
  Br + O3 --> RR237 + BrO + O2
  Br + NO3 --> RR247 + BrO + NO2
* BrNO3 --> RR386 + BrO + NO2

The starred reactions indicate reactions that SMVGEAR uses to compute PBrOx. KPP uses 17 total reactions for PBrOx, while SMVGEAR only uses 11 reactions. The number of reactions used in the prod/loss rate calculations for SMVGEAR and KPP (for the tropchem mechanism) are summarized below:

Family Name v11-01f
(SMVGEAR)
v11-01g
(KPP)
POX 92 163
LOX 45 100
PCO 57 57
LCO 7 7
PBrOx 11 17
PBry 4 34
LBry 0 30

The KPP generally use many more reactions in the prod/loss calculations than SMVGEAR. This may explain the large differences in the prod/loss rates returned by KPP as compared to SMVGEAR.

Note that SMVGEAR and KPP use the same number of reactions for calculating PCO and LCO (in fact, the reactions used are identical). The PCO and LCO rate values listed in the first table are also fairly similar between the SMVGEAR and KPP runs. This indicates that we can reasonably reproduce the old prod/loss rates from SMVGEAR when KPP uses the same reactions.

--Melissa Sulprizio (talk) 21:00, 11 August 2016 (UTC)

Validation

TBD

Known issues

TBD