Difference between revisions of "FlexChem"

From Geos-chem
Jump to: navigation, search
(Comparing KPP and SMVGEAR prod/loss output)
 
(207 intermediate revisions by 6 users not shown)
Line 1: Line 1:
On this page we provide information about the FlexChem chemical solver, which was introduced in [[GEOS-Chem v11-01#v11-01g|GEOS-Chem v11-01g]].
+
This content has been migrated to:
  
== Overview ==
+
* [https://kpp.readthedocs.io <tt>kpp.readthedocs.io</tt>]: User manual for The Kinetic Preprocessor (KPP)
 
+
* [https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/using-kpp-with-gc.html '''Update chemical mechanisms with KPP''' at <tt>geos-chem.readthedocs.io</tt>]
The clean and flexible reimplementation of the Kinetic PreProcessor package (aka KPP)&mdash;known as '''FlexChem'''&mdash;is nearing full integration into GEOS-Chem. Most of the remaining FlexChem development work will focus on replacing legacy infrastructure&mdash;which prevents GEOS-Chem from operating efficiently in high-performance computing (HPC) environments&mdash;with newer, more efficient algorithms.
+
 
+
Check back soon for the latest information!
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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.
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="600px"|Task
+
!width="150px"|Developer
+
!width="250px"|Status
+
 
+
|-valign="top"
+
|Add FlexChem into [[GEOS-Chem v11-01#v11-01c|v11-01c]]
+
|Mike Long
+
|Completed 14 Dec 2015
+
 
+
|-valign="top"
+
|Enable the "Tropchem" mechanism
+
|Mike Long
+
|Completed 14 Dec 2015
+
 
+
|-valign="top"
+
|Restore the OH and HO2 diagnostics (ND43)
+
|Melissa Sulprizio
+
|Completed 18 Dec 2015
+
 
+
|-valign="top"
+
|Remove CSPEC array and replaced with <tt>State_Chm%Species</tt>
+
|Melissa Sulprizio
+
|Completed 22 Dec 2015
+
 
+
|-valign="top"
+
|Enable a temporary workaround for family tracers (ISOPN, MMN, CFCX, HCFCX)
+
|Mike Long
+
|Completed 25 Jan 2016
+
 
+
|-valign="top"
+
|Enable FAST-JX photochemistry
+
|Mike Long
+
|Completed 25 Jan 2016
+
 
+
|-valign="top"
+
|Enable the "Benchmark" (aka "Standard") chemistry mechanism
+
|Melissa Sulprizio
+
|Completed 29 Jan 2016
+
 
+
|-valign="top"
+
|Restore the broken J-value diagnostic (ND22)
+
|Melissa Sulprizio
+
|Completed 15 Mar 2016
+
 
+
|-valign="top"
+
|Parallelize the main KPP driver loop; fixed other minor issues
+
|Bob Yantosca
+
|Completed 30 Mar 2016
+
 
+
|-valign="top"
+
|Enable the "SOA" and "SOA-SVPOA" mechanisms
+
|Lizzie Lundgren
+
|Completed 01 Apr 2016
+
 
+
|-valign="top"
+
|Merge FlexChem code based on [[GEOS-Chem v11-01#v11-01c|v11-01c]] with [[GEOS-Chem v11-01#v11-01f|v11-01f]]
+
|Melissa Sulprizio
+
|Completed 20 Apr 2016
+
 
+
|-valign="top"
+
|Add KPP repository to Bitbucket (https://bitbucket.org/gcst/kpp)
+
|Mike Long
+
|Completed 19 Apr 2016
+
 
+
|-valign="top"
+
|Create new <tt>gckpp_*.F90</tt> files from the updated KPP solver package
+
|Melissa Sulprizio
+
|Completed 22 Apr 2016
+
 
+
|-valign="top"
+
|Enable the "UCX" mechanism
+
|Melissa Sulprizio
+
|Completed 26 Apr 2016
+
 
+
|-valign="top"
+
|Introduce a new prod/loss diagnostic into the KPP solver package
+
|Mike Long
+
|Completed 29 Apr 2016
+
 
+
|-valign="top"
+
|Complete unit tests and 1-month benchmarks for the Standard, Tropchem, UCX, SOA, and SOA-SVPOA simulations
+
|Melissa Sulprizio<br>Lizzie Lundgren
+
|Completed 05 May 2016
+
 
+
|-valign="top"
+
|Remove tracer indices of Rn, Pb, Be, Hg, and POPs simulations from <tt>tracerid_mod.F</tt>. (This paves the way for us to retire <tt>tracerid_mod.F</tt>.)
+
|Bob Yantosca
+
|Completed 02 May 2016
+
 
+
|-valign="top"
+
|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.
+
 
+
|-valign="top"
+
|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
+
 
+
|-valign="top"
+
|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
+
 
+
|-valign="top"
+
|Merge FlexChem with other [[GEOS-Chem v11-01#v11-01g|v11-01g]] updates and bug fixes
+
|Bob Yantosca
+
|Completed 17 May 2016
+
 
+
|-valign="top"
+
|Remove family tracer fields of the <tt>Input_Opt</tt> object, namely: <tt>TRACER_N_CONST, TRACER_CONST, TRACER_COEFF, ID_EMITTED</tt>.  These were only used by SMVGEAR and are now obsolete.
+
|Bob Yantosca
+
|Completed 18 May 2016
+
 
+
|-valign="top"
+
|Create mapping vectors in the <tt>State_Chm</tt> 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
+
 
+
|-valign="top"
+
|Remove all 1-D loop indexing variables (<tt>JLOOP, KLOOP, KTLOOP, JLOP, IXSAVE, IYSAVE, IZSAVE</tt>) that were used by SMVGEAR
+
|Melissa Sulprizio
+
|Completed 19 May 2016
+
 
+
|-valign="top"
+
|Remove SMVGEAR input files (<tt>globchem.dat, mglob.dat</tt>) and associated subroutines (<tt>readchem.F, reader.F</tt>)
+
|Melissa Sulprizio
+
|Completed 30 Jun 2016
+
 
+
|-valign="top"
+
|Remove <tt>tracerid_mod.F</tt> and related tracer ID flags (<tt>IDTxxxx, IDxxxx</tt>) from GEOS-Chem.
+
|Jacob Group Code-A-Thon
+
|Completed 24 Jun 2016
+
 
+
|-valign="top"
+
|Use the GEOS-Chem species database to retrieve species index from species name
+
|GCST
+
|Completed 24 Jun 2016
+
 
+
|-valign="top"
+
|Remove tracers from restart files and read/write restart file species only
+
|Lizzie Lundgren
+
|Completed 12 Jul 2016
+
 
+
|-valign="top"
+
|Create unit conversion routines for species that mimic existing routines for tracers or convert to/from molecules/cm3
+
|Lizzie Lundgren
+
|Completed 25 Jul 2016
+
 
+
|-valign="top"
+
|Add State_Chm variable to track species units throughout GEOS-Chem (<tt>State_Chm%Spc_Units</tt>)
+
|Lizzie Lundgren
+
|Completed 25 Jul 2016
+
 
+
|-valign="top"
+
|Remove the remaining family tracers (ISOPN, MMN, CFCX, HCFCX). Henceforth,  FlexChem will only work with individual species.
+
|Melissa Sulprizio
+
|Completed 28 Jul 2016
+
 
+
|-valign="top"
+
|Move the non-advected species initial unit conversion of background values from <tt>INIT_FLEXCHEM</tt> (called during chemistry) to <tt>READ_GC_RESTART</tt> (called during restart file read)
+
|Lizzie Lundgren
+
|Completed 4 Aug 2016
+
 
+
|-valign="top"
+
|Store species background concentrations values previously stored in <tt>globchem.dat</tt> in the species database
+
|Lizzie Lundgren
+
|Completed 11 Aug 2016
+
 
+
|-valign="top"
+
|Rebuild Standard, Tropchem, UCX, SOA, SOA-SVPOA chemistry mechanisms to use the new prod/loss functionality in KPP (i.e. <tt>FLUX on</tt>)
+
|Melissa Sulprizio
+
|Completed 13 Jul 2016
+
 
+
|-valign="top"
+
|Attach the new KPP prod/loss output to the GEOS-Chem prod/loss diagnostic (ND65)
+
|Melissa Sulprizio
+
|Completed 11 Aug 2016
+
 
+
|-valign="top"
+
|Remove <tt>State_Chm%Tracers</tt> and use species concentrations in <tt>State_Chm%Species</tt> instead
+
|GCST
+
|In progress
+
 
+
|-valign="top"
+
|Rebuild Standard, Tropchem, UCX, SOA, SOA-SVPOA chemistry mechanisms with [http://www.paratools.com/Kppa Kppa]
+
|GCST
+
|TBD
+
 
+
|-valign="top"
+
|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
+
 
+
|-valign="top"
+
|Validate FlexChem with additional debugging, unit testing, and benchmarking
+
|GCST
+
|TBD
+
 
+
|-valign="top"
+
|Update GEOS-Chem documentation and user manual for v11-01
+
|GCST
+
|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 <tt>kpp</tt> in the <tt>kpp/kpp-2.2.3_01/bin/</tt> directory. Next, add KPP to your PATH. For bash users, add the following lines the <tt>~/.bashrc</tt> 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
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 21:18, 10 August 2016 (UTC)
+
 
+
=== Building a custom chemical mechanism ===
+
 
+
[[GEOS-Chem v11-01#v11-01g|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#Mechanisms_in_GEOS-Chem_v10-01_and_later_versions|''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 source code|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:
+
 
+
#The <tt>geos2kpp_parser.pl</tt> script can be used to create <tt>globchem.eqn</tt>, <tt>globchem.spc</tt>, and <tt>globchem.def</tt> files from a <tt>globchem.dat</tt> file. You may also choose to start from the preexisting <tt>globchem.eqn</tt>, <tt>globchem.spc</tt>, and <tt>globchem.def</tt> files found in the <tt>KPP</tt> subdirectories of the GEOS-Chem source code (e.g. <tt>Code.v11-01/KPP/Standard/</tt>).
+
#If needed, edit <tt>globchem.eqn</tt> to add/modify reactions for your mechanism and edit <tt>globchem.spc</tt> to add/modify species to your mechanism. Put the final <tt>globchem.*</tt> files in the same directory as the <tt>gckpp.kpp</tt> file.
+
#Execute KPP using <code>kpp gckpp.kpp</code>. This will create the necessary <tt>gckpp_*.f90</tt> files.
+
#Run <code>rename_f90.sh</code> to rename <tt>gckpp_*.f90</tt> to <tt>gckpp_*.F90</tt>.
+
#Open <tt>copy_gckpp.sh</tt> and modify the line for <tt>codedir</tt>. Save and run <code>copy_gckpp.sh</code>. This will copy the <tt>gckpp_*.F90</tt> files to <tt>codedir/Custom/</tt>.
+
#Compile GEOS-Chem for the new mechanism by including <tt>CHEM=Custom</tt> in your make command.
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|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 <tt>#FLUX on</tt> to the <tt>gckpp.kpp</tt> file. For example:
+
 
+
  #INTEGRATOR rosenbrock
+
  #LANGUAGE Fortran90
+
  #DRIVER none
+
  #HESSIAN off
+
  #MEX off
+
  #STOICMAT off
+
  <span style="color:red">#FLUX on</span>
+
 
+
  #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 <tt>gckpp.kpp</tt>, the chemistry mechanism will need to be rebuilt with KPP as [[#Building the chemical mechanism|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 [http://acmg.seas.harvard.edu/geos/doc/man/chapter_5.html#PLMenu ND65 diagnostic].
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|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 <tt>NREAC</tt> additional species to track. Making this code more efficient is a task for future development.
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 21:18, 10 August 2016 (UTC)
+
 
+
== Removal of family tracers ==
+
 
+
In [[GEOS-Chem v9-02]] we removed all family tracers from GEOS-Chem.  For example, the NOx family was replaced by individual tracers NO, O3, NO3, and HNO2.  Similarly, the Ox family was replaced by individual tracers O3, NO2, and NO3.
+
 
+
But certain updates that were made to GEOS-Chem after v9-02 introduced new family tracers into the various chemistry mechanisms:
+
 
+
* The [[Caltech isoprene scheme]] added the ISOPN and MVKN families
+
* The [[UCX chemistry mechanism]] added the CFCX and HCFCX families
+
 
+
The implementation of the FlexChem chemical solver package in [[GEOS-Chem v11-01]] forced us to remove these family tracers, because the KPP chemical solver is designed to only include individual species in its mechanism.  Removing these families also allows us to avoid some cumbersome sections of code that were used to construct each family from its constituent members.
+
 
+
Therefore, the following families have been removed from [[GEOS-Chem v11-01#v11-01g|GEOS-Chem v11-01g]], and replaced with individual species:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px" bgcolor="#FF0000"|Removed
+
!width="375px" colspan="3" bgcolor="#00FF00"|Added as individual advected species
+
!width="350px" bgcolor="#CCCCCC"|[[GEOS-Chem_chemistry_mechanisms#NOx-Ox-hydrocarbon-aerosol_chemistry_and_variants|Mechanisms]] in which these are used
+
 
+
|-valign="top"|
+
|width="125px"|ISOPN
+
|width="125px"|ISOPND
+
|width="125px"|ISOPNB
+
|
+
|width="350px"|Standard, UCX, TropChem, SOA, SOA-SVPOA
+
 
+
|-valign="top"
+
|MVKN
+
|MACRN
+
|MVKN
+
|
+
|Standard, UCX, TropChem, SOA, SOA-SVPOA
+
 
+
|-valign="top"
+
|CFCX
+
|CFC113
+
|CFC114
+
|CFC115
+
|Standard, UCX
+
 
+
|-valign="top
+
|HCFCX
+
|HCFC22
+
|HCFC141b
+
|HCFC142b
+
|Standard, UCX
+
 
+
|}
+
 
+
The constituents of each former family are now included as advected species in the various GEOS-Chem mechanisms.  To obtain diagnostic output for the former families, you can save out each of the individual species and combine the output in post-processing.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:20, 16 August 2016 (UTC)
+
 
+
== Validation ==
+
 
+
=== Preliminary timing tests ===
+
 
+
Several 7-day time tests were performed with the FlexChem code in order to evaluate model performance. The time tests all used 4&deg; x 5&deg; GEOS-FP met fields and were assigned 8 CPUs. Three model version were evaluated: [[GEOS-Chem v11-01#v11-01f|v11-01f]], FlexChem without production/loss diagnostics enabled in KPP, and FlexChem with [[FlexChem#Production_.26_loss_diagnostic|production/loss diagnostics enabled in KPP]]. The results for the [[GEOS-Chem_chemistry_mechanisms#Mechanisms_in_GEOS-Chem_v10-01_and_later_versions|standard mechanism]] and [[NOx-Ox-HC-aerosol|tropchem mechanism]] are summarized below.
+
 
+
 
+
'''Standard Chemistry Mechanism'''
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="160px"|Model Version
+
!width="100px"|Wall Time
+
!width="100px"|CPU Time
+
!width="160px"|CPU Time / Wall Time
+
!width="100px"|Memory
+
|-
+
|v11-01f
+
|1:43:15
+
|10:55:22
+
|6.3474 (79.34% ideal)
+
|6.32 GB
+
|-
+
|FlexChem w/o prod/loss
+
|3:30:20
+
|21:04:39
+
|6.0126 (75.16% ideal)
+
|5.42 GB
+
|-
+
|FlexChem w/ prod/loss
+
|4:27:38
+
|1-01:52:07
+
|5.7994 (72.49% ideal)
+
|6.90 GB
+
|}
+
 
+
 
+
'''Tropchem Chemistry Mechanism'''
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="160px"|Model Version
+
!width="100px"|Wall Time
+
!width="100px"|CPU Time
+
!width="160px"|CPU Time / Wall Time
+
!width="100px"|Memory
+
|-
+
|v11-01f
+
|0:48:23
+
|5:15:25
+
|6.5191 (81.49% ideal)
+
|3.57 GB
+
|-
+
|FlexChem w/o prod/loss
+
|1:11:58
+
|8:03:14
+
|6.7147 (83.93% ideal)
+
|2.76 GB
+
|-
+
|FlexChem w/ prod/loss
+
|1:24:26
+
|9:17:19
+
|6.6007 (82.51% ideal)
+
|3.37 GB
+
|}
+
 
+
 
+
These time tests were performed with code that will become [[GEOS-Chem v11-01#v11-01g|v11-01g]]. The GEOS-Chem Support Team will continue to evaluate and improve on the performance of the FlexChem code for the [[GEOS-Chem v11-01]] release.
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 12:39, 17 August 2016 (UTC)
+
 
+
== Known issues ==
+
 
+
TBD
+

Latest revision as of 20:24, 4 August 2022

This content has been migrated to: