Skip to content

Commit

Permalink
Merge branch 'docs' into cleanup_int
Browse files Browse the repository at this point in the history
  • Loading branch information
@yantosca
yantosca committed May 23, 2022
2 parents 40755a2 + d0fc21a commit 8a9c79e
Show file tree
Hide file tree
Showing 6 changed files with 130 additions and 124 deletions.
2 changes: 1 addition & 1 deletion docs/source/getting_started/02_running_kpp_sample_mech.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ capabilities. However, the software tools are general and can be applied
to virtually any kinetic mechanism.

We focus on Fortran90. Particularities of the C and Matlab
languages are discussed in the :ref:`language` section.
languages are discussed in the :ref:`language-cmd` section.

.. important::

Expand Down
31 changes: 15 additions & 16 deletions docs/source/tech_info/06_info_for_kpp_developers.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,13 +103,13 @@ following subdirectories:
.. option:: int/

Contains numerical time stepping (integrator) routines. The
command “*integrator*” will force KPP to look into this directory for
a definition file *integrator*. This file selects the numerical
routine (with the command) and sets the function type, the Jacobian
sparsity type, the target language, etc. Each integrator template is
found in a file that ends with the appropriate suffix
(:code:`.f90`, :code:`.F90`, :code:`c`, or :code:`matlab`). The
selected template is processed by the
:command:`#INTEGRATOR` command will force KPP to look into this
directory for a definition file with suffix :code:`.def`. This file
selects the numerical routine (with the command) and sets the
function type, the Jacobian sparsity type, the target language, etc.
Each integrator template is found in a file that ends with the
appropriate suffix (:code:`.f90`, :code:`.F90`, :code:`c`, or
:code:`matlab`). The selected template is processed by the
substitution preprocessor (cf. :ref:`list-of-symbols-replaced`).
Users can define here their own numerical integration routines.

Expand Down Expand Up @@ -184,7 +184,7 @@ Default setting: none
Optional specifies additional places where KPP will look for driver
files before searching the default folder.

Default setting: :file:`$KPP_HOME/drv`
Default setting: :file:`$KPP_HOME/drv`.

.. _kpp-internal-modules:

Expand Down Expand Up @@ -218,10 +218,8 @@ memory:

Error checking is performed at each step in the scanner and the parser.
For each syntax error the exact line and input file, along with an
appropriate error message are produced. In most of the cases the exact
cause of the error can be identified, therefore the error messages are
very precise. Some other errors like mass balance, and equation
duplicates, are tested at the end of this phase.
appropriate error message are produced. Some other errors like mass
balance, and equation duplicates, are tested at the end of this phase.

.. _species-reordering:

Expand Down Expand Up @@ -267,7 +265,7 @@ particularities of the target language. For example, the C module
includes a function that generates a valid C assignment when given an
expression tree. Similarly there are functions for data declaration,
initializations, comments, function prototypes, etc. Each of these
functions produce the code into an output buffer. A language specific
functions produce the code into an output buffer. A language-specific
routine reads from this buffer and splits the statements into lines to
improve readability of the generated code.

Expand Down Expand Up @@ -403,8 +401,9 @@ List of continuous integration tests
+-----------------------+------------------------------------------------+

Each continuous integration test is contained in a subfolder of
:file:`$KPP_HOME/ci-tests` a KPP definition file (ending in
:file:`.kpp`) from :file:`$KPP_HOME/models/`.
:file:`$KPP_HOME/ci-tests` in a KPP definition file (ending in
:file:`.kpp`) from :file:`$KPP_HOME/models/` or
:file:`$KPP_HOME/examples/`.

.. _running-ci-tests-on-azure:

Expand Down Expand Up @@ -472,7 +471,7 @@ pull requests to certain branches will trigger the C-I tests.
File :file:`ci-testing-script.sh` executes all of the C-I tests
whenever a push or a pull request is made to the selected branches
in the KPP Github repository. If you add new C-I tests, be sure to
update the:code:`for` loop in this file.
update the :code:`for` loop in this file.

.. _running-ci-tests-locally:

Expand Down
10 changes: 8 additions & 2 deletions docs/source/tech_info/07_numerical_methods.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,8 @@ in KPP. The symbols used in the formulas are explained in
Rosenbrock methods
==================

**Integrator file:** :file:`int/rosenbrock.f90`

An :math:`s`-stage Rosenbrock method (cf. Section IV.7 in
:cite:`1991:Hairer_and_Wanner`) computes the next-step solution by the
formulas
Expand Down Expand Up @@ -261,6 +263,8 @@ RODAS-4
Rosenbrock tangent linear model
--------------------------------

**Integrator file:** :file:`int/rosenbrock_tlm.f90`

The Tangent Linear method is combined with the sensitivity
equations. One step of the method reads:

Expand Down Expand Up @@ -302,6 +306,8 @@ respect to parameters for efficiency.
Rosenbrock discrete adjoint model
---------------------------------

**Integrator file:** :file:`int/rosenbrock_adj.f90`

To obtain the adjoint we first differentiate the method with respect to
:math:`y_n`. Here :math:`J` denotes the Jacobian and :math:`H` the
Hessian of the derivative function :math:`f`. The discrete adjoint of
Expand All @@ -328,7 +334,7 @@ the (non-autonomous) Rosenbrock method is
KPP contains adjoint models (for direct decoupled sensitivity analysis)
for each of the Rosenbrock methods (:ref:`rosenbrock-ros-2`,
:ref:`rosenbrock-ros-3`, :ref:`rosenbrock-ros-4`,
:ref:`rosenbrock-rodas3`, :ref:`rosenbrock-rodas-4`).
:ref:`rosenbrock-rodas-3`, :ref:`rosenbrock-rodas-4`).

.. _rk-methods:

Expand Down Expand Up @@ -373,7 +379,7 @@ Fully implicit 3-stage Runge-Kutta methods. Several variants are available:

RADAU5
------
**Integrator files:** :file:`int/radau5.f90`
**Integrator file:** :file:`int/radau5.f90`

This Runge-Kutta method of order 5 based on RADAU-IIA quadrature
is stiffly accurate. The KPP implementation follows the original
Expand Down
141 changes: 71 additions & 70 deletions docs/source/tech_info/08_bnf_description_of_kpp_lang.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,125 +8,126 @@ Following is the BNF-like specification of the KPP language:

.. code-block:: text
program ::= module | module program
module ::= section | command |inline_code
section ::= #ATOMS atom_definition_list |
#CHECK atom_list |
#DEFFIX species_definition_list |
#DEFVAR species_definition_list |
#EQUATIONS equation_list |
#FAMILIES family_list |
#INITVALUES initvalues_list |
#LOOKAT species_list atom_list |
#LUMP lump_list |
#MONITOR species_list atom_list |
#SETFIX species_list_plus |
#SETVAR species_list_plus |
program ::= module | module program
module ::= section | command |inline_code
section ::= #ATOMS atom_definition_list |
#CHECK atom_list |
#DEFFIX species_definition_list |
#DEFVAR species_definition_list |
#EQUATIONS equation_list |
#FAMILIES family_list |
#INITVALUES initvalues_list |
#LOOKAT species_list atom_list |
#LUMP lump_list |
#MONITOR species_list atom_list |
#SETFIX species_list_plus |
#SETVAR species_list_plus |
#TRANSPORT species_list
command ::= #CHECKALL |
#DECLARE [ SYMBOL | VALUE ] |
#DOUBLE [ ON | OFF ] |
#DRIVER driver_name |
#DUMMYINDEX [ ON | OFF ] |
#EQNTAGS [ ON | OFF ] |
#FUNCTION [ AGGREGATE | SPLIT ] |
#HESSIAN [ ON | OFF ] |
#INCLUDE file_name |
#INTEGRATOR integrator_name |
#INTFILE integrator_name |
#JACOBIAN [ OFF | FULL | SPARSE_LU_ROW | SPARSE_ROW ] |
#LANGUAGE[ Fortran90 | Fortran77 | C | Matlab ] |
#LOOKATALL |
#MEX [ ON | OFF ] |
#MINVERSION minimum_version_number |
#MODEL model_name |
#REORDER [ ON | OFF ] |
#STOCHASTIC [ ON | OFF ] |
#STOICHMAT [ ON | OFF ] |
#TRANSPORTALL [ ON | OFF] |
command ::= #CHECKALL |
#DECLARE [ SYMBOL | VALUE ] |
#DOUBLE [ ON | OFF ] |
#DRIVER driver_name |
#DUMMYINDEX [ ON | OFF ] |
#EQNTAGS [ ON | OFF ] |
#FUNCTION [ AGGREGATE | SPLIT ] |
#HESSIAN [ ON | OFF ] |
#INCLUDE file_name |
#INTEGRATOR integrator_name |
#INTFILE integrator_name |
#JACOBIAN [ OFF | FULL | SPARSE_LU_ROW | SPARSE_ROW ] |
#LANGUAGE[ Fortran90 | Fortran77 | C | Matlab ] |
#LOOKATALL |
#MEX [ ON | OFF ] |
#MINVERSION minimum_version_number |
#MODEL model_name |
#REORDER [ ON | OFF ] |
#STOCHASTIC [ ON | OFF ] |
#STOICHMAT [ ON | OFF ] |
#TRANSPORTALL [ ON | OFF ] |
#UPPERCASEF90 [ ON | OFF ]
inline_code ::= #INLINE inline_type
inline_code
#ENDINLINE
atom_count ::= integer atom_name |
atom_count ::= integer atom_name |
atom_name
atom_definition_list := atom_definition |
atom_definition_list := atom_definition |
atom_definition_list
atom_list ::= atom_name; |
atom_list ::= atom_name; |
atom_name; atom_list
equation ::= <equation_tag> expression = expression : rate; |
equation ::= <equation_tag> expression = expression : rate; |
expression = expression : rate;
equation_list ::= equation |
equation_list ::= equation |
equation equation_list
equation_tag ::= Alphanumeric expression, also including the
underscore. In scan.l it is defined as
"[a-zA-Z_0-0]+".
expression ::= term |
term + expression |
expression ::= term |
term + expression |
term - expression
initvalues_assignment := species_name_plus = program_expression; |
initvalues_assignment := species_name_plus = program_expression; |
CFACTOR = program_expression
initvalues_list ::= initvalues_assignment |
initvalues_list ::= initvalues_assignment |
initvalues_assignment initvalues_list
inline_type ::= F90_RATES | F90_RCONST | F90_GLOBAL |
F90_INIT | F90_DATA | F90_UTIL |
F77_RATES | F77_RCONST | F77_GLOBAL |
F77_INIT | F77_DATA | F77_UTIL |
C_RATES | C_RCONST | C_GLOBAL |
C_INIT | C_DATA | C_UTIL |
MATLAB_RATES | MATLAB_RCONST | MATLAB_GLOBAL |
inline_type ::= F90_RATES | F90_RCONST | F90_GLOBAL |
F90_INIT | F90_DATA | F90_UTIL |
F77_RATES | F77_RCONST | F77_GLOBAL |
F77_INIT | F77_DATA | F77_UTIL |
C_RATES | C_RCONST | C_GLOBAL |
C_INIT | C_DATA | C_UTIL |
MATLAB_RATES | MATLAB_RCONST | MATLAB_GLOBAL |
MATLAB_INIT | MATLAB_DATA | MATLAB_UTIL
lump ::= lump_sum : species_name;
lump_list ::= lump |
lump_list ::= lump |
lump lump_list
lump_sum ::= species_name |
lump_sum ::= species_name |
species_name + lump_sum
rate ::= number |
rate ::= number |
program_expression
species_composition ::= atom_count |
atom_count + species_composition |
species_composition ::= atom_count |
atom_count + species_composition |
IGNORE
species_definition ::= species_name = species_composition;
species_definition_list := species_definition |
species_definition_list := species_definition |
species_definition species_definition_list
species_list ::= species_name; |
species_list ::= species_name; |
species_name; species_list
species_list_plus ::= species_name_plus; |
species_list_plus ::= species_name_plus; |
species_name_plus; species_list_plus
species_name ::= Alphanumeric expression, also including the underscore,
starting with a letter. In scan.l it is defined as
"[a-zA-Z_][a-ZA-Z_0-9]*". Its maximum length is 32.
species_name ::= Alphanumeric expression, also including the
underscore, starting with a letter. In
scan.l it is defined as "[a-zA-Z_][a-ZA-Z_0-9]*".
Its maximum length is 32.
species_name_plus ::= species_name |
VAR_SPEC |
FIX_SPEC |
species_name_plus ::= species_name |
VAR_SPEC |
FIX_SPEC |
ALL_SPEC
term ::= number species_name |
species_name |
PROD |
term ::= number species_name |
species_name |
PROD |
hv
2 changes: 1 addition & 1 deletion docs/source/using_kpp/04_input_for_kpp.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -896,7 +896,7 @@ F90_RCONST
----------

This inline type can be used to define time-dependent values of rate
coefficients that were declared with :
coefficients that were declared with:

.. code-block:: F90
Expand Down

0 comments on commit 8a9c79e

Please sign in to comment.