FlexChem

From Geos-chem
Revision as of 21:27, 10 August 2016 by Melissa Payer (Talk | contribs) (→‎Building the chemical mechanism)

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
Rely totally on the GEOS-Chem species database for looking up a species index from its name. GCST
  • Completed 24 Jun 2016
  • Validated 27 Jun 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
Update unit conversion routines:
  • Get molecular weights (MW_g, EmMW_g from the species database instead of from Input_Opt
  • Remove obsolete fields Input_Opt%TCVV and Input_Opt%XNUMOL
 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:

  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/). 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.
  2. Execute KPP using kpp gckpp.kpp. This will create the necessary gckpp_*.f90 files.
  3. Run rename_f90.sh to rename gckpp_*.f90 to gckpp_*.F90.
  4. 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.
  5. 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.
  6. 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)

Comparing KPP and SMVGEAR prod/loss output

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=FlexChem&oldid=27137"