FlexChem
On this page we provide information about the FlexChem chemical solver, which was introduced in GEOS-Chem v11-01g.
Contents
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 |
|
Rely totally on the GEOS-Chem species database for looking up a species index from its name. | GCST |
|
Remove the remaining family tracers (ISOPN, MMN, CFCX, HCFCX). Henceforth, FlexChem will only work with individual species. | Melissa Sulprizio |
|
Update unit conversion routines:
|
Lizzie Lundgren | In progress |
Store all species concentrations in State_Chm%Species (thus making State_Chm%Tracers redundant)
|
GCST | In progress |
Attach the new KPP prod/loss output to the GEOS-Chem prod/loss diagnostic | Melissa Sulprizio | 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 |
--Bob Yantosca (talk) 19:34, 27 June 2016 (UTC)
Validation
TBD
Known issues
TBD
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 the 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 user-defined chemistry mechanism and build that KPP chemistry mechanism when you compile GEOS-Chem. For now, users still need to build the KPP 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 the chemistry mechanisms with KPP. Follow these steps:
- 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/). 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.
- Execute KPP using
kpp gckpp.kpp
. This will create the necessary gckpp_*.f90 files. - Run
rename_f90.sh
to rename gckpp_*.f90 to gckpp_*.F90. - Open copy_gckpp.sh and modify the lines for codedir and chem. Save and run
copy_gckpp.sh
. This will copy the gckpp_*.F90 files to codedir/chem. - Navigate to your code directory and change directories to KPP/MECHANISM/ (where MECHANISM is the name of the new directory created in step 3). Copy Makefile and gckpp_HetRates.F90 from the KPP/Standard/ directory to your new mechanism directory.
- Compile GEOS-Chem for the new mechanism by including CHEM=MECHANISM 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.
The KPP mechanism will need to be rebuilt with prod/loss enabled 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 can be saved out in GEOS-Chem via the ND65 diagnostic menu.
--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)