Merge pull request #277 from NCAR/271-add-tutorial-on-configuring-the…

…-solver-for-with-different-parameters

271 add tutorial on configuring the solver for with different parameters

docs/requirements.txt

@@ -3,4 +3,5 @@ sphinx
 sphinx-book-theme
 sphinx-copybutton
 sphinx-design
-sphinx-tabs
+sphinx-tabs
+sphinxcontrib-bibtex

docs/source/citing_and_bibliography/bibliography.rst

@@ -0,0 +1,7 @@
+
+############
+Bibliography
+############
+
+.. bibliography::
+   :all:

docs/source/citing_and_bibliography/citation.rst

@@ -0,0 +1,36 @@
+
+Citing MICM
+===========
+
+MICM is a group scientific and software effort. 
+
+Cite the science
+-----------------
+
+Cite the software
+-----------------
+
+The software can be cited like this
+
+.. code-block:: console
+
+  @software{ncar.acom.micm,
+    author       = {Kyle Shores and
+                    Qina Tan and
+                    Matt Dawson and
+                    cacraigucar and
+                    Jiwon Gim and
+                    David Fillmore and
+                    Francis Vitt and
+                    Andrew Conley and
+                    actions-user and
+                    davidfillmore and
+                    Aharon Karsenti},
+    title        = {NCAR/micm: v3.2.0},
+    month        = sep,
+    year         = 2023,
+    publisher    = {Zenodo},
+    version      = {v3.2.0},
+    doi          = {10.5281/zenodo.8377912},
+    url          = {https://doi.org/10.5281/zenodo.8377912}
+  }

docs/source/citing_and_bibliography/index.rst

@@ -0,0 +1,11 @@
+
+##########################
+Citations and Bibliography
+##########################
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   citation
+   bibliography

docs/source/conf.py

@@ -35,8 +35,12 @@
   'sphinx_copybutton',
   'sphinx_design',
   'sphinx_tabs.tabs',
+  'sphinxcontrib.bibtex',
 ]
 
+bibtex_bibfiles = ['references.bib']
+suppress_warnings = ["bibtex.missing_field"]
+
 breathe_default_project = "micm"
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/getting_started.rst

@@ -1,12 +1,12 @@
-
+###############
 Getting Started
-===============
+###############
 
 Build and Test
---------------
+==============
 
 CPU
-~~~
+---
 To build and install MICM locally, you must have the following libraries installed:
 
 - `CMake <https://cmake.org/>`_
@@ -43,7 +43,7 @@ others require that you have libraries installed on your system.
   - On macOS, you either need to configure cmake to use gcc which ships with OpenMP (either ``CXX=g++ cmake -DENABLE_OPENMP=ON ..`` or ``cmake -DCMAKE_CXX_COMPILER=g++ -DENABLE_OPENMP=ON ..``)
 
 Docker Container
-~~~~~~~~~~~~~~~~
+----------------
 
 Build and run the image::
 
@@ -53,19 +53,20 @@ Build and run the image::
 If you would like, you can ssh into a running docker container and edit the files there.
 
 GPU
-~~~
+---
 
 NCAR Hardware
--------------
+^^^^^^^^^^^^^
 
 On Cheyenne
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 On Casper
-~~~~~~~~~
+^^^^^^^^^
 
 On Gust and Derecho
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
+
 To compile and test on gust::
 
     $ qinteractive -A NTDD0005 --ngpus=1
@@ -76,7 +77,7 @@ To compile and test on gust::
     $ make test
 
 NOAA Hardware
--------------
+^^^^^^^^^^^^^
 
 Run an Example
 --------------

docs/source/index.rst

@@ -52,7 +52,7 @@ Welcome to MICM's documentation!
    user_guide/index
    api/index
    contributing/index
-   citation
+   citing_and_bibliography/index
 
 Indices and tables
 ==================

docs/source/references.bib

@@ -0,0 +1,154 @@
+@article{Daescu2003,
+  title = {Direct and Adjoint Sensitivity Analysis of Chemical Kinetic Systems with {{KPP}}: {{II}}\textemdash Numerical Validation and Applications},
+  shorttitle = {Direct and Adjoint Sensitivity Analysis of Chemical Kinetic Systems with {{KPP}}},
+  author = {Daescu, Dacian N. and Sandu, Adrian and Carmichael, Gregory R.},
+  year = {2003},
+  month = nov,
+  journal = {Atmospheric Environment},
+  volume = {37},
+  number = {36},
+  pages = {5097--5114},
+  issn = {1352-2310},
+  doi = {10.1016/j.atmosenv.2003.08.020},
+  urldate = {2023-02-15},
+  abstract = {The Kinetic PreProcessor KPP was extended to generate the building blocks needed for the direct and adjoint sensitivity analysis of chemical kinetic systems. An overview of the theoretical aspects of sensitivity calculations and a discussion of the KPP software tools is presented in the companion paper. In this work the correctness and efficiency of the KPP generated code for direct and adjoint sensitivity studies are analyzed through an extensive set of numerical experiments. Direct-decoupled Rosenbrock methods are shown to be cost-effective for providing sensitivities at low and medium accuracies. A validation of the discrete\textendash adjoint evaluated gradients is performed against the finite difference estimates. The accuracy of the adjoint gradients is measured using a reference gradient value obtained with a standard direct-decoupled method. The accuracy is studied for both constant step size and variable step size integration of the forward/adjoint model and the consistency between the discrete and continuous adjoint models is analyzed. Applications of the KPP-1.2 software package to direct and adjoint sensitivity studies, variational data assimilation, and parameter identification are considered for the comprehensive chemical mechanism SAPRC-99.},
+  langid = {english},
+  keywords = {Data assimilation,Optimization,Parameter identification,Sensitivity analysis},
+  file = {/Users/kshores/Zotero/storage/UC6A2K82/S1352231003006733.html}
+}
+
+@article{Damian2002,
+  title = {The Kinetic Preprocessor {{KPP-a}} Software Environment for Solving Chemical Kinetics},
+  author = {Damian, Valeriu and Sandu, Adrian and Damian, Mirela and Potra, Florian and Carmichael, Gregory R.},
+  year = {2002},
+  month = nov,
+  journal = {Computers \& Chemical Engineering},
+  volume = {26},
+  number = {11},
+  pages = {1567--1579},
+  issn = {0098-1354},
+  doi = {10.1016/S0098-1354(02)00128-X},
+  urldate = {2023-02-15},
+  abstract = {The kinetic preprocessor (KPP) is a software tool that assists the computer simulation of chemical kinetic systems. The concentrations of a chemical system evolve in time according to the differential law of mass action kinetics. A computer simulation requires the implementation of the differential system and its numerical integration in time. KPP translates a specification of the chemical mechanism into fortran or c simulation code that implement the concentration time derivative function and its Jacobian, together with a suitable numerical integration scheme. Sparsity in Jacobian is carefully exploited in order to obtain computational efficiency. KPP incorporates a library with several widely used atmospheric chemistry mechanisms and users can add their own chemical mechanisms to the library. KPP also includes a comprehensive suite of stiff numerical integrators. The KPP development environment is designed in a modular fashion and allows for rapid prototyping of new chemical kinetic schemes as well as new numerical integration methods.},
+  langid = {english},
+  keywords = {Automatic code generation,Chemical kinetics,Numerical integration,Sparsity},
+  file = {/Users/kshores/Zotero/storage/2VJ5XQH2/Damian et al. - 2002 - The kinetic preprocessor KPP-a software environmen.pdf;/Users/kshores/Zotero/storage/YQSFJ5YJ/S009813540200128X.html}
+}
+
+@book{Hairer1996,
+  title = {Solving {{Ordinary Differential Equations II}}: {{Stiff}} and {{Differential-Algebraic Problems}}},
+  shorttitle = {Solving {{Ordinary Differential Equations II}}},
+  author = {Hairer, Ernst and Wanner, Gerhard},
+  year = {1996},
+  month = sep,
+  edition = {2nd edition},
+  publisher = {{Springer}},
+  address = {{Berlin ; New York}},
+  abstract = {The subject of this book is the solution of stiff differential equations and of differential-algebraic systems. This second edition contains new material including new numerical tests, recent progress in numerical differential-algebraic equations, and improved FORTRAN codes.From the reviews:"A superb book...Throughout, illuminating graphics, sketches and quotes from papers of researchers in the field add an element of easy informality and motivate the text." --MATHEMATICS TODAY},
+  isbn = {978-3-540-60452-5},
+  langid = {english},
+  file = {/Users/kshores/Zotero/storage/GC4V85EX/Solving Ordinary Differential Equations II.pdf}
+}
+
+@book{Hairer2009,
+  title = {Solving {{Ordinary Differential Equations I}}: {{Nonstiff Problems}}},
+  shorttitle = {Solving {{Ordinary Differential Equations I}}},
+  author = {Hairer, Ernst and N{\o}rsett, Syvert P. and Wanner, Gerhard},
+  year = {2009},
+  month = dec,
+  edition = {2nd ed. 1993. Corr. 3rd printing 2009 edition},
+  publisher = {{Springer}},
+  address = {{Heidelberg ; London}},
+  abstract = {This book deals with methods for solving nonstiff ordinary differential equations. The first chapter describes the historical development of the classical theory, and the second chapter includes a modern treatment of Runge-Kutta and extrapolation methods. Chapter three begins with the classical theory of multistep methods, and concludes with the theory of general linear methods. The reader will benefit from many illustrations, a historical and didactic approach, and computer programs which help him/her learn to solve all kinds of ordinary differential equations. This new edition has been rewritten and new material has been included.},
+  isbn = {978-3-642-05163-0},
+  langid = {english},
+  file = {/Users/kshores/Zotero/storage/2AJ3I6HJ/1993 - Solving Ordinary Differential Equations I.pdf}
+}
+
+@article{Rosenbrock1963,
+  title = {Some General Implicit Processes for the Numerical Solution of Differential Equations},
+  author = {Rosenbrock, H. H.},
+  year = {1963},
+  month = jan,
+  journal = {The Computer Journal},
+  volume = {5},
+  number = {4},
+  pages = {329--330},
+  issn = {0010-4620},
+  doi = {10.1093/comjnl/5.4.329},
+  urldate = {2023-02-15},
+  abstract = {Some general implicit processes are given for the solution of simultaneous first-order differential equations. These processes, which use successive substitution, are implicit analogues of the (explicit) Runge-Kutta processes. They require the solution in each time step of one or more set of simultaneous linear equations, usually of a special and simple form.Processes of any required order can be devised, and they can be made to have a wide margin of stability when applied to a linear problem.},
+  file = {/Users/kshores/Zotero/storage/4NW8TWI5/Rosenbrock - 1963 - Some general implicit processes for the numerical .pdf;/Users/kshores/Zotero/storage/865XYEWP/316388.html}
+}
+
+@article{SanduStiff2-1997,
+  title = {Benchmarking Stiff Ode Solvers for Atmospheric Chemistry Problems {{II}}: {{Rosenbrock}} Solvers},
+  shorttitle = {Benchmarking Stiff Ode Solvers for Atmospheric Chemistry Problems {{II}}},
+  author = {Sandu, A. and Verwer, J. G. and Blom, J. G. and Spee, E. J. and Carmichael, G. R. and Potra, F. A.},
+  year = {1997},
+  month = oct,
+  journal = {Atmospheric Environment},
+  volume = {31},
+  number = {20},
+  pages = {3459--3472},
+  issn = {1352-2310},
+  doi = {10.1016/S1352-2310(97)83212-8},
+  urldate = {2023-02-15},
+  abstract = {In the numerical simulation of atmospheric transport-chemistry processes, a major task is the integration of the stiff systems of ordinary differential equations describing the chemical transformations. It is therefore of interest to systematically search for stiff solvers which can be identified as close to optimal for atmospheric applications. In this paper we continue our investigation from Sandu et al. (1996, CWI Report NM-R9603 and Report in Comput. Math., No. 85) and compare eight solvers on a set of seven box-models used in present day models. The focus is on Rosenbrock solvers. These turn out to be very well suited for our application when they are provided with highly efficient sparse matrix techniques to economize on the linear algebra. Two of the Rosenbrock solvers tested are from the literature, viz. rodas and Ros4, and two are new and specially developed for air quality applications, viz. rodas3 and ros3.},
+  langid = {english},
+  file = {/Users/kshores/Zotero/storage/5JMBVP79/Sandu et al. - 1997 - Benchmarking stiff ode solvers for atmospheric che.pdf;/Users/kshores/Zotero/storage/39YHBE2Z/S1352231097832128.html}
+}
+
+@article{SanduStiff1-1997,
+  title = {Benchmarking Stiff Ode Solvers for Atmospheric Chemistry Problems-{{I}}. Implicit vs Explicit},
+  author = {Sandu, A. and Verwer, J. G. and Van Loon, M. and Carmichael, G. R. and Potra, F. A. and Dabdub, D. and Seinfeld, J. H.},
+  year = {1997},
+  month = oct,
+  journal = {Atmospheric Environment},
+  series = {{{EUMAC}}: {{European Modelling}} of {{Atmospheric Constituents}}},
+  volume = {31},
+  number = {19},
+  pages = {3151--3166},
+  issn = {1352-2310},
+  doi = {10.1016/S1352-2310(97)00059-9},
+  urldate = {2023-02-15},
+  abstract = {In many applications of atmospheric transport-chemistry problems, a major task is the numerical integration of the stiff systems of ordinary differential equations describing the chemical transformations. This paper presents a comprehensive numerical comparison between five dedicated explicit and four implicit solvers for a set of seven benchmark problems from actual applications. The implicit solvers use sparse matrix techniques to economize on the numerical linear algebra overhead. As a result they are often more efficient than the dedicated explicit ones, particularly when approximately two or more figures of accuracy are required. In most test cases, sparse RODAs, a Rosenbrock solver, came out as most competitive in the 1\% error region. Of the dedicated explicit solvers, TWOSTEP came out as best. When less than 1\% accuracy is aimed at, this solver performs very efficiently for tropospheric gas-phase problems. However, like all other dedicated explicit solvers, it cannot efficiently deal with gas-liquid phase chemistry. The results presented may constitute a guide for atmospheric modelers to select a suitable integrator based on the type and dimension of their chemical mechanism and on the desired level of accuracy. Furthermore, we would like to consider this paper an open invitation for other groups to add new representative test problems to those described here and to benchmark their numerical algorithms in our standard computational environment.},
+  langid = {english},
+  file = {/Users/kshores/Zotero/storage/9SETTXQS/Sandu et al. - 1997 - Benchmarking stiff ode solvers for atmospheric che.pdf;/Users/kshores/Zotero/storage/3IF3VR72/S1352231097000599.html}
+}
+
+@article{Sandu2003,
+  title = {Direct and Adjoint Sensitivity Analysis of Chemical Kinetic Systems with {{KPP}}: {{Part I}}\textemdash Theory and Software Tools},
+  shorttitle = {Direct and Adjoint Sensitivity Analysis of Chemical Kinetic Systems with {{KPP}}},
+  author = {Sandu, Adrian and Daescu, Dacian N. and Carmichael, Gregory R.},
+  year = {2003},
+  month = nov,
+  journal = {Atmospheric Environment},
+  volume = {37},
+  number = {36},
+  pages = {5083--5096},
+  issn = {1352-2310},
+  doi = {10.1016/j.atmosenv.2003.08.019},
+  urldate = {2023-02-15},
+  abstract = {The analysis of comprehensive chemical reactions mechanisms, parameter estimation techniques, and variational chemical data assimilation applications require the development of efficient sensitivity methods for chemical kinetics systems. The new release (KPP-1.2) of the kinetic preprocessor (KPP) contains software tools that facilitate direct and adjoint sensitivity analysis. The direct-decoupled method, built using BDF formulas, has been the method of choice for direct sensitivity studies. In this work, we extend the direct-decoupled approach to Rosenbrock stiff integration methods. The need for Jacobian derivatives prevented Rosenbrock methods to be used extensively in direct sensitivity calculations; however, the new automatic and symbolic differentiation technologies make the computation of these derivatives feasible. The direct-decoupled method is known to be efficient for computing the sensitivities of a large number of output parameters with respect to a small number of input parameters. The adjoint modeling is presented as an efficient tool to evaluate the sensitivity of a scalar response function with respect to the initial conditions and model parameters. In addition, sensitivity with respect to time-dependent model parameters may be obtained through a single backward integration of the adjoint model. KPP software may be used to completely generate the continuous and discrete adjoint models taking full advantage of the sparsity of the chemical mechanism. Flexible direct-decoupled and adjoint sensitivity code implementations are achieved with minimal user intervention. In a companion paper, we present an extensive set of numerical experiments that validate the KPP software tools for several direct/adjoint sensitivity applications, and demonstrate the efficiency of KPP-generated sensitivity code implementations.},
+  langid = {english},
+  keywords = {Adjoint model,Chemical kinetics,Direct-decoupled method,Sensitivity analysis},
+  file = {/Users/kshores/Zotero/storage/Q2BN8Z5E/Sandu et al. - 2003 - Direct and adjoint sensitivity analysis of chemica.pdf;/Users/kshores/Zotero/storage/B26KZ24Z/S1352231003006721.html}
+}
+
+@article{Sandu1996,
+  title = {Efficient {{Implementation}} of {{Fully Implicit Methods}} for {{Atmospheric Chemical Kinetics}}},
+  author = {Sandu, A. and Potra, F. A. and Carmichael, G. R. and Damian, V.},
+  year = {1996},
+  month = nov,
+  journal = {Journal of Computational Physics},
+  volume = {129},
+  number = {1},
+  pages = {101--110},
+  issn = {0021-9991},
+  doi = {10.1006/jcph.1996.0236},
+  urldate = {2023-02-15},
+  abstract = {Implicit integrators are very useful in efficiently solving stiff systems of ODEs arising from atmospheric chemistry kinetics, provided that they are modified to take full advantage of the structure of the problem. A systematic way of treating sparsity for reducing the linear algebra cost is presented.},
+  langid = {english},
+  file = {/Users/kshores/Zotero/storage/XFN28QLI/Sandu et al. - 1996 - Efficient Implementation of Fully Implicit Methods.pdf;/Users/kshores/Zotero/storage/43WPJN5Y/S0021999196902363.html}
+}

docs/source/user_guide/but_how_fast_is_it.rst

@@ -72,7 +72,9 @@ in the stats object.
   singular: 0
 
 To get the total accumulated time of each function call, you need to specify the templated boolean argument to turn the timing on.
-We can also record the total runtime of the ``Solve`` function.
+We can also record the total runtime of the ``Solve`` function. Through the magic of templates, the timing information is only
+collected when you use the ``true`` version of the templated function. These values are not even computed, meaning no CPU cycles are 
+wasted, for the ``false`` version.
 
 .. literalinclude:: ../../../test/tutorial/test_but_how_fast_is_it.cpp
   :language: cpp
@@ -87,4 +89,4 @@ We can also record the total runtime of the ``Solve`` function.
   total_linear_solve_time: 3290 nanoseconds
 
 .. note::
-  Your systems clock may not report the same values depending on how accurate your system clock is. 
+  Your systems clock may not report the same granularity depending on how accurate your system clock is. 

docs/source/user_guide/index.rst

@@ -43,5 +43,6 @@ If you would like to include the json examples, you must configure micm to build
    rate_constant_tutorial
    user_defined_rate_constant_tutorial
    multiple_grid_cells
+   solver_configurations
    but_how_fast_is_it
    openmp