.. _kpp-commands: ############ KPP commands ############ A KPP command begins on a new line with a :code:`#` sign, followed by a command name and one or more parameters. Details about each command are given in the following subsections. .. _table-cmd-defaults: .. list-table:: Default values for KPP commands :align: center :header-rows: 1 * - KPP command - default value - KPP command - default value * - :command:`#AUTOREDUCE` - :code:`OFF` - :command:`#CHECKALL` - * - :command:`#DECLARE` - :code:`SYMBOL` - :command:`#DOUBLE` - :code:`ON` * - :command:`#DRIVER` - :code:`none` - :command:`#DUMMYINDEX` - :code:`OFF` * - :command:`#EQNTAGS` - :code:`OFF` - :command:`#FUNCTION` - :code:`AGGREGATE` * - :command:`#GRAPH` - :code:`OFF` - :command:`#HESSIAN` - :code:`ON` * - :command:`#INCLUDE` - - :command:`#INTEGRATOR` - * - :command:`#INTFILE` - - :command:`#JACOBIAN` - :code:`SPARSE_LU_ROW` * - :command:`#LANGUAGE` - - :command:`#LOOKATALL` - * - :command:`#MEX` - :code:`ON` - :command:`#MINVERSION` - * - :command:`#MODEL` - - :command:`#REORDER` - :code:`ON` * - :command:`#STOCHASTIC` - :code:`OFF` - :command:`#STOICMAT` - :code:`ON` * - :command:`#UPPERCASEF90` - :code:`OFF` - - .. _autoreduce-cmd: =========== #AUTOREDUCE =========== The :command:`#AUTOREDUCE ON` command can be used with :command:`#INTEGRATOR rosenbrock` to enable :ref:`automatic mechanism reduction ` as described in :cite:t:`Lin_et_al._2022`. Automatic mechanism reduction is disabled by default. .. _declare-cmd: ======== #DECLARE ======== The :command:`#DECLARE` command determines how constants like :code:`dp`, :code:`NSPEC`, :code:`NVAR`, :code:`NFIX`, and :code:`NREACT` are inserted into the KPP-generated code. :command:`#DECLARE SYMBOL` (the default) will declare array variables using parameters from the :ref:`Parameters` file. :command:`#DECLARE VALUE` will replace each parameter with its value. For example, the global array variable :code:`C` is declared in the :ref:`Global` file generated by KPP. In the :program:`small_strato` example (described in :ref:`running-kpp-with-an-example-mechanism`), :code:`C` has dimension :code:`NSPEC=7`. Using :command:`#DECLARE SYMBOL` will generate the following code in :ref:`Global`: .. code-block:: fortran ! C - Concentration of all species REAL(kind=dp), TARGET :: C(NSPEC) Whereas :command:`#DECLARE VALUE` will generate this code instead: .. code-block:: fortran ! C - Concentration of all species REAL(kind=dp), TARGET :: C(7) We recommend using :command:`#DECLARE SYMBOL`, as most modern compilers will automatically replace each parameter (e.g. :code:`NSPEC`) with its value (e.g :code:`7`). However, if you are using a very old compiler that is not as sophisticated, :command:`#DECLARE VALUE` might result in better-optmized code. .. _double-cmd: ======= #DOUBLE ======= The :command:`#DOUBLE` command selects single or double precision arithmetic. :command:`ON` (the default) means use double precision, :command:`OFF` means use single precision (see the section entitled :ref:`Precision`). .. important:: We recommend using double precision whenever possible. Using single precision may lead to integration non-convergence errors caused by roundoff and/or underflow. .. _driver-cmd: ======= #DRIVER ======= The :command:`#DRIVER` command selects the driver, i.e., the file from which the main function is to be taken. The parameter is a file name, without suffix. The appropriate suffix (:code:`.f90`, :code:`.F90`, :code:`.c`, or :code:`.m`) is automatically appended. Normally, KPP tries to find the selected driver file in the directory :file:`$KPP_HOME/drv/`. However, if the supplied file name contains a slash, it is assumed to be absolute. To access a driver in the current directory, the prefix :file:`./` can be used, e.g.: .. code-block:: console #DRIVER ./mydriver It is possible to choose the empty dummy driver :command:`none`, if the user wants to include the KPP generated modules into a larger model (e.g. a general circulation or a chemical transport model) instead of creating a stand-alone version of the chemical integrator. The driver :command:`none` is also selected when the :command:`#DRIVER` command is missing. If the command occurs twice, the second replaces the first. .. _dummyindex-cmd: =========== #DUMMYINDEX =========== It is possible to declare species in the :ref:`defvar-and-deffix` sections that are not used in the :ref:`equations` section. If your model needs to check at run-time if a certain species is included in the current mechanism, you can set to :command:`#DUMMYINDEX ON`. Then, KPP will set the indices to zero for all species that do not occur in any reaction. With :command:`#DUMMYINDEX OFF` (the default), those are undefined variables. For example, if you frequently switch between mechanisms with and without sulfuric acid, you can use this code: .. code-block:: fortran IF (ind_H2SO4=0) THEN PRINT *, 'no H2SO4 in current mechanism' ELSE PRINT *, 'c(H2SO4) =', C(ind_H2SO4) ENDIF .. _eqntags-cmd: ======== #EQNTAGS ======== Each reaction in the :ref:`equations` section may start with an equation tag which is enclosed in angle brackets, e.g.: .. code-block:: console NO2 + hv = NO + O3P : 6.69e-1*(SUN/60.0); With :command:`#EQNTAGS` set to :command:`ON`, this equation tag can be used to refer to a specific equation (cf. :ref:`monitor`). The default for :command:`#EQNTAGS` is :command:`OFF`. .. _function-cmd: ========= #FUNCTION ========= The :command:`#FUNCTION` command controls which functions are generated to compute the production/destruction terms for variable species. :command:`AGGREGATE` generates one function that computes the normal derivatives. :command:`SPLIT` generates two functions for the derivatives in production and destruction forms. .. _graph-cmd: ====== #GRAPH ====== Off by default, the :command:`#GRAPH` command leverages the pre-existing parsing of stoichiometric structure to create graph-based representations of the chemical mechanism. :command:`#GRAPH` currently supports two options, described below. .. _graph-cmd-stoic: #GRAPH stoic ------------ This option generates two CSV files describing the structure of the mechanism based on stoichiometric balances and species composition. 1. :file:`ROOT_BiadjacencyMatrix.csv`: A sparse matrix of the the net stoichiometric coefficients for each species in each reaction. .. list-table:: Structure of :file:`ROOT_BiadjacencyMatrix.csv` :header-rows: 1 :widths: 10 30 60 * - Column - Header - Description * - 1 - spc_name - Species name. * - 2 - species_index - Number of the species in the chemical mechanism * - 3 - reaction_index - Number of the reaction in the chemical mechanism * - 4 - stoichiometric_coefficient - The the net, weighted biadjacency matrix of the bipartite species-reaction graph, useful for automated detection of system-wide stoichiometric invariants and other mass conservation enforcing :cite:`Sturm_and_Wexler_2022`. 2. :file:`ROOT_SpeciesCompositionMatrix.csv`: This is a species composition dense matrix that for each variable species (row), records the atom count of each element present (columns). .. list-table:: Structure of :file:`ROOT_SpeciesCompositionMatrix.csv` :header-rows: 1 :widths: 15 20 65 * - Column - Name - Description * - 1 - species_index - Number of the species in the chemical mechanism * - 2 - species_name - Species name. * - 3 - NSPEC - Species matrix - One column for each atom present in the mechanism (including IGNORE if used for some species). This matrix can be used for automated mass balance checking of mechanism output or individual reactions :cite:`Sturm_and_Silva_2025`. .. _graph-cmd-edgelist: #GRAPH edgelist --------------- The :ref:`graph-cmd-stoic` option uses net stoichiometry, which neglects reciprocal reactions (e.g. when the same species is a reactant and a product its net stoichiometry is zero). This :command:`#GRAPH edgelist` option generates a :file:`ROOT_Edgelist.csv` file listing the edges of the species-reaction bipartite graph. Each row represents a connection between a species and a reaction, with direction and stoichiometric value. .. list-table:: :header-rows: 1 :widths: 10 20 70 * - Column - Name - Description * - 1 - species_index - Species index (starts from 1) * - 2 - reaction_index - Reaction index (starts from 1) * - 3 - From - Starting edge * - 4 - To - Ending edge * - 5 - Stoichometric value - Directed stoichiometric value .. _hessian-cmd: ======== #HESSIAN ======== The option :command:`ON` (the default) of the :command:`#HESSIAN` command turns the Hessian generation on (see section :ref:`Hessian-and-HessianSP`). With :command:`OFF` it is switched off. .. _include-cmd: ======== #INCLUDE ======== The :command:`#INCLUDE` command instructs KPP to look for the file specified as a parameter and parse the content of this file before proceeding to the next line. This allows the atoms definition, the species definition and the equation definition to be shared between several models. Moreover this allows for custom configuration of KPP to accommodate various classes of users. Include files can be either in one of the KPP directories or in the current directory. .. _integrator-cmd: =========== #INTEGRATOR =========== The :command:`#INTEGRATOR` command selects the integrator definition file. The parameter is the file name of an integrator, without suffix. The effect of .. code-block:: console #INTEGRATOR integrator_name is similar to: .. code-block:: console #INCLUDE $KPP_HOME/int/integrator_name.def The :command:`#INTEGRATOR` command allows the use of different integration techniques on the same model. If it occurs twice, the second replaces the first. Normally, KPP tries to find the selected integrator files in the directory :file:`$KPP_HOME/int/`. However, if the supplied file name contains a slash, it is assumed to be absolute. To access an integrator in the current directory, the prefix :file:`./` can be used, e.g.: .. code-block:: console #INTEGRATOR ./mydeffile .. _intfile-cmd: ======== #INTFILE ======== .. attention:: :command:`#INTFILE` is used internally by KPP but should not be used by the KPP user. Using :ref:`integrator-cmd` alone suffices to specify an integrator. The integrator definition file selects an integrator file with :command:`#INTFILE` and also defines some suitable options for it. The :command:`#INTFILE` command selects the file that contains the integrator routine. The parameter of the command is a file name, without suffix. The appropriate suffix (:code:`.f90`, :code:`.F90`, :code:`.c`, or :code:`.m` is appended and the result selects the file from which the integrator is taken. This file will be copied into the code file in the appropriate place. .. _jacobian-cmd: ========= #JACOBIAN ========= The :command:`#JACOBIAN` command controls which functions are generated to compute the Jacobian. The option :command:`OFF` inhibits the generation of the Jacobian routine. The option :command:`FULL` generates the Jacobian as a square :code:`NVAR x NVAR` matrix. It should only be used if the integrator needs the whole Jacobians. The options :command:`SPARSE_ROW` and :command:`SPARSE_LU_ROW` (the default) both generate the Jacobian in sparse (compressed on rows) format. They should be used if the integrator needs the whole Jacobian, but in a sparse form. The format used is compressed on rows. With :command:`SPARSE_LU_ROW`, KPP extends the number of nonzeros to account for the fill-in due to the LU decomposition. .. _language-cmd: ========= #LANGUAGE ========= .. attention:: The :command:`Fortran77` language option is deprecated in :ref:`kpp250` and later versions. All further KPP development will only support Fortran90. The :command:`#LANGUAGE` command selects the target language in which the code file is to be generated. Available options are :command:`Fortran90`, :command:`C`, or :command:`matlab`. You can select the suffix (:code:`.F90` or :code:`.f90`) to use for Fortran90 source code generated by KPP (cf. :ref:`uppercasef90-cmd`). .. _mex-cmd: ==== #MEX ==== :program:`Mex` is a Matlab extension that allows to call functions written in Fortran and C directly from within the Matlab environment. KPP generates the mex interface routines for the ODE function, Jacobian, and Hessian, for the target languages C, Fortran77, and Fortran90. The default is :command:`#MEX ON`. With :command:`#MEX OFF`, no Mex files are generated. .. _minversion-cmd: =========== #MINVERSION =========== You may restrict a chemical mechanism to use a given version of KPP or later. To do this, add .. code-block:: console #MINVERSION X.Y.Z to the definition file. The version number (:code:`X.Y.Z`) adheres to the Semantic Versioning style (https://semver.org), where :code:`X` is the major version number, :code:`Y` is the minor version number, and :code:`Z` is the bugfix (aka “patch”) version number. For example, if :command:`#MINVERSION 2.4.0` is specified, then KPP will quit with an error message unless you are using KPP 2.4.0 or later. .. _model-cmd: ====== #MODEL ====== The chemical model contains the description of the atoms, species, and chemical equations. It also contains default initial values for the species and default options including a suitable integrator for the model. In the simplest case, the main kinetic description file, i.e. the one passed as parameter to KPP, can contain just a single line selecting the model. KPP tries to find a file with the name of the model and the suffix :file:`.def` in the :file:`$KPP_HOME/models` subdirectory. This file is then parsed. The content of the model definition file is written in the KPP language. The model definition file points to a species file and an equation file. The species file includes further the atom definition file. All default values regarding the model are automatically selected. For convenience, the best integrator and driver for the given model are also automatically selected. The :command:`#MODEL` command is optional, and intended for using a predefined model. Users who supply their own reaction mechanism do not need it. .. _reorder-cmd: ======== #REORDER ======== Reordering of the species is performed in order to minimize the fill-in during the LU factorization, and therefore preserve the sparsity structure and increase efficiency. The reordering is done using a diagonal Markowitz algorithm. The details are explained in :cite:t:`Sandu_et_al._1996`. The default is :command:`ON`. :command:`OFF` means that KPP does not reorder the species. The order of the variables is the order in which the species are declared in the :command:`#DEFVAR` section. .. _stochastic-cmd: =========== #STOCHASTIC =========== The option :command:`ON` of the :command:`#STOCHASTIC` command turns on the generation of code for stochastic kinetic simulations (see the section entitled :ref:`Stochastic`. The default option is :command:`OFF`. .. _stoicmat-cmd: ========= #STOICMAT ========= Unless the :command:`#STOICMAT` command is set to :command:`OFF`, KPP generates code for the stoichiometric matrix, the vector of reactant products in each reaction, and the partial derivative of the time derivative function with respect to rate coefficients (cf. :ref:`Stoichiom-and-StoichiomSP`). .. _checkall-lookatall-cmd: ===================== #CHECKALL, #LOOKATALL ===================== The shorthand commands :command:`#CHECKALL` and :command:`#LOOKATALL` apply :command:`#CHECK` and :command:`#LOOKAT`, respectively, to all species in the mechanism. .. _uppercasef90-cmd: ============= #UPPERCASEF90 ============= If you have selected :command:`#LANGUAGE Fortran90` option, KPP will generate source code ending in :code:`.f90` by default. Setting :command:`#UPPERCASEF90 ON` will tell KPP to generate Fortran90 code ending in :code:`.F90` instead.