k p p - peopleasandu/software/kpp/download/... · 2005. 7. 16. · k kpp-2.1 user’s manualp p the...

KPPKPP-2.1 User’s Manual

The Kinetic PreProcessor KPPAn Environment for the

Simulation of Chemical Kinetic Systems

Adrian Sandu† & Rolf Sander‡

† Department of Computer ScienceVirginia Polytechnic Institute and State University

Blacksburg, Virginia 24060, [email protected]

‡ Air Chemistry DepartmentMax-Planck Institute of Chemistry

PO Box 3060, 55020 Mainz, [email protected]

This manual is part of the electronic supplement of our article “Technical note: Simulating chemicalsystems in Fortran90 and Matlab with the Kinetic PreProcessor KPP-2.1” in Atmos. Chem. Phys.(2005), available at: http://www.atmos-chem-phys.org

Date: 2005/07/15

2 Sandu & Sander: KPP User Manual

Contents

1 Installation 4

2 Running KPP with an Example Strato-spheric Mechanism 4

3 Input for KPP 5

3.1 KPP sections . . . . . . . . . . . . . . . . . 5

3.1.1 Atom definitions (#ATOMS) . . . . . . 6

3.1.2 Mass balance checking (#CHECK) . . 6

3.1.3 Species definitions (#DEFVAR and#DEFFIX) . . . . . . . . . . . . . . . 6

3.1.4 Equations (#EQUATIONS) . . . . . . . 6

3.1.5 Initial values (#INITVALUES) . . . . 7

3.1.6 Output data selection (#LOOKAT and#MONITOR) . . . . . . . . . . . . . . . 7

3.1.7 Lump species definitions (#LUMP) . . 7

3.1.8 Redefining species definitions(#SETVAR and #SETFIX) . . . . . . . 7

3.1.9 Transport (#TRANSPORT) . . . . . . . 7

3.2 KPP commands . . . . . . . . . . . . . . . 8

3.2.1 Precision control (#DOUBLE) . . . . . 8

3.2.2 Driver selection (#DRIVER) . . . . . . 8

3.2.3 Dummy indices (#DUMMYINDEX) . . . 8

3.2.4 Generation of equation tags(#EQNTAGS) . . . . . . . . . . . . . . 8

3.2.5 The function generation (#FUNCTION) 8

3.2.6 Generation of Hessian (#HESSIAN) . 9

3.2.7 File include command (#INCLUDE) . 9

3.2.8 Integrator selection (#INTEGRATORand #INTFILE) . . . . . . . . . . . . 9

3.2.9 The Jacobian (#JACOBIAN) . . . . . 9

3.2.10 Target language selection(#LANGUAGE) . . . . . . . . . . . . . 9

3.2.11 Mex files (#MEX) . . . . . . . . . . . 9

3.2.12 Selcting a chemical model (#MODEL) 9

3.2.13 Reordering (#REORDER) . . . . . . . . 9

3.2.14 Stochastic simulation (#STOCHASTIC) 10

3.2.15 The Stoichiometric Formulation(#STOICMAT) . . . . . . . . . . . . . 10

3.2.16 Shorthand commands (#CHECKALL,#LOOKATALL and #TRANSPORTALL) . . 10

3.3 Inlined code . . . . . . . . . . . . . . . . . . 10

3.3.1 Inline type F90 DATA . . . . . . . . . 10

3.3.2 Inline type F90 GLOBAL . . . . . . . 10

3.3.3 Inline type F90 INIT . . . . . . . . . 10

3.3.4 Inline type F90 RATES . . . . . . . . 10

3.3.5 Inline type F90 RCONST . . . . . . . 10

3.3.6 Inline type F90 UTIL . . . . . . . . . 10

3.4 Auxiliary files and the substitution prepro-cessor . . . . . . . . . . . . . . . . . . . . . 10

4 Output from KPP 11

4.1 The Fortran90 Code . . . . . . . . . . . . . 11

4.1.1 root Main.f90 . . . . . . . . . . . 12

4.1.2 root Model.f90 . . . . . . . . . . . 13

4.1.3 root Initialize.f90 . . . . . . . 13

4.1.4 root Integrator.f90 . . . . . . . 13

4.1.5 root Monitor.f90 . . . . . . . . . 13

4.1.6 root Precision.f90 . . . . . . . . 13

4.1.7 root Rates.f90 . . . . . . . . . . . 14

4.1.8 root Parameters.f90 . . . . . . . 14

4.1.9 root Global.f90 . . . . . . . . . . 15

4.1.10 root Function.f90 . . . . . . . . . 15

4.1.11 root Jacobian.f90 androot JacobianSP.f90 . . . . . . . 15

4.1.12 root Hessian.f90 androot HessianSP.f90 . . . . . . . . 16

4.1.13 root LinearAlgebra.f90 . . . . . 16

4.1.14 root Stoichiom.f90 androot StoichiomSP.f90 . . . . . . . 17

4.1.15 root Stochastic.f90 . . . . . . . 18

4.1.16 root Util.f90 . . . . . . . . . . . 18

4.1.17 root mex Fun.f90,root mex Jac SP.f90, androot mex Hessian.f90 . . . . . . . 18

4.1.18 The Makefile . . . . . . . . . . . . . 18

4.2 The C Code . . . . . . . . . . . . . . . . . . 18

4.3 The Fortran77 Code . . . . . . . . . . . . . 19

4.4 The Matlab Code . . . . . . . . . . . . . . . 19

4.5 The map file . . . . . . . . . . . . . . . . . 20

5 KPP Internal Structure 20

5.1 KPP directory structure . . . . . . . . . . . 20

5.2 KPP environment variables . . . . . . . . . 21

5.3 KPP internal modules . . . . . . . . . . . . 21

5.3.1 Scanner and Parser . . . . . . . . . . 21

5.3.2 Species reordering . . . . . . . . . . 22

5.3.3 Expression trees computation . . . . 22

5.3.4 Code generation . . . . . . . . . . . 22

Sandu & Sander: KPP User Manual 3

6 Numerical methods 22

6.1 Rosenbrock Methods . . . . . . . . . . . . . 23

6.1.1 Tangent Linear Model . . . . . . . . 23

6.1.2 The Discrete Adjoint . . . . . . . . . 24

6.2 Runge-Kutta methods . . . . . . . . . . . . 24

6.2.1 Tangent Linear Model . . . . . . . . 25

6.2.2 Discrete Adjoint Model . . . . . . . 25

6.3 Backward Differentiation Formulas . . . . . 25

7 Differences between KPP-2.1 and PreviousVersions 26

7.1 New features of KPP-2.1 . . . . . . . . . . . 26

7.2 Upgrading KPP input files from previousversions to KPP-2.1 . . . . . . . . . . . . . 26

8 Acknowledgements 27

A BNF Description of the KPP Language 28


1 Installation

This section can be skipped if KPP is already installed onyour system. If you work under Linux, you can probablyuse the precompiled executable file that is in the bin di-rectory of the distribution. Then you only have to definethe $KPP_HOME environment variable.

1. Define the $KPP_HOME environment variable to pointto the complete path where KPP is installed. Also,add the path of the KPP executable to the $PATHenvironment variable. If, for example, KPP is in-stalled in $HOME/kpp, under the C shell you have toedit the file $HOME/.cshrc and add:

setenv KPP_HOME $HOME/kppsetenv PATH $PATH:$KPP_HOME/bin

If you use the bash shell, edit $HOME/.bashrc andadd:

export KPP_HOME=$HOME/kppexport PATH=$PATH:$KPP_HOME/bin

After editing .cshrc or .bashrc, start a new shell tomake sure these changes are in effect.

2. Make sure that sed is installed on your machine.Type “which sed” to test this.

3. Make sure that yacc is installed on your machine.Type “which yacc” to test this.

4. Make sure that the lexical analizer flex is installedon your machine. Type “flex --version” to testthis. Note down the exact path name where the flexlibrary is installed. The library is called: libfl.a orlibfl.sh.

5. Change to the KPP directory:

cd $KPP_HOME

6. To clean the KPP installation, delete the KPP ob-ject files and all the examples with:

make clean

To delete the KPP executable as well, type:

make distclean

7. Edit Makefile.defs and follow the instructions in-cluded to specify the compiler, the location of theflex library, etc.

8. Create the kpp executable with:

make

2 Running KPP with an ExampleStratospheric Mechanism

Here we consider as an example a very simple Chapman-like mechanism for stratospheric chemistry:

O2hν→ 2O (1)

O + O2 → O3 (2)

O3hν→ O + O2 (3)

O + O3 → 2O2 (4)

O3hν→ O(1D) + O2 (5)

O(1D) + M → O + M (6)O(1D) + O3 → 2O2 (7)

NO + O3 → NO2 + O2 (8)NO2 + O → NO + O2 (9)

NO2hν→ NO + O (10)

We use the mechanism with the purpose of illustrating theKPP capabilities. However, the software tools are generaland can be applied to virtually any kinetic mechanism.

We focus on Fortran90. Particularities of the C, For-tran77, and Matlab languages are discussed in Sec-tions 4.2, 4.3, 4.4, respectively.

The KPP input files (with suffix .kpp) specify the model,the target language, the precision, the integrator and thedriver, etc. The file name (without the suffix .kpp) servesas the root name for the simulation. In this paper we willrefer to this name as root. Since the root name will beincorporated into Fortran90 module names, it can onlycontain valid Fortran90 characters, i.e. letters, numbers,and the underscore. To specify a KPP model, write aroot.kpp file with the following lines:

#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 thecode generated by KPP) is selected with the command:

#LANGUAGE Fortran90

Here, we have chosen Fortran90. See Sect. 3.2.10 for otheroptions.

The data type of the generated model can be switched be-tween single/double precision with the command #DOUBLE.The #INTEGRATOR command selects a specific numerical


integration routine (from the templates provided by KPPor implemented by the user) and the #DRIVER commandselects a specific main program. The #MODEL commandselects a specific kinetic mechanism. In our examplethe model definition file small_strato.def includes thespecies and the equation files,

#INCLUDE small_strato.spc#INCLUDE small_strato.eqn

The species file lists all the species in the model. Some ofthem are variable (defined with #DEFVAR), meaning thattheir concentrations change according to the law of massaction kinetics. Others are fixed (defined with #DEFFIX),with the concentrations determined by physical and notchemical factors. For each species its atomic compositionis given (unless the user chooses to ignore it). The atomfile lists the periodic table of elements in an #ATOM section.The equation file contains the description of the equationsin an #EQUATIONS section.

#INCLUDE atoms#DEFVARO = O;O1D = O;O3 = O + O + O;NO = N + O;NO2 = N + O + O;

#DEFFIXM = IGNORE;O2 = O + O;

The chemical kinetic mechanism is specified in the KPPlanguage in the file small_strato.eqn. Each reaction isdescribed as “the sum of reactants equals the sum of prod-ucts” and is followed by its rate coefficient. SUN is the nor-malized sunlight intensity, equal to one at noon and zeroat night.

#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:

kpp small_strato.kpp

Next, compile and run the Fortran90 code:

make -fMakefile_small_strato./small_strato.exe

3 Input for KPP

KPP basically handles two types of files: Kinetic descrip-tion files and auxiliary files. Kinetic description files arein KPP syntax and described in the following sections.Auxiliary files are described in Sect. 3.4. KPP kinetic de-scription files specify the chemical equations, the initialvalues of each of the species involved, the integration pa-rameters, and many other options. The KPP preprocessorparses the kinetic description files and generates severaloutput files. Files that are written in KPP syntax haveone of the suffixes .kpp, .spc, .eqn, or .def. An exceptionis the file atoms, which has no suffix.

The following general rules define the structure of a kineticdescription file:

� A KPP program is composed of KPP sections, KPPcommands and inlined code. Their syntax is pre-sented in the appendix.

� Comments are either enclosed between the curlybraces “{” and “}”, or written in a line starting withtwo slashes “//”.

� Any name given by the user to denote an atom or aspecies is restricted to be less than 32 character inlength and can only contain letters, numbers, or theunderscore character. The first character cannot bea number. All names are case insensitive.

The kinetic description files contain a detailed specifica-tion of the chemical model, information about the integra-tion method and the desired type of results. KPP acceptsonly one of these files as input, but using the #INCLUDEcommand, code from separate files cn be combined. Theinclude files can be nested up to 10 levels. KPP will parsethese files as if they were a single big file. By carefullysplitting the chemical description, KPP can be configuredfor a broad range of users. In this way the users can havedirect access to that part of the model that they are in-terested in, and all the other details can be hidden insideseveral include files. Often, a file with atom definitionsis included first, then species definitions, and finally theequations of the chemical mechanism.

3.1 KPP sections

A # sign at the beginning of a line followed by a sectionname starts a new KPP section. Then a list of items sepa-rated by semicolons follows. A section ends when anotherKPP section or command occurs, i.e. when another # signoccurs at the beginning of a line. The syntax of an itemdefinition is different for each particular section. Table 1shows all the sections defined in the KPP language. Eachof them will be described separately in the following sub-sections.


Table 1: KPP sections

name see Sect.

#ATOMS 3.1.1#CHECK 3.1.2#DEFFIX 3.1.3#DEFVAR 3.1.3#EQUATIONS 3.1.4#INITVALUES 3.1.5#LOOKAT 3.1.6#LUMP 3.1.7#MONITOR 3.1.6#SETFIX 3.1.8#SETVAR 3.1.8#TRANSPORT 3.1.9

3.1.1 Atom definitions (#ATOMS)

The atoms that will be further used to specify the compo-nents of a species must be declared in an #ATOMS section,e.g.:

#ATOMS N; O; Na; Br;

Usually, the names of the atoms are the ones specified inthe periodic table of elements. For this table there is apredefined file containing all definitions that can be usedby the command:

#INCLUDE atoms

This should be the first line in a KPP input file, becauseit allows to use any atom in the periodic table of elementsthroughout the kinetic description file.

3.1.2 Mass balance checking (#CHECK)

KPP is able to do a mass balance checking for all equa-tions. Some chemical equations are not balanced for allatoms, and this might still be correct from a chemical pointof view. To accommodate for this, KPP can perform massbalance checking only for the list of atoms specified in the#CHECK section, e.g.:

#CHECK N; C; O;

The balance checking for all atoms can be enabled by usingthe #CHECKALL command. Without #CHECK or #CHECKALL,no checking is performed. The IGNORE atom can also beused to control mass balance checking.

3.1.3 Species definitions (#DEFVAR and #DEFFIX)

There are two ways to declare new species together withtheir atom composition: #DEFVAR and #DEFFIX. Thesesections define all the species that will be used in the chem-ical mechanism. Species can be variable or fixed. Thetype is implicitly specified by defining the species in theappropriate sections. A species can be considered fixedif its concentration does not vary too much. The vari-able species are medium or short lived species and theirconcentrations vary in time. This division of species intodifferent categories is helpful for integrators that benefitfrom treating them differently.

For each species the user has to declare the atom composi-tion. This information is used for mass balance checking.If the species is a lumped species without an exact com-position, it can be ignored. To do this one can declarethe predefined atom IGNORE as being part of the speciescomposition. Examples for these sections are:

#DEFVARNO2 = N + 2O;CH3OOH = C + 4H + 2O;HSO4m = IGNORE;RCHO = IGNORE;

#DEFFIXCO2 = C + 2O;

3.1.4 Equations (#EQUATIONS)

The chemical mechanism is specified in the #EQUATIONSsection. Each equation is written in the natural way inwhich a chemist would write it, e.g.:

#EQUATIONSNO2 + hv = NO + O : 0.533*SUN;OH + NO2 = HNO3 : k_3rd(temp,cair,2.E-30,3.,2.5E-11,0.,0.6);

Only the names of already defined species can be used.The rate coefficient has to be placed at the end of eachequation, separated by a colon. The rate coefficient doesnot necessarily need to be a numerical value. Instead,it can be a valid expression in the target language. Ifthere are several #EQUATIONS sections in the input, theircontents will be concatenated.

A minus sign in an equation shows that a secies is con-sumed in a reaction but it does not affect the reactionrate. For example, the oxidation of methane can be writ-ten as:

CH4 + OH = CH3OO + H2O - O2 : k_CH4_OH;

Often, the stoichiometric factors are integers. However, itis also possible to have non-integer yields, which is veryuseful to parameterize organic reactions that branch intoseveral side reactions:


CH4 + O1D = .75 CH3O2 + .75 OH + .25 HCHO+ .4 H + .05 H2 : k_CH4_O1D;

One restriction is that the list of products must not beempty. If you have such a reaction (e.g. the dry depositionof atmospheric species to the surface), you can define aDUMMY species as the product:

O3 = DUMMY : v_d_O3;

The same equation must not occur twice in the#EQUATIONS section. For example, you may have both thegas-phase reaction of N2O5 with water in your mechanismand also the heterogeneous reaction on aerosols:

N2O5 + H2O = 2 HNO3 : k_gas;N2O5 + H2O = 2 HNO3 : k_aerosol;

These reactions must be merged by adding the rate coef-ficients:

N2O5 + H2O = 2 HNO3 : k_gas+k_aerosol;

3.1.5 Initial values (#INITVALUES)

The initial concentration values for all species can be de-fined in the #INITVALUES section, e.g.:

#INITVALUESCFACTOR = 2.5E19;NO2 = 1.4E-9;CO2 = MyCO2Func();ALL_SPEC = 0.0;

If no value is specified for a particular species, the defaultvalue zero is used. One can set the default values usingthe generic species names: VAR_SPEC, FIX_SPEC, and ALL_SPEC. In order to use coherent units for concentration andrate coefficients, it is sometimes necessary to multiply eachvalue by a constant factor. This factor can be set by usingthe generic name CFACTOR. Each of the initial values willbe multiplied by this factor before being used. If CFACTORis omitted, it defaults to one.

The information gathered in this section is used to gener-ate the Initialize subroutine (see Sect. 4.1.3). In morecomplex 3D models, the initial values are usually takenfrom some input files or some global data structures. Inthis case, #INITVALUES may not be needed.

3.1.6 Output data selection (#LOOKAT and#MONITOR)

There are two sections in this category: #LOOKAT and#MONITOR.

The #LOOKAT section instructs the preprocessor what arethe species for which the evolution of the concentration,

should be saved in a data file. By default, if no #LOOKATsection is present, all the species are saved. If an atomis specified in the #LOOKAT list then the total mass of theparticular atom is reported. This allows to check how themass of a specific atom was conserved by the integrationmethod. The #LOOKATALL command can be used to specifyall the species. Output of #LOOKAT can be directed to thefile root.dat using the utility subroutines described inSect. 4.1.16.

The #MONITOR section defines a different list of species andatoms. This list is used by the driver to display the concen-tration of the elements in the list during the integration.This may give us a feedback of the evolution in time ofthe selected species during the integration. The syntax issimilar to the #LOOKAT section. With the driver general,output of #MONITOR goes to the screen (STDOUT). Theorder of the output is: first variable species, then fixesspecies, finally atoms. It is not the order in the #MONITORcommand.

Examples for these sections are:

#LOOKAT NO2; CO2; O3; N;#MONITOR O3; N;

3.1.7 Lump species definitions (#LUMP)

To reduce the stiffness of some models, various lumpingof species may be defined in the #LUMP section. The ex-ample below shows how the concentration of NO2 can bereplaced by the sum of concentrations for NO2 and NOwhich is considered to be a single variable. At the end ofthe integration, the concentration of NO2 is computed bysubstraction from the lumped variable.

#LUMP NO2 + NO : NO2

3.1.8 Redefining species definitions (#SETVAR and#SETFIX)

The commands #SETVAR and #SETFIX change the type ofan already defined species. Then, depending on the inte-gration method, one may or may not use the initial clas-sification, or can easily move one species from one cate-gory to another. The use of the generic species VAR_SPEC,FIX_SPEC, and ALL_SPEC is also allowed. Examples forthese sections are:

#SETVAR ALL_SPEC;#SETFIX H2O; CO2;

3.1.9 Transport (#TRANSPORT)

The #TRANSPORT section is only used for transport chem-istry models. It specifies the list of species that needs tobe included in the transport model, e.g.:


Table 2: KPP commands

name see Sect.

#CHECKALL 3.2.16#DOUBLE 3.2.1#DRIVER 3.2.2#DUMMYINDEX 3.2.3#EQNTAGS 3.2.4#FUNCTION 3.2.5#HESSIAN 3.2.6#INCLUDE 3.2.7#INTEGRATOR 3.2.8#INTFILE 3.2.8#JACOBIAN 3.2.9#LANGUAGE 3.2.10#LOOKATALL 3.2.16#MEX 3.2.11#MODEL 3.2.12#REORDER 3.2.13#STOCHASTIC 3.2.14#STOICMAT 3.2.15#TRANSPORTALL 3.2.16

#TRANSPORT NO2; CO2; O3; N;

One may use a more complex chemical model from whichonly a couple of species are considered for the transportcalculations. The #TRANSPORTALL command is also avail-able as a shorthand for specifying that all the species usedin the chemical model have to be included in the transportcalculations.

3.2 KPP commands

A command begins on a new line with a # sign, followedby a command name and one or more parameters. A sum-mary of the commands available in KPP is shown in Ta-ble 2. Details about each command are given in the fol-lowing subsections.

3.2.1 Precision control (#DOUBLE)

The #DOUBLE command selects single or double precisionarithmetique. ON (the default) means use double precision,OFF means use single precision (see Sect. 4.1.6).

3.2.2 Driver selection (#DRIVER)

The #DRIVER command selects the driver, i.e., the file fromwhich the main function is to be taken. The parameter isa file name, without suffix. The appropriate suffix (.f90,.f, .c, or .m) is automatically appended.

Normally, KPP tries to find the selected driver file in thedirectory $KPP_HOME/drv/. However, if the supplied filename contains a slash, it is assumed to be absolute. Toaccess a driver in the current directory, the prefix “./” canbe used, e.g.:

#DRIVER ./mydriver

It is possible to choose the empty dummy driver none,if the user wants to include the KPP generated modulesinto a larger model (e.g. a general circulation or a chemicaltransport model) instead of creating a stand-alone versionof the chemical integrator. The driver none is also selectedwhen the #DRIVER command is missing. If the #DRIVERcommand occurs twice, the second replaces the first.

3.2.3 Dummy indices (#DUMMYINDEX)

It is possible to declare species in the #SPECIES sectionthat are not used in the #EQUATIONS section. If your modelneeds to check at run-time if a certain species is includedin the current mechanism, you can set #DUMMYINDEX toON. Then, KPP will set the indices ind_spc to zerofor all species that do not occur in any reaction. With#DUMMYINDEX OFF (the default), those ind_spc are unde-fined variables. For example, if you frequently switch be-tween mechanisms with and without sulfuric acid, you canuse this code:

IF (ind_H2SO4=0) THENPRINT *, ’no H2SO4 in current mechanism’

ELSEPRINT *, ’c(H2SO4) =’, C(ind_H2SO4)

ENDIF

3.2.4 Generation of equation tags (#EQNTAGS)

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

<J1> NO2 + hv = NO + O : 0.533*SUN;

With #EQNTAGS set to ON, this equation tag can be usedto refer to a specific equation, as described in Sect. 4.1.5.The default for #EQNTAGS is OFF.

3.2.5 The function generation (#FUNCTION)

The #FUNCTION command controls which functions aregenerated to compute the production/destruction termsfor variable species. AGGREGATE generates one functionthat computes the normal derivatives. SPLIT generatestwo functions for the derivatives in production and de-struction forms.


3.2.6 Generation of Hessian (#HESSIAN)

The option ON (the default) of the #HESSIAN commandturns the Hessian generation on (see Sect. 4.1.12). WithOFF it is switched off.

3.2.7 File include command (#INCLUDE)

The #INCLUDE command instructs KPP to look for the filespecified as a parameter and parse the content of this filebefore proceeding to the next line. This allows the atomsdefinition, the species definition and even the equationdefinition to be shared between several models. Moreoverthis allows for custom configuration of KPP to accommo-date various classes of users. Include files can be either inone of the KPP directories or in the current directory.

3.2.8 Integrator selection (#INTEGRATOR and#INTFILE)

The #INTEGRATOR command selects the integrator defini-tion file. The parameter is the file name of an integrator,without suffix. The effect of:

#INTEGRATOR integrator

is similar to:

#INCLUDE $KPP_HOME/int/integrator.def

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 theintegrator routine. This command allows the use of differ-ent integration techniques on the same model. The param-eter of the command is a file name, without suffix. Theappropriate suffix (.f90, .f, .c, or .m) is appended and theresult selects the file from which the integrator is taken.This file will be copied into the code file in the appropri-ate place. All integrators have to conform to the samespecific calling sequence. Normally, KPP tries to find theselected integrator file in the directory $KPP_HOME/int/.However, if the supplied file name contains a slash, it isassumed to be absolute. To access an integrator in thecurrent directory, the prefix “./” can be used, e.g.:

#INTEGRATOR ./mydeffile#INTFILE ./myintegrator

If the #INTEGRATOR command occurs twice, the secondreplaces the first.

3.2.9 The Jacobian (#JACOBIAN)

The #JACOBIAN command controls which functions aregenerated to compute the Jacobian. The option OFF in-hibits the generation of the Jacobian routine. The optionFULL generates the Jacobian as a square (NVAR×NVAR) ma-trix. It should 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 (com-pressed on rows) format. They should be used if the inte-grator needs the whole Jacobian, but in a sparse form. Theformat used is compressed on rows. With SPARSE_LU_ROW,KPP extends the number of nonzeros to account for thefill-in due to the LU decomposition.

3.2.10 Target language selection (#LANGUAGE)

The #LANGUAGE command selects the target language inwhich the code file is to be generated. Available optionsare Fortran90, Fortran77, C, or Matlab.

3.2.11 Mex files (#MEX)

Mex is a matlab extension that allows to call functionswritten in Fortran and C directly from within the Matlabenvironment. KPP generates the mex interface routinesfor the ODE function, Jacobian, and Hessian, for the tar-get languages C, Fortran77, and Fortran90. The defaultis ON. With OFF, no Mex files are generated.

3.2.12 Selcting a chemical model (#MODEL)

The chemical model contains the description of the atoms,species, and chemical equations. It also contains defaultinitial values for the species and default options includingthe best integrator for the model. In the simplest case,the main kinetic description file, i.e. the one passed as pa-rameter to KPP, can contain just a single line selectingthe model. KPP tries to find a file with the name of themodel and the suffix .def in the $KPP_HOME/models subdi-rectory. This file is then parsed. The content of the modeldefinition file is written in the KPP language. The modeldefinition 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 automaticallyselected. For convenience, the best integrator and driverfor the given model are also automatically selected.

The #MODEL command is optional, and intended for usinga predefined model. Users who supply their own reactionmechanism do not need it.

3.2.13 Reordering (#REORDER)

Reordering of the species is performed in order to mini-mize the fill-in during the LU factorization, and thereforepreserve the sparsity structure and increase efficiency. Thereordering is done using a diagonal markowitz algorithm.The details are explained in Sandu et al. (1996). The de-fault is ON. OFF means that KPP does not reorder thespecies. The order of the variables is the order in whichthe species are declared in the #DEFVAR section.


3.2.14 Stochastic simulation (#STOCHASTIC)

The option ON of the #STOCHASTIC command turns on thegeneration of code for stochastic kinetic simulations (seeSect. 4.1.15). The default option is OFF.

3.2.15 The Stoichiometric Formulation(#STOICMAT)

Unless this command is set to OFF, KPP generates code forthe stoichiometric matrix, the vector of reactant productsin each reaction, and the partial derivative of the timederivative function with respect to rate coefficients. Theseelements are discussed in Sect. 4.1.14.

3.2.16 Shorthand commands (#CHECKALL,#LOOKATALL and #TRANSPORTALL)

KPP defines a couple of shorthand commands. Thecommands that fall into this category are #CHECKALL,#LOOKATALL and #TRANSPORTALL. All of them have beendescribed in the previous sections.

3.3 Inlined code

In order to offer maximum flexibility, KPP allows the userto include pieces of code in the kinetic description file.Inlined code begins on a new line with #INLINE and theinline type. Next, one or more lines of code follow, writtenin the target language (Fortran90, Fortran77, C, or Mat-lab) as specified by the inline type. The inlined code endswith #ENDINLINE. The code is inserted into the KPP out-put at a position which is also determined by inline typeas explained in Table 3. If two inline commands with thesame inline type are declared, then the contents of thesecond is appended to the first one. In this manual, weshow the inline types for Fortran90. The inline types forthe other languages are produced by replacing “F90_” by“F77_”, “C_”, or “MATLAB_”, respectively.

3.3.1 Inline type F90 DATA

This inline type was introduced in a previous version ofKPP to initialize variables. It is now obsolete but kept forcompatibility. For Fortran90, F90_GLOBAL should be usedinstead.

3.3.2 Inline type F90 GLOBAL

F90_GLOBAL can be used to declare global variables, e.g.for a special rate coefficient:

#INLINE F90_GLOBALREAL(dp) :: k_DMS_OH

#ENDINLINE

3.3.3 Inline type F90 INIT

F90_INIT can be used to define initial values before thestart of the integartion, e.g.:

#INLINE F90_INITTSTART = (12.*3600.)TEND = TSTART + (3.*24.*3600.)DT = 0.25*3600.TEMP = 270.

#ENDINLINE

3.3.4 Inline type F90 RATES

F90_RATES can be used to add new subroutines to calcu-late rate coefficients, e.g.:

#INLINE F90_RATESREAL FUNCTION k_SIV_H2O2(k_298,tdep,cHp,temp)! special rate function for S(IV) + H2O2REAL, INTENT(IN) :: k_298, tdep, cHp, tempk_SIV_H2O2 = k_298 &* EXP(tdep*(1./temp-3.3540E-3)) &* cHp / (cHp+0.1)

END FUNCTION k_SIV_H2O2#ENDINLINE

3.3.5 Inline type F90 RCONST

F90_RCONST can be used to define time-dependent valuesof rate coefficients that were declared with F90_GLOBAL:

#INLINE F90_RCONSTk_DMS_OH = 1.E-9*EXP(5820./temp)*C(ind_O2)/ &(1.E30+5.*EXP(6280./temp)*C(ind_O2))

#ENDINLINE

3.3.6 Inline type F90 UTIL

F90_UTIL can be used to define utility subroutines.

3.4 Auxiliary files and the substitutionpreprocessor

The auxiliary files (listed in Table 4) are templates for in-tegrators, drivers, and utilities. They are inserted into theKPP output after being run through the substitution pre-processor. This preprocessor replaces several placeholders(listed in Table 5) in the template files with their partic-ular values in the model at hand. Usually, only KPP_ROOTand KPP_REAL are needed because the other values canalso be obtained via the variables listed in Tab. 8.

KPP_REAL is replaced by the appropriate single or doubleprecision declaration type. Depending on the target lan-guage KPP will select the correct declaration type. For


Table 3: Inline types

inline type file placement usage

F90_DATA root_Monitor.f90 specification section (obsolete)F90_GLOBAL root_Global.f90 specification section global variablesF90_INIT root_Initialize.f90 subroutine Initialize integration parametersF90_RATES root_Rates.f90 executable section rate law functionsF90_RCONST root_Rates.f90 subroutine UPDATE_RCONST USE statements and definitions of rate coefficientsF90_UTIL root_Util.f90 executable section utility functions

Table 4: Auxiliary files (for Fortran90)

File Contents

dFun_dRcoeff.f90 derivatives with respect to reaction ratesdJac_dRcoeff.f90 derivatives with respect to reaction ratesMakefile.f90 unix makefilesMex_Fun.f90 mex filesMex_Jac_SP.f90 mex filesMex_Hessian.f90 mex filessutil.f90 Sparse utility functionstag2num.f90 Function related to equation tagsUpdateSun.f90 Function related to solar zenith angleUserRateLaws.f90 User-defined rate law functionsutil.f90 Input/output utilities

example if one needs to declare an array BIG of size 1000,a declaration like the following must be used:

KPP_REAL BIG(1000)

When used with the option #DOUBLE ON, the above linewill be automatically translated into:

REAL(dp) BIG(1000)

and when used with the option #DOUBLE OFF, the sameline will become:

REAL(sp) BIG(1000)

in the resulting Fortran90 output file.

KPP_ROOT is replaced by the root file name of the mainkinetic description file. In our example where we are pro-cessing small_strato.kpp, a line in an auxiliary Fortran90file like

USE KPP_ROOT_Monitor

will be translated into

USE small_strato_Monitor

in the generated Fortran90 output file.

4 Output from KPP

4.1 The Fortran90 Code

The code generated by KPP is organized in a set of sepa-rate files. Each has a time stamp and a complete descrip-tion of how it was generated at the begining of the file. Thefiles associated with root are named with a correspond-ing prefix “root_”. The list of files and a short descrip-tion is shown in Table 6. All subroutines and functions,global parameters, variables, and sparsity data structuresare encapsulated in modules. There is exactly one modulein each file, and the name of the module is identical tothe file name but without the suffix .f90. Fig. 1 showshow these modules are related to each other. A conciselist of the main subroutines generated by KPP is shownin Table 7. The generated code is consistent with the For-tran90 standard. It will not exceed the maximum numberof 39 continuation lines. If KPP cannot properly split anexpression to keep the number of continuation lines be-low the threshold then it will generate a warning messagepointing to the location of this expression.


Table 5: List of symbols replaced by the substitution preprocessor with their particular values for the simulation athand

Placeholder Replaced by Example

KPP_ROOT the root name small_stratoKPP_REAL the real data type REAL(kind=dp)KPP_NSPEC number of species 7KPP_NVAR number of variable species 5KPP_NFIX number of fixed species 2KPP_NREACT number of chemical reactions 10KPP_NONZERO number of Jacobian nonzero elements 18KPP_LU_NONZERO number of Jacobian nonzero elements, with LU fill-in 19KPP_NHESS number of Hessian nonzero elements 10

Table 6: List of model files generated by KPP (for Fortran90). Optional files are only produced under certaincircumstances, as specified in the third column.

File Description Only if. . . see Sect.

root_Main.f90 Driver #DRIVER 6= none 4.1.1

root_Function.f90 ODE function 4.1.10root_Global.f90 Global data headers 4.1.9root_Initialize.f90 Initialization 4.1.3root_Integrator.f90 Numerical integration 4.1.4root_LinearAlgebra.f90 Sparse linear algebra 4.1.13root_Model.f90 Summary of modules 4.1.2root_Monitor.f90 Equation info 4.1.5root_Parameters.f90 Model parameters 4.1.8root_Precision.f90 Parameterized types 4.1.6root_Rates.f90 User-defined rate laws 4.1.7root_Util.f90 Utility input-output 4.1.16

root_Jacobian.f90 ODE Jacobian 4.1.11root_JacobianSP.f90 Jacobian sparsity #JACOBIAN SPARSE_∗ 4.1.11

root_Hessian.f90 ODE Hessian #HESSIAN ON 4.1.12root_HessianSP.f90 Sparse Hessian data #HESSIAN ON and #JACOBIAN SPARSE_∗ 4.1.12

root_Stochastic.f90 Stochastic functions #STOCHASTIC ON 4.1.15

root_Stoichiom.f90 Stoichiometric model #STOICMAT ON 4.1.14root_StoichiomSP.f90 Stoichiometric matrix #STOICMAT ON and #JACOBIAN SPARSE_∗ 4.1.14

root_mex_Fun.f90 Matlab interface Fun #MEX ON 4.1.17root_mex_Jac_SP.f90 Matlab interface Jac #MEX ON and #JACOBIAN SPARSE_∗ 4.1.17root_mex_Hessian.f90 Matlab interface Hess #MEX ON and #HESSIAN ON 4.1.17

Makefile_root Makefile 4.1.18

root.map Human-readable info 4.5

4.1.1 root Main.f90

root_Main.f90 is the main Fortran90 program. It con-tains the driver after modifications by the substitution pre-

processor. The name of the file is computed by KPP byappending the suffix _Main.f90 to the root name.


Figure 1: Interdependencies of the KPP-generated files. Each arrow starts at the module that exports a variable orsubroutine and points to the module that imports it via the Fortran90 USE instruction. The prefix root has beenomitted from the module names for better readability. Dotted boxes show optional files that are only produced undercertain circumstances, as listed in Tab. 6.

4.1.2 root Model.f90

The file root Model.f90 completely defines the model byusing all the associated modules.

4.1.3 root Initialize.f90

The file root Initialize.f90 contains the subroutineInitialize which defines initial values of the chemicalspecies. The driver calls the subroutine Initialize oncebefore the time integration loop starts.

4.1.4 root Integrator.f90

The file root Integrator.f90 contains the subrou-tine INTEGRATE which is called every time step duringthe integration. The integrator that was chosen with#INTEGRATOR is also included in root Integrator.f90.

4.1.5 root Monitor.f90

The file root Monitor.f90 contains PARAMETER arrayswith information about the chemical mechanism. Thenames of all species are included in SPC_NAMES and thenames of all equations are included in EQN_NAMES.

It was shown above (Sect. 3.2.4) that each reaction in the#EQUATIONS section may start with an equation tag whichis enclosed in angle brackets, e.g.:

<J1> NO2 + hv = NO + O : 0.533*SUN;

If the equation tags are switched on, KPP also gener-ates the PARAMETER array EQN_TAGS. In combination withEQN_NAMES and the function tag2num that converts theequation tag to the KPP-internal equation number, thiscan be used to describe a reaction:

PRINT *,’Reaction J1 is:’, &EQN_NAMES(tag2num(’J1’))

4.1.6 root Precision.f90

Fortran90 code uses parameterized real types.root_Precision.f90 contains the following real kinddefinitions:

! KPP_SP - Single precision kindINTEGER, PARAMETER :: &SP = SELECTED_REAL_KIND(6,30)

! KPP_DP - Double precision kindINTEGER, PARAMETER :: &DP = SELECTED_REAL_KIND(12,300)


Table 7: List of selected Fortran90 subroutines generated by KPP

Subroutine Description File

Fun ODE function root_Function.f90

Jac_SP ODE Jacobian in sparse format root_Jacobian.f90Jac_SP_Vec sparse multiplication root_Jacobian.f90JacTR_SP_Vec sparse multiplication root_Jacobian.f90Jac ODE Jacobian in full format root_Jacobian.f90

Hessian ODE Hessian in sparse format root_Hessian.f90Hess_Vec Hessian action on vectors root_Hessian.f90HessTR_Vec Transposed Hessian action on vectors root_Hessian.f90

dFun_dRcoeff Derivatives of Fun with respect to rate coefficients root_Stoichiom.f90dJac_dRcoeff Derivatives of Jac with respect to rate coefficients root_Stoichiom.f90ReactantProd Reactant products root_Stoichiom.f90JacReactantProd Jacobian of reactant products root_Stoichiom.f90

KppDecomp Sparse LU decomposition root_LinearAlgebra.f90KppSolve Sparse back substitution root_LinearAlgebra.f90

Update_PHOTO Update photolysis rate coefficients root_Rates.f90Update_RCONST Update all rate coefficients root_Rates.f90Update_SUN Update solar intensity root_Rates.f90

Initialize Set initial values root_Initialize.f90

Integrate Integrate one time step root_Integrator.f90

GetMass Check mass balance for selected atoms root_Util.f90Shuffle_kpp2user Shuffle concentration vector root_Util.f90Shuffle_user2kpp Shuffle concentration vector root_Util.f90InitSaveData Utility for #LOOKAT command root_Util.f90SaveData Utility for #LOOKAT command root_Util.f90CloseSaveData Utility for #LOOKAT command root_Util.f90tag2num Calculate reaction number from equation tag root_Util.f90

Depending on the choice of the #DOUBLE command, thereal variables are of type double (REAL(kind=R_8)) or sin-gle precision (REAL(kind=R_4)). Changing the parame-ters of the SELECTED_REAL_KIND function in this modulewill cause a change in the working precision for the wholemodel.

4.1.7 root Rates.f90

The code to update the rate constants is inroot_Rates.f90. The user defined rate law functions arealso placed here.

4.1.8 root Parameters.f90

The global parameters (Table 8) are defined and initializedin root_Parameters.f90.

KPP orders the variable species such that the sparsitypattern of the Jacobian is maintained after an LU decom-position. For our small_strato example there are fivevariable species (NVAR=5) ordered as

ind_O1D=1, ind_O=2, ind_O3=3,ind_NO=4, ind_NO2=5

and two fixed species (NFIX=2)

ind_M = 6, ind_O2 = 7.

KPP defines a complete set of simulation parameters, in-cluding the numbers of variable and fixed species, the num-ber of chemical reactions, the number of nonzero entries inthe sparse Jacobian and in the sparse Hessian, etc. Someimportant simulation parameters generated by KPP arepresented in Table 8.


Table 8: List of important simulation parameters and theirvalues for the small strato example

Parameter Represents Value

NSPEC No. chemical species 7NVAR No. variable species 5NFIX No. fixed species 2NREACT No. reactions 10NONZERO No. nonzero entries Jacobian 18LU_NONZERO As above, after LU factorization 19NHESS Length, sparse Hessian 10NJVRP Length, sparse Jacobian JVRP 13NSTOICM Length, stoichiometric matrix 22ind_spc Index of species spc in C()indf_spc Index of fixed species spc in FIX()

Table 9: List of important global variables

Global variable Represents

C(NSPEC) Concentrations, all speciesVAR(NVAR) Concentrations, variable speciesFIX(NFIX) Concentrations, fixed speciesRCONST(NREACT) Rate coefficient valuesTIME Current integration timeSUN Sun intensity between 0 and 1TEMP TemperatureRTOLS Relative tolerance (scalar)TSTART,TEND Simulation start/end timeDT Simulation stepATOL(NSPEC) Absolute tolerancesRTOL(NSPEC) Relative tolerancesSTEPMIN Lower bound for time stepSTEPMAX Upper bound for time stepCFACTOR Conversion factorSPC_NAMES(NSPEC) Names of chemical speciesEQN_NAMES(NREACT) Names of chemical equations

4.1.9 root Global.f90

The global variables (Table 9) are declared inroot_Global.f90. Global variables are presentedin Table 9.

Both variable and fixed species are stored in the one-dimensional array C. The first part (indices from 1 toNVAR) contains the variable species, and the second part(indices from NVAR+1 to NSPEC) the fixed species. The to-tal number of species NSPEC is the sum of the NVAR andNFIX. The parts can also be accessed separately throughthe arrays VAR and FIX:

VAR(1:NVAR) = C(1:NVAR)FIX(1:NFIX) = C(NVAR+1:NSPEC)

4.1.10 root Function.f90

The code for the ODE function is in root_Function.f90.The chemical reaction mechanism represents a set of or-dinary differential equations (ODEs) of dimension NVAR.The concentrations of fixed species are parameters in thederivative function. The subroutine Fun computes firstthe vector A of reaction rates and then the vector Vdotof variable species time derivatives. The input argumentsV, F, and RCT are the concentrations of variable species,fixed species, and the rate coefficients, respectively. Be-low is the Fortran90 code generated by KPP for the ODEfunction of our small_strato example.

SUBROUTINE Fun (V, F, RCT, Vdot )REAL(kind=DP) :: V(NVAR), &

F(NFIX), RCT(NREACT), &Vdot(NVAR), A(NREACT) &

! Computation of equation ratesA(1) = RCT(1)*F(2)A(2) = RCT(2)*V(2)*F(2)A(3) = RCT(3)*V(3)A(4) = RCT(4)*V(2)*V(3)A(5) = RCT(5)*V(3)A(6) = RCT(6)*V(1)*F(1)A(7) = RCT(7)*V(1)*V(3)A(8) = RCT(8)*V(3)*V(4)A(9) = RCT(9)*V(2)*V(5)A(10) = RCT(10)*V(5)

! Aggregate functionVdot(1) = A(5)-A(6)-A(7)Vdot(2) = 2*A(1)-A(2)+A(3) &

-A(4)+A(6)-A(9)+A(10)Vdot(3) = A(2)-A(3)-A(4)-A(5) &

-A(7)-A(8)Vdot(4) = -A(8)+A(9)+A(10)Vdot(5) = A(8)-A(9)-A(10)

END SUBROUTINE Fun

4.1.11 root Jacobian.f90 androot JacobianSP.f90

The sparse data structures for the Jacobian are de-clared and initialized in root_JacobianSP.f90. The codefor the ODE Jacobian and sparse multiplications is inroot_Jacobian.f90. The Jacobian of the ODE func-tion is automatically constructed by KPP. KPP generatesthe Jacobian subroutine Jac or Jac_SP where the latter isgenerated when the sparse format is required. Using thevariable species V, the fixed species F, and the rate coeffi-cients RCT as input, the subroutine calculates the JacobianJVS. The default data structures for the sparse compressedon rows Jacobian representation are shown in Table 10(for the case where the LU fill-in is accounted for). JVSstores the LU_NONZERO elements of the Jacobian in roworder. Each row I starts at position LU_CROW(I), and


1 2 3 4 5

1

2

3

4

5

nz = 19

Jac = d f / d y

Figure 2: The sparsity pattern of the Jacobian for thesmall strato example.

Table 10: Sparse Jacobian Data Structures


JVS(LU_NONZERO) Jacobian nonzero elementsLU_IROW(LU_NONZERO) Row indicesLU_ICOL(LU_NONZERO) Column indicesLU_CROW(NVAR+1) Start of rowsLU_DIAG(NVAR+1) Diagonal entries

LU_CROW(NVAR+1)=LU_NONZERO+1. The location of the I-th diagonal element is LU_DIAG(I). The sparse elementJVS(K) is the Jacobian entry in row LU_IROW(K) and col-umn LU_ICOL(K). For the small_strato example KPPgenerates the following Jacobian sparse data structure:

LU_ICOL = (/ 1,3,1,2,3,5,1,2,3,4, &5,2,3,4,5,2,3,4,5 /)

LU_IROW = (/ 1,1,2,2,2,2,3,3,3,3, &3,4,4,4,4,5,5,5,5 /)

LU_CROW = (/ 1,3,7,12,16,20 /)LU_DIAG = (/ 1,4,9,14,19,20 /)

This is visualized in Fig. 2. The sparsity coordinate vec-tors are computed by KPP and initialized statically. Thesevectors are constant as the sparsity pattern of the Jaco-bian does not change during the computation.

Two other KPP-generated routines, Jac_SP_Vec andJacTR_SP_Vec are useful for direct and adjoint sensitivityanalysis. They perform sparse multiplication of JVS (orits transpose for JacTR_SP_Vec) with the user-suppliedvector UV without any indirect addressing.

Table 11: Sparse Hessian Data

Variable Represents

HESS(NHESS) Hessian nonzero elements Hi,j,k

IHESS_I(NHESS) Index i of element Hi,j,k

IHESS_J(NHESS) Index j of element Hi,j,k

IHESS_K(NHESS) Index k of element Hi,j,k

4.1.12 root Hessian.f90 and root HessianSP.f90

The sparse data structures for the Hessian are declaredand initialized in root_HessianSP.f90. The Hessianfunction and associated sparse multiplications are inroot_Hessian.f90. The Hessian contains the second or-der derivatives of the time derivative functions. More ex-actly, the Hessian is a 3-tensor such that

Hi,j,k =∂2(dc/dt)i

∂cj ∂ck, 1 ≤ i, j, k ≤ Nvar . (11)

KPP generates the routine Hessian. Using the variablespecies V, the fixed species F, and the rate coefficientsRCT as input, the subroutine calculates the Hessian. TheHessian is a very sparse tensor. The sparsity of the Hes-sian for our small_strato example is visualized in Fig. 3.KPP computes the number of nonzero Hessian entries andsaves it in the variable NHESS. The Hessian itself is rep-resented in coordinate sparse format. The real vectorHESS holds the values, and the integer vectors IHESS_I,IHESS_J, and IHESS_K hold the indices of nonzero en-tries as illustrated in Table 11. Since the time derivativefunction is smooth, these Hessian matrices are symmet-ric, HESSi,j,k=HESSi,k,j . KPP stores only those entriesHESSi,j,k with j ≤ k. The sparsity coordinate vectorsIHESS_I, IHESS_J, and IHESS_K are computed by KPPand initialized statically. They are constant as the spar-sity pattern of the Hessian does not change during thecomputation.

The routines Hess_Vec and HessTR_Vec compute the ac-tion of the Hessian (or its transpose) on a pair of user-supplied vectors U1 and U2. Sparse operations are em-ployed to produce the result vector.

4.1.13 root LinearAlgebra.f90

Sparse linear algebra routines are in the fileroot_LinearAlgebra.f90. To numerically solve forthe chemical concentrations one must employ an implicittimestepping technique, as the system is usually stiff.Implicit integrators solve systems of the form

P x = (I − hγJ) x = b (12)

where the matrix P = I − hγJ is refered to as the “pre-diction matrix”. I the identity matrix, h the integration


1 2 3 4 5

12345

nz = 2

d2 f1 / d y2

1 2 3 4 5

12345

nz = 4

d2 f2 / d y2

1 2 3 4 5

12345

nz = 6

d2 f3 / d y2

1 2 3 4 5

12345

nz = 4

d2 f4 / d y2

1 2 3 4 5

12345

nz = 4

d2 f5 / d y2

Figure 3: The Hessian of the small strato example.

time step, γ a scalar parameter depending on the method,and J the system Jacobian. The vector b is the systemright hand side and the solution x typically represents anincrement to update the solution.

The chemical Jacobians are typically sparse, i.e. only arelatively small number of entries are nonzero. The spar-sity structure of P is given by the sparsity structure of theJacobian, and is produced by KPP (with account for thefill-in) as discussed above.

KPP generates the sparse linear algebra subroutineKppDecomp which performs an in-place, non-pivoting,sparse LU decomposition of the prediction matrix P .Since the sparsity structure accounts for fill-in, all ele-ments of the full LU decomposition are actually stored.The output argument IER returns a value that is nonzeroif singularity is detected.

The subroutines KppSolve and KppSolveTR use the in-place LU factorization P as computed by KppDecomp andperform sparse backward and forward substitutions (usingP or its transpose). The sparse linear algebra routinesKppDecomp and KppSolve are extremely efficient, as shownby (Sandu et al., 1996).

4.1.14 root Stoichiom.f90 androot StoichiomSP.f90

These files contain a description of the chemi-cal mechanism in stoichiometric form. The fileroot_Stoichiom.f90 contains the functions for reactantproducts and its Jacobian, and derivatives with respectto rate coefficients. The declaration and initialization ofthe stoichiometric matrix and the associated sparse datastructures is done in root_StoichiomSP.f90.

The stoichiometric matrix is constant sparse. For ourexample the matrix has NSTOICM=22 nonzero entries outof 50 entries. KPP produces the stoichiometric matrixin sparse, column-compressed format, as shown in Table12. Elements are stored in columnwise order in the one-dimensional vector of values STOICM. Their row and col-umn indices are stored in IROW_STOICM and ICOL_STOICMrespectively. The vector CCOL_STOICM contains point-ers to the start of each column. For example column j

Table 12: Sparse Stoichiometric Matrix


STOICM(NSTOICM) Stoichiometric matrixIROW_STOICM(NSTOICM) Row indicesICOL_STOICM(NSTOICM) Column indicesCCOL_STOICM(NREACT+1) Start of columns

Table 13: Sparse Data for Jacobian of Reactant Products


JVRP(NJVRP) Nonzero elements of JVRPICOL_JVRP(NJVRP) Column indices in JVRPIROW_JVRP(NJVRP) Row indices in JVRPCROW_JVRP(NREACT+1) Start of rows in JVRP

starts in the sparse vector at position CCOL_STOICM(j)and ends at CCOL_STOICM(j+1)-1. The last value CCOL_STOICM(NVAR+1)=NSTOICM+1 simplifies the handling ofsparse data structures.

The subroutine ReactantProd computes the reactantproducts ARP for each reaction, and the subroutineJacReactantProd computes the Jacobian of reactantproducts vector, i.e.:

JVRP = ∂ARP/∂V (13)

The matrix JVRP is sparse and is computed and stored inrow compressed sparse format, as shown in Table 13. Theparameter NJVRP holds the number of nonzero elements.For our example:

NJVRP = 13CROW_JVRP = (/ 1,1,2,3,5,6,7,9,11,13,14 /)ICOL_JVRP = (/ 2,3,2,3,3,1,1,3,3,4,2,5,4 /)

If #STOICMAT is set to ON, the stoichiometric formulationallows a direct computation of the derivatives with respectto rate coefficients.


The subroutine dFun_dRcoeff computes the partialderivative DFDR of the ODE function with respect to asubset of NCOEFF reaction coefficients, whose indices arespecifies in the array JCOEFF

DFDR = ∂Vdot/∂RCT(JCOEFF) (14)

Similarly one can obtain the partial derivative of the Jaco-bian with respect to a subset of the rate coefficients. Moreexactly, KPP generates the subroutine dJac_dRcoeffwhich calculates DJDR, the product of this partial deriva-tive with a user-supplied vector:

DJDR = [∂JVS/∂RCT(JCOEFF)]× U (15)

4.1.15 root Stochastic.f90

If the generation of stochastic functions is switched on,KPP produces the file root_Stochastic.f90 with thefollowing functions:

Propensity calculates the propensity vector. The propen-sity function uses the number of molecules of variable(NmlcV) and fixed (NmlcF) species, as well as the stochas-tic rate coefficients (SCT) to calculate the vector of propen-sity rates (Propensity). The propensity Propj defines theprobability that the next reaction in the system is the jth

reaction.

StochasticRates converts deterministic rates to stochas-tic. The stochastic rate coefficients (SCT) are obtainedthrough a scaling of the deterministic rate coefficients(RCT). The scaling depends on the Volume of the reactioncontainer and on the number of molecules which react.

MoleculeChange calculates changes in the number ofmolecules. When the reaction with index IRCT takes place,the number of molecules of species involved in that reac-tion changes. The total number of molecules NmlcV isupdated by the function.

These functions are used by the Gillespie numerical in-tegrators (direct stochastic simulation algorithm). Theseintegrators are provided in both Fortran90 and C imple-mentations (the template file name is gillespie). Driversfor stochastic simulations are also implemented (the tem-plate file name is general_stochastic).

4.1.16 root Util.f90

The utility and input/output functions are inroot_Util.f90. In addition to the chemical systemdescription routines discussed above, KPP generatesseveral utility routines, some of which are summarized inTable 7.

The subroutines InitSaveData, SaveData, andCloseSaveData can be used to print the concentra-tion of the species that were selected with #LOOKAT to thefile root.dat.

4.1.17 root mex Fun.f90, root mex Jac SP.f90,and root mex Hessian.f90

Mex is a Matlab extension. KPP generates the mex rou-tines for the ODE function, Jacobian, and Hessian, forthe target languages C, Fortran77, and Fortran90. Aftercompilation (using Matlab’s mex compiler) the mex func-tions can be called instead of the corresponding Matlab m-functions. Since the calling syntaxes are identical, the useronly has to insert the mex string within the correspondingfunction name. Replacing m-functions by mex-functionsgives the same numerical results, but the computationaltime could be considerably smaller, especially for large ki-netic systems.

If possible we recommend to build mex files using the Clanguage, as Matlab offers most mex interface options forthe C language. Moreover, Matlab distributions comewith a native C compiler (lcc) for building executablefunctions from mex files. Fortran77 mex files work wellon most platforms without additional efforts. However,the mex files built using Fortran90 may require furtherplatform-specific tuning of the mex compiler options.

4.1.18 The Makefile

KPP produces a Makefile that allows for an easy compi-lation of all KPP-generated source files. The file name isMakefile_root. The Makefile assumes that the selecteddriver contains the main program. However, if no driverwas selected (i.e. #DRIVER none), it is necessary to addthe name of the main program file manually to the Make-file.

4.2 The C Code

The driver file root.c contains the main (driver) andnumerical integrator functions, as well as declarationsand initializations of global variables. The generated Ccode includes three header files which are #include-d inother files as appropriate. The global parameters (Table8) are #define-d in the header file root_Parameters.h.The global variables (Table 9) are extern-declared inroot_Global.h, and declared in the driver file root.c.The header file root_Sparse.h contains extern declara-tions of sparse data structures for the Jacobian (Table10), Hessian (Table 11), stoichiometric matrix (Table 12),and the Jacobian of reaction products (Table 13). Theactual declarations of each data structures is done in thecorresponding files.

The code for the ODE function (Sect. 4.1.10) is inroot_Function.c. The code for the ODE Jaco-bian and sparse multiplications (Sect. 4.1.11) is inroot_Jacobian.c, and the declaration and initializationof the Jacobian sparse data structures (Table 10) is inthe file root_JacobianSP.c. Similarly, the Hessian func-tion and associated sparse multiplications (Section 4.1.12)


are in root_Hessian.c, and the declaration and initial-ization of Hessian sparse data structures (Table 11) inroot_HessianSP.c.

The file root_Stoichiom.c contains the functions for re-actant products and its Jacobian, and derivatives with re-spect to rate coefficients (Sect. 4.1.14). The declarationand initialization of the stoichiometric matrix and the as-sociated sparse data structures (Tables 12 and 13) is donein root_StoichiomSP.c.

Sparse linear algebra routines (Sect. 4.1.13) are in thefile root_LinearAlgebra.c. The code to update therate constants and user defined code for rate laws is inroot_Rates.c.

Various utility and input/output functions (Sect. 4.1.16)are in root_Util.c and root_Monitor.c.

Finally, mex gateway routines that allow the C implemen-tation of the ODE function, Jacobian, and Hessian to becalled directly from Matlab (Sect. 4.1.17) are also gener-ated (in the files root_mex_Fun.c, root_mex_Jac_SP.c,and root_mex_Hessian.c).

4.3 The Fortran77 Code

The general layout of the Fortran77 code is similar to thelayout of the C code. The driver file root.f contains themain (driver) and numerical integrator functions.

The generated Fortran77 code includes three header files.The global parameters (Table 8) are defined as parametersand initialized in the header file root_Parameters.h. Theglobal variables (Table 9) are declared in root_Global.has common block variables. There are global commonblocks for real (GDATA), integer (INTGDATA), and charac-ter (CHARGDATA) global data. They can be accessed fromwithin each program unit that includes the global headerfile.

The header file root_Sparse.h contains common blockdeclarations of sparse data structures for the Jacobian(Table 10), Hessian (Table 11), stoichiometric matrix(Table 12), and the Jacobian of reaction products (Ta-ble 13). These sparse data structures are initialized infour named block data statements: JACOBIAN_SPARSE_DATA (in root_HessianSP.f), HESSIAN_SPARSE_DATA (inroot_HessianSP.f), JVRP_SPARSE_DATA and STOICM_MATRIX (in root_StoichiomSP.f).

The code for the ODE function (Sect. 4.1.10) is inroot_Function.f. The code for the ODE Jaco-bian and sparse multiplications (Sect. 4.1.11) is inroot_Jacobian.f. The Hessian function and as-sociated sparse multiplications (Sect. 4.1.12) are inroot_Hessian.f.

The file root_Stoichiom.f contains the functions for re-actant products and its Jacobian, and derivatives with re-spect to rate coefficients (Sect. 4.1.14). The declaration

and initialization of the stoichiometric matrix and the as-sociated sparse data structures (Tables 12 and 13) is donein the STOICM_MATRIX block data statement.

Sparse linear algebra routines (Sect. 4.1.13) are in the fileroot_LinearAlgebra.f. The code to update the rateconstants is in root_Rates.f, and the utility and in-put/output functions (Sect. 4.1.16) are in root_Util.fand root_Monitor.f.

Matlab-mex gateway routines for the ODE function, Ja-cobian, and Hessian are discussed in Sect. 4.1.17.

4.4 The Matlab Code

Matlab (http://www.mathworks.com/products/matlab/) provides a high-level programming envi-ronment that allows algorithm development, numericalcomputations, and data analysis and visualization. TheKPP-generated Matlab code allows for a rapid proto-typing of chemical kinetic schemes, and for a convenientanalysis and visualization of the results. Differencesbetween different kinetic mechanisms can be easily under-stood. The Matlab code can be used to derive referencenumerical solutions, which are then compared against theresults obtained with user-supplied numerical techniques.Last but not least Matlab is an excellent environment foreducational purposes. KPP/Matlab can be used to teachstudents fundamentals of chemical kinetics and chemicalnumerical simulations.

Each Matlab function has to reside in a separate m-file. Function calls use the m-function-file names to ref-erence the function. Consequently, KPP generates onem-function-file for each of the functions discussed in Sec-tions 4.1.10, 4.1.11, 4.1.12, 4.1.13, 4.1.14, and 4.1.16. Thenames of the m-function-files are the same as the namesof the functions (prefixed by the model name root).

The Matlab syntax for calling each function is

[Vdot] = Fun (V, F, RCT);[JVS ] = Jac_SP (V, F, RCT);[HESS] = Hessian(V, F, RCT);

The global parameters (Table 8) are defined asMatlab global variables and initialized in the fileroot_parameter_defs.m. The variables of Table 9are declared as Matlab global variables in the fileroot_Global_defs.m. They can be accessed from withineach Matlab function by using global declarations of thevariables of interest.

The sparse data structures for the Jacobian (Table 10),the Hessian (Table 11), the stoichiometric matrix (Ta-ble 12), and the Jacobian of reaction products (Table13) are declared as Matlab global variables in the fileroot_Sparse_defs.m. They are initialized in separatem-files, namely root_JacobianSP.m root_HessianSP.m,and root_StoichiomSP.m respectively.


Two wrappers (root_Fun_Chem.m and root_Jac_SP_Chem.m) are provided for interfacing the ODE function andthe sparse ODE Jacobian with Matlab’s suite of ODE in-tegrators. Specifically, the syntax of the wrapper callsmatches the syntax required by Matlab’s integrators likeode15s. Moreover, the Jacobian wrapper converts thesparse KPP format into a Matlab sparse matrix.

4.5 The map file

The map file root.map contains a summary of all the func-tions, subroutines and data structures defined in the codefile, plus a summary of the numbering and category of thespecies involved.

This file contains supplementary information for the user.Several statistics are listed here, like the total numberequations, the total number of species, the number of vari-able and fixed species. Each species from the chemicalmechanism is then listed followed by its type and number-ing.

Furthermore it contains the complete list of all the func-tions generated in the target source file. For each func-tion, a brief description of the computation performed isattached containing also the meaning of the input andoutput parameters.

5 KPP Internal Structure

This chapter is mainly concerned with describing the in-ternal architecture of the KPP preprocessor. It describesthe basic modules and their functionalities, and all thepreprocessing analysis performed on the input files. KPPcan be very easily configured to suit a broad class of users.

5.1 KPP directory structure

The KPP distribution will unfold a directory $KPP_HOMEwith the following subdirectories:

� src/ Contains the KPP source code files, as listedin Table 15.

� bin/ Contains the KPP executable. The path tothis directory needs to be added to the environmentPATH variable.

� util/ Contains different function templates usefulfor the simulation. Each template file has a suffixthat matches the appropriate target language (.f90,.f, .c, or .m). KPP will run the template files throughthe substitution preprocessor. The user can definetheir own auxiliary functions by inserting them intothe files.

Table 15: Source code files

File Description

kpp.c main program

code.c generic code generation functionscode.h header filecode_c.c generation of C codecode_f77.c generation of Fortran77 codecode_f90.c generation of Fortran90 codecode_matlab.c generation of matlab codedebug.c debugging outputgdata.h header filegdef.h header filegen.c generic code generation functionslex.yy.c flex/yacc-generated filescan.h input for flex/yaccscan.l input for flex/yaccscan.y input for flex/yaccscanner.c evaluate parsed inputscanutil.c evaluate parsed inputy.tab.c flex/yacc-generated filey.tab.h flex/yacc-generated header file

� models/ Contains the description of the chemicalmodels. Users can define their own models by plac-ing the model description files in this directory. TheKPP distribution contains several models from at-mospheric chemistry which can be used as templatesfor model definitions.

� drv/ Contains driver templates for chemical simula-tions. Each driver has a suffix that matches the ap-propriate target language (.f90, .f, .c, or .m). KPPwill run the appropriate driver through the substitu-tion preprocessor. The driver template general pro-vided with the distribution works with any example.Users can define here their own driver templates.

� int/ Contains numerical time stepping (integrator)routines. The command “#INTEGRATOR integrator”will force KPP to look into this directory for a defi-nition file integrator.def. This file selects the numer-ical routine (with the #INTFILE command) and setsthe function type, the Jacobian sparsity type, thetarget language, etc. Each integrator template isfound in a file that ends with the appropriate suffix(.f90, .f, .c, or .m). The selected template is pro-cessed by the substitution preprocessor. Users candefine here their own numerical integration routines.

� examples/ Contains several model description ex-amples (.kpp files) which can be used as templatesfor building simulations with KPP.


Table 14: List of Matlab model files

File Description

root.m driver

root_parameter_defs.m Global parametersroot_global_defs.m Global variablesroot_monitor_defs.m Global monitor variablesroot_sparse_defs.m Global sparsity data

root_Fun_Chem.m Template for ODE functionroot_Fun.m ODE function

root_Jac_Chem.m Template for ODE Jacobianroot_Jac_SP.m ODE Jacobian in sparse formatroot_JacobianSP.m Sparsity data structures

root_Hessian.m ODE Hessian in sparse formatroot_HessianSP.m Sparsity data structuresroot_HessTR_Vec.m Hessian action on vectorsroot_Hess_Vec.m Transposed Hessian action on vectors

root_stoichiom.m Derivatives of Fun and Jac with respect to rate coefficientsroot_StoichiomSP.m Sparse dataroot_ReactantProd.m Reactant productsroot_JacReactantProd.m Jacobian of reactant products

root_rates.m User-defined reaction rate lawsroot_Update_PHOTO.m Update photolysis rate coefficientsroot_Update_RCONST.m Update all rate coefficientsroot_Update_SUN.m Update solar intensity

root_GetMass.m Check mass balance for selected atomsroot_Initialize.m Set initial valuesroot_Shuffle_kpp2user.m Shuffle concentration vectorroot_Shuffle_user2kpp.m Shuffle concentration vector

� site-lisp/ Contains the file kpp.el which provides aKPP mode for emacs with color highlighting.

5.2 KPP environment variables

In order for KPP to find its components, it has to knowthe path to the location where the KPP distribution isinstalled. This is achieved by requiring the $KPP_HOMEenvironment variable to be set to the path where KPP isinstalled.

The PATH variable should be updated to contain the$KPP_HOME/bin directory.

There are several optional environment variable that con-trol the places where KPP looks for module files, integra-tors, and drivers. They are all summarized in Table 16.

5.3 KPP internal modules

5.3.1 Scanner and Parser

This module is responsible for reading the kinetic descrip-tion files and extracting the information necessary in thecode generation phase. We make use of the flex and yaccgeneric tools in implementing our own scanner and parser.Using these tools this module gathers information fromthe input files and fills in the following data structures inmemory:

� The atom list

� The species list

� The left hand side matrix of coefficients

� The right hand side matrix of coefficients

� The equation rates


Table 16: Environment variables used by KPP

Variable Description Default assumed

$KPP_HOME Required, stores the absolute path to the KPP distribution no default$KPP_MODEL Optional, specifies additional places were KPP will look for model

files before searching the default$KPP_HOME/models

$KPP_INT Optional, specifies additional places were KPP will look for inte-grator files before searching the default.

$KPP_HOME/int

$KPP_DRV Optional, specifies additional places were KPP will look for driverfiles before searching the default

$KPP_HOME/drv

� The option list

Error checking is performed at each step in the scannerand the parser. For each syntax error the exact line andinput file, along with an appropriate error message areproduced. In most of the cases the exact cause of theerror can be identified, therefore the error messages arevery precise. Some other errors like mass balance, andequation duplicates, are tested at the end of this phase.

5.3.2 Species reordering

When parsing the input files, the species list is updated assoon as a new species is encountered in a chemical equa-tion. Therefore the ordering of the species is the orderin which they appear in the equation description section.This is not a useful order for subsequent operations. Thespecies have to be first sorted such that all variable speciesand all fixed species are put together. Then if a sparsitystructure of the Jacobian is required, it might be better toreorder the species in such a way that the factorization ofthe Jacobian will preserve the sparsity. This reordering isdone using a Markovitz type of algorithm.

5.3.3 Expression trees computation

This is the core of the preprocessor. This module has togenerate the production/destruction functions the Jaco-bian and all the data structure nedeed by these functions.This module has to build a language independent struc-ture of each function and statement in the target sourcefile. Instead of using an intermediate format for this assome other compilers do, KPP generates the intermedi-ate format for just one statement at a time. The vastmajority of the statements in the target source file areassignments. The expression tree for each assignment isincrementally build by scanning the coefficient matricesand the rate constant vector. At the end these expres-sion trees are simplified. Similar approaches are appliedto function declaration and prototypes, data declarationand initialization.

5.3.4 Code generation

There are basically two modules, each dealing with thesyntax particularities of the target language. For exam-ple, the C module includes a function that generates avalid C assignment when given an expression tree. Sim-ilarly there are functions for data declaration, initializa-tions, comments, function prototypes, etc. Each of thesefunctions produce the code into an output buffer. A lan-guage specific routine reads from this buffer and splits thestatements into lines to improve readability of the gener-ated code.

6 Numerical methods

The KPP numerical library contains a set of numerical in-tegrators selected to be very efficient in the low to mediumaccuracy regime (relative errors ∼ 10−2 . . . 10−5). In ad-dition, the KPP numerical integrators preserve the linearinvariants (i.e., mass) of the chemical system.

KPP implements several Rosenbrock methods: Ros–1 andRos–2 (Verwer et al., 1999), Ros–3 (Sandu et al., 1997),Rodas–3 (Sandu et al., 1997), Ros–4 (Hairer and Wanner,1991), and Rodas–4 (Hairer and Wanner, 1991). For eachof them KPP implements the tangent linear model (directdecoupled sensitivity) and the adjoint models. The imple-mentations distinguish between sensitivities with respectto initial values and sensitivities with respect to parame-ters for efficiency.

Note that KPP produces the building blocks for the sim-ulation and also for the sensitivity calculations. It alsoprovides application programming templates. Some mini-mal programming may be required from the users in orderto construct their own application from the KPP buildingblocks.

In order to offer more control over the integrator, theKPP-generated subroutine INTEGRATE provides the op-tional input parameters ICNTRL_U and RCNTRL_U. Each ofthem is an array of 20 elements that allow the fine-tuningof the integrator, e.g. by setting a particular integratormethod, tolerances, minimum and maximum step sizes,


Table 17: Symbols used in the decription of the numerical methods implemented in KPP

Symbol Description

s Number of stagestn Discrete time momenth Time step h = tn+1 − tn

yn Numerical solution (concentration) at tn

δyn tangent linear solution at tn

λn Adjoint numerical solution at tn

f(·, ·) The ODE derivative function: y′ = f(t, y)ft(·, ·) Partial time derivative ft(t, y) = ∂f(t, y)/∂tJ(·, ·) The Jacobian J(t, y) = ∂f(t, y)/∂yJt(·, ·) Partial time derivative of Jacobian Jt(t, y) = ∂J(t, y)/∂t

A The system matrixH(·, ·) The Hessian H(t, y) = ∂2f(t, y)/∂y2

Ti Internal stage time moment for Runge Kutta and Rosenbrock methodsYi Internal stage solution for Runge Kutta and Rosenbrock methods

ki, ì, ui, vi Internal stage vectors for Runge Kutta and Rosenbrock methods, theirtangent linear and adjoint models

αi, αij , aij , bi, ci, cij , ei, mi Method coefficients

and more. The exact meaning of the elements dependson the integrator and may change in the future. Pleaseread the comment lines in the individual integrator files$KPP_HOME/int/*.f90.

Similarly, to obtain more information about the integra-tion, the subroutine INTEGRATE provides the optional out-put parameters ISTATUS_U and RSTATUS_U. They areboth arrays of 20 elements and contain the length ofthe last time step, the number of accepted and rejectedsteps, the number of miscellaneous function calls, andmore. Again, for the exact meaning, the reader is ref-ered to the comment lines in the individual integrator files$KPP_HOME/int/*.f90.

In the following sections we introduce the numerical meth-ods implemented in KPP. The symbols used in the formu-las are explained in Table 17.

6.1 Rosenbrock Methods

An s-stage Rosenbrock method (Hairer and Wanner, 1991,Section IV.7) computes the next-step solution by the for-mulas

yn+1 = yn +s∑

i=1

miki , Errn+1 =s∑

i=1

eiki (16)

Ti = tn + αih , Yi = yn +i−1∑j=1

aijkj ,

A =[

1hγ

− JT (tn, yn)]

A · ki = f ( Ti, Yi ) +i−1∑j=1

cij

hkj + hγift (tn, yn) .

where s is the number of stages, αi =∑

j αij and γi =∑j γij . The formula coefficients (aij and γij) give the or-

der of consistency and the stability properties. A is thesystem matrix (in the linear systems to be solved duringimplicit integration, or in the Newton’s method used tosolve the nonlinear systems). It is the scaled identity ma-trix minus the Jacobian.

The coefficients of the methods implemented in KPP areshown in Table 18.

6.1.1 Tangent Linear Model

The method (16) is combined with the sensitivity equa-tions. One step of the method reads

δyn+1 = δyn +s∑

i=1

miì (17)

Ti = tn + αih , δYi = δyn +i−1∑j=1

aij`j

A · ì = J ( Ti, Yi ) · δYi +i−1∑j=1

cij

h`j

+(H(tn, yn)× ki) · δyn + hγiJt (tn, yn) · δyn

The method requires a single n×n LU decomposition perstep to obtain both the concentrations and the sensitivi-ties.


Table 18: Rosenbrock methods implemented in KPP

Method Stages Function Order Stability Methodname (s) calls properties coefficients

Ros–2 2 2 2(1) L-stable γ = 1 + 1/√

2, a2,1 = 1/γ, c2,1 = −2/γ, m1 = 3/(2γ), m2 =1/(2γ), e1 = 1/(2γ), e2 = 1/(2γ), α1 = 0, α2 = 1, γ1 = γ,γ2 = −γ

Ros–3 3 2 3(2) L-stable a2,1 = 1, a3,1 = 1, a3,2 = 0, c2,1 = −1.015, c3,1 = 4.075,c3,2 = 9.207, m1 = 1, m2 = 6.169, m3 = −0.427, e1 = 0.5,e2 = −2.908, e3 = 0.223, α1 = 0, α2 = 0.436, α3 = 0.436,γ1 = 0.436, γ2 = 0.243, γ3 = 2.185

Ros–4 4 3 4(3) L-stable a2,1 = 2, a3,1 = 1.868, a3,2 = 0.234, a4,1 = a3,1, a4,2 = a3,2,a4,3 = 0, c2,1 = −7.137, c3,1 = 2.581, c3,2 = 0.652, c4,1 =−2.137, c4,2 = −0.321, c4,3 = −0.695, m1 = 2.256, m2 =0.287, m3 = 0.435, m4 = 1.094, e1 = −0.282, e2 = −0.073,e3 = −0.108, e4 = −1.093, α1 = 0, α2 = 1.146, α3 = 0.655,α4 = α3, γ1 = 0.573, γ2 = −1.769, γ3 = 0.759, γ4 = −0.104

Rodas–3 4 3 3(2) Stifflyaccurate

a2,1 = 0, a3,1 = 2, a3,2 = 0, a4,1 = 2, a4,2 = 0, a4,3 = 1,c2,1 = 4, c3,1 = 1, c3,2 = −1, c4,1 = 1, c4,2 = −1, c4,3 = −8/3,m1 = 2, m2 = 0, m3 = 1, m4 = 1, e1 = 0, e2 = 0, e3 = 0,e4 = 1, α1 = 0, α2 = 0, α3 = 1, α4 = 1, γ1 = 0.5, γ2 = 1.5,γ3 = 0, γ4 = 0

Rodas–4 6 5 4(3) Stifflyaccurate

α1 = 0, α2 = 0.386, α3 = 0.210, α4 = 0.630, α5 = 1, α6 = 1,γ1 = 0.25, γ2 = −0.104, γ3 = 0.104, γ4 = −0.036, γ5 = 0,γ6 = 0, a2,1 = 1.544, a3,1 = 0.946, a3,2 = 0.255, a4,1 = 3.314,a4,2 = 2.896, a4,3 = 0.998, a5,1 = 1.221, a5,2 = 6.019, a5,3 =12.537, a5,4 = −0.687, a6,1 = a5,1, a6,2 = a5,2, a6,3 = a5,3,a6,4 = a5,4, a6,5 = 1, c2,1 = −5.668, c3,1 = −2.430, c3,2 =−0.206, c4,1 = −0.107, c4,2 = −9.594, c4,3 = −20.47, c5,1 =7.496, c5,2 = −0.124, c5,3 = −34, c5,4 = 11.708, c6,1 = 8.083,c6,2 = −7.981, c6,3 = −31.521, c6,4 = 16.319, c6,5 = −6.058,m1 = a5,1, m2 = a5,2, m3 = a5,3, m4 = a5,4, m5 = 1, m6 = 1,e1 = 0, e2 = 0, e3 = 0, e4 = 0, e5 = 0, e6 = 1

KPP contains tangent linear models (for direct decou-pled sensitivity analysis) for each of the Rosenbrock meth-ods (Ros–1, Ros–2, Ros–3, Ros–4, Rodas–3, and Rodas–4). The implementations distinguish between sensitivitieswith respect to initial values and sensitivities with respectto parameters for efficiency.

6.1.2 The Discrete Adjoint

To obtain the adjoint we first differentiate the methodwith respect to yn. Here J denotes the Jacobian and Hthe Hessian of the derivative function f . The discreteadjoint of the (non-autonomous) Rosenbrock method is

A · ui = miλn+1 +

s∑j=i+1

(ajivj +

cji

huj

), (18)

vi = JT (Ti, Yi) · ui , i = s, s− 1, · · · , 1 ,

λn = λn+1 +s∑

i=1

(H(tn, yn)× ki)T · ui

+hJTt (tn, yn) ·

s∑i=1

γiui +s∑

i=1

vi

KPP contains adjoint models (for direct decoupled sensi-tivity analysis) for each of the Rosenbrock methods (Ros–1, Ros–2, Ros–3, Ros–4, Rodas–3, and Rodas–4).

6.2 Runge-Kutta methods

A general s-stage Runge-Kutta method is defined as(Hairer et al., 1993, Section II.1)

yn+1 = yn + hs∑

i=1

biki , (19)

Ti = tn + cih , Yi = yn + hs∑

j=1

aijkj ,


Table 19: Runge-Kutta methods implemented in KPP

Method File(s) Description

Radau5 atm radau5.f,kpp radau5.f90

This Runge Kutta method of order 5 based on Radau-IIA quadra-ture (Hairer and Wanner, 1991) is stiffly accurate. The KPP im-plementation follows the original implementation of Hairer andWanner (1991). While Radau5 is relatively expensive (when com-pared to the Rosenbrock methods), it is more robust and is usefulto obtain accurate reference solutions.

SDIRK4 kpp sdirk.f,kpp sdirk.f90

The implementation is based on the implementation of Hairer andWanner (1991). SDIRK4 is an L-stable, singly-diagonally-implicitRunge Kutta method of order 4.

SEULEX kpp seulex.f,kpp seulex.f90

SEULEX is a variable order stiff extrapolation code able to pro-duce highly accurate solutions. The KPP implementation is basedon the implementation of Hairer and Wanner (1991).

ki = f ( Ti, Yi ) ,

where the coefficients aij , bi and ci are prescribed forthe desired accuracy and stability properties. The stagederivative values ki are defined implicitly, and require solv-ing a (set of) nonlinear system(s). Newton-type methodssolve coupled linear systems of dimension (at most) n× s.

KPP numerical library implements a Radau5, a RungeKutta method of order 5 based on Radau-IIA quadrature(Hairer and Wanner, 1991, Section IV.10). This numeri-cal method is stiffly accurate. The KPP implementationfollows the original implementation of Hairer and Wanner(1991). While Radau5 is relatively expensive (when com-pared to the Rosenbrock methods), it is more robust andis useful to obtain highly accurate reference solutions.

The Runge-Kutta methods implemented in KPP are sum-marized in Table 19.

6.2.1 Tangent Linear Model

The tangent linear method associated with the RungeKutta method is

δyn+1 = δyn + hs∑

i=1

bi`i , (20)

δYi = δyn + hs∑

j=1

aij`j ,

`i = J (Ti, Yi) · δYi .

The system (20) is linear and does not require an iterativeprocedure. However, even for a SDIRK method (aij = 0for i > j and aii = γ) each stage requires the LU factor-ization of a different matrix.

No Runge Kutta tangent linear model is currently imple-mented in KPP.

6.2.2 Discrete Adjoint Model

The first order Runge-Kutta adjoint is

ui = h JT (Ti, Yi) ·

biλn+1 +

s∑j=1

ajiuj

(21)

λn = λn+1 +s∑

j=1

uj .

For bi 6= 0 the Runge-Kutta adjoint can be rewritten asanother Runge-Kutta method:

ui = h JT (Ti, Yi) ·

λn+1 +s∑

j=1

bj aji

biuj

(22)

λn = λn+1 +s∑

j=1

bj uj .

No Runge Kutta adjoint model is currently implementedin KPP.

6.3 Backward Differentiation Formulas

Backward differentiation formulas (BDF) are linear mul-tistep methods with excellent stability properties for theintegration of chemical systems (Hairer and Wanner, 1991,Section V.1). The k-step BDF method reads

k∑i=0

αiyn−i = hnβ f (tn, yn) (23)

where the coefficients αi and β are chosen such that themethod has order of consistency k.

The KPP library contains two off-the-shelf, highly popularimplementations of BDF methods, described in Table 20.


Table 20: BDF methods implemented in KPP

Method File(s) Description

LSODE kpp lsode.f90 LSODE, the Livermore ODE solver (Radhakrishnan and Hind-marsh, 1993), implements backward differentiation formula (BDF)methods for stiff problems. LSODE has been translated to For-tran90 for the incorporation into the KPP library.

LSODES atm lsodes.f LSODES (Radhakrishnan and Hindmarsh, 1993), the sparse ver-sion of the Livermore ODE solver LSODE, is modified to interfacedirectly with the KPP generated code

VODE kpp dvode.f VODE (Brown et al., 1989) uses another formulation of backwarddifferentiation formulas. The version of VODE present in the KPPlibrary uses directly the KPP sparse linear algebra routines.

ODESSA atm odessa.f The BDF-based direct-decoupled sensitivity integrator Odessa(Leis and Kramer, 1986) has been modified to use the KPP sparselinear algebra routines.

7 Differences between KPP-2.1and Previous Versions

7.1 New features of KPP-2.1

This user manual describes recently added features of KPPas well as those which have been available for a longer pe-riod. Here we give an overview about the recent changes:

� Fortran90 output has been available since thepreliminary version “1.1-f90-alpha12” provided inSander et al. (2005).

� Matlab is a new target language (see Sect. 4.4).

� The set of integrators has been extended with a gen-eral Rosenbrock integrator, and the correspondingtangent linear and adjoint methods.

� The KPP-generated Fortran90 code has a differentfile structure than the C or Fortran77 output (seeSects. 4.2 and 4.3).

� An automatically generated Makefile facilitatesthe compilation of the KPP-generated code (seeSect. 4.1.18).

� Equation tags provide a convenient way to refer tospecific chemical reactions (see Sect. 4.1.5).

� The dummy index allows to test if a certain speciesoccurs in the current chemistry mechanism. (seeSect. 3.2.3).

� Lines starting with “//” are comment lines.

7.2 Upgrading KPP input files from pre-vious versions to KPP-2.1

KPP users who want to upgrade from previous versions toKPP-2.1 need to make a few modifications to their inputfiles.

� To select the target language, change the previouscommand name “#USE” to “#LANGUAGE”.

� To access global variables, change “USE gdata” to“USE root_global”.

� Rename all inline types “*_DECL” and “*_DATA” to“*_GLOBAL”.

If you have already used the Fortran90 output of thepreliminary version “1.1-f90-alpha12” from Sander et al.(2005), these changes are also necessary:

� Change “#USE Fortran95” to “#LANGUAGEFortran90”.

� Change the names of the indices of the species from“kpp_*” to “ind_*”.

� Rename all inline types from “F95_*” to “F90_*”.

� Since the name of the initialization subroutine haschanged, replace

USE ROOT_Init, ONLY: initvalCALL initval

by

USE ROOT_Initialize, ONLY: initializeCALL initialize


8 Acknowledgements

Parts of this user manual are based on the thesis ofDamian-Iordache (1996).

References

Brown, P., Byrne, G., and Hindmarsh, A.: VODE: A Vari-able Step ODE Solver, SIAM J. Sci. Stat. Comput., 10,1038–1051, 1989.

Damian-Iordache, V.: KPP – Chemistry simulation de-velopment environment, Master’s thesis, University ofIowa, USA, 1996.

Hairer, E. and Wanner, G.: Solving Ordinary DifferentialEquations II. Stiff and Differential-Algebraic Problems.,Springer-Verlag, Berlin, 1991.

Hairer, E., Norsett, S., and Wanner, G.: Solving OrdinaryDifferential Equations I. Nonstiff Problems., Springer-Verlag, Berlin, 1993.

Leis, J. and Kramer, M.: ODESSA - An Ordinary Differ-ential Equation Solver with Explicit Simultaneous Sen-sitivity Analysis., ACM Transactions on MathematicalSoftware, 14, 61, 1986.

Radhakrishnan, K. and Hindmarsh, A.: Description anduse of LSODE, the Livermore solver for differentialequations, NASA reference publication 1327, 1993.

Sander, R., Kerkweg, A., Jockel, P., and Lelieveld, J.:Technical Note: The new comprehensive atmosphericchemistry module MECCA, Atmos. Chem. Phys., 5,445–450, 2005.

Sandu, A., Potra, F. A., Damian, V., and Carmichael,G. R.: Efficient implementation of fully implicit meth-ods for atmospheric chemistry, J. Comp. Phys., 129,101–110, 1996.

Sandu, A., Verwer, J. G., Blom, J. G., Spee, E. J.,Carmichael, G. R., and Potra, F. A.: Benchmarkingstiff ODE solvers for atmospheric chemistry problemsII: Rosenbrock solvers, Atmos. Environ., 31, 3459–3472,1997.

Verwer, J., Spee, E., Blom, J. G., and Hunsdorfer, W.:A second order Rosenbrock method applied to photo-chemical dispersion problems, SIAM Journal on Scien-tific Computing, 20, 1456–1480, 1999.

k p p - peopleasandu/software/kpp/download/... · 2005. 7. 16. · k kpp-2.1 user’s manualp p the...

Documents