KPP commands

A KPP command begins on a new line with a # sign, followed by a command name and one or more parameters. Details about each command are given in the following subsections.

Default values for KPP commands
KPP command	default value	KPP command	default value
#AUTOREDUCE	`OFF`	#CHECKALL
#DECLARE	`SYMBOL`	#DOUBLE	`ON`
#DRIVER	`none`	#DUMMYINDEX	`OFF`
#EQNTAGS	`OFF`	#FUNCTION	`AGGREGATE`
#GRAPH	`OFF`	#HESSIAN	`ON`
#INCLUDE		#INTEGRATOR
#INTFILE		#JACOBIAN	`SPARSE_LU_ROW`
#LANGUAGE		#LOOKATALL
#MEX	`ON`	#MINVERSION
#MODEL		#REORDER	`ON`
#STOCHASTIC	`OFF`	#STOICMAT	`ON`
#UPPERCASEF90	`OFF`

#AUTOREDUCE

The #AUTOREDUCE ON command can be used with #INTEGRATOR rosenbrock to enable automatic mechanism reduction as described in Lin et al. [2023]. Automatic mechanism reduction is disabled by default.

#DECLARE

The #DECLARE command determines how constants like dp, NSPEC, NVAR, NFIX, and NREACT are inserted into the KPP-generated code. #DECLARE SYMBOL (the default) will declare array variables using parameters from the ROOT_Parameters file. #DECLARE VALUE will replace each parameter with its value.

For example, the global array variable C is declared in the ROOT_Global file generated by KPP. In the small_strato example (described in Running KPP with an example stratospheric mechanism), C has dimension NSPEC=7. Using #DECLARE SYMBOL will generate the following code in ROOT_Global:

! C - Concentration of all species
  REAL(kind=dp), TARGET :: C(NSPEC)

Whereas #DECLARE VALUE will generate this code instead:

! C - Concentration of all species
  REAL(kind=dp), TARGET :: C(7)

We recommend using #DECLARE SYMBOL, as most modern compilers will automatically replace each parameter (e.g. NSPEC) with its value (e.g 7). However, if you are using a very old compiler that is not as sophisticated, #DECLARE VALUE might result in better-optmized code.

#DOUBLE

The #DOUBLE command selects single or double precision arithmetic. ON (the default) means use double precision, OFF means use single precision (see the section entitled ROOT_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

The #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 (.f90, .F90, .c, or .m) is automatically appended.

Normally, KPP tries to find the selected driver file in the directory $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 ./ can be used, e.g.:

#DRIVER ./mydriver

It is possible to choose the empty dummy driver 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 none is also selected when the #DRIVER command is missing. If the command occurs twice, the second replaces the first.

#DUMMYINDEX

It is possible to declare species in the #DEFVAR and #DEFFIX sections that are not used in the #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 #DUMMYINDEX ON. Then, KPP will set the indices to zero for all species that do not occur in any reaction. With #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:

IF (ind_H2SO4=0) THEN
  PRINT *, 'no H2SO4 in current mechanism'
ELSE
  PRINT *, 'c(H2SO4) =', C(ind_H2SO4)
ENDIF

#EQNTAGS

Each reaction in the #EQUATIONS section may start with an equation tag which is enclosed in angle brackets, e.g.:

<R1> NO2 + hv = NO + O3P :  6.69e-1*(SUN/60.0);

With #EQNTAGS set to ON, this equation tag can be used to refer to a specific equation (cf. ROOT_Monitor). The default for #EQNTAGS is OFF.

#FUNCTION

The #FUNCTION command controls which functions are generated to compute the production/destruction terms for variable species. AGGREGATE generates one function that computes the normal derivatives. SPLIT generates two functions for the derivatives in production and destruction forms.

#GRAPH

Off by default, the #GRAPH command leverages the pre-existing parsing of stoichiometric structure to create graph-based representations of the chemical mechanism. #GRAPH currently supports two options, described below.

#GRAPH stoic

This option generates two CSV files describing the structure of the mechanism based on stoichiometric balances and species composition.

ROOT_BiadjacencyMatrix.csv: A sparse matrix of the the net stoichiometric coefficients for each species in each reaction.

Structure of `ROOT_BiadjacencyMatrix.csv`
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 [Sturm and Wexler, 2022].

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).

Structure of `ROOT_SpeciesCompositionMatrix.csv`
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 [Sturm and Silva, 2025].

#GRAPH edgelist

The #GRAPH 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 #GRAPH edgelist option generates a 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.

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

The option ON (the default) of the #HESSIAN command turns the Hessian generation on (see section ROOT_Hessian and ROOT_HessianSP). With OFF it is switched off.

#INCLUDE

The #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

The #INTEGRATOR command selects the integrator definition file. The parameter is the file name of an integrator, without suffix. The effect of

#INTEGRATOR integrator_name

is similar to:

#INCLUDE $KPP_HOME/int/integrator_name.def

The #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 $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 ./ can be used, e.g.:

#INTEGRATOR ./mydeffile

#INTFILE

Attention

#INTFILE is used internally by KPP but should not be used by the KPP user. Using #INTEGRATOR alone suffices to specify an integrator.

The integrator definition file selects an integrator file with #INTFILE and also defines some suitable options for it. The #INTFILE command selects the file that contains the integrator routine. The parameter of the command is a file name, without suffix. The appropriate suffix (.f90, .F90, .c, or .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

The #JACOBIAN command controls which functions are generated to compute the Jacobian. The option OFF inhibits the generation of the Jacobian routine. The option FULL generates the Jacobian as a square NVAR x NVAR matrix. It should only be used if the integrator needs the whole Jacobians. The options SPARSE_ROW and 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 SPARSE_LU_ROW, KPP extends the number of nonzeros to account for the fill-in due to the LU decomposition.

#LANGUAGE

Attention

The Fortran77 language option is deprecated in KPP 2.5.0 and later versions. All further KPP development will only support Fortran90.

The #LANGUAGE command selects the target language in which the code file is to be generated. Available options are Fortran90, C, or matlab.

You can select the suffix (.F90 or .f90) to use for Fortran90 source code generated by KPP (cf. #UPPERCASEF90).

#MEX

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 #MEX ON. With #MEX OFF, no Mex files are generated.

#MINVERSION

You may restrict a chemical mechanism to use a given version of KPP or later. To do this, add

#MINVERSION X.Y.Z

to the definition file.

The version number (X.Y.Z) adheres to the Semantic Versioning style (https://semver.org), where X is the major version number, Y is the minor version number, and Z is the bugfix (aka “patch”) version number.

For example, if #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

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 .def in the $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 #MODEL command is optional, and intended for using a predefined model. Users who supply their own reaction mechanism do not need it.

#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 Sandu et al. [1996]. The default is ON. 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 #DEFVAR section.

#STOCHASTIC

The option ON of the #STOCHASTIC command turns on the generation of code for stochastic kinetic simulations (see the section entitled ROOT_Stochastic. The default option is OFF.

#STOICMAT

Unless the #STOICMAT command is set to 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. ROOT_Stoichiom and ROOT_StoichiomSP).

#CHECKALL, #LOOKATALL

The shorthand commands #CHECKALL and #LOOKATALL apply #CHECK and #LOOKAT, respectively, to all species in the mechanism.

#UPPERCASEF90

If you have selected #LANGUAGE Fortran90 option, KPP will generate source code ending in .f90 by default. Setting #UPPERCASEF90 ON will tell KPP to generate Fortran90 code ending in .F90 instead.