|
|
| (239 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-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)—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!
| + | |
| − | | + | |
| − | --[[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 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 State_Chm%Species
| + | |
| − | |Melissa Sulprizio
| + | |
| − | |Completed 22 Dec 2015
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Enable a temporary workaround for family tracers (ISOPN, MMN)
| + | |
| − | |Mike Long
| + | |
| − | |Completed 25 Jan 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Enable FAST-JX photochemistry
| + | |
| − | |Mike Long
| + | |
| − | |Completed 25 Jan 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Enable the "benchmark" chemistry mechanism
| + | |
| − | |Melissa Sulprizio
| + | |
| − | |Completed 29 Jan 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Fix HBr and HOBr hetchem rates for the "tropchem" mechanism
| + | |
| − | |Melissa Sulprizio
| + | |
| − | |Completed 04 Feb 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Fix unit conversions for heterogeneous chemistry
| + | |
| − | |Mike Long
| + | |
| − | |Completed 18 Feb 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"
| + | |
| − | |Add more parallelization fixes
| + | |
| − | |Bob Yantosca
| + | |
| − | |Completed 18 Apr 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Merge FlexChem with 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 gckpp* 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"
| + | |
| − | |Fix various other bugs and cleaned up some leftover things
| + | |
| − | |Melissa Sulprizio
| + | |
| − | |Completed 04 May 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Complete unit tests and 1-month benchmarks for the tropchem, benchmark, 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 <code>tracerid_mod.F</code>. (This paves the way for us to retire <code>tracerid_mod.F</code>.)
| + | |
| − | |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 v11-01g updates
| + | |
| − | |Bob Yantosca
| + | |
| − | |Completed 17 May 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Remove family tracer fields of the <code>Input_Opt</code> object, namely : <code>TRACER_N_CONST, TRACER_CONST, TRACER_COEFF, ID_EMITTED</code>. These were only used by SMVGEAR and are now obsolete.
| + | |
| − | |Bob Yantosca
| + | |
| − | |Completed 18 May 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Create mapping vectors in the <code>State_Chm</code> 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 (<code>JLOOP, KLOOP, KTLOOP, JLOP, IXSAVE, IYSAVE, IZSAVE</code>) that were used by SMVGEAR
| + | |
| − | |Melissa Sulprizio
| + | |
| − | |Completed 19 May 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Remove SMVGEAR input files (<code>globchem.dat, mglob.dat</code>) and associated subroutines (<code>readchem.F, reader.F</code>)
| + | |
| − | |Melissa Sulprizio
| + | |
| − | |Completed 30 Jun 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Remove <code>tracerid_mod.F</code> and related tracer ID flags (<code>IDTxxxx</code>, <code>IDxxxx</code>) from GEOS-Chem.
| + | |
| − | |GCST
| + | |
| − | |
| + | |
| − | *Completed 24 Jun 2016
| + | |
| − | *Validated 27 Jun 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |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
| + | |
| − | | + | |
| − | |-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 | + | |
| − | *Validated 01 Aug 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Update unit conversion routines:
| + | |
| − | *Get molecular weights (<code>MW_g, EmMW_g</code> from the species database instead of from <code>Input_Opt</code>
| + | |
| − | *Remove obsolete fields <code>Input_Opt%TCVV</code> and <code>Input_Opt%XNUMOL</code>
| + | |
| − | |Lizzie Lundgren
| + | |
| − | |In progress
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Store all species concentrations in <code>State_Chm%Species</code> (thus making <code>State_Chm%Tracers</code> redundant)
| + | |
| − | |GCST
| + | |
| − | |In progress
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Attach the new KPP prod/loss output to the GEOS-Chem prod/loss diagnostic
| + | |
| − | |Melissa Sulprizio
| + | |
| − | |In progress
| + | |
| − | | + | |
| − | |-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
| + | |
| − | | + | |
| − | |}
| + | |
| − | | + | |
| − | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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 <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 the 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 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 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 the 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> 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 the <tt>globchem.eqn</tt> to add/modify reactions for your mechanism and edit the <tt>globchem.spc</tt> file 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 the <tt>copy_gckpp.sh</tt> script and modify the lines for <tt>codedir</tt> and <tt>chem</tt>. Save and run <code>copy_gckpp.sh</code>. This will copy the <tt>gckpp_*.F90</tt> files to <tt>codedir/chem</tt>.
| + | |
| − | #In your code directory, change directories to the <tt>KPP/MECHANISM/</tt> directory (where <tt>MECHANISM</tt> is the name of the new directory created in step 3). Copy the <tt>Makefile</tt> and <tt>gckpp_HetRates.F90</tt> files from the <tt>KPP/Standard/</tt> directory to your mechanism directory.
| + | |
| − | #Compile GEOS-Chem for the new mechanism by including <tt>CHEM=MECHANISM</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.
| + | |
| − | | + | |
| − | The KPP mechanism will need to be rebuilt with prod/loss enabled 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 can be saved out in GEOS-Chem via the ND65 diagnostic menu.
| + | |
| − | | + | |
| − | --[[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)
| + | |
| − | | + | |
| − | ==== Comparing KPP and SMVGEAR prod/loss output ====
| + | |
