Added more chapters to Sphinx/ReadTheDocs format

The documentation is still a work in progress... some pages still need hand-formatting. To be done soon. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>
KineticPreProcessor · May 9, 2022 · d53f0a7 · d53f0a7
1 parent 6e7ea36
commit d53f0a7
Show file tree

Hide file tree

Showing 15 changed files with 3,699 additions and 16 deletions.
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -0,0 +1,4 @@
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: inherit;
+    vertical-align: top;
+}
diff --git a/docs/source/_static/kpp2_use_diagr.png b/docs/source/_static/kpp2_use_diagr.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -14,16 +14,16 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-master_doc = 'index'
+master_doc = "index"
 
 # -- Project information -----------------------------------------------------
 
-project = 'KPP: The Kinetic PreProcessor'
-copyright = '2022, The KPP development team'
-author = 'A. Sandu, R. Sander, M. Long, H. Lin, and R. Yantosca'
+project = "KPP: The Kinetic PreProcessor"
+copyright = "2022, The KPP development team"
+author = "A. Sandu, R. Sander, M. Long, H. Lin, and R. Yantosca"
 
 # The full version, including alpha/beta/rc tags
-release = '2.5.0'
+release = "2.5.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -36,7 +36,7 @@
     "sphinxcontrib.bibtex",
     "recommonmark",
 ]
-bibtex_default_style = 'gcrefstyle'
+bibtex_default_style = "gcrefstyle"
 
 from pybtex.style.formatting.unsrt import Style as UnsrtStyle
 from pybtex.style.names.lastfirst import NameStyle as LastFirst
@@ -69,7 +69,10 @@ def format_web_refs(self, e):
 bibtex_bibliography_header = ".. rubric:: References"
 bibtex_footbibliography_header = bibtex_bibliography_header
 
-bibtex_bibfiles = ['reference/geos-chem.bib']
+bibtex_bibfiles = [
+    'reference/rolf.bib',
+    'reference/adrian.bib'
+]
 
 
 # List of patterns, relative to source directory, that match files and
@@ -83,18 +86,23 @@ def format_web_refs(self, e):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
-#html_theme = 'alabaster'
+html_theme = "sphinx_rtd_theme"
+#html_theme = "alabaster"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (e.g. https://...)
+html_css_files = ["custom.css"]
 
 # Display KPP logo
-html_favicon = '_static/kpp-favicon.png'
+html_favicon = "_static/kpp-favicon.png"
 html_logo = "_static/kpp-logo.png"
+
+# RTD theme settings
 html_theme_options = {
     'logo_only': True,
     'display_version': False,

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -19,6 +19,10 @@ The Kinetic PreProcessor: KPP
    <a href="https://kpp.readthedocs.io/en/latest/"><img src="https://img.shields.io/readthedocs/kpp?label=ReadTheDocs"></a>
    </p>
 
+.. important:: This documentation is still being converted to the
+	       ReadTheDocs format.  Some pages may appear incomplete.
+	       Please bear with us!
+
 This site provides instructions for :program:`KPP`, the Kinetic PreProcessor.
 
 Contributions (e.g., suggestions, edits, revisions) would be greatly
@@ -27,14 +31,24 @@ and our :ref:`contributing guidelines <reference/CONTRIBUTING.rst>`.
 If you find a something hard to understand---let us know!
 
 .. toctree::
-   :maxdepth: 4
-   :caption: Getting Started
+   :caption: User Guide
 
    user_manual/01_installation.rst
+   user_manual/02_running_kpp_sample_mech.rst
+   user_manual/03_input_for_kpp.rst
+   user_manual/04_output_from_kpp.rst
+   user_manual/05_info_for_developers.rst
+   user_manual/06_numerical_methods.rst
+   user_manual/07_revision_history.rst
+   user_manual/08_acknowledgments.rst
+
+.. toctree:: 
+   :caption: Supplemental Guides
+
+   user_manual/A1_bnf_description_of_kpp_lang.rst
 
 .. toctree::
-   :maxdepth: 4
-   :caption: Reference
+   :caption: Help & Reference
 
    reference/known-bugs.rst 
    reference/SUPPORT.rst

diff --git a/docs/source/user_manual/01_installation.rst b/docs/source/user_manual/01_installation.rst
@@ -10,7 +10,8 @@ This section can be skipped if KPP is already installed on your system.
 Download KPP from Github
 ========================
 
-Clone the KPP source code from the `KPP Github repository <(https://github.com/KineticPreProcessor/KPP>`_:
+Clone the KPP source code from the `KPP Github repository
+<(https://github.com/KineticPreProcessor/KPP>`_: 
 
 .. code-block:: console
 

diff --git a/docs/source/user_manual/02_running_kpp_sample_mech.rst b/docs/source/user_manual/02_running_kpp_sample_mech.rst
@@ -0,0 +1,127 @@
+.. _running-kpp-with-an-example-mechanism:
+
+###################################################
+Running KPP with an Example Stratospheric Mechanism
+###################################################
+
+Here we consider as an example a very simple Chapman-like mechanism for
+stratospheric chemistry:
+
+.. math::
+
+   \begin{aligned}
+   O_2    + h\nu   & \longrightarrow  & 2 O           & ~~~~~~~~~~ (1)\\
+   O      + O_2    & \longrightarrow  & O_3           & ~~~~~~~~~~ (2)\\
+   O_3    + h\nu   & \longrightarrow  & O      + O_2  & ~~~~~~~~~~ (3)\\
+   O      + O_3    & \longrightarrow  & 2 O_2         & ~~~~~~~~~~ (4)\\
+   O_3    + h\nu   & \longrightarrow  & O(^1D) + O_2  & ~~~~~~~~~~ (5)\\
+   O(^1D) + M      & \longrightarrow  & O + M         & ~~~~~~~~~~ (6)\\
+   O(^1D) + O_3    & \longrightarrow  & 2 O_2         & ~~~~~~~~~~ (7)\\
+   NO     + O_3    & \longrightarrow  & NO_2   + O_2  & ~~~~~~~~~~ (8)\\
+   NO_2   + O      & \longrightarrow  & NO     + O_2  & ~~~~~~~~~~ (9)\\
+   NO_2   + h\nu   & \longrightarrow  & NO     + O    & ~~~~~~~~~~ (10)
+   \end{aligned}
+
+We use the mechanism with the purpose of illustrating the KPP
+capabilities. However, the software tools are general and can be applied
+to virtually any kinetic mechanism.
+
+We focus on Fortran90. Particularities of the C, Fortran77, and Matlab
+languages are discussed in `Target language selection
+<target-language-selection_>`_. 
+
+The KPP input files (with suffix :file:`.kpp`) specify the model, the
+target language, the precision, the integrator and the driver, etc. The file
+name (without the suffix :file:`.kpp`) serves as the root name for the
+simulation. In this paper we will refer to this name as root. Since
+the root name will be incorporated into Fortran90 module names, it can
+only contain valid Fortran90 characters, i.e. letters, numbers, and the
+underscore. To specify a KPP model, write a root file with the following lines: 
+
+.. code-block:: console
+
+   #MODEL      small_strato
+   #LANGUAGE   Fortran90
+   #DOUBLE     ON
+   #INTEGRATOR rosenbrock
+   #DRIVER     general
+   #JACOBIAN   SPARSE_LU_ROW
+   #HESSIAN    ON
+   #STOICMAT   ON
+
+The target language Fortran90 (i.e. the language of the code generated
+by KPP) is selected with the command:
+
+.. code-block:: console
+
+   #LANGUAGE Fortran90
+
+Here, we have chosen Fortran90. See `Target language selection
+<target-language-selection_>`_ for other options. 
+
+The data type of the generated model can be switched between
+single/double precision with the command . The command selects a
+specific numerical integration routine (from the templates provided by
+KPP or implemented by the user) and the command selects a specific main
+program. The command selects a specific kinetic mechanism. In our
+example the model definition file includes the species and the equation
+files,
+
+.. code-block:: console
+
+   #INCLUDE small_strato.spc
+   #INCLUDE small_strato.eqn
+
+The species file lists all the species in the model. Some of them are
+variable (defined with ), meaning that their concentrations change
+according to the law of mass action kinetics. Others are fixed (defined
+with ), with the concentrations determined by physical and not chemical
+factors. For each species its atomic composition is given (unless the
+user chooses to ignore it). The atom file lists the periodic table of
+elements in an section. The equation file contains the description of
+the equations in an section.
+
+.. code-block:: console
+
+   #INCLUDE atoms
+   #DEFVAR
+     O   = O;
+     O1D = O;
+     O3  = O + O + O;
+     NO  = N + O;
+     NO2 = N + O + O;
+   #DEFFIX
+     M   = IGNORE;
+     O2  = O + O;
+
+The chemical kinetic mechanism is specified in the KPP language in the
+file . Each reaction is described as “the sum of reactants equals the
+sum of products” and is followed by its rate coefficient. is the
+normalized sunlight intensity, equal to one at noon and zero at night.
+
+.. code-block:: console
+
+   #EQUATIONS { Stratospheric Mechanism }
+   <R1>  O2  + hv = 2O       : 2.643E-10*SUN;
+   <R2>  O   + O2 = O3       : 8.018E-17;
+   <R3>  O3  + hv = O   + O2 : 6.120E-04*SUN;
+   <R4>  O   + O3 = 2O2      : 1.576E-15;
+   <R5>  O3  + hv = O1D + O2 : 1.070E-03*SUN;
+   <R6>  O1D + M  = O   + M  : 7.110E-11;
+   <R7>  O1D + O3 = 2O2      : 1.200E-10;
+   <R8>  NO  + O3 = NO2 + O2 : 6.062E-15;
+   <R9>  NO2 + O  = NO  + O2 : 1.069E-11;
+   <R10> NO2 + hv = NO  + O  : 1.289E-02*SUN;
+
+To run the model, type:
+
+.. code-block:: console
+
+   $ kpp small_strato.kpp
+
+Next, compile and run the Fortran90 code:
+
+.. code-block:: console
+
+   $ make -f Makefile_small_strato
+   $ ./small_strato.exe