Skip to content

Commit

Permalink
lots of very minor updates of the docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@RolfSander
RolfSander committed Jun 29, 2022
1 parent 2021f36 commit f1affbd
Show file tree
Hide file tree
Showing 5 changed files with 143 additions and 188 deletions.
32 changes: 17 additions & 15 deletions docs/source/getting_started/00_revision_history.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@ KPP revision history
####################

Only the major new features are listed here. For a detailed description
of the changes, read the file :file:`$KPP_HOME/CHANGELOG.md`.
of the changes, read `CHANGELOG.md
<https://github.com/KineticPreProcessor/KPP/blob/main/CHANGELOG.md>`_.

.. _kpp300:

Expand All @@ -23,12 +24,6 @@ is currently still in preparation.
to change :code:`#INCLUDE atoms` to :code:`#INCLUDE atoms.kpp` in your
KPP input file.

- If you have been using :code:`ICNTRL(5)` for maximal order in the
:code:`lsode` integrator, you now have to use :code:`ICNTRL(10)`
instead. The index 5 in the :code:`ICNTRL` array is now used
consistently for the maximum number of Newton iterations in all
integrators.

- The utility functions :code:`ARR`, :code:`ARR2`, :code:`k_3rd` and
:code:`k_arr` have been replaced by the new set of the consistent
functions :code:`ARR_abc`, :code:`ARR_ab`, :code:`ARR_ac`,
Expand All @@ -39,13 +34,19 @@ is currently still in preparation.
old functions into a separate file and make them available via
:ref:`f90-RCONST`.

- If you have been using :code:`ICNTRL(5)` for maximal order in the
:code:`lsode` integrator, you now have to use :code:`ICNTRL(10)`
instead. The index 5 in the :code:`ICNTRL` array is now used
consistently for the maximum number of Newton iterations in all
integrators.

.. _kpp260:

=========
KPP 2.6.0
=========

- Added the **rosenbrock_autoreduce** integrator :cite:`2022:Lin_et_al`
- Added the **rosenbrock_autoreduce** integrator :cite:`2022:Lin_et_al`.

.. _kpp250:

Expand All @@ -59,7 +60,7 @@ KPP 2.5.0
stream. Previously hardwired code has been removed and replaced
with code selectable via KPP commands.

- Added a new forward-Euler method integrator (:program:`feuler.f90`).
- Added a new forward-Euler method integrator (:file:`feuler.f90`).

- Added KPP commands :command:`#MINVERSION` and :command:`#UPPERCASEF90`
(along with corresponding continuous integration tests).
Expand Down Expand Up @@ -104,7 +105,7 @@ KPP 2.4.0
KPP 2.3.2_gc
============

NOTE: Contains KPP Modifications specific to GEOS-Chem:
NOTE: Contains KPP Modifications specific to GEOS-Chem.

- Added workaround for F90 derived-type objects in inlined code
(i.e. properly parse :code:`State_Het%xArea`, etc).
Expand All @@ -127,7 +128,7 @@ NOTE: Contains KPP Modifications specific to GEOS-Chem:
KPP 2.3.1_gc
============

NOTE: KPP modifications specific to GEOS-Chem
NOTE: KPP modifications specific to GEOS-Chem.

ALSO NOTE: ReadTheDocs documentation has been updated in :ref:`kpp250`
to remove GEOS-Chem specific information.
Expand All @@ -146,7 +147,7 @@ to remove GEOS-Chem specific information.
KPP 2.3.0_gc
============

NOTE: Contains KPP modifications specific to GEOS-Chem
NOTE: Contains KPP modifications specific to GEOS-Chem.

- Added :file:`README.md` for the GC_updates branch.

Expand Down Expand Up @@ -176,7 +177,7 @@ NOTE: Contains KPP modifications specific to GEOS-Chem
KPP 2.2.5_gc
============

NOTE: Contains KPP modifications specific to GEOS-Chem
NOTE: Contains KPP modifications specific to GEOS-Chem.

- Increase :code:`MAX_INLINE` from 20000 to 50000

Expand All @@ -186,7 +187,7 @@ NOTE: Contains KPP modifications specific to GEOS-Chem
KPP 2.2.4_gc
============

NOTE: Contains KPP modifications specific to GEOS-Chem
NOTE: Contains KPP modifications specific to GEOS-Chem.

- Add MIT license files for GC_updates branch and update
:file:`README.md` accordingly
Expand Down Expand Up @@ -254,7 +255,8 @@ KPP 2.2.3

- New Rosebrock method :code:`Rang3` was added.

- The new KPP command :code:`#DECLARE` was added (see :ref:`declare-cmd`).
- The new KPP command :command:`#DECLARE` was added (see
:ref:`declare-cmd`).

- Several vector and array functions from :program:`BLAS` (:code:`WCOPY`,
:code:`WAXPY`, etc.) were replaced by Fortran90 expressions.
Expand Down
7 changes: 3 additions & 4 deletions docs/source/getting_started/01_installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,10 +81,9 @@ with `Spack <https://spack.readthedocs.io>`_.
gcc
---

KPP uses the `GNU Compiler Collection (aka gcc)
<https://gcc.gnu.org/>`_ by default. A version of gcc comes
pre-installed with most Linux or MacOS systems. To test if gcc is
installed on your system, type:
KPP uses the `GNU Compiler Collection <https://gcc.gnu.org/>`_ (aka gcc)
by default. A version of gcc comes pre-installed with most Linux or
MacOS systems. To test if gcc is installed on your system, type:

.. code-block :: console
Expand Down
146 changes: 54 additions & 92 deletions docs/source/getting_started/02_running_kpp_sample_mech.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,16 @@ 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)
O_2 + h\nu & \longrightarrow & 2 O & ~~~~~~~~~~ (R1)\\
O + O_2 & \longrightarrow & O_3 & ~~~~~~~~~~ (R2)\\
O_3 + h\nu & \longrightarrow & O + O_2 & ~~~~~~~~~~ (R3)\\
O + O_3 & \longrightarrow & 2 O_2 & ~~~~~~~~~~ (R4)\\
O_3 + h\nu & \longrightarrow & O(^1D) + O_2 & ~~~~~~~~~~ (R5)\\
O(^1D) + M & \longrightarrow & O + M & ~~~~~~~~~~ (R6)\\
O(^1D) + O_3 & \longrightarrow & 2 O_2 & ~~~~~~~~~~ (R7)\\
NO + O_3 & \longrightarrow & NO_2 + O_2 & ~~~~~~~~~~ (R8)\\
NO_2 + O & \longrightarrow & NO + O_2 & ~~~~~~~~~~ (R9)\\
NO_2 + h\nu & \longrightarrow & NO + O & ~~~~~~~~~~ (R10)
\end{aligned}
We use the mechanism with the purpose of illustrating the KPP
Expand All @@ -45,7 +45,7 @@ refer to this name as :code:`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.

The sections below outline the steps necessary to build an run a
The sections below outline the steps necessary to build and run a
"box-model" simulation with an example mechanism.

.. _example-step-1:
Expand Down Expand Up @@ -82,12 +82,8 @@ For this example, write the following lines into a file named
#MODEL small_strato
#LANGUAGE Fortran90
#DOUBLE ON
#INTEGRATOR rosenbrock
#DRIVER general
#JACOBIAN SPARSE_LU_ROW
#HESSIAN ON
#STOICMAT ON
.. important::

Expand All @@ -96,23 +92,18 @@ For this example, write the following lines into a file named
Therefore you won't need to copy these manually to the example
folder.

Also note, KPP command options can be either uppercase or lowercase
(i.e. :command:`INTEGRATOR ON` or :command:`INTEGRATOR on` are
identical).

We will now look at the following :ref:`kpp-commands` in
:file:`small_strato.kpp`.
We will now look at the :ref:`kpp-commands` in :file:`small_strato.kpp`.

.. _example-model-ss:

#MODEL small_strato
-------------------

The :ref:`model-cmd` command selects a specific kinetic mechanism (in
this example, :program:`small_strato`). KPP will look in the path
this example, :program:`small_strato`). KPP will look in the path
:file:`$KPP_HOME/models/` for the *model definition file*
:file:`small_strato.def`. This file contains the following
code in the :ref:`KPP language <bnf-description>`.
:file:`small_strato.def` which contains the following code in the
:ref:`KPP language <bnf-description>`:

.. code-block:: console
Expand Down Expand Up @@ -159,19 +150,18 @@ code in the :ref:`KPP language <bnf-description>`.
TEMP = 270;
#ENDINLINE
File (:file:`small_strato.def`) :ref:`include-cmd`-s the *species
file* and the *equation file*. It also specifies parameters for
running a "box-model" simualation, such as :ref:`species initial
values <initvalues>`, start time, stop, time, and timestep
(cf. :ref:`inlined-code`).
The *definition file* :file:`small_strato.def` uses the
:ref:`include-cmd` command to include the *species file* and the
*equation file*. It also specifies parameters for running a "box-model"
simulation, such as :ref:`species initial values <initvalues>`, start
time, stop, time, and timestep (cf. :ref:`inlined-code`).

The *species file* (:file:`small_strato.spc`) file lists all the
species in the model. Some of them are variable, meaning that their
concentrations change according to the law of mass action
kinetics. Others are fixed, with the concentrations determined by
physical and not chemical factors (cf. :ref:`defvar-and-deffix`). For
each species its atomic composition is given (unless the user chooses
to ignore it).
The *species file* :file:`small_strato.spc` lists all the species in the
model. Some of them are variable, meaning that their concentrations
change according to the law of mass action kinetics. Others are fixed,
with the concentrations determined by physical and not chemical factors
(cf. :ref:`defvar-and-deffix`). For each species its atomic composition
is given (unless the user chooses to ignore it).

.. code-block:: console
Expand All @@ -186,18 +176,16 @@ to ignore it).
M = IGNORE;
O2 = O + O;
The species file also includes the *atoms file* (:file:`atoms.kpp`), which
lists the periodic table of elements in an :command:`ATOM` section
(cf. :ref:`atoms`).
The species file also includes the *atoms file* (:file:`atoms.kpp`),
which defines the chemical elements in the :ref:`atoms` section.

The *equation file* (:file:`small_strato.eqn`) contains the
description of the equations in an :ref:`equations` section. The
chemical kinetic mechanism is specified in the :ref:`KPP language
<bnf-description>`. Each reaction is described as “the sum
of reactants equals the sum of products” and is followed by its rate
coefficient. :code:`SUN` is the normalized sunlight intensity, equal
to one at noon and zero at night. Equation tags, e.g. :code:`<R1>`,
are optional.
The *equation file* :file:`small_strato.eqn` contains the description of
the equations in an :ref:`equations` section. The chemical kinetic
mechanism is specified in the :ref:`KPP language <bnf-description>`.
Each reaction is described as “the sum of reactants equals the sum of
products” and, after a colon, is followed by its rate coefficient.
:code:`SUN` is the normalized sunlight intensity, equal to one at noon
and zero at night. Equation tags, e.g. :code:`<R1>`, are optional.

.. code-block:: console
Expand Down Expand Up @@ -225,28 +213,17 @@ KPP-generated solver code. In this example we are using Fortran90.

.. _example-double-on:

#DOUBLE ON
----------

The data type of the generated model can be switched between
single/double precision with the :ref:`double-cmd` command. We
recommend using double-precision in order to avoid integrator errors
caused by roundoff or underflow/overflow.

.. _example-integrator-rosenbrock:

#INTEGRATOR rosenbrock
----------------------

The :ref:`integrator-cmd` command selects a numerical integration routine
from the templates provided in the :file:`$KPP_HOME/int` folder, or
implemented by the user.

In this example, the :ref:`Rosenbrock integrator
<rosenbrock-methods>` and the Fortran90 language have been been
specified. Therefore it will use the file
:file:`$KPP_HOME/int/rosenbrock.f90`.

In this example, the :ref:`Rosenbrock integrator <rosenbrock-methods>`
and the Fortran90 language have been been specified. Therefore, the file
:file:`$KPP_HOME/int/rosenbrock.f90` will be used.

.. _example-driver-general:


Expand All @@ -267,24 +244,14 @@ either adjoint or tangent-linear methods, so the
:file:`$KPP_HOME/drv/general.f90` will be used.


Other options
-------------

The other options listed control internal aspects of the integration
(cf. :ref:`Jacobian-and-JacobianSP`), as well as activating optional
outputs (cf. :ref:`Hessian-and-HessianSP` and
:ref:`Stoichiom-and-StoichiomSP`).

.. _example-step-3:

===============================
3. Build the mechanism with KPP
===============================

Now that all the necessary files have been copied to the example
folder, the :program:`small_strato` mechanism can be built.

Type:
Now that all the necessary files have been copied to the example folder,
the :program:`small_strato` mechanism can be built. Type:

.. code-block:: console
Expand All @@ -294,7 +261,7 @@ You should see output similar to:

.. code-block:: console
This is KPP-2.6.0.
This is KPP-3.0.0.
KPP is parsing the equation file.
KPP is computing Jacobian sparsity structure.
Expand Down Expand Up @@ -334,13 +301,8 @@ You should see output similar to:
KPP has succesfully created the model "small_strato".
This will generate the Fortran90 code needed to solve the
:program:`small_strato` mechanism. Get a file listing:

.. code-block:: console
ls
and you should see output similar to:
:program:`small_strato` mechanism. The file listing should be similar
to:

.. code-block:: console
Expand All @@ -361,10 +323,10 @@ and you should see output similar to:
small_strato_JacobianSP.f90 small_strato_Util.f90
KPP creates Fortran90 beginning with the mechanism name (which is
:file:`small_strato_` in this example). KPP also generates a
human-readable summary of the mechanism (:file:`small_strato.map`) as
well as the :file:`Makefile_small_strato`) that can be used to build the
executable.
:file:`ROOT_` = :file:`small_strato_` in this example). KPP also
generates a human-readable summary of the mechanism
(:file:`small_strato.map`) as well as the Makefile
:file:`Makefile_small_strato` that can be used to build the executable.

.. _example_step_4:

Expand Down Expand Up @@ -415,10 +377,10 @@ You will see the concentrations of selected species at several
timesteps displayed to the screen (aka the Unix stdout stream) as well
as to a log file (:file:`small_strato.log`).

If your simulation results exits abruptly with the :code:`Killed`
error, you will need to increase your stack memory limit. On most
Linux systems the default stacksize limit is 8 kIb = or 8192 kB. You
can max this out with the following commands:
If your simulation results exits abruptly with the :code:`Killed` error,
you probably need to increase your stack memory limit. On most Linux
systems the default stacksize limit is 8 kIb = or 8192 kB. You can max
this out with the following commands:

If you are using bash, type:

Expand All @@ -444,11 +406,11 @@ files generated by the Fortran compiler, type:

.. code-block:: console
$ make clean
$ make -f Makefile_small_strato clean
If you also wish to remove all the files that were generated by KPP
(i.e. :file:`small_strato.map` and :file:`small_strato_*.f90`), type:

.. code-block:: console
$ make distclean
$ make -f Makefile_small_strato distclean

0 comments on commit f1affbd

Please sign in to comment.