|
|
| (148 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| − | ----
| + | This content has been migrated to: |
| − | ----
| + | |
| − | <big><strong>GEOS-Chem v11-02-final</strong> '''will also carry the designation''' <strong>GEOS-Chem 12.0.0</strong>'''.''' We are migrating to a purely numeric versioning system in order to adhere more closely to software development best practices. For a complete description of the new versioning system, please see [[GEOS-Chem version numbering system|our ''GEOS-Chem version numbering system'' wiki page]].</big>
| + | |
| − | ----
| + | |
| − | ----
| + | |
| | | | |
| − | | + | * [https://kpp.readthedocs.io <tt>kpp.readthedocs.io</tt>]: User manual for The Kinetic Preprocessor (KPP) |
| − | 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]].
| + | * [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>] |
| − | | + | |
| − | == 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!
| + | |
| − | | + | |
| − | --[[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>). Instead, use the GEOS-Chem species database to retrieve species index from species name.
| + | |
| − | |Jacob Group Code-A-Thon
| + | |
| − | |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
| + | |
| − | |Completed 29 Aug 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Validate FlexChem with [[GEOS-Chem v11-01#v11-01g|v11-01g]] benchmarks
| + | |
| − | |GCST
| + | |
| − | |''1-month benchmark:''<br>Approved 14 Sep 2016
| + | |
| − | ''1-year benchmark:''<br>Approved 28 Sep 2016
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |Fix P/L diagnostics to ignore cycling reactions
| + | |
| − | |Mike Long
| + | |
| − | |08 Nov 2016
| + | |
| − | | + | |
| − | |-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
| + | |
| − | | + | |
| − | |}
| + | |
| − | | + | |
| − | == 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
| + | |
| − | git checkout -b GC_updates origin/GC_updates
| + | |
| − | | + | |
| − | 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 ===
| + | |
| − | | + | |
| − | ==== In GEOS-Chem v11-02 ====
| + | |
| − | | + | |
| − | [[GEOS-Chem v11-02]] has three pre-built chemical mechanisms: Standard, Tropchem, and SOA_SVPOA. 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 using the following files that can be found in the Custom mechanism subdirectory (e.g <tt>Code.v11-02/KPP/Custom/</tt>):
| + | |
| − | | + | |
| − | Custom.eqn
| + | |
| − | gckpp.kpp
| + | |
| − | build_mechanism.sh
| + | |
| − | rename_f90.sh (used by build_mechanism.sh)
| + | |
| − | | + | |
| − | The <tt>.eqn</tt> file currently included in each of the KPP mechanism subdirectories defines the variable species (<tt>#DEFVAR</tt>), fixed species (<tt>#DEFFIX</tt>), and reactions (<tt>#EQUATIONS</tt>) to include in that mechanism. The equations section is further broken down into gas-phase reactions, heterogeneous reactions, and photolysis reactions. The default custom mechanism defined in <tt>Custom.eqn</tt> is based on the [[GEOS-Chem_chemistry_mechanisms#Mechanisms_in_GEOS-Chem_v10-01_and_later_versions|Standard (UCX-based) mechanism]] (found in <tt>KPP/Standard/Standard.eqn</tt>). The production and loss families in the custom gckpp.kpp are also built for the [[GEOS-Chem_chemistry_mechanisms#Mechanisms_in_GEOS-Chem_v10-01_and_later_versions|Standard (UCX-based) mechanism]] (found in <tt> KPP/Standard/gckpp.kpp </tt>), and will not work with the <tt>Tropchem.eqn </tt>. If you would like to base your custom mechanism on the tropchem mechanism instead, simply copy the <tt>Tropchem.eqn </tt> and <tt> gckpp.kpp</tt> files over instead:
| + | |
| − | | + | |
| − | cd KPP/Custom/
| + | |
| − | cp ../Tropchem/Tropchem.eqn Custom.eqn
| + | |
| − | cp ../Tropchem/gckpp.kpp gckpp.kpp
| + | |
| − | | + | |
| − | #Edit the <tt>Custom.eqn</tt> to add or modify species and reactions for your mechanism. If you are adding a heterogeneous reaction or photolysis reaction, those require additional modifications to other files. See [[FlexChem#Adding_a_reaction_to_the_mechanism|the ''Adding a reaction to the mechanism section'' below]].
| + | |
| − | #Modify the <tt>gckpp.kpp</tt> file if needed. This file defines the KPP integrator and tells KPP to use the specified <tt>.eqn</tt> file to build the mechanism. This file also defines the prod/loss families as [[FlexChem#Production_.26_loss_diagnostic|described below]].
| + | |
| − | #Rebuild the mechanism with KPP by typing <tt>./build_mechanism.sh</tt>. The <tt>build_mechanism.sh</tt> script will call on KPP to build the necessary <tt>gckpp_*.F90</tt> files.
| + | |
| − | #Compile GEOS-Chem for the new mechanism by including <tt>CHEM=Custom</tt> in your make command. NOTE: If your custom mechanism is a UCX-based mechanism then you should also include <tt>NO_REDUCED=y</tt> in your make command.
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 17:54, 6 February 2018 (UTC)
| + | |
| − | | + | |
| − | --[[User:Jared Brewer|Jared Brewer]] 20:30, 25 July 2018 (UTC)
| + | |
| − | | + | |
| − | ==== In GEOS-Chem v11-01 ====
| + | |
| − | | + | |
| − | [[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
| + | |
| − | | + | |
| − | Note: You'll need to checkout the <tt>GC_updates</tt> branch in the KPP repository to access these files. This can be achieved with <code>git checkout GC_updates</code>.
| + | |
| − | | + | |
| − | 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 or modify reactions for your mechanism (see below) 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.
| + | |
| − | #Modify the <tt>gckpp.kpp</tt> file if needed. This file defines the KPP integrator and tells KPP to use the <tt>globchem.spc</tt> and <tt>globchem.eqn</tt> files to build the mechanism. This file also defines the prod/loss families as [[FlexChem#Production_.26_loss_diagnostic|described below]].<br><span style="color:red">IMPORTANT: The default <tt>gckpp.kpp</tt> file that is included with KPP does not define any prod/loss families. Therefore, you must make sure the ND65 prod/loss diagnostic is turned off in <tt>input.geos</tt> when you run GEOS-Chem. If you would like to use prod/loss families in your custom mechanism, you can see the <tt>gckpp.kpp</tt> files in the <tt>KPP</tt> subdirectories of the GEOS-Chem source code (e.g. <tt>Code.v11-01/KPP/Standard/gckpp.kpp</tt>) for examples.</span>
| + | |
| − | #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)
| + | |
| − | | + | |
| − | === Adding a reaction to the mechanism ===
| + | |
| − | | + | |
| − | No matter what reaction is being added, the general procedure is the same. A new line must be added to <tt>.eqn</tt> of the following form:
| + | |
| − | | + | |
| − | {700} A + B = C + 2.000D : REQN(ARG_A,ARG_B);
| + | |
| − | | + | |
| − | The first number (700) is a KPP tag. The specific value has no effect on the reaction, but this should uniquely identify the reaction. The second section denotes the reactants (A and B) as well as the products (C and D) of the reaction. If exactly one molecule is consumed or produced, then the factor can be omitted; otherwise the number of molecules consumed or produced should be specified with at least 1 decimal place of accuracy. The final section, between the colon and semi-colon, specifies the function and arguments which will be used to calculate the reaction rate constant k. For a two-body reaction, the overall rate at which the reaction proceeds will be calculated as k[A][B].
| + | |
| − | | + | |
| − | '''Two-body reactions'''
| + | |
| − | | + | |
| − | In the case of two-body reactions proceeding according to the Arrhenius equation, calculation of k is straightforwardly implemented by calling the GCARR function. For example, the most recent JPL chemical data evaluation (as of February 2017) specifies that the reaction O3 + NO produces NO2 and O2, and its Arrhenius parameters are A = 3.0x10^-12 and E/R = 1500. The entry for this reaction therefore reads as follows (noting the different sign convention used for E/R)
| + | |
| − | | + | |
| − | {1} O3 + NO = NO2 + O2 : GCARR(3.00E-12,0,-1500);
| + | |
| − | | + | |
| − | The exact implementation of the Arrhenius rate calculation can be found in <tt>gckpp.kpp</tt>, as can other rate functions such as that required for three-body, pressure-dependent reactions. Any rate function which is to be referenced in the <tt>.eqn</tt> file must be available in <tt>gckpp.kpp</tt> prior to building the reaction mechanism.
| + | |
| − | | + | |
| − | '''Photolysis reactions'''
| + | |
| − | | + | |
| − | Similarly, a photolysis reaction can be specified by giving the correct index of the <tt>PHOTOL</tt> array. This index can be determined by inspecting the file [[FAST-JX_v7.0_photolysis_mechanism#FJX_j2j.dat|<tt>FJX_j2j.dat</tt>]] in your run directory. For example, one branch of the NO3 photolysis reaction is specified in the <tt>.eqn</tt> file as
| + | |
| − | | + | |
| − | {522} NO3 + hv = NO2 + O : PHOTOL(<span style="color:red">12</span>)
| + | |
| − | | + | |
| − | Referring back to <tt>FJX_j2j.dat</tt> shows that reaction 12, as specified by the left-most index, is indeed NO3 = NO2 + O:
| + | |
| − | | + | |
| − | <span style="color:red">12</span> NO3 PHOTON NO2 O 0.886 /NO3 /
| + | |
| − | | + | |
| − | If your reaction is not already in <tt>FJX_j2j.dat</tt>, you may add it there. You may also need to modify <tt>FJX_spec.dat</tt> (also found in your run directory) to include cross-sections for your species.
| + | |
| − | | + | |
| − | Finally, you will need to update routine <tt>PHOTO_JX</tt> found in <tt>fast_jx_mod.F</tt> to archive the J-values for your new reaction to the ND22 diagnostic. The J-values are obtained from array <tt>ZPJ</tt> which uses the same index found in the <tt>FJX_j2j.dat</tt> file. For example:
| + | |
| − | | + | |
| − | !---------------------------------------------------------------
| + | |
| − | ! Archive J-values for ND22 diagnostic
| + | |
| − | !---------------------------------------------------------------
| + | |
| − | IF ( ND22 > 0 ) THEN
| + | |
| − |
| + | |
| − | ! Save J-values for 2PM diagnostic boxes
| + | |
| − | IF ( LTJV(ILON,ILAT) > 0 ) THEN
| + | |
| − |
| + | |
| − | DO L = 1, LD22
| + | |
| − | ! AD22 IDs 5, 6, and 15 (J-values for O3 and O2)
| + | |
| − | ! are handled in routine PHOTRATE_ADJ
| + | |
| − | ! Hardcode ZPJ indices based on valued from FJX_j2j.dat
| + | |
| − | ! for now (mps, 3/15/16)
| + | |
| − | AD22(ILON,ILAT,L, 1) = AD22(ILON,ILAT,L, 1) + ! JNO2
| + | |
| − | & ZPJ(L,<span style="color:red">11</span>,ILON,ILAT)
| + | |
| − | ...
| + | |
| − | | + | |
| − | Index 11 used for obtaining JNO2 correcponds to the index found <tt>FJX_j2j_mod.F90</tt>:
| + | |
| − | | + | |
| − | <span style="color:red">11</span> NO2 PHOTON NO O 1.000 /NO2 /
| + | |
| − | | + | |
| − | '''Heterogeneous reactions'''
| + | |
| − | | + | |
| − | Implementing new heterogeneous chemistry requires an additional step. For the reaction in question, a reaction should be added as usual, but this time the rate function should be given as an entry in the <tt>HET</tt> array. A simple example is uptake of HO2, specified as
| + | |
| − | | + | |
| − | {285} HO2 = O2 : HET(ind_HO2,1);
| + | |
| − | | + | |
| − | Note that the product in this case, O2, is actually a fixed species, so no O2 will actually be produced. O2 is used in this case only as a dummy product to satisfy the KPP requirement that all reactions have at least one product. Here, <tt>HET</tt> is simply an array of pre-calculated rate constants. The rate constants in <tt>HET</tt> are actually calculated in <tt>gckpp_HetRates.F90</tt>. To implement an additional heterogeneous reaction, the rate calculation must be added to this file. The following example illustrates a (fictional) heterogeneous mechanism which converts the species XYZ into CH2O. This reaction is assumed to take place on the surface of all aerosols, but not cloud droplets (this requires additional steps not shown here). Three steps would be required:
| + | |
| − | | + | |
| − | * Add a new line to the <tt>.eqn</tt> file, such as <tt>{900} XYZ = CH2O : HET(ind_XYZ,1);</tt>
| + | |
| − | * Add a new function to <tt>gckpp_HetRates.F90</tt> designed to calculate the heterogeneous reaction rate. As a simple example, we can copy the function <tt>HETNO3</tt> and rename it <tt>HETXYZ</tt>. This function accepts two arguments: molecular mass of the impinging gas-phase species, in this case XYZ, and the reaction's "sticking coefficient" - the probability that an incoming molecule will stick to the surface and undergo the reaction in question. In the case of <tt>HETNO3</tt>, it is assumed that all aerosols will have the same sticking coefficient, and the function returns a first-order rate constant based on the total available aerosol surface area and the frequency of collisions.
| + | |
| − | * Add a new line to the function <tt>SET_HET</tt> in <tt>gckpp_HetRates.F90</tt> which calls the new function with the appropriate arguments and passes the calculated constant to <tt>HET</tt>. Example: assuming a molar mass of 93 g/mol, and a sticking coefficient of 0.2, we would write <tt>HET(ind_XYZ, 1) = HETXYZ(9.30E1_fp, 2E-1_fp)</tt>
| + | |
| − | | + | |
| − | The function <tt>HETXYZ</tt> can then be specialized to distinguish between aerosol types, or extended to provide a second-order reaction rate, or whatever the user desires.
| + | |
| − | | + | |
| − | --[[User:Sebastian D. Eastham|Sebastian D. Eastham]] ([[User talk:Sebastian D. Eastham|talk]]) 22:45, 14 February 2017 (UTC)
| + | |
| − | | + | |
| − | == Chemical species in FlexChem ==
| + | |
| − | | + | |
| − | A complete list of chemical species included in the pre-built (Standard, Tropchem, SOA, SOA-SVPOA, UCX) mechanisms can be viewed on our [[Species in GEOS-Chem]] wiki page.
| + | |
| − | | + | |
| − | === Adding a chemical species ===
| + | |
| − | | + | |
| − | Adding chemical species to FlexChem can be achieved be following these simple steps:
| + | |
| − | | + | |
| − | #Add the species name(s) to the <tt>.spc</tt> file under the <tt>#DEFVAR</tt> or <tt>#DEFFIX</tt> section.
| + | |
| − | #Add or modify any reactions in the <tt>.eqn</tt> file under the <tt>#EQUATIONS</tt> section.
| + | |
| − | #Build the chemical mechanism with KPP by following [[#Building a custom chemical mechanism|the steps outlined above]].
| + | |
| − | | + | |
| − | NOTE: If a species is defined by KPP, it will automatically be added to the species database with the default settings for non-advected chemical species when GEOS-Chem runs. However, we recommend also adding your species to the species database by following [[GEOS-Chem_species_database#Adding_new_species_to_the_GEOS-Chem_species_database|these instructions]]. Including a species in the species database is required if the new species is to be defined as an advected species in <tt>input.geos</tt>.
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 17:27, 22 November 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)
| + | |
| − | | + | |
| − | == Production & loss diagnostic ==
| + | |
| − | | + | |
| − | Mike Long implemented the functionality for chemical prod/loss families in the KPP source code. With this option turned on, KPP will calculate the net prod/loss rates for user-defined chemical families.
| + | |
| − | | + | |
| − | === Adding production & loss families ===
| + | |
| − | | + | |
| − | KPP prod/loss families are turned on by the <tt>#FAMILIES</tt> token in the <tt>gckpp.kpp</tt> file. For example:
| + | |
| − | | + | |
| − | #INTEGRATOR rosenbrock
| + | |
| − | #LANGUAGE Fortran90
| + | |
| − | #DRIVER none
| + | |
| − |
| + | |
| − | #INCLUDE globchem.spc
| + | |
| − | #INCLUDE globchem.eqn
| + | |
| − |
| + | |
| − | <span style="color:green">#FAMILIES
| + | |
| − | POx : O3 + NO2 + 2NO3 + PAN + PMN + PPN + HNO4 + 3N2O5 + HNO3 + BrO + HOBr + BrNO2 + 2BrNO3 + MPN + ETHLN + ISN1 + ISOPNB + ISOPND + MACRN + MVKN + PROPNN + R4N2 + INPN + ISNP + INO2 + ISNOOA + ISNOOB + ISNOHOO + MAN2 + PRN1 + PRPN + R4N1 + PMNN + MACRNO2 + ClO + HOCl + ClNO2 + 2ClNO3 + 2Cl2O2 + 2OClO + O + O1D;
| + | |
| − | LOx : O3 + NO2 + 2NO3 + PAN + PMN + PPN + HNO4 + 3N2O5 + HNO3 + BrO + HOBr + BrNO2 + 2BrNO3 + MPN + ETHLN + ISN1 + ISOPNB + ISOPND + MACRN + MVKN + PROPNN + R4N2 + INPN + ISNP + INO2 + ISNOOA + ISNOOB + ISNOHOO + MAN2 + PRN1 + PRPN + R4N1 + PMNN + MACRNO2 + ClO + HOCl + ClNO2 + 2ClNO3 + 2Cl2O2 + 2OClO + O + O1D;
| + | |
| − | PCO : CO;
| + | |
| − | LCO : CO;
| + | |
| − | PSO4 : SO4;</span>
| + | |
| − | | + | |
| − | To add a new prod/loss family, add a new line to the <tt>#FAMILIES</tt> section with the format
| + | |
| − | | + | |
| − | FAM_NAME : MEMBER_1 + MEMBER_2 + ... + MEMBER_N;
| + | |
| − | | + | |
| − | The family name must start with <tt>P</tt> or <tt>L</tt> to indicate whether KPP should calculate a production or a loss rate.
| + | |
| − | | + | |
| − | <span style="color:red">'''IMPORTANT:''' When adding a prod/loss family or changing any of the other settings in <tt>gckpp.kpp</tt>, the chemistry mechanism will need to be rebuilt with KPP as [[#Building a custom chemical mechanism|described above]].</span>
| + | |
| − | | + | |
| − | The pre-built chemistry mechanisms (Standard, Tropchem, SOA, SOA-SVPOA, and UCX) were built with the default prod/loss families listed in the example above. For the Tropchem, SOA, and SOA-SVPOA mechanisms several species (ClO + HOCl + ClNO2 + 2ClNO3 + 2Cl2O2 + 2OClO + O + O1D) were removed from the Ox family because those species are not defined in those mechanisms. The Ox and CO rates are used in GEOS-Chem for computing budgets in the [http://acmg.seas.harvard.edu/geos/geos_benchmark.html 1-month benchmark simulations] and PSO4 is required for simulations using [[TOMAS_aerosol_microphysics|TOMAS aerosol microphysics]].
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 17:13, 9 November 2016 (UTC) | + | |
| − | | + | |
| − | === Tagging reactions ===
| + | |
| − | | + | |
| − | Reactions may be manually tagged so that reaction rates can be saved out to the prod/loss diagnostic. To do this, follow these steps:
| + | |
| − | | + | |
| − | 1. Create dummy species in <tt>#DEFVAR</tt> section in the <tt>.eqn</tt> file
| + | |
| − | | + | |
| − | #DEFVAR
| + | |
| − |
| + | |
| − | A3O2 = IGNORE; {CH3CH2CH2OO; Primary RO2 from C3H8}
| + | |
| − | ACET = IGNORE; {CH3C(O)CH3; Acetone}
| + | |
| − | ACTA = IGNORE; {CH3C(O)OH; Acetic acid}
| + | |
| − | ...
| + | |
| − | <span style="color:green">RXN1 = IGNORE; {Dummy species to tag reaction}</span>
| + | |
| − | | + | |
| − | 2. Add the dummy species as a product in desired reaction
| + | |
| − | | + | |
| − | #EQUATIONS
| + | |
| − | //
| + | |
| − | // Gas-phase reactions
| + | |
| − | //
| + | |
| − | O3 + NO = NO2 + O2 <span style="color:green">+ RXN1</span>: GCARR(3.00E-12, 0.0E+00, -1500.0);
| + | |
| − | | + | |
| − | 3. Add the dummy species to the <tt>#FAMILIES</tt> section in <tt>gckpp.kpp</tt>
| + | |
| − | | + | |
| − | #FAMILIES
| + | |
| − | POx : O3 + NO2 + 2NO3 + PAN + NPMN + PPN + HNO4 + 3N2O5 + ...;
| + | |
| − | LOx : O3 + NO2 + 2NO3 + PAN + NPMN + PPN + HNO4 + 3N2O5 + ...;
| + | |
| − | PCO : CO;
| + | |
| − | LCO : CO;
| + | |
| − | PSO4 : SO4
| + | |
| − | <span style="color:green">PRXN1 : RXN1;</span>
| + | |
| − | | + | |
| − | 4. Rebuild the mechanism with KPP. Each mechanism subdirectory (e.g. <tt>Code.v11-02/KPP/Standard/</tt>) in [[GEOS-Chem v11-02]] includes a <tt>build_mechanism.sh</tt> script that will call KPP and create the <tt>gckpp*.F90</tt> files. To build the mechanism, type <tt>./build_mechanism.sh</tt>.
| + | |
| − | | + | |
| − | 5. Recompile and run GEOS-Chem, making sure you [[FlexChem#Saving_out_production_.26_loss_rates|turn on the prod/loss diagnostics]].
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 17:31, 6 February 2018 (UTC)
| + | |
| − | | + | |
| − | === How it works ===
| + | |
| − | | + | |
| − | ==== In GEOS-Chem v11-02 and later versions ====
| + | |
| − | | + | |
| − | <span style="color:green">'''''This update was included in [[GEOS-Chem v11-02#v11-02a|v11-02a]] and approved on 12 May 2017.'''''</span>
| + | |
| − | | + | |
| − | In [[GEOS-Chem v11-02]], KPP has been updated to greatly simplify how the prod/loss rates are computed. In v11-02a, the chemical mechanisms were rebuilt with KPP at commit <tt>Fix to add coefficients to *_Monitor.F90 - MSL.</tt>. In the updated KPP, prod/loss families now produce one dummy species that is now named with the family name in the <tt>SPC_NAMES</tt> array. For example, POx is now computed using KPP species <tt>POx</tt> in the variable species array <tt>VAR</tt> instead of using several <tt>RR*</tt> species. This greatly reduces the number of dummy species down to the number of prod/loss families that are defined in the input file <tt>gckpp.kpp</tt>. KPP will tag a reaction with the prod/loss family name by processing all reactions to determine if they are net production or net loss for that family.
| + | |
| − |
| + | |
| − | GEOS-Chem can now obtain the prod/loss rates directly from the <tt>VAR</tt> array in KPP. The following updates were made to routine <tt>Do_FlexChem</tt> in <tt>GeosCore/flexchem_mod.F90</tt> in v11-02a to properly use the updated KPP prod/loss rates. Text <span style="color:green">green</span> (<span style="color:red">red</span>) indicates code that was added (removed).
| + | |
| − | | + | |
| − | :1. Declare new variable <tt>KppID</tt> and remove obsolete variables for the prod/loss diagnostic
| + | |
| − | | + | |
| − | !
| + | |
| − | ! !LOCAL VARIABLES:
| + | |
| − | !
| + | |
| − | INTEGER :: I, J, L, N, F, SpcID, <span style="color:green">KppID</span>
| + | |
| − |
| + | |
| − | ...
| + | |
| − |
| + | |
| − | <span style="color:red">! For prod/loss diagnostic
| + | |
| − | REAL(fp) :: FAM(NFAM)
| + | |
| − | INTEGER :: IND
| + | |
| − | INTEGER :: COEF
| + | |
| − | CHARACTER(LEN=14) :: NAME</span>
| + | |
| − | | + | |
| − | :2. Declare <tt>KppID</tt> as <tt>!OMP PRIVATE</tt>
| + | |
| − | | + | |
| − | !$OMP PRIVATE ( SpcID, <span style="color:green">KppID</span>, F ) &
| + | |
| − | | + | |
| − | :3. Initialize the prod/loss rates to zero in KPP each time <tt>Do_FlexChem</tt> is called
| + | |
| − | | + | |
| − | !===========================================================
| + | |
| − | ! Initialize species concentrations
| + | |
| − | !===========================================================
| + | |
| − | ! Loop over KPP Species
| + | |
| − | DO N=1,NSPEC
| + | |
| − |
| + | |
| − | ! GEOS-Chem species ID
| + | |
| − | SpcID = State_Chm%Map_KppSpc(N)
| + | |
| − |
| + | |
| − | ! Initialize KPP species concentration array
| + | |
| − | IF ( SpcID .eq. 0) THEN
| + | |
| − | C(N) = 0.0_dp
| + | |
| − | ELSE
| + | |
| − | C(N) = State_Chm%Species(I,J,L,SpcID)
| + | |
| − | ENDIF
| + | |
| − |
| + | |
| − | ENDDO
| + | |
| − |
| + | |
| − | <span style="color:green">IF ( Input_Opt%DO_SAVE_PL ) THEN
| + | |
| − |
| + | |
| − | ! Loop over # prod/loss families
| + | |
| − | DO F = 1, NFAM
| + | |
| − |
| + | |
| − | ! Determine dummy species index in KPP
| + | |
| − | KppID = Ind_(TRIM(FAM_NAMES(F)),'K')
| + | |
| − |
| + | |
| − | ! Initialize prod/loss rates
| + | |
| − | IF ( KppID > 0 ) C(KppID) = 0.0_dp
| + | |
| − |
| + | |
| − | ENDDO
| + | |
| − |
| + | |
| − | ENDIF</span>
| + | |
| − | | + | |
| − | :4. Update the prod/loss rate diagnostic code
| + | |
| − | | + | |
| − | !==============================================================
| + | |
| − | ! Obtain prod/loss rates from KPP [molec/cm3]
| + | |
| − | !==============================================================
| + | |
| − | IF ( Input_Opt%DO_SAVE_PL ) THEN
| + | |
| − |
| + | |
| − | <span style="color:red">! Obtain prod/loss rates from KPP [molec/cm3]
| + | |
| − | CALL ComputeFamilies( VAR, FAM )</span>
| + | |
| − |
| + | |
| − | ! Loop over # prod/loss families
| + | |
| − | DO F = 1, NFAM
| + | |
| − |
| + | |
| − | <span style="color:green">! Determine dummy species index in KPP
| + | |
| − | KppID = Ind_(TRIM(FAM_NAMES(F)),'K')</span>
| + | |
| − |
| + | |
| − | !--------------------------------------------------------
| + | |
| − | ! Add to AD65 array [molec/cm3/s]
| + | |
| − | !--------------------------------------------------------
| + | |
| − | <span style="color:red">AD65(I,J,L,F) = AD65(I,J,L,F) + FAM(F) / DT</span>
| + | |
| − | <span style="color:green">IF ( KppID > 0 ) THEN
| + | |
| − | AD65(I,J,L,F) = AD65(I,J,L,F) + VAR(KppID) / DT
| + | |
| − | ENDIF</span>
| + | |
| − |
| + | |
| − | !--------------------------------------------------------
| + | |
| − | ! Save out P(Ox) and L(Ox) from the fullchem simulation
| + | |
| − | ! for a future tagged O3 run
| + | |
| − | !--------------------------------------------------------
| + | |
| − | IF ( Input_Opt%DO_SAVE_O3 ) THEN
| + | |
| − | IF ( TRIM(FAM_NAMES(F)) == 'POx' ) THEN
| + | |
| − | <span style="color:red">POx(I,J,L) = FAM(F) / DT</span>
| + | |
| − | <span style="color:green">POx(I,J,L) = VAR(KppID) / DT</span>
| + | |
| − | ENDIF
| + | |
| − | IF ( TRIM(FAM_NAMES(F)) == 'LOx' ) THEN
| + | |
| − | <span style="color:red">LOx(I,J,L) = FAM(F) / DT</span>
| + | |
| − | <span style="color:green">LOx(I,J,L) = VAR(KppID) / DT</span>
| + | |
| − | ENDIF
| + | |
| − | ENDIF
| + | |
| − |
| + | |
| − | #if defined( TOMAS )
| + | |
| − | !-------------------------------------------------------
| + | |
| − | ! FOR TOMAS MICROPHYSICS:
| + | |
| − | !
| + | |
| − | ! Obtain P/L with a unit [kg S] for tracing
| + | |
| − | ! gas-phase sulfur species production (SO2, SO4, MSA)
| + | |
| − | ! (win, 8/4/09)
| + | |
| − | !-------------------------------------------------------
| + | |
| − |
| + | |
| − | ! Calculate H2SO4 production rate [kg s-1] in each
| + | |
| − | ! time step (win, 8/4/09)
| + | |
| − | IF ( TRIM(FAM_NAMES(F)) == 'PSO4' ) THEN
| + | |
| − | ! Hard-coded MW
| + | |
| − | <span style="color:red">H2SO4_RATE(I,J,L) = FAM(F) / AVO * 98.e-3_fp * &</span>
| + | |
| − | <span style="color:green">H2SO4_RATE(I,J,L) = VAR(KppID) / AVO * 98.e-3_fp * &</span>
| + | |
| − | State_Met%AIRVOL(I,J,L) * &
| + | |
| − | 1e+6_fp / DT
| + | |
| − | ENDIF
| + | |
| − | #endif
| + | |
| − | ENDDO
| + | |
| − |
| + | |
| − | ENDIF
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 20:12, 23 March 2017 (UTC)
| + | |
| − | | + | |
| − | | + | |
| − | The table below shows the speedup that is obtained with the improved prod/loss rate diagnostics.
| + | |
| − | | + | |
| − | {| border=1 cellspacing=0 cellpadding=5
| + | |
| − | |-valign="top" bgcolor="#CCCCCC"
| + | |
| − | !width="125px"|Run name, <br>timesteps,<br>and submitter
| + | |
| − | !width="175px"|Machine or Node<br>and Compiler
| + | |
| − | !width="100px"|CPU vendor
| + | |
| − | !width="150px"|CPU model
| + | |
| − | !width="75px"|Speed [MHz]
| + | |
| − | !width="50px"|# of<br>CPUs
| + | |
| − | !width="85px"|CPU time
| + | |
| − | !width="120px"|Wall time
| + | |
| − | !width="75px|CPU / Wall<br>ratio
| + | |
| − | !width="75px"|% of ideal
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |v11-01-public<br>(C20T10)<br>Bob Yantosca
| + | |
| − | |regal16.rc.fas.harvard.edu<br>ifort 11.1
| + | |
| − | |GenuineIntel
| + | |
| − | |Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz
| + | |
| − | |2199.915
| + | |
| − | |8
| + | |
| − | |62554.07 s<br>'''17:22:34'''
| + | |
| − | |9355.80 s<br>'''02:35:59'''
| + | |
| − | |6.6861
| + | |
| − | |83.58
| + | |
| − | | + | |
| − | |-valign="top"
| + | |
| − | |v11-02a-P/L<br>(C20T10)<br>Melissa Sulprizio
| + | |
| − | |regal17.rc.fas.harvard.edu<br>ifort 11.1
| + | |
| − | |GenuineIntel
| + | |
| − | |Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz
| + | |
| − | |2199.993
| + | |
| − | |8
| + | |
| − | |55853.62 s<br>'''15:30:54'''
| + | |
| − | |8373.14 s<br>'''02:19:44'''<br><span style="color:red">1.12X faster than v11-01-public</span>
| + | |
| − | |6.6706
| + | |
| − | |83.38
| + | |
| − | | + | |
| − | |}
| + | |
| − | | + | |
| − | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:58, 9 February 2017 (UTC)
| + | |
| − | | + | |
| − | ==== In GEOS-Chem v11-01 ====
| + | |
| − | | + | |
| − | <span style="color:darkorange">'''''NOTE: The way that KPP computes production and loss families was greatly simplified in [[GEOS-Chem v11-02#v11-02a|GEOS-Chem v11-02a]]. See the [[#In GEOS-Chem v11-02 and later versions|post above]] for more information.'''''</span>
| + | |
| − | | + | |
| − | The number of prod/loss families is defined by <tt>NFAM</tt> in <tt>gckpp_Parameters.F90</tt>. KPP automatically sets this number according to the number of families listed in the <tt>gckpp.kpp</tt> file used to build the mechanism. The prod/loss family names are defined in array <tt>FAM_NAMES</tt> in <tt>gckpp_Monitor.F90</tt>. For example, for the default prod/loss families listed above we have:
| + | |
| − | | + | |
| − | CHARACTER(LEN=15), PARAMETER, DIMENSION(5) :: FAM_NAMES = (/ &
| + | |
| − | 'POx ','LOx ','PCO ', & ! index 1 - 3
| + | |
| − | 'LCO ','PSO4 ' /)
| + | |
| − | | + | |
| − | KPP computes the prod/loss families in routine <tt>ComputeFamilies</tt> (found in <tt>gckpp_Util.F90</tt>). The <tt>FAM</tt> array in that routine contains the accumulated prod/loss rates for that family. For example, the POx family (family 1) is computed as:
| + | |
| − | | + | |
| − | FAM(1) = V(13)+V(14)+V(15)+V(16)+V(17)+V(18)+V(19)+V(20)+V(21)+2*V(22)+...
| + | |
| − | | + | |
| − | The <tt>V</tt> array here corresponds to KPP's <tt>VAR</tt> array containing species concentrations in molec/cm3. The indices passed to <tt>V</tt> indicate which reaction rates are used to compute the prod/loss rate for that family. Here are the steps you can take to validate the reactions used for a given family:
| + | |
| − | | + | |
| − | #Select any index number for array V used in the computation
| + | |
| − | #Find the index number in SPC_NAMES (defined in <tt>gckpp_Monitor.F90</tt>)
| + | |
| − | #Find the dummy RR species in <tt>EQN_NAMES</tt> (defined in <tt>gckpp_Monitor.F90</tt>)
| + | |
| − | #Make sure the reaction identified in the previous step includes a family member as a product (for prod families) or a reactant (for loss families)
| + | |
| − | | + | |
| − | Following these steps for the POx family example, we have:
| + | |
| − | | + | |
| − | #Select <tt>V(13)</tt>
| + | |
| − | #Index 13 corresponds to <tt>RR10</tt> in <tt>SPC_NAMES</tt>
| + | |
| − | #<tt>RR10</tt> is found in <tt>HO2 + NO --> RR10 + NO2 + OH</tt> in <tt>EQN_NAMES</tt>
| + | |
| − | #NO2 is a member of the POx family and is a product in the above reaction ✔
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 17:13, 9 November 2016 (UTC)
| + | |
| − | | + | |
| − | === Saving out production & loss rates ===
| + | |
| − | | + | |
| − | ==== Binary punch format ====
| + | |
| − | | + | |
| − | The prod/loss rates from KPP are saved out in GEOS-Chem via the [http://acmg.seas.harvard.edu/geos/doc/man/chapter_5.html#PLMenu ND65 diagnostic]. To activate this diagnostic, set the option for ND65 (stored in <tt>Input_Opt%DO_SAVE_PL</tt>) to <tt>T</tt> in the input.geos file:
| + | |
| − | | + | |
| − | -------------------------------------------------------------------------------
| + | |
| − | %%% PROD & LOSS MENU %%%:
| + | |
| − | Turn on P/L (ND65) diag?: '''T'''
| + | |
| − | # of levels for ND65 : 72
| + | |
| − | Save O3 P/L (ND20)? : F
| + | |
| − | ------------------------+------------------------------------------------------
| + | |
| − | | + | |
| − | When <tt>Input_Opt%DO_SAVE_PL</tt> is true, FlexChem will call KPP routine <tt>ComputeFamilies</tt> (found in <tt>gckpp_Util.F90</tt>) to obtain the prod/loss rates stored in array <tt>FAM</tt>. The ND65 diagnostic is set up to automatically save out <tt>NFAM</tt> families to the output file and obtain the family names from <tt>FAM_NAMES</tt>, so no code modifications are required when adding prod/loss families to the chemical mechanism.
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 17:13, 9 November 2016 (UTC)
| + | |
| − | | + | |
| − | ==== NetCDF format ====
| + | |
| − | | + | |
| − | [[GEOS-Chem v11-02]] introduces the option to save GEOS-Chem diagnostics to netCDF format by compiling with <tt>NC_DIAG=y</tt>. To save out the prod/loss diagnostics to netCDF format, you can add the following field names to your defined collection(s) in <tt>HISTORY.rc</tt>:
| + | |
| − | | + | |
| − | 'Prod_?PRD?', 'GIGCchem',
| + | |
| − | 'Loss_?LOS?', 'GIGCchem',
| + | |
| − | | + | |
| − | where <tt>?PRD?</tt> and <tt>?LOS?</tt> are wildcards that will be placed with all production and loss species as defined in GEOS-Chem. '''''NOTE: GCHP doesn't accept wildcards at this time, so each prod/loss species will need to be listed separately.'''''
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 17:21, 6 February 2018 (UTC)
| + | |
| − | | + | |
| − | == Validation ==
| + | |
| − | | + | |
| − | === Benchmark simulations ===
| + | |
| − | | + | |
| − | FlexChem was implemented in [[GEOS-Chem v11-01#v11-01g|v11-01g]] and validated with a 1-month benchmark and a 1-year benchmark. Please see the following links for more information:
| + | |
| − | | + | |
| − | #[[GEOS-Chem_v11-01_benchmark_history#v11-01g|''Approval form for 1-month benchmark simulation v11-01g'']]
| + | |
| − | #[[GEOS-Chem_v11-01_benchmark_history#v11-01g-Run0|''Results for 1-year benchmark simulation v11-01g-Run0'']]
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 18:38, 9 November 2016 (UTC)
| + | |
| − | | + | |
| − | === Preliminary timing tests ===
| + | |
| − | | + | |
| − | [[GEOS-Chem_performance#7-day_time_tests|Seven-day time tests]] were performed with the FlexChem code in order to evaluate model performance. The time tests all used 4° x 5° GEOS-FP met fields and were assigned 8 CPUs. Two model version were evaluated: [[GEOS-Chem v11-01#v11-01f|v11-01f]] and [[GEOS-Chem v11-01#v11-01g|v11-01g]] (which includes FlexChem). 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
| + | |
| − | |-
| + | |
| − | |v11-01g
| + | |
| − | |2:10:37
| + | |
| − | |14:19:33
| + | |
| − | |6.5807 (82.26% ideal)
| + | |
| − | |5.00 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
| + | |
| − | |-
| + | |
| − | |v11-01g
| + | |
| − | |0:50:24
| + | |
| − | |5:37:04
| + | |
| − | |6.6878 (83.60% ideal)
| + | |
| − | |2.70 GB
| + | |
| − | |}
| + | |
| − | | + | |
| − | The GEOS-Chem Support Team will continue to evaluate and improve the performance of the FlexChem code for the [[GEOS-Chem v11-01]] release.
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:26, 7 September 2016 (UTC)
| + | |
| − | | + | |
| − | == Previous issues that are now resolved ==
| + | |
| − | | + | |
| − | === FlexChem bug fix: do not zero ACTA, EOH, HCOOH ===
| + | |
| − | | + | |
| − | <span style="color:darkorange">'''''This fix will be included in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]].'''''</span>
| + | |
| − | | + | |
| − | '''''[[User:Katherine Travis|Katie Travis]] wrote:'''''
| + | |
| − | | + | |
| − | <blockquote>I am working on a VOC simulation, and noticed that in my copy of v11-02f, the following species are set to zero in two places:</blockquote>
| + | |
| − | | + | |
| − | ! Zero certain species
| + | |
| − | C(ind_ACTA) = 0.e0_dp
| + | |
| − | C(ind_EOH) = 0.e0_dp
| + | |
| − | C(ind_HCOOH) = 0.e0_dp
| + | |
| − | | + | |
| − | <blockquote>And</blockquote>
| + | |
| − | | + | |
| − | C(ind_ACTA) = 0.0_dp
| + | |
| − | C(ind_HCOOH) = 0.0_dp
| + | |
| − | | + | |
| − | <blockquote>Since none of these species are fixed in Tropchem.eqn, shouldn’t they NOT be set to zero?</blockquote>
| + | |
| − | | + | |
| − | '''''Mike Long wrote:'''''
| + | |
| − | | + | |
| − | <blockquote>I think the code should be removed. This must have been a patch added to maintain parity with SMVGEAR w/o anticipating that the species would become active.</blockquote>
| + | |
| − | | + | |
| − | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:19, 17 May 2018 (UTC)
| + | |
| − | | + | |
| − | === Fix for compiling with CHEM=Custom ===
| + | |
| − | | + | |
| − | <span style="color:green">'''''This fix was included in [[GEOS-Chem v11-01#v11-01 public release|GEOS-Chem v11-01 public release]]'''''</span>
| + | |
| − | | + | |
| − | '''''Prasad Kasibhatla wrote:'''''
| + | |
| − | | + | |
| − | :I am trying to create a custom simulation with some chemistry added to the SOA_SVPOA simulation. I followed all the steps in the wiki to create the <tt>gckpp*F90</tt> files and copy them to the <tt>Code.v11-01/KPP/Custom</tt> directory. I then compile from <tt>Code.v11-01</tt> using the command
| + | |
| − | | + | |
| − | make -j4 MET=geosfp GRID=4x5 CHEM=Custom
| + | |
| − | | + | |
| − | :I noticed that during the compile, the KPP files being compiled are in the <tt>Standard</tt> KPP directory. So it looks like the <tt>CHEM=Custom</tt> option is not directing the compiler to the right place.
| + | |
| − | | + | |
| − | :I solved the problem by adding the following to <tt>Makefile_header.mk</tt> in the Code directory:
| + | |
| − |
| + | |
| − | # %%%%% Test if Custom %%%%%
| + | |
| − | REGEXP :=(^[Cc][Uu][Ss][Tt][Oo][Mm])
| + | |
| − | ifeq ($(shell <nowiki>[[ "$(CHEM)" =~ $(REGEXP) ]]</nowiki> && echo true),true)
| + | |
| − | KPP_CHEM :=Custom
| + | |
| − | IS_CHEM_SET :=1
| + | |
| − | endif
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 22:43, 17 January 2017 (UTC)
| + | |
| − | | + | |
| − | === Remove calls to UPDATE_SUN, UPDATE_RCONST from gckpp_Integrator.F90 ===
| + | |
| − | | + | |
| − | <span style="color:green">'''''This update was included in [[GEOS-Chem v11-01 benchmark history#v11-01 provisional release|GEOS-Chem v11-01 provisional release]]'''''</span>
| + | |
| − | | + | |
| − | A slow down in GEOS-Chem run time was observed following the implementation of FlexChem in [[GEOS-Chem v11-01|v11-01]]. To resolve this, a temporary workaround was implemented. This fix may be replaced with a more permanent solution in [[GEOS-Chem v11-01#v11-01 public release|GEOS-Chem v11-01 public release]].
| + | |
| − | | + | |
| − | '''''[[User:Bmy|Bob Yantosca]] wrote:'''''
| + | |
| − | | + | |
| − | <blockquote>KPP automatically places calls to <tt>UPDATE_SUN</tt> and <tt>UPDATE_RCONST</tt> in the routines <tt>FunTemplate</tt> and <tt>JacTemplate</tt> (both in the <tt>gckpp_Integrator.F90</tt> module). This assumes that you are not interfacing KPP into any other model, and that you will use KPP to compute the sun angles at each timestep.
| + | |
| − |
| + | |
| − | We now call <tt>UPDATE_RCONST</tt> once per grid box before calling the KPP integrator. Also, because we use FAST-JX to get the photo rates, we no longer need to call <tt>UPDATE_SUN</tt>. These duplicate calls were causing a performance bottleneck, as <tt>UPDATE_RCONST</tt> was being called more than 7 million times per day.
| + | |
| − |
| + | |
| − | We have removed the duplicate calls from the <tt>gckpp_Integrator.F90</tt> modules in each of the chemistry mechanisms. But we will also need to make sure that when building KPP fresh from an equation file, that this step gets automatically added to the build sequence.</blockquote>
| + | |
| − | | + | |
| − | --[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 19:53, 9 January 2017 (UTC)
| + | |
| − | | + | |
| − | === Incorrect species units used in routines UCX_NOX and UCX_H2SO4PHOT ===
| + | |
| − | | + | |
| − | <span style="color:green">'''''This update was validated with the 1-month benchmark simulation [[GEOS-Chem v11-01 benchmark history#v11-01j|v11-01j]] and approved on 03 Dec 2016'''''</span>
| + | |
| − | | + | |
| − | [[User:Sebastian_D._Eastham|Seb Eastham]] reported an error in <tt>FlexChem_mod.F90</tt> routine <tt>DO_FLEXCHEM</tt>, where UCX routines <tt>UCX_NOX</tt> and <tt>UCX_H2SO4PHOT</tt> are called when species concentrations are in the wrong units. Both routines expect species concentrations in units of kg but species are not converted from molec/cm3 to kg until after the calls.
| + | |
| − | | + | |
| − | '''''Seb Eastham wrote:'''''
| + | |
| − | | + | |
| − | <blockquote>
| + | |
| − | The consequences of this error can actually be seen in the v11-01g benchmark zonal mean concentrations. N2O should be uniform in the trop and then lost in the strat, but if you check out the color bar you’ll see that there is a very difficult-to-see (but huge!) maximum in the mesosphere. This is why the concentration in the trop, which should be the maximum, is so low on the color scale.
| + | |
| − | </blockquote>
| + | |
| − | | + | |
| − | To correct this issue, the UCX routines are now called after the species unit conversion to kg.
| + | |
| − | | + | |
| − | --[[User:Lizzie Lundgren|Lizzie Lundgren]] ([[User talk:Lizzie Lundgren|talk]]) 22:01, 14 November 2016 (UTC)
| + | |
| − | | + | |
| − | == Known issues ==
| + | |
| − | | + | |
| − | TBD
| + | |
