Documentation improvements for 3.0.0: Auto-reduction solver and State_Het

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

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:
 
 ============================

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