diff --git a/docs/source/citations/kpp.bib b/docs/source/citations/kpp.bib index aef4b39..463b930 100644 --- a/docs/source/citations/kpp.bib +++ b/docs/source/citations/kpp.bib @@ -397,9 +397,35 @@ @article{1999:Verwer year = {1999} } +@article{2010:Santillana_et_al, + title = {An adaptive reduction algorithm for efficient chemical calculations in global atmospheric chemistry models}, + journal = {Atmospheric Environment}, + volume = {44}, + number = {35}, + pages = {4426-4431}, + year = {2010}, + issn = {1352-2310}, + doi = {https://doi.org/10.1016/j.atmosenv.2010.07.044}, + url = {https://www.sciencedirect.com/science/article/pii/S1352231010006242}, + author = {Mauricio Santillana and Philippe {Le Sager} and Daniel J. Jacob and Michael P. Brenner} +} + +@Article{2020:Shen_et_al, + AUTHOR = {Shen, L. and Jacob, D. J. and Santillana, M. and Wang, X. and Chen, W.}, + TITLE = {An adaptive method for speeding up the numerical integration of chemical + mechanisms in atmospheric chemistry models: application to GEOS-Chem version + 12.0.0}, + JOURNAL = {Geoscientific Model Development}, + VOLUME = {13}, + YEAR = {2020}, + NUMBER = {5}, + PAGES = {2475--2486}, + URL = {https://gmd.copernicus.org/articles/13/2475/2020/}, + DOI = {10.5194/gmd-13-2475-2020} +} + @article{2022:Lin_et_al, - author = {H.P.~ Lin and M.S.~ Long and R.~ Sander and A.~ Sandu - and D.J.~ Jacob and R.M.~ Yantosca}, + author = {H. Lin and M.S. Long and R. Sander and A. Sandu and R.M. Yantosca and L.A. Estrada and L. Shen and D.J. Jacob}, title = {An adaptive auto-reduction solver for speeding up integration of chemical kinetics in atmospheric chemistry models: implementation and evaluation within the Kinetic diff --git a/docs/source/tech_info/07_numerical_methods.rst b/docs/source/tech_info/07_numerical_methods.rst index 42ff69d..15509d0 100644 --- a/docs/source/tech_info/07_numerical_methods.rst +++ b/docs/source/tech_info/07_numerical_methods.rst @@ -336,6 +336,25 @@ for each of the Rosenbrock methods (:ref:`rosenbrock-ros-2`, :ref:`rosenbrock-ros-3`, :ref:`rosenbrock-ros-4`, :ref:`rosenbrock-rodas-3`, :ref:`rosenbrock-rodas-4`). +.. _rosenbrock-autoreduce: + +Rosenbrock with mechanism auto-reduction +----------------------------------------- + +**Integrator file:** :file:`int/rosenbrock_autoreduce.f90` + +Mechanism auto-reduction (described in :cite:`2022:Lin_et_al`) expands previous work by :cite:`2020_Shen_et_al`, :cite:`2010:Santillana_et_al` to a computationally efficient implementation in KPP, avoiding memory re-allocation, re-compile of the code, and on-the-fly mechanism reduction based on dynamically determined production and loss rate thresholds. + +We define a threshold :math:`\delta` which can be fixed (as in :cite:`2010:Santillana_et_al`) or determined by the production and loss rates of a "target species" scaled by a factor :math:`\delta = max(P_{target}, L_{target}) * \alpha_{target}`. + +For each species :math:`i`, the species is partitioned as "slow" iff. + +.. math:: + + max(P_i, L_i) < \delta + +if the species is partitioned as "slow", it is solved explicitly (decoupled from the rest of the mechanism) using a first-order approximation. Otherwise, "fast" species are retained in the implicit Rosenbrock solver. + .. _rk-methods: ============================ diff --git a/docs/source/using_kpp/04_input_for_kpp.rst b/docs/source/using_kpp/04_input_for_kpp.rst index 8402b3a..3bf04a0 100644 --- a/docs/source/using_kpp/04_input_for_kpp.rst +++ b/docs/source/using_kpp/04_input_for_kpp.rst @@ -853,6 +853,55 @@ special rate coefficient: REAL(dp) :: k_DMS_OH #ENDINLINE +Inlining code can be useful to introduce additional state variables +(such as temperature, humidity, etc.) for use by KPP routines, such as +for calculating rate coefficients. + +If a large number of state variables need to be held in inline code, or +require intermediate computation that may be repeated for many rate +coefficients, a derived type object should be used for efficiency. + +The GEOS-Chem model introduces a derived type object, :code:`State_Het`, which holds quantities +used for heterogeneous chemistry calculation, such as cloud liquid water content, +aerosol size distribution, pH and/or alkalinity, and the intermediate quantities +necessary for computation. This avoids recomputing intermediate quantities +(especially numerically expensive operations such as exponentials) repeatedly, +and also avoids excessive variables cluttering the inlined code in :command:`F90_GLOBAL`, +as well as unnecessary memory use. + +An example of a derived-type object being included: + +.. code-block:: F90 + + #INLINE F90_GLOBAL + TYPE, PUBLIC :: HetState + LOGICAL :: debugBox ! Are we in a debugging box? + REAL(dp) :: AVO ! Avogadro's constant [molec/mol] + LOGICAL :: natSurface ! Is there NAT in this box? + LOGICAL :: pscBox ! Are there polar strat clouds? + LOGICAL :: stratBox ! Are we in the stratosphere + ! ... more variables below ... + END TYPE HetState + TYPE(HetState), TARGET, PUBLIC :: State_Het + !$OMP THREADPRIVATE( State_Het ) + +This global variable :code:`State_Het` can then be used globally in KPP. + +To avoid cluttering up the KPP input file, an additional input file can be introduced: + +.. code-block:: F90 + + #INLINE F90_GLOBAL + ! Inline common variables into KPP_ROOT_Global.F90 + #include "commonIncludeVars.H" + #ENDINLINE + +where extra code is included in a separate file, :code:`commonIncludeVars.H`. + +In future versions of KPP, the global state will be reorganized into derived type +objects as well. + + .. _inline-type-f90-init: F90_INIT