KPP
KPP-2.1 User’s Manual The Kinetic PreProcessor KPP An Environment for the Simulation of Chemical Kinetic Systems
Adrian Sandu† & Rolf Sander‡
† Department of Computer Science Virginia Polytechnic Institute and State University Blacksburg, Virginia 24060, USA [email protected]
‡ Air Chemistry Department Max-Planck Institute of Chemistry PO Box 3060, 55020 Mainz, Germany [email protected]
This manual is part of the electronic supplement of our article “Technical note: Simulating chemical systems 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 3.3.3 Inline type F90 INIT ...... 10 3.3.4 Inline type F90 RATES ...... 10 1 Installation 4 3.3.5 Inline type F90 RCONST ...... 10 2 Running KPP with an Example Strato- 3.3.6 Inline type F90 UTIL ...... 10 spheric Mechanism 4 3.4 Auxiliary files and the substitution prepro- cessor ...... 10 3 Input for KPP 5 3.1 KPP sections ...... 5 4 Output from KPP 11 3.1.1 Atom definitions (#ATOMS)...... 6 4.1 The Fortran90 Code ...... 11 3.1.2 Mass balance checking (#CHECK).. 6 4.1.1 root Main.f90 ...... 12 3.1.3 Species definitions (#DEFVAR and 4.1.2 root Model.f90 ...... 13 #DEFFIX)...... 6 4.1.3 root Initialize.f90 ...... 13 3.1.4 Equations (#EQUATIONS)...... 6 4.1.4 root Integrator.f90 ...... 13 3.1.5 Initial values (#INITVALUES).... 7 4.1.5 root Monitor.f90 ...... 13 3.1.6 Output data selection (#LOOKAT and 4.1.6 root Precision.f90 ...... 13 #MONITOR)...... 7 4.1.7 root Rates.f90 ...... 14 3.1.7 Lump species definitions (#LUMP).. 7 4.1.8 root Parameters.f90 ...... 14 3.1.8 Redefining species definitions 4.1.9 root Global.f90 ...... 15 (#SETVAR and #SETFIX)...... 7 4.1.10 root Function.f90 ...... 15 3.1.9 Transport (#TRANSPORT)...... 7 4.1.11 root Jacobian.f90 and 3.2 KPP commands ...... 8 root JacobianSP.f90 ...... 15 3.2.1 Precision control (#DOUBLE)..... 8 4.1.12 root Hessian.f90 and 3.2.2 Driver selection (#DRIVER)...... 8 root HessianSP.f90 ...... 16 3.2.3 Dummy indices (#DUMMYINDEX)... 8 4.1.13 root LinearAlgebra.f90 ..... 16 3.2.4 Generation of equation tags 4.1.14 root Stoichiom.f90 and (#EQNTAGS)...... 8 root StoichiomSP.f90 ...... 17 3.2.5 The function generation (#FUNCTION) 8 4.1.15 root Stochastic.f90 ...... 18 3.2.6 Generation of Hessian (#HESSIAN). 9 4.1.16 root Util.f90 ...... 18 3.2.7 File include command (#INCLUDE). 9 4.1.17 root mex Fun.f90, root mex Jac SP.f90, and 3.2.8 Integrator selection (#INTEGRATOR root mex Hessian.f90 ...... 18 and #INTFILE)...... 9 4.1.18 The Makefile ...... 18 3.2.9 The Jacobian (#JACOBIAN)..... 9 4.2 The C Code ...... 18 3.2.10 Target language selection (#LANGUAGE)...... 9 4.3 The Fortran77 Code ...... 19 3.2.11 Mex files (#MEX)...... 9 4.4 The Matlab Code ...... 19 3.2.12 Selcting a chemical model (#MODEL) 9 4.5 The map file ...... 20 3.2.13 Reordering (#REORDER)...... 9 5 KPP Internal Structure 20 3.2.14 Stochastic simulation (#STOCHASTIC) 10 5.1 KPP directory structure ...... 20 3.2.15 The Stoichiometric Formulation (#STOICMAT)...... 10 5.2 KPP environment variables ...... 21 3.2.16 Shorthand commands (#CHECKALL, 5.3 KPP internal modules ...... 21 #LOOKATALL and #TRANSPORTALL).. 10 5.3.1 Scanner and Parser ...... 21 3.3 Inlined code ...... 10 5.3.2 Species reordering ...... 22 3.3.1 Inline type F90 DATA ...... 10 5.3.3 Expression trees computation . . . . 22 3.3.2 Inline type F90 GLOBAL ...... 10 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 Previous Versions 26 7.1 New features of KPP-2.1 ...... 26 7.2 Upgrading KPP input files from previous versions to KPP-2.1 ...... 26
8 Acknowledgements 27
A BNF Description of the KPP Language 28 4 Sandu & Sander: KPP User Manual
1 Installation 2 Running KPP with an Example Stratospheric Mechanism This section can be skipped if KPP is already installed on your system. If you work under Linux, you can probably Here we consider as an example a very simple Chapman- use the precompiled executable file that is in the bin di- like mechanism for stratospheric chemistry: rectory of the distribution. Then you only have to define the $KPP_HOME environment variable. hν O2 → 2O (1) 1. Define the $KPP_HOME environment variable to point O + O2 → O3 (2) to the complete path where KPP is installed. Also, hν O3 → O + O2 (3) add the path of the KPP executable to the $PATH O + O → 2O (4) environment variable. If, for example, KPP is in- 3 2 hν 1 stalled in $HOME/kpp, under the C shell you have to O3 → O( D) + O2 (5) edit the file $HOME/.cshrc and add: O(1D) + M → O + M (6) O(1D) + O → 2O (7) setenv KPP_HOME $HOME/kpp 3 2 setenv PATH $PATH:$KPP_HOME/bin NO + O3 → NO2 + O2 (8) NO2 + O → NO + O2 (9) If you use the bash shell, edit $HOME/.bashrc and hν add: NO2 → NO + O (10) We use the mechanism with the purpose of illustrating the export KPP_HOME=$HOME/kpp KPP capabilities. However, the software tools are general export PATH=$PATH:$KPP_HOME/bin and can be applied to virtually any kinetic mechanism. After editing .cshrc or .bashrc, start a new shell to We focus on Fortran90. Particularities of the C, For- make sure these changes are in effect. tran77, and Matlab languages are discussed in Sec- tions 4.2, 4.3, 4.4, respectively. 2. Make sure that sed is installed on your machine. The KPP input files (with suffix . ) specify the model, Type “which sed” to test this. kpp the target language, the precision, the integrator and the 3. Make sure that yacc is installed on your machine. driver, etc. The file name (without the suffix .kpp) serves Type “which yacc” to test this. as the root name for the simulation. In this paper we will refer to this name as root. Since the root name will be 4. Make sure that the lexical analizer flex is installed incorporated into Fortran90 module names, it can only on your machine. Type “flex --version” to test contain valid Fortran90 characters, i.e. letters, numbers, this. Note down the exact path name where the flex and the underscore. To specify a KPP model, write a library is installed. The library is called: libfl.a or root.kpp file with the following lines: libfl.sh. 5. Change to the KPP directory: #MODEL small_strato #LANGUAGE Fortran90 cd $KPP_HOME #DOUBLE ON #INTEGRATOR rosenbrock 6. To clean the KPP installation, delete the KPP ob- #DRIVER general ject files and all the examples with: #JACOBIAN SPARSE_LU_ROW #HESSIAN ON make clean #STOICMAT ON
To delete the KPP executable as well, type: The target language Fortran90 (i.e. the language of the code generated by KPP) is selected with the command: make distclean #LANGUAGE Fortran90 7. Edit Makefile.defs and follow the instructions in- cluded to specify the compiler, the location of the Here, we have chosen Fortran90. See Sect. 3.2.10 for other flex library, etc. options. 8. Create the kpp executable with: The data type of the generated model can be switched be- tween single/double precision with the command #DOUBLE. make The #INTEGRATOR command selects a specific numerical Sandu & Sander: KPP User Manual 5 integration routine (from the templates provided by KPP 3 Input for KPP or implemented by the user) and the #DRIVER command selects a specific main program. The #MODEL command KPP basically handles two types of files: Kinetic descrip- selects a specific kinetic mechanism. In our example tion files and auxiliary files. Kinetic description files are the model definition file small_strato.def includes the in KPP syntax and described in the following sections. species and the equation files, Auxiliary files are described in Sect. 3.4. KPP kinetic de- scription files specify the chemical equations, the initial #INCLUDE small_strato.spc values of each of the species involved, the integration pa- #INCLUDE small_strato.eqn rameters, and many other options. The KPP preprocessor The species file lists all the species in the model. Some of parses the kinetic description files and generates several them are variable (defined with #DEFVAR), meaning that output files. Files that are written in KPP syntax have their concentrations change according to the law of mass one of the suffixes .kpp, .spc, .eqn, or .def. An exception action kinetics. Others are fixed (defined with #DEFFIX), is the file atoms, which has no suffix. with the concentrations determined by physical and not The following general rules define the structure of a kinetic chemical factors. For each species its atomic composition description file: is given (unless the user chooses to ignore it). The atom file lists the periodic table of elements in an #ATOM section. A KPP program is composed of KPP sections, KPP The equation file contains the description of the equations commands and inlined code. Their syntax is pre- in an #EQUATIONS section. sented in the appendix.
#INCLUDE atoms Comments are either enclosed between the curly #DEFVAR braces “{” and “}”, or written in a line starting with O = O; two slashes “//”. O1D = O; Any name given by the user to denote an atom or a O3 = O + O + O; species is restricted to be less than 32 character in NO = N + O; length and can only contain letters, numbers, or the NO2 = N + O + O; underscore character. The first character cannot be #DEFFIX a number. All names are case insensitive. M = IGNORE; O2 = O + O; The kinetic description files contain a detailed specifica- The chemical kinetic mechanism is specified in the KPP tion of the chemical model, information about the integra- language in the file small_strato.eqn. Each reaction is tion method and the desired type of results. KPP accepts described as “the sum of reactants equals the sum of prod- only one of these files as input, but using the #INCLUDE ucts” and is followed by its rate coefficient. SUN is the nor- command, code from separate files cn be combined. The malized sunlight intensity, equal to one at noon and zero include files can be nested up to 10 levels. KPP will parse at night. these files as if they were a single big file. By carefully splitting the chemical description, KPP can be configured #EQUATIONS { Stratospheric Mechanism } for a broad range of users. In this way the users can have
3.1.3 Species definitions (#DEFVAR and #DEFFIX) Table 1: KPP sections name see Sect. There are two ways to declare new species together with their atom composition: #DEFVAR and #DEFFIX. These #ATOMS 3.1.1 sections define all the species that will be used in the chem- #CHECK 3.1.2 ical mechanism. Species can be variable or fixed. The #DEFFIX 3.1.3 type is implicitly specified by defining the species in the #DEFVAR 3.1.3 appropriate sections. A species can be considered fixed #EQUATIONS 3.1.4 if its concentration does not vary too much. The vari- #INITVALUES 3.1.5 able species are medium or short lived species and their #LOOKAT 3.1.6 concentrations vary in time. This division of species into #LUMP 3.1.7 different categories is helpful for integrators that benefit #MONITOR 3.1.6 from treating them differently. #SETFIX 3.1.8 #SETVAR 3.1.8 For each species the user has to declare the atom composi- #TRANSPORT 3.1.9 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 declare the predefined atom IGNORE as being part of the species 3.1.1 Atom definitions (#ATOMS) composition. Examples for these sections are:
The atoms that will be further used to specify the compo- #DEFVAR nents of a species must be declared in an #ATOMS section, NO2 = N + 2O; e.g.: CH3OOH = C + 4H + 2O; HSO4m = IGNORE; RCHO = IGNORE; #ATOMS N; O; Na; Br; #DEFFIX CO2 = C + 2O; Usually, the names of the atoms are the ones specified in the periodic table of elements. For this table there is a predefined file containing all definitions that can be used 3.1.4 Equations (#EQUATIONS) by the command: The chemical mechanism is specified in the #EQUATIONS #INCLUDE atoms section. Each equation is written in the natural way in which a chemist would write it, e.g.: This should be the first line in a KPP input file, because it allows to use any atom in the periodic table of elements #EQUATIONS throughout the kinetic description file. NO2 + hv = NO + O : 0.533*SUN; OH + NO2 = HNO3 : k_3rd(temp, cair,2.E-30,3.,2.5E-11,0.,0.6); 3.1.2 Mass balance checking (#CHECK) Only the names of already defined species can be used. KPP is able to do a mass balance checking for all equa- The rate coefficient has to be placed at the end of each tions. Some chemical equations are not balanced for all equation, separated by a colon. The rate coefficient does atoms, and this might still be correct from a chemical point not necessarily need to be a numerical value. Instead, of view. To accommodate for this, KPP can perform mass it can be a valid expression in the target language. If balance checking only for the list of atoms specified in the there are several #EQUATIONS sections in the input, their #CHECK section, e.g.: contents will be concatenated. A minus sign in an equation shows that a secies is con- #CHECK N; C; O; sumed in a reaction but it does not affect the reaction rate. For example, the oxidation of methane can be writ- The balance checking for all atoms can be enabled by using ten as: the #CHECKALL command. Without #CHECK or #CHECKALL, no checking is performed. The IGNORE atom can also be CH4 + OH = CH3OO + H2O - O2 : k_CH4_OH; used to control mass balance checking. Often, the stoichiometric factors are integers. However, it is also possible to have non-integer yields, which is very useful to parameterize organic reactions that branch into several side reactions: Sandu & Sander: KPP User Manual 7
CH4 + O1D = .75 CH3O2 + .75 OH + .25 HCHO should be saved in a data file. By default, if no #LOOKAT + .4 H + .05 H2 : k_CH4_O1D; section is present, all the species are saved. If an atom is specified in the #LOOKAT list then the total mass of the One restriction is that the list of products must not be particular atom is reported. This allows to check how the empty. If you have such a reaction (e.g. the dry deposition mass of a specific atom was conserved by the integration of atmospheric species to the surface), you can define a method. The #LOOKATALL command can be used to specify DUMMY species as the product: all the species. Output of #LOOKAT can be directed to the file root.dat using the utility subroutines described in O3 = DUMMY : v_d_O3; Sect. 4.1.16. The #MONITOR section defines a different list of species and The same equation must not occur twice in the atoms. This list is used by the driver to display the concen- #EQUATIONS section. For example, you may have both the tration of the elements in the list during the integration. gas-phase reaction of N O with water in your mechanism 2 5 This may give us a feedback of the evolution in time of and also the heterogeneous reaction on aerosols: the selected species during the integration. The syntax is similar to the #LOOKAT section. With the driver general, N2O5 + H2O = 2 HNO3 : k_gas; output of #MONITOR goes to the screen (STDOUT). The N2O5 + H2O = 2 HNO3 : k_aerosol; order of the output is: first variable species, then fixes species, finally atoms. It is not the order in the These reactions must be merged by adding the rate coef- #MONITOR command. ficients: Examples for these sections are: N2O5 + H2O = 2 HNO3 : k_gas+k_aerosol; #LOOKAT NO2; CO2; O3; N; #MONITOR O3; N; 3.1.5 Initial values (#INITVALUES)
The initial concentration values for all species can be de- 3.1.7 Lump species definitions (#LUMP) fined in the #INITVALUES section, e.g.: To reduce the stiffness of some models, various lumping #INITVALUES of species may be defined in the #LUMP section. The ex- CFACTOR = 2.5E19; ample below shows how the concentration of NO2 can be NO2 = 1.4E-9; replaced by the sum of concentrations for NO2 and NO CO2 = MyCO2Func(); which is considered to be a single variable. At the end of ALL_SPEC = 0.0; the integration, the concentration of NO2 is computed by substraction from the lumped variable. If no value is specified for a particular species, the default value zero is used. One can set the default values using #LUMP NO2 + NO : NO2 the generic species names: VAR_SPEC, FIX_SPEC, and ALL_ SPEC. In order to use coherent units for concentration and rate coefficients, it is sometimes necessary to multiply each 3.1.8 Redefining species definitions (#SETVAR and value by a constant factor. This factor can be set by using #SETFIX) the generic name CFACTOR. Each of the initial values will The commands #SETVAR and #SETFIX change the type of be multiplied by this factor before being used. If CFACTOR an already defined species. Then, depending on the inte- is omitted, it defaults to one. gration method, one may or may not use the initial clas- The information gathered in this section is used to gener- sification, or can easily move one species from one cate- ate the Initialize subroutine (see Sect. 4.1.3). In more gory to another. The use of the generic species VAR_SPEC, complex 3D models, the initial values are usually taken FIX_SPEC, and ALL_SPEC is also allowed. Examples for from some input files or some global data structures. In these sections are: this case, #INITVALUES may not be needed. #SETVAR ALL_SPEC; 3.1.6 Output data selection (#LOOKAT and #SETFIX H2O; CO2; #MONITOR) 3.1.9 Transport (#TRANSPORT) There are two sections in this category: #LOOKAT and #MONITOR. The #TRANSPORT section is only used for transport chem- The #LOOKAT section instructs the preprocessor what are istry models. It specifies the list of species that needs to the species for which the evolution of the concentration, be included in the transport model, e.g.: 8 Sandu & Sander: KPP User Manual
Normally, KPP tries to find the selected driver file in the Table 2: KPP commands directory $KPP_HOME/drv/. However, if the supplied file name see Sect. name contains a slash, it is assumed to be absolute. To #CHECKALL 3.2.16 access a driver in the current directory, the prefix “./” can #DOUBLE 3.2.1 be used, e.g.: #DRIVER 3.2.2 #DUMMYINDEX 3.2.3 #DRIVER ./mydriver #EQNTAGS 3.2.4 #FUNCTION 3.2.5 It is possible to choose the empty dummy driver none, #HESSIAN 3.2.6 if the user wants to include the KPP generated modules #INCLUDE 3.2.7 into a larger model (e.g. a general circulation or a chemical #INTEGRATOR 3.2.8 transport model) instead of creating a stand-alone version #INTFILE 3.2.8 of the chemical integrator. The driver none is also selected #JACOBIAN 3.2.9 when the #DRIVER command is missing. If the #DRIVER #LANGUAGE 3.2.10 command occurs twice, the second replaces the first. #LOOKATALL 3.2.16 #MEX 3.2.11 3.2.3 Dummy indices (#DUMMYINDEX) #MODEL 3.2.12 #REORDER 3.2.13 It is possible to declare species in the #SPECIES section #STOCHASTIC 3.2.14 that are not used in the #EQUATIONS section. If your model #STOICMAT 3.2.15 needs to check at run-time if a certain species is included #TRANSPORTALL 3.2.16 in the current mechanism, you can set #DUMMYINDEX to ON. Then, KPP will set the indices ind_spc to zero for all species that do not occur in any reaction. With #DUMMYINDEX OFF (the default), those ind_spc are unde- #TRANSPORT NO2; CO2; O3; N; fined variables. For example, if you frequently switch be- tween mechanisms with and without sulfuric acid, you can One may use a more complex chemical model from which use this code: only a couple of species are considered for the transport calculations. The #TRANSPORTALL command is also avail- IF (ind_H2SO4=0) THEN able as a shorthand for specifying that all the species used PRINT *, ’no H2SO4 in current mechanism’ in the chemical model have to be included in the transport ELSE calculations. PRINT *, ’c(H2SO4) =’, C(ind_H2SO4) ENDIF 3.2 KPP commands 3.2.4 Generation of equation tags (#EQNTAGS) A command begins on a new line with a # sign, followed by a command name and one or more parameters. A sum- Each reaction in the #EQUATIONS section may start with mary of the commands available in KPP is shown in Ta- an equation tag which is enclosed in angle brackets, e.g.: ble 2. Details about each command are given in the fol- lowing subsections.
With #EQNTAGS set to ON, this equation tag can be used 3.2.1 Precision control (#DOUBLE) to refer to a specific equation, as described in Sect. 4.1.5. The default for #EQNTAGS is OFF. The #DOUBLE command selects single or double precision arithmetique. ON (the default) means use double precision, OFF means use single precision (see Sect. 4.1.6). 3.2.5 The function generation (#FUNCTION)
The #FUNCTION command controls which functions are 3.2.2 Driver selection (#DRIVER) generated to compute the production/destruction terms for variable species. AGGREGATE generates one function The #DRIVER command selects the driver, i.e., the file from that computes the normal derivatives. SPLIT generates which the main function is to be taken. The parameter is two functions for the derivatives in production and de- a file name, without suffix. The appropriate suffix (. , f90 struction forms. .f, .c, or .m) is automatically appended. Sandu & Sander: KPP User Manual 9
3.2.6 Generation of Hessian (#HESSIAN) Jacobians. The options SPARSE_ROW and SPARSE_LU_ROW (the default) both generate the Jacobian in sparse (com- The option ON (the default) of the #HESSIAN command pressed on rows) format. They should be used if the inte- turns the Hessian generation on (see Sect. 4.1.12). With grator needs the whole Jacobian, but in a sparse form. The OFF it is switched off. format used is compressed on rows. With SPARSE_LU_ROW, KPP extends the number of nonzeros to account for the 3.2.7 File include command (#INCLUDE) fill-in due to the LU decomposition.
The #INCLUDE command instructs KPP to look for the file 3.2.10 Target language selection (#LANGUAGE) specified as a parameter and parse the content of this file before proceeding to the next line. This allows the atoms The #LANGUAGE command selects the target language in definition, the species definition and even the equation which the code file is to be generated. Available options definition to be shared between several models. Moreover are Fortran90, Fortran77, C, or Matlab. this allows for custom configuration of KPP to accommo- date various classes of users. Include files can be either in one of the KPP directories or in the current directory. 3.2.11 Mex files (#MEX) Mex is a matlab extension that allows to call functions 3.2.8 Integrator selection (#INTEGRATOR and written in Fortran and C directly from within the Matlab #INTFILE) environment. KPP generates the mex interface routines for the ODE function, Jacobian, and Hessian, for the tar- The #INTEGRATOR command selects the integrator defini- get languages C, Fortran77, and Fortran90. The default tion file. The parameter is the file name of an integrator, is ON. With OFF, no Mex files are generated. without suffix. The effect of: #INTEGRATOR integrator 3.2.12 Selcting a chemical model (#MODEL) is similar to: #INCLUDE $KPP_HOME/int/integrator.def The chemical model contains the description of the atoms, species, and chemical equations. It also contains default The integrator definition file selects an integrator file with initial values for the species and default options including #INTFILE and also defines some suitable options for it. the best integrator for the model. In the simplest case, The #INTFILE command selects the file that contains the the main kinetic description file, i.e. the one passed as pa- integrator routine. This command allows the use of differ- rameter to KPP, can contain just a single line selecting ent integration techniques on the same model. The param- the model. KPP tries to find a file with the name of the eter of the command is a file name, without suffix. The model and the suffix .def in the $KPP_HOME/models subdi- appropriate suffix (.f90, .f, .c, or .m) is appended and the rectory. This file is then parsed. The content of the model result selects the file from which the integrator is taken. definition file is written in the KPP language. The model This file will be copied into the code file in the appropri- definition file points to a species file and an equation file. ate place. All integrators have to conform to the same The species file includes further the atom definition file. specific calling sequence. Normally, KPP tries to find the All default values regarding the model are automatically selected integrator file in the directory $KPP_HOME/int/. selected. For convenience, the best integrator and driver However, if the supplied file name contains a slash, it is for the given model are also automatically selected. assumed to be absolute. To access an integrator in the current directory, the prefix “./” can be used, e.g.: The #MODEL command is optional, and intended for using a predefined model. Users who supply their own reaction #INTEGRATOR ./mydeffile mechanism do not need it. #INTFILE ./myintegrator 3.2.13 Reordering (#REORDER) If the #INTEGRATOR command occurs twice, the second replaces the first. Reordering of the species is performed in order to mini- mize the fill-in during the LU factorization, and therefore 3.2.9 The Jacobian (#JACOBIAN) preserve the sparsity structure and increase efficiency. The reordering is done using a diagonal markowitz algorithm. The #JACOBIAN command controls which functions are The details are explained in Sandu et al. (1996). The de- generated to compute the Jacobian. The option OFF in- fault is ON. OFF means that KPP does not reorder the hibits the generation of the Jacobian routine. The option species. The order of the variables is the order in which FULL generates the Jacobian as a square (NVAR×NVAR) ma- the species are declared in the #DEFVAR section. trix. It should be used if the integrator needs the whole 10 Sandu & Sander: KPP User Manual
3.2.14 Stochastic simulation (#STOCHASTIC) 3.3.3 Inline type F90 INIT
The option ON of the #STOCHASTIC command turns on the F90_INIT can be used to define initial values before the generation of code for stochastic kinetic simulations (see start of the integartion, e.g.: Sect. 4.1.15). The default option is OFF. #INLINE F90_INIT TSTART = (12.*3600.) 3.2.15 The Stoichiometric Formulation TEND = TSTART + (3.*24.*3600.) (#STOICMAT) DT = 0.25*3600. TEMP = 270. Unless this command is set to OFF, KPP generates code for the stoichiometric matrix, the vector of reactant products #ENDINLINE in each reaction, and the partial derivative of the time derivative function with respect to rate coefficients. These 3.3.4 Inline type F90 RATES elements are discussed in Sect. 4.1.14. F90_RATES can be used to add new subroutines to calcu- late rate coefficients, e.g.: 3.2.16 Shorthand commands (#CHECKALL, #LOOKATALL and #TRANSPORTALL) #INLINE F90_RATES REAL FUNCTION k_SIV_H2O2(k_298,tdep,cHp,temp) KPP defines a couple of shorthand commands. The ! special rate function for S(IV) + H2O2 commands that fall into this category are #CHECKALL, REAL, INTENT(IN) :: k_298, tdep, cHp, temp #LOOKATALL and #TRANSPORTALL. All of them have been k_SIV_H2O2 = k_298 & described in the previous sections. * EXP(tdep*(1./temp-3.3540E-3)) & * cHp / (cHp+0.1) 3.3 Inlined code END FUNCTION k_SIV_H2O2 #ENDINLINE In order to offer maximum flexibility, KPP allows the user to include pieces of code in the kinetic description file. 3.3.5 Inline type F90 RCONST Inlined code begins on a new line with #INLINE and the inline type. Next, one or more lines of code follow, written F90_RCONST can be used to define time-dependent values in the target language (Fortran90, Fortran77, C, or Mat- of rate coefficients that were declared with F90_GLOBAL: lab) as specified by the inline type. The inlined code ends with #ENDINLINE. The code is inserted into the KPP out- #INLINE F90_RCONST put at a position which is also determined by inline type k_DMS_OH = 1.E-9*EXP(5820./temp)*C(ind_O2)/ & as explained in Table 3. If two inline commands with the (1.E30+5.*EXP(6280./temp)*C(ind_O2)) same inline type are declared, then the contents of the #ENDINLINE second is appended to the first one. In this manual, we show the inline types for Fortran90. The inline types for the other languages are produced by replacing “F90_” by 3.3.6 Inline type F90 UTIL “F77_”, “C_”, or “MATLAB_”, respectively. F90_UTIL can be used to define utility subroutines.
3.3.1 Inline type F90 DATA 3.4 Auxiliary files and the substitution This inline type was introduced in a previous version of preprocessor KPP to initialize variables. It is now obsolete but kept for compatibility. For Fortran90, F90_GLOBAL should be used The auxiliary files (listed in Table 4) are templates for in- instead. tegrators, drivers, and utilities. They are inserted into the KPP output after being run through the substitution pre- processor. This preprocessor replaces several placeholders 3.3.2 Inline type F90 GLOBAL (listed in Table 5) in the template files with their partic- F90_GLOBAL can be used to declare global variables, e.g. ular values in the model at hand. Usually, only KPP_ROOT for a special rate coefficient: and KPP_REAL are needed because the other values can also be obtained via the variables listed in Tab. 8. #INLINE F90_GLOBAL KPP_REAL is replaced by the appropriate single or double REAL(dp) :: k_DMS_OH precision declaration type. Depending on the target lan- #ENDINLINE guage KPP will select the correct declaration type. For Sandu & Sander: KPP User Manual 11
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 variables F90_INIT root_Initialize.f90 subroutine Initialize integration parameters F90_RATES root_Rates.f90 executable section rate law functions F90_RCONST root_Rates.f90 subroutine UPDATE_RCONST USE statements and definitions of rate coefficients F90_UTIL root_Util.f90 executable section utility functions
Table 4: Auxiliary files (for Fortran90)
File Contents dFun_dRcoeff.f90 derivatives with respect to reaction rates dJac_dRcoeff.f90 derivatives with respect to reaction rates Makefile.f90 unix makefiles Mex_Fun.f90 mex files Mex_Jac_SP.f90 mex files Mex_Hessian.f90 mex files sutil.f90 Sparse utility functions tag2num.f90 Function related to equation tags UpdateSun.f90 Function related to solar zenith angle UserRateLaws.f90 User-defined rate law functions util.f90 Input/output utilities
example if one needs to declare an array BIG of size 1000, 4 Output from KPP a declaration like the following must be used: KPP_REAL BIG(1000) 4.1 The Fortran90 Code When used with the option #DOUBLE ON, the above line The code generated by KPP is organized in a set of sepa- will be automatically translated into: rate files. Each has a time stamp and a complete descrip- REAL(dp) BIG(1000) tion of how it was generated at the begining of the file. The and when used with the option #DOUBLE OFF, the same files associated with root are named with a correspond- line will become: ing prefix “root_”. The list of files and a short descrip- tion is shown in Table 6. All subroutines and functions, REAL(sp) BIG(1000) global parameters, variables, and sparsity data structures in the resulting Fortran90 output file. are encapsulated in modules. There is exactly one module KPP_ROOT is replaced by the root file name of the main in each file, and the name of the module is identical to kinetic description file. In our example where we are pro- the file name but without the suffix .f90. Fig. 1 shows cessing small_strato.kpp, a line in an auxiliary Fortran90 how these modules are related to each other. A concise file like list of the main subroutines generated by KPP is shown in Table 7. The generated code is consistent with the For- USE KPP_ROOT_Monitor tran90 standard. It will not exceed the maximum number of 39 continuation lines. If KPP cannot properly split an will be translated into expression to keep the number of continuation lines be- low the threshold then it will generate a warning message USE small_strato_Monitor pointing to the location of this expression. in the generated Fortran90 output file. 12 Sandu & Sander: KPP User Manual
Table 5: List of symbols replaced by the substitution preprocessor with their particular values for the simulation at hand
Placeholder Replaced by Example KPP_ROOT the root name small_strato KPP_REAL the real data type REAL(kind=dp) KPP_NSPEC number of species 7 KPP_NVAR number of variable species 5 KPP_NFIX number of fixed species 2 KPP_NREACT number of chemical reactions 10 KPP_NONZERO number of Jacobian nonzero elements 18 KPP_LU_NONZERO number of Jacobian nonzero elements, with LU fill-in 19 KPP_NHESS number of Hessian nonzero elements 10
Table 6: List of model files generated by KPP (for Fortran90). Optional files are only produced under certain circumstances, 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.10 root_Global.f90 Global data headers 4.1.9 root_Initialize.f90 Initialization 4.1.3 root_Integrator.f90 Numerical integration 4.1.4 root_LinearAlgebra.f90 Sparse linear algebra 4.1.13 root_Model.f90 Summary of modules 4.1.2 root_Monitor.f90 Equation info 4.1.5 root_Parameters.f90 Model parameters 4.1.8 root_Precision.f90 Parameterized types 4.1.6 root_Rates.f90 User-defined rate laws 4.1.7 root_Util.f90 Utility input-output 4.1.16 root_Jacobian.f90 ODE Jacobian 4.1.11 root_JacobianSP.f90 Jacobian sparsity #JACOBIAN SPARSE_∗ 4.1.11 root_Hessian.f90 ODE Hessian #HESSIAN ON 4.1.12 root_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.14 root_StoichiomSP.f90 Stoichiometric matrix #STOICMAT ON and #JACOBIAN SPARSE_∗ 4.1.14 root_mex_Fun.f90 Matlab interface Fun #MEX ON 4.1.17 root_mex_Jac_SP.f90 Matlab interface Jac #MEX ON and #JACOBIAN SPARSE_∗ 4.1.17 root_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 processor. The name of the file is computed by KPP by appending the suffix _Main.f90 to the root name. root_Main.f90 is the main Fortran90 program. It con- tains the driver after modifications by the substitution pre- Sandu & Sander: KPP User Manual 13
Figure 1: Interdependencies of the KPP-generated files. Each arrow starts at the module that exports a variable or subroutine and points to the module that imports it via the Fortran90 USE instruction. The prefix root has been omitted from the module names for better readability. Dotted boxes show optional files that are only produced under certain circumstances, as listed in Tab. 6.
4.1.2 root Model.f90 It was shown above (Sect. 3.2.4) that each reaction in the #EQUATIONS section may start with an equation tag which The file root Model.f90 completely defines the model by is enclosed in angle brackets, e.g.: using all the associated modules.
4.1.3 root Initialize.f90 If the equation tags are switched on, KPP also gener- ates the PARAMETER array EQN_TAGS. In combination with The file root Initialize.f90 contains the subroutine EQN_NAMES and the function tag2num that converts the Initialize which defines initial values of the chemical equation tag to the KPP-internal equation number, this species. The driver calls the subroutine Initialize once can be used to describe a reaction: before the time integration loop starts. PRINT *,’Reaction J1 is:’, & EQN_NAMES(tag2num(’J1’)) 4.1.4 root Integrator.f90
The file root Integrator.f90 contains the subrou- 4.1.6 root Precision.f90 tine INTEGRATE which is called every time step during the integration. The integrator that was chosen with Fortran90 code uses parameterized real types. #INTEGRATOR is also included in root Integrator.f90. root_Precision.f90 contains the following real kind definitions:
4.1.5 root Monitor.f90 ! KPP_SP - Single precision kind INTEGER, PARAMETER :: & The file root Monitor.f90 contains PARAMETER arrays SP = SELECTED_REAL_KIND(6,30) with information about the chemical mechanism. The ! KPP_DP - Double precision kind names of all species are included in SPC_NAMES and the INTEGER, PARAMETER :: & names of all equations are included in EQN_NAMES. DP = SELECTED_REAL_KIND(12,300) 14 Sandu & Sander: KPP User Manual
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.f90 Jac_SP_Vec sparse multiplication root_Jacobian.f90 JacTR_SP_Vec sparse multiplication root_Jacobian.f90 Jac ODE Jacobian in full format root_Jacobian.f90 Hessian ODE Hessian in sparse format root_Hessian.f90 Hess_Vec Hessian action on vectors root_Hessian.f90 HessTR_Vec Transposed Hessian action on vectors root_Hessian.f90 dFun_dRcoeff Derivatives of Fun with respect to rate coefficients root_Stoichiom.f90 dJac_dRcoeff Derivatives of Jac with respect to rate coefficients root_Stoichiom.f90 ReactantProd Reactant products root_Stoichiom.f90 JacReactantProd Jacobian of reactant products root_Stoichiom.f90 KppDecomp Sparse LU decomposition root_LinearAlgebra.f90 KppSolve Sparse back substitution root_LinearAlgebra.f90 Update_PHOTO Update photolysis rate coefficients root_Rates.f90 Update_RCONST Update all rate coefficients root_Rates.f90 Update_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.f90 Shuffle_kpp2user Shuffle concentration vector root_Util.f90 Shuffle_user2kpp Shuffle concentration vector root_Util.f90 InitSaveData Utility for #LOOKAT command root_Util.f90 SaveData Utility for #LOOKAT command root_Util.f90 CloseSaveData Utility for #LOOKAT command root_Util.f90 tag2num Calculate reaction number from equation tag root_Util.f90
Depending on the choice of the #DOUBLE command, the KPP orders the variable species such that the sparsity real variables are of type double (REAL(kind=R_8)) or sin- pattern of the Jacobian is maintained after an LU decom- gle precision (REAL(kind=R_4)). Changing the parame- position. For our small_strato example there are five ters of the SELECTED_REAL_KIND function in this module variable species (NVAR=5) ordered as will cause a change in the working precision for the whole model. ind_O1D=1, ind_O=2, ind_O3=3, ind_NO=4, ind_NO2=5 4.1.7 root Rates.f90 and two fixed species (NFIX=2) The code to update the rate constants is in root_Rates.f90. The user defined rate law functions are ind_M = 6, ind_O2 = 7. also placed here. KPP defines a complete set of simulation parameters, in- cluding the numbers of variable and fixed species, the num- 4.1.8 root Parameters.f90 ber of chemical reactions, the number of nonzero entries in the sparse Jacobian and in the sparse Hessian, etc. Some The global parameters (Table 8) are defined and initialized important simulation parameters generated by KPP are in root_Parameters.f90. presented in Table 8. Sandu & Sander: KPP User Manual 15
4.1.10 root Function.f90 Table 8: List of important simulation parameters and their values for the small strato example The code for the ODE function is in root_Function.f90. The chemical reaction mechanism represents a set of or- Parameter Represents Value dinary differential equations (ODEs) of dimension NVAR. The concentrations of fixed species are parameters in the No. chemical species 7 NSPEC derivative function. The subroutine Fun computes first No. variable species 5 NVAR the vector A of reaction rates and then the vector Vdot NFIX No. fixed species 2 of variable species time derivatives. The input arguments No. reactions 10 NREACT V, F, and RCT are the concentrations of variable species, NONZERO No. nonzero entries Jacobian 18 fixed species, and the rate coefficients, respectively. Be- LU_NONZERO As above, after LU factorization 19 low is the Fortran90 code generated by KPP for the ODE Length, sparse Hessian 10 NHESS function of our small_strato example. NJVRP Length, sparse Jacobian JVRP 13 NSTOICM Length, stoichiometric matrix 22 SUBROUTINE Fun (V, F, RCT, Vdot ) ind_spc Index of species spc in C() REAL(kind=DP) :: V(NVAR), & indf_spc Index of fixed species spc in FIX() F(NFIX), RCT(NREACT), & Vdot(NVAR), A(NREACT) & ! Computation of equation rates Table 9: List of important global variables A(1) = RCT(1)*F(2) A(2) = RCT(2)*V(2)*F(2) Global variable Represents A(3) = RCT(3)*V(3) A(4) = RCT(4)*V(2)*V(3) C(NSPEC) Concentrations, all species A(5) = RCT(5)*V(3) VAR(NVAR) Concentrations, variable species A(6) = RCT(6)*V(1)*F(1) FIX(NFIX) Concentrations, fixed species A(7) = RCT(7)*V(1)*V(3) RCONST(NREACT) Rate coefficient values A(8) = RCT(8)*V(3)*V(4) TIME Current integration time A(9) = RCT(9)*V(2)*V(5) SUN Sun intensity between 0 and 1 A(10) = RCT(10)*V(5) TEMP Temperature ! Aggregate function RTOLS Relative tolerance (scalar) Vdot(1) = A(5)-A(6)-A(7) TSTART,TEND Simulation start/end time Vdot(2) = 2*A(1)-A(2)+A(3) & DT Simulation step -A(4)+A(6)-A(9)+A(10) ATOL(NSPEC) Absolute tolerances Vdot(3) = A(2)-A(3)-A(4)-A(5) & RTOL(NSPEC) Relative tolerances -A(7)-A(8) STEPMIN Lower bound for time step Vdot(4) = -A(8)+A(9)+A(10) STEPMAX Upper bound for time step Vdot(5) = A(8)-A(9)-A(10) CFACTOR Conversion factor END SUBROUTINE Fun SPC_NAMES(NSPEC) Names of chemical species EQN_NAMES(NREACT) Names of chemical equations 4.1.11 root Jacobian.f90 and root JacobianSP.f90 4.1.9 root Global.f90 The sparse data structures for the Jacobian are de- The global variables (Table 9) are declared in clared and initialized in root_JacobianSP.f90. The code for the ODE Jacobian and sparse multiplications is in root_Global.f90. Global variables are presented in Table 9. root_Jacobian.f90. The Jacobian of the ODE func- tion is automatically constructed by KPP. KPP generates Both variable and fixed species are stored in the one- the Jacobian subroutine Jac or Jac_SP where the latter is dimensional array C. The first part (indices from 1 to generated when the sparse format is required. Using the NVAR) contains the variable species, and the second part variable species V, the fixed species F, and the rate coeffi- (indices from NVAR+1 to NSPEC) the fixed species. The to- cients RCT as input, the subroutine calculates the Jacobian tal number of species NSPEC is the sum of the NVAR and JVS. The default data structures for the sparse compressed NFIX. The parts can also be accessed separately through on rows Jacobian representation are shown in Table 10 the arrays VAR and FIX: (for the case where the LU fill-in is accounted for). JVS stores the LU_NONZERO elements of the Jacobian in row VAR(1:NVAR) = C(1:NVAR) order. Each row I starts at position LU_CROW(I), and FIX(1:NFIX) = C(NVAR+1:NSPEC) 16 Sandu & Sander: KPP User Manual
Jac = d f / d y Table 11: Sparse Hessian Data
Variable Represents 1 HESS(NHESS) Hessian nonzero elements Hi,j,k IHESS_I(NHESS) Index i of element Hi,j,k 2 IHESS_J(NHESS) Index j of element Hi,j,k IHESS_K(NHESS) Index k of element Hi,j,k 3
4.1.12 root Hessian.f90 and root HessianSP.f90 4 The sparse data structures for the Hessian are declared and initialized in root_HessianSP.f90. The Hessian 5 function and associated sparse multiplications are in root_Hessian.f90. The Hessian contains the second or- der derivatives of the time derivative functions. More ex- 1 2 3 4 5 actly, the Hessian is a 3-tensor such that nz = 19 ∂2(dc/dt) Figure 2: The sparsity pattern of the Jacobian for the H = i , 1 ≤ i, j, k ≤ N . (11) i,j,k ∂c ∂c var small strato example. j k KPP generates the routine Hessian. Using the variable Table 10: Sparse Jacobian Data Structures species V, the fixed species F, and the rate coefficients RCT as input, the subroutine calculates the Hessian. The Hessian is a very sparse tensor. The sparsity of the Hes- Global variable Represents sian for our small_strato example is visualized in Fig. 3. JVS(LU_NONZERO) Jacobian nonzero elements KPP computes the number of nonzero Hessian entries and LU_IROW(LU_NONZERO) Row indices saves it in the variable NHESS. The Hessian itself is rep- LU_ICOL(LU_NONZERO) Column indices resented in coordinate sparse format. The real vector LU_CROW(NVAR+1) Start of rows HESS holds the values, and the integer vectors IHESS_I, LU_DIAG(NVAR+1) Diagonal entries IHESS_J, and IHESS_K hold the indices of nonzero en- tries as illustrated in Table 11. Since the time derivative function is smooth, these Hessian matrices are symmet- ric, HESS =HESS . KPP stores only those entries . The location of the - i,j,k i,k,j LU_CROW(NVAR+1)=LU_NONZERO+1 I HESS with j ≤ k. The sparsity coordinate vectors th diagonal element is . The sparse element i,j,k LU_DIAG(I) IHESS_I, IHESS_J, and IHESS_K are computed by KPP JVS(K) is the Jacobian entry in row LU_IROW(K) and col- and initialized statically. They are constant as the spar- umn LU_ICOL(K). For the small_strato example KPP sity pattern of the Hessian does not change during the generates the following Jacobian sparse data structure: computation. LU_ICOL = (/ 1,3,1,2,3,5,1,2,3,4, & The routines Hess_Vec and HessTR_Vec compute the ac- 5,2,3,4,5,2,3,4,5 /) tion of the Hessian (or its transpose) on a pair of user- LU_IROW = (/ 1,1,2,2,2,2,3,3,3,3, & supplied vectors U1 and U2. Sparse operations are em- 3,4,4,4,4,5,5,5,5 /) ployed to produce the result vector. LU_CROW = (/ 1,3,7,12,16,20 /) LU_DIAG = (/ 1,4,9,14,19,20 /) 4.1.13 root LinearAlgebra.f90
This is visualized in Fig. 2. The sparsity coordinate vec- Sparse linear algebra routines are in the file tors are computed by KPP and initialized statically. These root_LinearAlgebra.f90. To numerically solve for vectors are constant as the sparsity pattern of the Jaco- the chemical concentrations one must employ an implicit bian does not change during the computation. timestepping technique, as the system is usually stiff. Two other KPP-generated routines, Jac_SP_Vec and Implicit integrators solve systems of the form JacTR_SP_Vec are useful for direct and adjoint sensitivity P x = (I − hγJ) x = b (12) analysis. They perform sparse multiplication of JVS (or its transpose for JacTR_SP_Vec) with the user-supplied where the matrix P = I − hγJ is refered to as the “pre- vector UV without any indirect addressing. diction matrix”. I the identity matrix, h the integration Sandu & Sander: KPP User Manual 17
d2 f / d y2 d2 f / d y2 d2 f / d y2 d2 f / d y2 d2 f / d y2 1 2 3 4 5
1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 5 5 5 5 5
1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 nz = 2 nz = 4 nz = 6 nz = 4 nz = 4
Figure 3: The Hessian of the small strato example. time step, γ a scalar parameter depending on the method, Table 12: Sparse Stoichiometric Matrix and J the system Jacobian. The vector b is the system right hand side and the solution x typically represents an increment to update the solution. Global variable Represents The chemical Jacobians are typically sparse, i.e. only a STOICM(NSTOICM) Stoichiometric matrix relatively small number of entries are nonzero. The spar- IROW_STOICM(NSTOICM) Row indices sity structure of P is given by the sparsity structure of the ICOL_STOICM(NSTOICM) Column indices Jacobian, and is produced by KPP (with account for the CCOL_STOICM(NREACT+1) Start of columns fill-in) as discussed above. KPP generates the sparse linear algebra subroutine KppDecomp which performs an in-place, non-pivoting, Table 13: Sparse Data for Jacobian of Reactant Products sparse LU decomposition of the prediction matrix P . Since the sparsity structure accounts for fill-in, all ele- Global variable Represents ments of the full LU decomposition are actually stored. The output argument IER returns a value that is nonzero JVRP(NJVRP) Nonzero elements of JVRP if singularity is detected. ICOL_JVRP(NJVRP) Column indices in JVRP IROW_JVRP(NJVRP) Row indices in JVRP The subroutines KppSolve and KppSolveTR use the in- CROW_JVRP(NREACT+1) Start of rows in JVRP place LU factorization P as computed by KppDecomp and perform sparse backward and forward substitutions (using P or its transpose). The sparse linear algebra routines KppDecomp and KppSolve are extremely efficient, as shown starts in the sparse vector at position CCOL_STOICM(j) by (Sandu et al., 1996). and ends at CCOL_STOICM(j+1)-1. The last value CCOL_ STOICM(NVAR+1)=NSTOICM+1 simplifies the handling of sparse data structures. 4.1.14 root Stoichiom.f90 and root StoichiomSP.f90 The subroutine ReactantProd computes the reactant products ARP for each reaction, and the subroutine These files contain a description of the chemi- JacReactantProd computes the Jacobian of reactant cal mechanism in stoichiometric form. The file products vector, i.e.: root_Stoichiom.f90 contains the functions for reactant products and its Jacobian, and derivatives with respect JVRP = ∂ARP/∂V (13) to rate coefficients. The declaration and initialization of The matrix JVRP is sparse and is computed and stored in the stoichiometric matrix and the associated sparse data row compressed sparse format, as shown in Table 13. The structures is done in root_StoichiomSP.f90. parameter NJVRP holds the number of nonzero elements. The stoichiometric matrix is constant sparse. For our For our example: example the matrix has NSTOICM=22 nonzero entries out of 50 entries. KPP produces the stoichiometric matrix NJVRP = 13 in sparse, column-compressed format, as shown in Table CROW_JVRP = (/ 1,1,2,3,5,6,7,9,11,13,14 /) 12. Elements are stored in columnwise order in the one- ICOL_JVRP = (/ 2,3,2,3,3,1,1,3,3,4,2,5,4 /) dimensional vector of values STOICM. Their row and col- umn indices are stored in IROW_STOICM and ICOL_STOICM If #STOICMAT is set to ON, the stoichiometric formulation respectively. The vector CCOL_STOICM contains point- allows a direct computation of the derivatives with respect ers to the start of each column. For example column j to rate coefficients. 18 Sandu & Sander: KPP User Manual
The subroutine dFun_dRcoeff computes the partial 4.1.17 root mex Fun.f90, root mex Jac SP.f90, derivative DFDR of the ODE function with respect to a and root mex Hessian.f90 subset of NCOEFF reaction coefficients, whose indices are specifies in the array JCOEFF Mex is a Matlab extension. KPP generates the mex rou- tines for the ODE function, Jacobian, and Hessian, for DFDR = ∂Vdot/∂RCT(JCOEFF) (14) the target languages C, Fortran77, and Fortran90. After compilation (using Matlab’s mex compiler) the mex func- Similarly one can obtain the partial derivative of the Jaco- tions can be called instead of the corresponding Matlab m- bian with respect to a subset of the rate coefficients. More functions. Since the calling syntaxes are identical, the user exactly, KPP generates the subroutine dJac_dRcoeff only has to insert the mex string within the corresponding which calculates DJDR, the product of this partial deriva- function name. Replacing m-functions by mex-functions tive with a user-supplied vector: gives the same numerical results, but the computational time could be considerably smaller, especially for large ki- DJDR = [∂JVS/∂RCT(JCOEFF)] × U (15) netic systems. If possible we recommend to build mex files using the C 4.1.15 root Stochastic.f90 language, as Matlab offers most mex interface options for the C language. Moreover, Matlab distributions come If the generation of stochastic functions is switched on, with a native C compiler (lcc) for building executable KPP produces the file root_Stochastic.f90 with the functions from mex files. Fortran77 mex files work well following functions: on most platforms without additional efforts. However, Propensity calculates the propensity vector. The propen- the mex files built using Fortran90 may require further sity function uses the number of molecules of variable platform-specific tuning of the mex compiler options. (NmlcV) and fixed (NmlcF) species, as well as the stochas- tic rate coefficients (SCT) to calculate the vector of propen- 4.1.18 The Makefile sity rates (Propensity). The propensity Propj defines the probability that the next reaction in the system is the jth KPP produces a Makefile that allows for an easy compi- reaction. lation of all KPP-generated source files. The file name is StochasticRates converts deterministic rates to stochas- Makefile_root. The Makefile assumes that the selected tic. The stochastic rate coefficients (SCT) are obtained driver contains the main program. However, if no driver through a scaling of the deterministic rate coefficients was selected (i.e. #DRIVER none), it is necessary to add (RCT). The scaling depends on the Volume of the reaction the name of the main program file manually to the Make- container and on the number of molecules which react. file. MoleculeChange calculates changes in the number of molecules. When the reaction with index IRCT takes place, 4.2 The C Code the number of molecules of species involved in that reac- tion changes. The total number of molecules NmlcV is The driver file root.c contains the main (driver) and updated by the function. numerical integrator functions, as well as declarations and initializations of global variables. The generated C These functions are used by the Gillespie numerical in- code includes three header files which are #include-d in tegrators (direct stochastic simulation algorithm). These other files as appropriate. The global parameters (Table integrators are provided in both Fortran90 and C imple- 8) are #define-d in the header file root_Parameters.h. mentations (the template file name is gillespie). Drivers The global variables (Table 9) are extern-declared in for stochastic simulations are also implemented (the tem- root_Global.h, and declared in the driver file root.c. plate file name is general_stochastic). The header file root_Sparse.h contains extern declara- tions of sparse data structures for the Jacobian (Table 4.1.16 root Util.f90 10), Hessian (Table 11), stoichiometric matrix (Table 12), and the Jacobian of reaction products (Table 13). The The utility and input/output functions are in actual declarations of each data structures is done in the root_Util.f90. In addition to the chemical system corresponding files. description routines discussed above, KPP generates The code for the ODE function (Sect. 4.1.10) is in several utility routines, some of which are summarized in root_Function.c. The code for the ODE Jaco- Table 7. bian and sparse multiplications (Sect. 4.1.11) is in The subroutines InitSaveData, SaveData, and root_Jacobian.c, and the declaration and initialization CloseSaveData can be used to print the concentra- of the Jacobian sparse data structures (Table 10) is in tion of the species that were selected with #LOOKAT to the the file root_JacobianSP.c. Similarly, the Hessian func- file root.dat. tion and associated sparse multiplications (Section 4.1.12) Sandu & Sander: KPP User Manual 19 are in root_Hessian.c, and the declaration and initial- and initialization of the stoichiometric matrix and the as- ization of Hessian sparse data structures (Table 11) in sociated sparse data structures (Tables 12 and 13) is done root_HessianSP.c. in the STOICM_MATRIX block data statement. The file root_Stoichiom.c contains the functions for re- Sparse linear algebra routines (Sect. 4.1.13) are in the file actant products and its Jacobian, and derivatives with re- root_LinearAlgebra.f. The code to update the rate spect to rate coefficients (Sect. 4.1.14). The declaration constants is in root_Rates.f, and the utility and in- and initialization of the stoichiometric matrix and the as- put/output functions (Sect. 4.1.16) are in root_Util.f sociated sparse data structures (Tables 12 and 13) is done and root_Monitor.f. in root_StoichiomSP.c. Matlab-mex gateway routines for the ODE function, Ja- Sparse linear algebra routines (Sect. 4.1.13) are in the cobian, and Hessian are discussed in Sect. 4.1.17. file root_LinearAlgebra.c. The code to update the rate constants and user defined code for rate laws is in root_Rates.c. 4.4 The Matlab Code Various utility and input/output functions (Sect. 4.1.16) Matlab (http://www.mathworks.com/products/ are in root_Util.c and root_Monitor.c. matlab/) provides a high-level programming envi- Finally, mex gateway routines that allow the C implemen- ronment that allows algorithm development, numerical tation of the ODE function, Jacobian, and Hessian to be computations, and data analysis and visualization. The called directly from Matlab (Sect. 4.1.17) are also gener- KPP-generated Matlab code allows for a rapid proto- ated (in the files root_mex_Fun.c, root_mex_Jac_SP.c, typing of chemical kinetic schemes, and for a convenient and root_mex_Hessian.c). analysis and visualization of the results. Differences between different kinetic mechanisms can be easily under- stood. The Matlab code can be used to derive reference 4.3 The Fortran77 Code numerical solutions, which are then compared against the results obtained with user-supplied numerical techniques. The general layout of the Fortran77 code is similar to the Last but not least Matlab is an excellent environment for layout of the C code. The driver file root.f contains the educational purposes. KPP/Matlab can be used to teach main (driver) and numerical integrator functions. students fundamentals of chemical kinetics and chemical The generated Fortran77 code includes three header files. numerical simulations. The global parameters (Table 8) are defined as parameters Each Matlab function has to reside in a separate m- and initialized in the header file root_Parameters.h. The file. Function calls use the m-function-file names to ref- global variables (Table 9) are declared in root_Global.h erence the function. Consequently, KPP generates one as common block variables. There are global common m-function-file for each of the functions discussed in Sec- blocks for real (GDATA), integer (INTGDATA), and charac- tions 4.1.10, 4.1.11, 4.1.12, 4.1.13, 4.1.14, and 4.1.16. The ter (CHARGDATA) global data. They can be accessed from names of the m-function-files are the same as the names within each program unit that includes the global header of the functions (prefixed by the model name root). file. The Matlab syntax for calling each function is The header file root_Sparse.h contains common block declarations of sparse data structures for the Jacobian [Vdot] = Fun (V, F, RCT); (Table 10), Hessian (Table 11), stoichiometric matrix [JVS ] = Jac_SP (V, F, RCT); (Table 12), and the Jacobian of reaction products (Ta- [HESS] = Hessian(V, F, RCT); ble 13). These sparse data structures are initialized in four named block data statements: JACOBIAN_SPARSE_ The global parameters (Table 8) are defined as DATA (in root_HessianSP.f), HESSIAN_SPARSE_DATA (in Matlab global variables and initialized in the file root_HessianSP.f), JVRP_SPARSE_DATA and STOICM_ root_parameter_defs.m. The variables of Table 9 MATRIX (in root_StoichiomSP.f). are declared as Matlab global variables in the file The code for the ODE function (Sect. 4.1.10) is in root_Global_defs.m. They can be accessed from within root_Function.f. The code for the ODE Jaco- each Matlab function by using global declarations of the bian and sparse multiplications (Sect. 4.1.11) is in variables of interest. root_Jacobian.f. The Hessian function and as- The sparse data structures for the Jacobian (Table 10), sociated sparse multiplications (Sect. 4.1.12) are in the Hessian (Table 11), the stoichiometric matrix (Ta- root_Hessian.f. ble 12), and the Jacobian of reaction products (Table 13) are declared as Matlab variables in the file The file root_Stoichiom.f contains the functions for re- global actant products and its Jacobian, and derivatives with re- root_Sparse_defs.m. They are initialized in separate spect to rate coefficients (Sect. 4.1.14). The declaration m-files, namely root_JacobianSP.m root_HessianSP.m, and root_StoichiomSP.m respectively. 20 Sandu & Sander: KPP User Manual
Two wrappers (root_Fun_Chem.m and root_Jac_SP_ Table 15: Source code files Chem.m) are provided for interfacing the ODE function and the sparse ODE Jacobian with Matlab’s suite of ODE in- tegrators. Specifically, the syntax of the wrapper calls File Description matches the syntax required by Matlab’s integrators like kpp.c main program ode15s. Moreover, the Jacobian wrapper converts the sparse KPP format into a Matlab sparse matrix. code.c generic code generation functions code.h header file code_c.c generation of C code 4.5 The map file code_f77.c generation of Fortran77 code code_f90.c generation of Fortran90 code The map file root.map contains a summary of all the func- code_matlab.c generation of matlab code tions, subroutines and data structures defined in the code debug.c debugging output file, plus a summary of the numbering and category of the gdata.h header file species involved. gdef.h header file This file contains supplementary information for the user. gen.c generic code generation functions Several statistics are listed here, like the total number lex.yy.c flex/yacc-generated file equations, the total number of species, the number of vari- scan.h input for flex/yacc able and fixed species. Each species from the chemical scan.l input for flex/yacc mechanism is then listed followed by its type and number- scan.y input for flex/yacc ing. scanner.c evaluate parsed input scanutil.c evaluate parsed input Furthermore it contains the complete list of all the func- y.tab.c flex/yacc-generated file tions generated in the target source file. For each func- y.tab.h flex/yacc-generated header file tion, a brief description of the computation performed is attached containing also the meaning of the input and output parameters.
models/ Contains the description of the chemical 5 KPP Internal Structure models. Users can define their own models by plac- ing the model description files in this directory. The KPP distribution contains several models from at- This chapter is mainly concerned with describing the in- mospheric chemistry which can be used as templates ternal architecture of the KPP preprocessor. It describes for model definitions. the basic modules and their functionalities, and all the preprocessing analysis performed on the input files. KPP drv/ Contains driver templates for chemical simula- can be very easily configured to suit a broad class of users. tions. Each driver has a suffix that matches the ap- propriate target language (.f90, .f, .c, or .m). KPP will run the appropriate driver through the substitu- 5.1 KPP directory structure tion preprocessor. The driver template general pro- vided with the distribution works with any example. The KPP distribution will unfold a directory $KPP_HOME Users can define here their own driver templates. with the following subdirectories: int/ Contains numerical time stepping (integrator) src/ Contains the KPP source code files, as listed routines. The command “#INTEGRATOR integrator” in Table 15. will force KPP to look into this directory for a defi- nition file integrator.def. This file selects the numer- bin/ Contains the KPP executable. The path to ical routine (with the #INTFILE command) and sets this directory needs to be added to the environment the function type, the Jacobian sparsity type, the variable. PATH target language, etc. Each integrator template is util/ Contains different function templates useful found in a file that ends with the appropriate suffix for the simulation. Each template file has a suffix (.f90, .f, .c, or .m). The selected template is pro- that matches the appropriate target language (.f90, cessed by the substitution preprocessor. Users can .f, .c, or .m). KPP will run the template files through define here their own numerical integration routines. the substitution preprocessor. The user can define examples/ Contains several model description ex- their own auxiliary functions by inserting them into amples (.kpp files) which can be used as templates the files. for building simulations with KPP. Sandu & Sander: KPP User Manual 21
Table 14: List of Matlab model files
File Description root.m driver root_parameter_defs.m Global parameters root_global_defs.m Global variables root_monitor_defs.m Global monitor variables root_sparse_defs.m Global sparsity data root_Fun_Chem.m Template for ODE function root_Fun.m ODE function root_Jac_Chem.m Template for ODE Jacobian root_Jac_SP.m ODE Jacobian in sparse format root_JacobianSP.m Sparsity data structures root_Hessian.m ODE Hessian in sparse format root_HessianSP.m Sparsity data structures root_HessTR_Vec.m Hessian action on vectors root_Hess_Vec.m Transposed Hessian action on vectors root_stoichiom.m Derivatives of Fun and Jac with respect to rate coefficients root_StoichiomSP.m Sparse data root_ReactantProd.m Reactant products root_JacReactantProd.m Jacobian of reactant products root_rates.m User-defined reaction rate laws root_Update_PHOTO.m Update photolysis rate coefficients root_Update_RCONST.m Update all rate coefficients root_Update_SUN.m Update solar intensity root_GetMass.m Check mass balance for selected atoms root_Initialize.m Set initial values root_Shuffle_kpp2user.m Shuffle concentration vector root_Shuffle_user2kpp.m Shuffle concentration vector
site-lisp/ Contains the file kpp.el which provides a 5.3 KPP internal modules KPP mode for emacs with color highlighting. 5.3.1 Scanner and Parser
5.2 KPP environment variables This module is responsible for reading the kinetic descrip- tion files and extracting the information necessary in the In order for KPP to find its components, it has to know code generation phase. We make use of the flex and yacc the path to the location where the KPP distribution is generic tools in implementing our own scanner and parser. installed. This is achieved by requiring the $KPP_HOME Using these tools this module gathers information from environment variable to be set to the path where KPP is the input files and fills in the following data structures in installed. memory: The PATH variable should be updated to contain the $KPP_HOME/bin directory. The atom list There are several optional environment variable that con- The species list trol the places where KPP looks for module files, integra- tors, and drivers. They are all summarized in Table 16. The left hand side matrix of coefficients The right hand side matrix of coefficients The equation rates 22 Sandu & Sander: KPP User Manual
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 $KPP_HOME/models files before searching the default $KPP_INT Optional, specifies additional places were KPP will look for inte- $KPP_HOME/int grator files before searching the default. $KPP_DRV Optional, specifies additional places were KPP will look for driver $KPP_HOME/drv files before searching the default
The option list 5.3.4 Code generation
Error checking is performed at each step in the scanner There are basically two modules, each dealing with the and the parser. For each syntax error the exact line and syntax particularities of the target language. For exam- input file, along with an appropriate error message are ple, the C module includes a function that generates a produced. In most of the cases the exact cause of the valid C assignment when given an expression tree. Sim- error can be identified, therefore the error messages are ilarly there are functions for data declaration, initializa- very precise. Some other errors like mass balance, and tions, comments, function prototypes, etc. Each of these equation duplicates, are tested at the end of this phase. functions produce the code into an output buffer. A lan- guage specific routine reads from this buffer and splits the statements into lines to improve readability of the gener- 5.3.2 Species reordering ated code. When parsing the input files, the species list is updated as soon as a new species is encountered in a chemical equa- tion. Therefore the ordering of the species is the order 6 Numerical methods in which they appear in the equation description section. This is not a useful order for subsequent operations. The The KPP numerical library contains a set of numerical in- species have to be first sorted such that all variable species tegrators selected to be very efficient in the low to medium −2 −5 and all fixed species are put together. Then if a sparsity accuracy regime (relative errors ∼ 10 ... 10 ). In ad- structure of the Jacobian is required, it might be better to dition, the KPP numerical integrators preserve the linear reorder the species in such a way that the factorization of invariants (i.e., mass) of the chemical system. the Jacobian will preserve the sparsity. This reordering is KPP implements several Rosenbrock methods: Ros–1 and done using a Markovitz type of algorithm. Ros–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 each 5.3.3 Expression trees computation of them KPP implements the tangent linear model (direct This is the core of the preprocessor. This module has to decoupled sensitivity) and the adjoint models. The imple- generate the production/destruction functions the Jaco- mentations distinguish between sensitivities with respect bian and all the data structure nedeed by these functions. to initial values and sensitivities with respect to parame- This module has to build a language independent struc- ters for efficiency. ture of each function and statement in the target source Note that KPP produces the building blocks for the sim- file. Instead of using an intermediate format for this as ulation and also for the sensitivity calculations. It also some other compilers do, KPP generates the intermedi- provides application programming templates. Some mini- ate format for just one statement at a time. The vast mal programming may be required from the users in order majority of the statements in the target source file are to construct their own application from the KPP building assignments. The expression tree for each assignment is blocks. incrementally build by scanning the coefficient matrices In order to offer more control over the integrator, the and the rate constant vector. At the end these expres- KPP-generated subroutine INTEGRATE provides the op- sion trees are simplified. Similar approaches are applied tional input parameters ICNTRL_U and RCNTRL_U. Each of to function declaration and prototypes, data declaration them is an array of 20 elements that allow the fine-tuning and initialization. of the integrator, e.g. by setting a particular integrator method, tolerances, minimum and maximum step sizes, Sandu & Sander: KPP User Manual 23
Table 17: Symbols used in the decription of the numerical methods implemented in KPP Symbol Description s Number of stages tn Discrete time moment h 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: y0 = f(t, y) ft(·, ·) Partial time derivative ft(t, y) = ∂f(t, y)/∂t J(·, ·) The Jacobian J(t, y) = ∂f(t, y)/∂y Jt(·, ·) Partial time derivative of Jacobian Jt(t, y) = ∂J(t, y)/∂t A The system matrix H(·, ·) The Hessian H(t, y) = ∂2f(t, y)/∂y2 Ti Internal stage time moment for Runge Kutta and Rosenbrock methods Yi Internal stage solution for Runge Kutta and Rosenbrock methods ki, `i, ui, vi Internal stage vectors for Runge Kutta and Rosenbrock methods, their tangent linear and adjoint models αi, αij, aij, bi, ci, cij, ei, mi Method coefficients
i−1 and more. The exact meaning of the elements depends X cij A · k = f ( T ,Y ) + k + hγ f (tn, yn) . on the integrator and may change in the future. Please i i i h j i t read the comment lines in the individual integrator files j=1 $KPP_HOME/int/*.f90. P where s is the number of stages, αi = αij and γi = P j Similarly, to obtain more information about the integra- j γij. The formula coefficients (aij and γij) give the or- tion, the subroutine INTEGRATE provides the optional out- der of consistency and the stability properties. A is the put parameters ISTATUS_U and RSTATUS_U. They are system matrix (in the linear systems to be solved during both arrays of 20 elements and contain the length of implicit integration, or in the Newton’s method used to the last time step, the number of accepted and rejected solve the nonlinear systems). It is the scaled identity ma- steps, the number of miscellaneous function calls, and trix minus the Jacobian. more. Again, for the exact meaning, the reader is ref- The coefficients of the methods implemented in KPP are ered to the comment lines in the individual integrator files shown in Table 18. $KPP_HOME/int/*.f90. In the following sections we introduce the numerical meth- 6.1.1 Tangent Linear Model ods implemented in KPP. The symbols used in the formu- las are explained in Table 17. The method (16) is combined with the sensitivity equa- tions. One step of the method reads
6.1 Rosenbrock Methods s n+1 n X δy = δy + mi`i (17) An s-stage Rosenbrock method (Hairer and Wanner, 1991, i=1 Section IV.7) computes the next-step solution by the for- i−1 mulas n n X Ti = t + αih , δYi = δy + aij`j s s j=1 n+1 n X n+1 X y = y + miki , Err = eiki (16) i−1 X cij i=1 i=1 A · ` = J ( T ,Y ) · δY + ` i i i i h j i−1 j=1 n n X n n n n n n Ti = t + αih , Yi = y + aijkj , + (H(t , y ) × ki) · δy + hγiJt (t , y ) · δy j=1 1 The method requires a single n × n LU decomposition per A = − J T (tn, yn) hγ step to obtain both the concentrations and the sensitivi- ties. 24 Sandu & Sander: KPP User Manual
Table 18: Rosenbrock methods implemented in KPP
Method Stages Function Order Stability Method name (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) Stiffly a2,1 = 0, a3,1 = 2, a3,2 = 0, a4,1 = 2, a4,2 = 0, a4,3 = 1, accurate 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) Stiffly α1 = 0, α2 = 0.386, α3 = 0.210, α4 = 0.630, α5 = 1, α6 = 1, accurate γ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
s KPP contains tangent linear models (for direct decou- X T λn = λn+1 + (H(tn, yn) × k ) · u pled sensitivity analysis) for each of the Rosenbrock meth- i i i=1 ods (Ros–1, Ros–2, Ros–3, Ros–4, Rodas–3, and Rodas– s s 4). The implementations distinguish between sensitivities T n n X X +hJt (t , y ) · γiui + vi with respect to initial values and sensitivities with respect i=1 i=1 to parameters for efficiency. KPP contains adjoint models (for direct decoupled sensi- tivity analysis) for each of the Rosenbrock methods (Ros– 6.1.2 The Discrete Adjoint 1, Ros–2, Ros–3, Ros–4, Rodas–3, and Rodas–4).
To obtain the adjoint we first differentiate the method 6.2 Runge-Kutta methods with respect to yn. Here J denotes the Jacobian and H the Hessian of the derivative function f. The discrete A general s-stage Runge-Kutta method is defined as adjoint of the (non-autonomous) Rosenbrock method is (Hairer et al., 1993, Section II.1) s s X cji X A · u = m λn+1 + a v + u , (18) yn+1 = yn + h b k , (19) i i ji j h j i i j=i+1 i=1 T s vi = J (Ti,Yi) · ui , i = s, s − 1, ··· , 1 , n n X Ti = t + cih , Yi = y + h aijkj , j=1 Sandu & Sander: KPP User Manual 25
Table 19: Runge-Kutta methods implemented in KPP Method File(s) Description Radau5 atm radau5.f, This Runge Kutta method of order 5 based on Radau-IIA quadra- kpp radau5.f90 ture (Hairer and Wanner, 1991) is stiffly accurate. The KPP im- plementation follows the original implementation of Hairer and Wanner (1991). While Radau5 is relatively expensive (when com- pared to the Rosenbrock methods), it is more robust and is useful to obtain accurate reference solutions. SDIRK4 kpp sdirk.f, The implementation is based on the implementation of Hairer and kpp sdirk.f90 Wanner (1991). SDIRK4 is an L-stable, singly-diagonally-implicit Runge Kutta method of order 4. SEULEX kpp seulex.f, SEULEX is a variable order stiff extrapolation code able to pro- kpp seulex.f90 duce highly accurate solutions. The KPP implementation is based on the implementation of Hairer and Wanner (1991).
ki = f ( Ti,Yi ) , 6.2.2 Discrete Adjoint Model where the coefficients aij, bi and ci are prescribed for The first order Runge-Kutta adjoint is the desired accuracy and stability properties. The stage s derivative values ki are defined implicitly, and require solv- T n+1 X ing a (set of) nonlinear system(s). Newton-type methods ui = h J (Ti,Yi) · biλ + ajiuj (21) solve coupled linear systems of dimension (at most) n × s. j=1 s KPP numerical library implements a Radau5, a Runge X λn = λn+1 + u . Kutta method of order 5 based on Radau-IIA quadrature j j=1 (Hairer and Wanner, 1991, Section IV.10). This numeri- cal method is stiffly accurate. The KPP implementation For bi 6= 0 the Runge-Kutta adjoint can be rewritten as follows the original implementation of Hairer and Wanner another Runge-Kutta method: (1991). While Radau5 is relatively expensive (when com- pared to the Rosenbrock methods), it is more robust and s T n+1 X bj aji is useful to obtain highly accurate reference solutions. ui = h J (Ti,Yi) · λ + uj (22) bi The Runge-Kutta methods implemented in KPP are sum- j=1 s marized in Table 19. n n+1 X λ = λ + bj uj . j=1 6.2.1 Tangent Linear Model No Runge Kutta adjoint model is currently implemented The tangent linear method associated with the Runge in KPP. Kutta method is s 6.3 Backward Differentiation Formulas n+1 n X δy = δy + h bi`i , (20) i=1 Backward differentiation formulas (BDF) are linear mul- s n X tistep methods with excellent stability properties for the δYi = δy + h aij`j , integration of chemical systems (Hairer and Wanner, 1991, j=1 Section V.1). The k-step BDF method reads `i = J (Ti,Yi) · δYi . k X n−i n n The system (20) is linear and does not require an iterative αiy = hnβ f (t , y ) (23) procedure. However, even for a SDIRK method (aij = 0 i=0 for i > j and aii = γ) each stage requires the LU factor- ization of a different matrix. where the coefficients αi and β are chosen such that the method has order of consistency k. No Runge Kutta tangent linear model is currently imple- mented in KPP. The KPP library contains two off-the-shelf, highly popular implementations of BDF methods, described in Table 20. 26 Sandu & Sander: KPP User Manual
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 interface directly with the KPP generated code VODE kpp dvode.f VODE (Brown et al., 1989) uses another formulation of backward differentiation formulas. The version of VODE present in the KPP library 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 sparse linear algebra routines.
7 Differences between KPP-2.1 7.2 Upgrading KPP input files from pre- and Previous Versions vious versions to KPP-2.1 KPP users who want to upgrade from previous versions to 7.1 New features of KPP-2.1 KPP-2.1 need to make a few modifications to their input files. This user manual describes recently added features of KPP as well as those which have been available for a longer pe- To select the target language, change the previous riod. Here we give an overview about the recent changes: command name “#USE” to “#LANGUAGE”. Fortran90 output has been available since the To access global variables, change “USE gdata” to preliminary version “1.1-f90-alpha12” provided in “USE root_global”. Sander et al. (2005). Rename all inline types “*_DECL” and “*_DATA” to Matlab is a new target language (see Sect. 4.4). “*_GLOBAL”. The set of integrators has been extended with a gen- If you have already used the Fortran90 output of the eral Rosenbrock integrator, and the corresponding preliminary version “1.1-f90-alpha12” from Sander et al. tangent linear and adjoint methods. (2005), these changes are also necessary: The KPP-generated Fortran90 code has a different file structure than the C or Fortran77 output (see Change “#USE Fortran95” to “#LANGUAGE Sects. 4.2 and 4.3). Fortran90”. An automatically generated Makefile facilitates Change the names of the indices of the species from the compilation of the KPP-generated code (see “kpp_*” to “ind_*”. Sect. 4.1.18). Rename all inline types from “F95_*” to “F90_*”. Equation tags provide a convenient way to refer to specific chemical reactions (see Sect. 4.1.5). Since the name of the initialization subroutine has changed, replace The dummy index allows to test if a certain species occurs in the current chemistry mechanism. (see USE ROOT_Init, ONLY: initval Sect. 3.2.3). CALL initval Lines starting with “//” are comment lines. by
USE ROOT_Initialize, ONLY: initialize CALL initialize Sandu & Sander: KPP User Manual 27
8 Acknowledgements
Parts of this user manual are based on the thesis of Damian-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 of Iowa, USA, 1996. Hairer, E. and Wanner, G.: Solving Ordinary Differential Equations II. Stiff and Differential-Algebraic Problems., Springer-Verlag, Berlin, 1991. Hairer, E., Norsett, S., and Wanner, G.: Solving Ordinary Differential 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 Mathematical Software, 14, 61, 1986. Radhakrishnan, K. and Hindmarsh, A.: Description and use of LSODE, the Livermore solver for differential equations, NASA reference publication 1327, 1993. Sander, R., Kerkweg, A., J¨ockel, P., and Lelieveld, J.: Technical Note: The new comprehensive atmospheric chemistry 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.: Benchmarking stiff ODE solvers for atmospheric chemistry problems II: 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. 28 Sandu & Sander: KPP User Manual
A BNF Description of the KPP Language
Following is the BNF-like specification of the language: program ::= module | module program
module ::= section | command | inline code
section ::= #ATOMS atom definition list | #CHECK atom list | #DEFFIX species definition list | #DEFVAR species definition list | #EQUATIONS equation list | #INITVALUES initvalues list | #LOOKAT species list atom list | #LUMP lump list | #MONITOR species list atom list | #SETFIX species list plus | #SETVAR species list plus | #TRANSPORT species list
command ::= #CHECKALL | #DOUBLE [ ON | OFF ] | #DRIVER driver name | #DUMMYINDEX [ ON | OFF ] | #EQNTAGS [ ON | OFF ] | #FUNCTION [ AGGREGATE | SPLIT ] | #HESSIAN [ ON | OFF ] | #INCLUDE file name | #INTEGRATOR integrator name | #INTFILE integrator name | #JACOBIAN [ OFF | FULL | SPARSE_LU_ROW | SPARSE_ROW ] | #LANGUAGE [ Fortran90 | Fortran77 | C | Matlab ] | #LOOKATALL | #MEX [ ON | OFF ] | #MODEL model name | #REORDER [ ON | OFF ] | #STOCHASTIC [ ON | OFF ] | #STOICMAT [ ON | OFF ] | #TRANSPORTALL
inline code ::= #INLINE inline type inline code #ENDINLINE Sandu & Sander: KPP User Manual 29
atom count ::= integer atom name | atom name atom definition list ::= atom definition | atom definition atom definition list atom list ::= atom name; | atom name; atom list equation ::=