Home

KPP-2.1 User`s Manual

1. 3 3 5 Inline type F90_RCONST F90_RCONST can be used to define time dependent values of rate coefficients that were declared with F90_GLOBAL INLINE F90_RCONST k_DMS_OH 1 E 9 EXP 5820 temp C ind_02 amp 1 E30 5 EXP 6280 temp C ind_02 ENDINLINE 3 3 6 Inline type F90_UTIL F90_UTIL can be used to define utility subroutines 3 4 Auxiliary files and the substitution preprocessor The auxiliary files listed in Table 4 are templates for in tegrators drivers and utilities They are inserted into the KPP 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_ROOT and KPP_REAL are needed because the other values can also be obtained via the variables listed in Tab 8 KPP_REAL is replaced by the appropriate single or double precision declaration type Depending on the target lan guage KPP will select the correct declaration type For Sandu amp 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_RCO
2. KPP 2 1 User s Manual The Kinetic PreProcessor KPP An Environment for the Simulation of Chemical Kinetic Systems Adrian Sandu amp Rolf Sander Department of Computer Science Virginia Polytechnic Institute and State University Blacksburg Virginia 24060 USA sandu cs vt edu t Air Chemistry Department Max Planck Institute of Chemistry PO Box 3060 55020 Mainz Germany sander mpch mainz mpg de 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 Contents Installation Running KPP with an Example Strato spheric Mechanism Input for KPP 3 1 KPP sections a 3 1 1 Atom definitions ATOMS 3 1 2 Mass balance checking CHECK 3 1 3 Species definitions DEFVAR and DEFFIX Equations EQUATIONS Initial values 4 INITVALUES Output data selection LOOKAT and MONITOR as ota ms 3 1 4 3 1 5 3 1 6 3 1 7 3 1 8 Lump species definitions LUMP Redefining species definitions SETVAR and SETFIX 3 1 9 Transport TRANSPORT 3 2 KPP commands 3 2 1 Precision control DOUBLE 3 2 2 Driver selection DRIVER 3 2 3 Dummy indices 4DUMMYINDEX 3 2 4 Generation of equation tags EQNTAGS zs Satu Railu The function generation F
3. DUMMYINDEX It is possible to declare species in the SPECIES section that are not used in the EQUATIONS section If your model needs to check at run time if a certain species is included in the current mechanism you can set 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 fined variables For example if you frequently switch be tween mechanisms with and without sulfuric acid you can use this code IF ind_H2S04 0 THEN PRINT no H2804 in current mechanism ELSE PRINT c H2S04 C ind_H2S04 ENDIF 3 2 4 Generation of equation tags EQNTAGS Each reaction in the EQUATIONS section may start with an equation tag which is enclosed in angle brackets e g lt Jt gt N02 hv NO 0 0 533 SUN With EQNTAGS set to ON this equation tag can be used to 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 are generated to compute the production destruction terms for variable species AGGREGATE generates one function that computes the normal derivatives SPLIT generates two functions for the derivatives in production and de struction forms Sandu amp Sander KPP User Manual 3 2 6 Generation of Hessian HESSIAN The option ON the default of the
4. i e JVRP OARP OV 13 The matrix JVRP is sparse and is computed and stored in row compressed sparse format as shown in Table 13 The parameter NJVRP holds the number of nonzero elements For our example NJVRP 13 CROW_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 formulation allows a direct computation of the derivatives with respect to rate coefficients 18 The subroutine dFun_dRcoeff computes the partial derivative DFDR of the ODE function with respect to a subset of NCOEFF reaction coefficients whose indices are specifies in the array JCOEFF DFDR OVdot ORCT JCOEFF 14 Similarly one can obtain the partial derivative of the Jaco bian with respect to a subset of the rate coefficients More exactly KPP generates the subroutine dJac_dRcoeff which calculates DJDR the product of this partial deriva tive with a user supplied vector DJDR 0JVS 0RCT JCOEFF x 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 the following functions Propensity calculates the propensity vector The propen sity function uses the number of molecules of variable Nm1cV and fixed NmlcF species as well as the stochas tic rate coefficients SCT to calculate the vector of propen sity rates Propensity The propensity Prop defines the probability that th
5. m 3 27 m2 1 29 1 1 29 EB 1 29 Q 0 Q2 1 yi Y ee Ros 3 3 2 3 2 L stable a21 1 a3 1 a32 0 C2 1 1 015 C3 1 4 075 C3 2 9 207 M1 1 m2 6 169 m3 0 427 ey 0 5 ez 2 908 e3 0 223 ay 0 ag 0 436 ag 0 436 y 0 436 92 0 243 y3 2 185 Ros 4 4 3 4 3 L stable a21 2 Q3 1 868 a3 2 0 234 a4 1 43 1 44 2 43 2 a4 3 0 C2 1 7 137 C3 1 2 581 639 0 652 C4 1 2 137 c42 0 321 c43 0 695 m 2 256 m 0 287 m3 0 435 ma 1 094 e1 0 282 e gt 0 073 e3 0 108 e4 1 098 a1 0 az 1 146 ag 0 655 A4 a3 J1 0 573 yo 1 769 y3 0 759 y4 0 104 Rodas 3 4 3 3 2 Stiffly a21 0 31 2 a3 2 0 a41 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 8 m 2 Mo 0 m3 1 m4 1 ey 0 e2 0 e3 0 e4 1 a 0 ag 0 ag 1 a4 1 11 0 5 Jo 1 5 YET 0 V4 0 Rodas 4 6 5 4 3 Stifly a 0 ag 0 386 a3 0 210 a4 0 630 as 1 ag 1 accurate y 0 25 y2 0 104 y3 0 104 y4 0 036 y5 0 Y 0 G2 1 1 544 3 1 0 946 a3 2 0 255 a4 3 314 Q4 2 2 896 a4 3 0 998 a5 1 1 221 a5 2 6 019 45 3 12 537 5 4 0 687 a6 1 45 15 a6 2 d5 2 46 3 5 3 46 4 a5 4 46 5 1 C2 1 5 668 C3 1 2 430 C3 2 0 206 ca 1 0 107 c4 2 9 594 c43 2
6. 16 4 1 13 ROOT_LinearAlgebra f90 16 4 1 14 ROOT _Stoichiom 90 and ROOT_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 and ROOT_mex_Hessian f90 18 4 1 18 The Makefile 18 4 2 TheCCode 18 4 3 The Fortran77 Code 19 4 4 The Matlab Code 19 4 5 The mapfile 20 5 KPP Internal Structure 20 5 1 KPP directory structure i 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 amp Sander KPP User Manual 6 Numerical methods 6 1 Rosenbrock Methods 6 1 1 Tangent Linear Model 6 1 2 The Discrete Adjoint 6 2 Runge Kutta methods 6 2 1 Tangent Linear Model 6 2 2 Discrete Adjoint Model 6 3 Backward Differentiation Formulas 7 Differences between KPP 2 1 and Previous Versions 7 1 New features of KPP 2 1 7 2 Upgrading KPP input files from previous versions to KPP 2 1 8 Acknowledgements A BNF Description of the KPP Language 1 Installation This section can be skipped if KPP is already installed on your system If you work under Linux you can probably use th
7. HESSIAN command turns the Hessian generation on see Sect 4 1 12 With OFF it is switched off 3 2 7 File include command INCLUDE The INCLUDE command instructs KPP to look for the file specified as a parameter and parse the content of this file before proceeding to the next line This allows the atoms definition the species definition and even the equation definition to be shared between several models Moreover 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 8 Integrator selection and INTFILE INTEGRATOR 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 the integrator 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 The appropriate suffix 90 f c or m is appended and the result selects the file from which the integrator is taken This file will be copied into the code file in the appropri ate place All integrators have to conform to the
8. Hessian of the small_strato example time step y a scalar parameter depending on the method 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 The chemical Jacobians are typically sparse i e only a relatively small number of entries are nonzero The spar sity structure of P is given by the sparsity structure of the Jacobian and is produced by KPP with account for the fill in as discussed above KPP generates the sparse linear algebra subroutine KppDecomp 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 nonzero if singularity is detected The subroutines KppSolve and KppSolveTR use the in 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 by Sandu et al 1996 4 1 14 ROOT Stoichiom f90 and ROOT StoichiomSP f90 These files contain a description of the chemi cal mechanism in stoichiometric form The file ROOT_Stoichiom f90 contains the functions for reactant products and its Jacobian and derivatives with respect to rate coefficients The declaration and i
9. Table 20 BDF methods implemented in KPP Method File s Description LSODE LSODES VODE ODESSA kpp_lsode 90 LSODE the Livermore ODE solver Radhakrishnan and Hind atm_lsodes f kpp_dvode f atm_odessa f 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 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 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 The BDF based direct decoupled sensitivity integrator Odessa Leis and Kramer 1986 has been modified to use the KPP sparse linear algebra routines between KPP 2 1 and Previous Versions Differences New features of KPP 2 1 This user manual describes recently added features of KPP as 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 the preliminary version 1 1 f90 alphal2 provided in Sander 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 corresponding
10. by USE ROOT_Initialize ONLY CALL initialize initialize Sandu amp Sander KPP User Manual 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 lordache 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 ckel 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
11. chemical mechanism The names of all species are included in SPC_NAMES and the names 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 which is enclosed in angle brackets e g lt J1 gt N02 hv NO 0 0 533 SUN If the equation tags are switched on KPP also gener ates the PARAMETER array EQN_TAGS In combination with EQN_NAMES and the function tag2num that converts the equation tag to the KPP internal equation number this can be used to describe a reaction PRINT Reaction Ji is amp EQN_NAMES tag2num J1 4 1 6 ROOT_Precision f90 Fortran90 code uses parameterized real types ROOT_Precision f90 contains the following real kind definitions KPP_SP Single precision kind INTEGER PARAMETER amp SP SELECTED_REAL_KIND 6 30 KPP_DP Double precision kind INTEGER PARAMETER amp DP SELECTED_REAL_KIND 12 300 Sandu amp 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_
12. dition the KPP numerical integrators preserve the linear invariants i e mass of the chemical system KPP implements several Rosenbrock methods Ros 1 and 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 of them KPP implements the tangent linear model direct decoupled sensitivity and the adjoint models The imple mentations distinguish between sensitivities with respect to 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 also provides application programming templates Some mini mal programming may be required from the users in order to construct their own application from the KPP building blocks In order to offer more control over the integrator the KPP generated subroutine INTEGRATE provides the op tional input parameters ICNTRL_U and RCNTRL_U Each of them is an array of 20 elements that allow the fine tuning of the integrator e g by setting a particular integrator method tolerances minimum and maximum step sizes Sandu amp 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 t Discrete time moment h Time step h t t y Numerical solution co
13. 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 source file Instead of using an intermediate format for this as some other compilers do KPP generates the intermedi ate format for just one statement at a time The vast majority of the statements in the target source file are assignments The expression tree for each assignment is incrementally build by scanning the coefficient matrices and the rate constant vector At the end these expres sion trees are simplified Similar approaches are applied to function declaration and prototypes data declaration and initialization 5 3 4 Code generation There are basically two modules each dealing with the syntax particularities of the target language For exam ple the C module includes a function that generates a valid C assignment when given an expression tree Sim ilarly there are functions for data declaration initializa tions comments function prototypes etc Each of these 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 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 medium accuracy regime relative errors 10 10 In ad
14. working precision for the whole model 4 1 7 ROOT Rates f90 The code to update the rate constants is in ROOT_Rates f90 The user defined rate law functions are also placed here 4 1 8 ROOT_Parameters f90 The global parameters Table 8 are defined and initialized in ROOT_Parameters f90 KPP orders the variable species such that the sparsity pattern of the Jacobian is maintained after an LU decom position For our small_strato example there are five variable species NVAR 5 ordered as ind_01D 1 ind_NO 4 ind_0 2 ind_N02 5 ind_03 3 and two fixed species NFIX 2 ind_M 6 ind_02 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 in the sparse Jacobian and in the sparse Hessian etc Some important simulation parameters generated by KPP are presented in Table 8 Sandu amp Sander KPP User Manual Table 8 List of important simulation parameters and their values for the small_strato example Parameter Represents Value NSPEC No chemical species 7 NVAR No variable species 5 NFIX No fixed species 2 NREACT No reactions 10 NONZERO No nonzero entries Jacobian 18 LU_NONZERO As above after LU factorization 19 NHESS Length sparse Hessian 10 NJVRP Length sparse Jacobian JVRP 13 NSTOICM Length stoichiometric matrix 22 ind_spc Index of species spc in C indf_spc Index of fi
15. 0 47 c51 7 496 C5 2 0 124 C5 3 34 C5 4 11 708 C6 1 8 083 Cg 2 7 981 cg 3 31 521 ce 16 319 cg 5 6 058 Ma 45 1 M2 d5 2 M3 45 3 M4 G54 M5 1 mg 1 er 0 e2 0 e3 0 e4 0 e5 0 eg 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 2 2 4 The implementations distinguish between sensitivities HAJT E y D yiti y v i 1 i 1 Ar AS H y x ki u t with respect to initial values and sensitivities with respect t ters for effici A VVA ST 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 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 6 2 Runge Kutta methods j t 1 i vu J T Yi uj i s s 1 1 Ti s tah W y h dijkj j l Sandu amp 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
16. 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 by appending the suffix _Main f90 to the ROOT name Sandu amp Sander KPP User Manual E 13 Update_Rconst 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 The file ROOT_Model f90 completely defines the model by using all the associated modules 4 1 3 ROOT_Initialize f90 The file ROOT Initialize f90 contains the subroutine Initialize which defines initial values of the chemical species The driver calls the subroutine Initialize once before 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 during the 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 arrays with information about the
17. 8 Create the kpp executable with make Sandu amp Sander KPP User Manual 2 Running KPP with an Example Stratospheric Mechanism Here we consider as an example a very simple Chapman like mechanism for stratospheric chemistry O 1 20 1 0 02 gt O 2 Od O 0 3 O 03 202 4 Os O D 02 5 O D M gt O M 6 O D 03 gt 202 7 NO 0O3 NO2 02 8 NOz O gt NO 02 9 NO NO 0 10 We use the mechanism with the purpose of illustrating the KPP capabilities However the software tools are general and 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 the driver etc The file name without the suffix kpp serves as the root name for the simulation In this paper we will refer to this name as ROOT Since the root name will be incorporated into Fortran90 module names it can only contain valid Fortran90 characters i e letters numbers and the underscore To specify a KPP model write a ROOT 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 the code generated by
18. 91 While Radau5 is relatively expensive when com pared to the Rosenbrock methods it is more robust and is 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 Runge Kutta method is byt Sy thd biti 20 i 1 OY by h ijb j l t J T Y 6Y The system 20 is linear and does not require an iterative procedure However even for a SDIRK method a 0 for i gt j and aj y each stage requires the LU factor ization of a different matrix No Runge Kutta tangent linear model is currently imple mented in KPP For b 0 the Runge Kutta adjoint can be rewritten as another Runge Kutta method ui KJT T Y a S 22 j l A AHY bju j 1 No Runge Kutta adjoint model is currently implemented in KPP 6 3 Backward Differentiation Formulas Backward differentiation formulas BDF are linear mul tistep methods with excellent stability properties for the integration of chemical systems Hairer and Wanner 1991 Section V 1 The k step BDF method reads k Day Smee 23 i 0 where the coefficients a and 8 are chosen such that the method has order of consistency k The KPP library contains two off the shelf highly popular implementations of BDF methods described in Table 20 26 7 7 1 Sandu amp Sander KPP User Manual
19. E inline_type inline_code ENDINLINE Sandu amp Sander KPP User Manual Sandu amp Sander KPP User Manual atom_count atom_definition_list atom_list equation eguation_list expression initvalues_assignment initvalues_list inline_type lump lump_list lump_sum rate species_composttion species_definition species_defin tion_list species_list species_list_plus species_name_plus term integer atom_name atom_name atom_definition atom_definition atom_definition_list atom_name atom_name atom_list lt equation_tag gt expression expression rate expression expression rate equation equation equation_list term term expression term expression species_name_plus program_expression CFACTOR program_expression initvalues_assignment initvalues_assignment initvalues_list F90_RATES F90_RCONST F90_GLOBAL F90_INIT F90_DATA F90_UTIL F77_RATES F77_RCONST F77_GLOBAL F77_INIT F77_DATA F77_UTIL C_RATES C_RCONST C_GLOBAL C_INIT C_DATA C_UTIL MATLAB_RATES MATLAB_RCONST MATLAB_GLOBAL MATLAB_INIT MATLAB_DATA MATLAB_UTIL lump sum species_name lump lump lump_list species_name species_name lump_sum number program_expression atom_count atom_count spectes_composition IGNORE species_name species_composition species_definition sp
20. ESS 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 derivative function is smooth these Hessian matrices are symmet ric HESS x HESS kj KPP stores only those entries HESS jx with j lt k The sparsity coordinate vectors IHESS_I IHESS_J and IHESS_K are computed by KPP and initialized statically They are constant as the spar sity pattern of the Hessian does not change during the computation 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 file ROOT_LinearAlgebra f90 To numerically solve for the chemical concentrations one must employ an implicit timestepping technique as the system is usually stiff Implicit integrators solve systems of the form Pxr I hyJ x b 12 where the matrix P I hyJ is refered to as the pre diction matrix J the identity matrix h the integration Sandu amp Sander KPP User Manual 2 2 2 2 2 2 2 2 2 2 dff dy dft dy df dy dt dy df dy 1 e 1 1 e 1 1 2 2 e 2 e 2 e 2 e 31 3 e 3 ve e 3 e 3 e 4 4 4 4 e 4 e 5 5 5 5 5 e 12345 12345 12345 12345 12345 nz 2 nz 4 nz 6 nz 4 nz 4 17 Figure 3 The
21. Hessian f90 HessTR_Vec Transposed Hessian action on vectors ROOT_Hessian f90 dFun_dRcoeff dJac_dRcoeff Derivatives of Fun with respect to rate coefficients Derivatives of Jac with respect to rate coefficients ROOT_Stoichiom f90 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_RCONST Update photolysis rate coefficients Update all rate coefficients ROOT_Rates f90 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_user2kpp InitSaveData SaveData CloseSaveData tag2num Shuffle concentration vector Shuffle concentration vector Utility for LOOKAT command Utility for LOOKAT command Utility for LOOKAT command Calculate reaction number from equation tag ROOT_Util f90 ROOT_Util f90 ROOT_Util f90 ROOT_Util f90 ROOT_Util f90 ROOT_Util f90 Depending on the choice of the 4DOUBLE command the real 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 module will cause a change in the
22. KPP is selected with the command LANGUAGE Fortran90 Here we have chosen Fortran90 See Sect 3 2 10 for other options 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 Sandu amp Sander KPP User Manual integration routine from the templates provided by KPP or implemented by the user and the DRIVER command selects a specific main program The MODEL command selects a specific kinetic mechanism In our example the model definition file small_strato def includes the species and the equation files INCLUDE small_strato spc INCLUDE small_strato eqn The species file lists all the species in the model Some of them are variable defined with DEFVAR meaning that their concentrations change according to the law of mass action kinetics Others are fixed defined with DEFFIX with the concentrations determined by physical and not chemical factors For each species its atomic composition is given unless the user chooses to ignore it The atom file lists the periodic table of elements in an ATOM section The equation file contains the description of the equations in an EQUATIONS section INCLUDE atoms DEFVAR 0 01D 03 NO N02 DEFFIX M 02 I 22000 ooo oe R o IGNORE 0 0 The chemical kinetic mechanism is specified in the KPP language in the file small_strato eq
23. NST 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 dJac_dRcoeff f90 Makefile f90 Mex_Fun f90 mex files Mex_Jac_SP f90 mex files Mex_Hessian f90 mex files sutil f90 tag2num f90 UpdateSun f90 UserRateLaws f90 util f90 derivatives with respect to reaction rates derivatives with respect to reaction rates unix makefiles Sparse utility functions Function related to equation tags Function related to solar zenith angle User defined rate law functions 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 line will be automatically translated into REAL dp BIG 1000 and when used with the option DOUBLE OFF the same line will become REAL sp BIG 1000 in the resulting Fortran90 output file KPP_ROOT is replaced by the ROOT file name of the main kinetic description file In our example where we are pro cessing small_strato kpp a line in an auxiliary Fortran90 file 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
24. P generates the mex rou tines for the ODE function Jacobian and Hessian for the target languages C Fortran77 and Fortran90 After compilation 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 user only has to insert the mex string within the corresponding function name Replacing m functions by mex functions gives the same numerical results but the computational time could be considerably smaller especially for large ki netic systems If possible we recommend to build mex files using the C language as Matlab offers most mex interface options for the C language Moreover Matlab distributions come with a native C compiler lcc for building executable functions from mex files Fortran77 mex files work well on most platforms without additional efforts However the mex files built using Fortran90 may require further platform 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 is Makefile_ROOT The Makefile assumes that the selected driver contains the main program However if no driver was selected i e DRIVER none it is necessary to add the 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 and numerical integrator functi
25. P_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 e The option list Error checking is performed at each step in the scanner and the parser For each syntax error the exact line and input file along with an appropriate error message are produced In most of the cases the exact cause of the error can be identified therefore the error messages are very precise Some other errors like mass balance and equation duplicates are tested at the end of this phase 5 3 2 Species reordering 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 in which they appear in the equation description section This is not a useful order for subsequent operations The species have to be first sorted such that all variable species and all fixed species are put together Then if a sparsity structure of the Jacobian is required it might be better to reorder the species in such a way that the factorization of the Jacobian will preserve the sparsity This reordering is done using a Markovitz type of algorithm 5 3 3 Expression trees computation This is the core of the preprocessor This module has to generate the production destruction
26. R The concentrations of fixed species are parameters in the derivative function The subroutine Fun computes first the vector A of reaction rates and then the vector Vdot of variable species time derivatives The input arguments V 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 ODE function of our small_strato example SUBROUTINE Fun V F RCT Vdot REAL kind DP V NVAR amp F NFIX RCT NREACT amp Vdot NVAR A NREACT amp Computation of equation rates A 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 AT 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 function Vdot 1 A 5 A 6 A 7 Vdot 2 2 A 1 A 2 A 3 amp A 4 A 6 A 9 A 10 Vdot 3 A 2 A 3 A 4 A 5 amp 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 and ROOT_JacobianSP 90 The sparse data structures for the Jacobian are de clared and initialized in ROOT_JacobianSP f90 The code for the ODE Jacobian and sparse multiplications is in ROOT_Jacobian f90 The Jacobian of the ODE func tion is automatically constructed by KPP KPP generates the Jacobian subroutine Jac or Jac_SP where the latter is generated when the
27. UNCTION Generation of Hessian HESSIAN File include command INCLUDE Integrator selection INTEGRATOR and INTFILE so ba a a 3 2 9 The Jacobian JACOBIAN 3 2 10 Target LANGUAGE 3 2 11 Mex files MEX 3 2 12 Selcting a chemical model MODEL 3 2 13 Reordering REORDER 3 2 14 Stochastic simulation STOCHASTIC 3 2 15 The Stoichiometric STOICMAT 3 2 16 Shorthand commands CHECKALL LOOKATALL and TRANSPORTALL 3 3 Inlined coden i suka ats vaaks Se ay 3 3 1 Inline type F9O_DATA 3 3 2 Inline type F90_GLOBAL 3 2 5 3 2 6 3 2 7 3 2 8 language selection Formulation Sandu amp Sander KPP User Manual 3 3 3 Inline type F9O_LINIT 10 3 3 4 Inline type F90_RATES 10 3 3 5 Inline type F90_RCONST 10 3 3 6 Inline type F9OUTIL 10 3 4 Auxiliary files and the substitution prepro CESSO nears Pe ee ae ae ee a kd 10 4 Output from KPP 11 4 1 The Fortran90 Code 11 4 1 1 ROOTMain f90 12 4 1 2 ROOTModel f90 13 4 1 3 ROOT _Initialize f90 13 4 1 4 RooT_Integrator f90 13 4 1 5 ROOTMonitor f90 13 4 1 6 ROOT Precision f90 13 4 1 7 ROOTRates f90 14 4 1 8 ROOT_Parameters f90 14 41 9 ROOT_Global f90 15 4 1 10 ROoOT_Function f90 15 4 1 11 ROOT_Jacobian 90 and ROOT_JacobianSP f90 15 4 1 12 ROOT_Hessian f90 and ROOT_HessianSP f90
28. 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 27 28 A BNF Description of the KPP Language Following is the BNF like specification of the language program module section command inline_code module module program section command inline_code 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 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 INLIN
29. an Table 11 the stoichiometric matrix Ta ble 12 and the Jacobian of reaction products Table 13 are declared as Matlab global variables in the file ROOT_Sparse_defs m They are initialized in separate m files namely ROOT_JacobianSP m ROOT_HessianSP m and ROOT_StoichiomSP m respectively 20 Two wrappers ROOT_Fun_Chem m and ROOT_Jac_SP_ 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 matches the syntax reguired by Matlab s integrators like odel5s Moreover the Jacobian wrapper converts the sparse 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 code file plus a summary of the numbering and category of the species involved This file contains supplementary information for the user Several statistics are listed here like the total number equations the total number of species the number of vari able and fixed species Each species from the chemical mechanism 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 is attached containing also the meaning of the input and output parameters 5 KPP Internal Structure T
30. complete descrip tion of how it was generated at the begining of the file The files 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 structures are encapsulated in modules There is exactly one module in each file and the name of the module is identical to the file name but without the suffix 90 Fig 1 shows how these modules are related to each other A concise list of the main subroutines generated by KPP is shown in Table 7 The generated code is consistent with the For tran90 standard It will not exceed the maximum number of 39 continuation lines If KPP cannot properly split an expression to keep the number of continuation lines be low the threshold then it will generate a warning message pointing to the location of this expression 12 Table 5 List of symbols replaced by the substitution preprocessor with their particular values for the simulation at hand Table 6 List of model files generated by KPP for Fortran90 Sandu amp Sander KPP User Manual 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 el
31. 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 the species The order of the variables is the order in which the species are declared in the DEFVAR section 10 3 2 14 Stochastic simulation STOCHASTIC The option ON of the STOCHASTIC command turns on the generation of code for stochastic kinetic simulations see Sect 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 for the stoichiometric matrix the vector of reactant products in each reaction and the partial derivative of the time derivative function with respect to rate coefficients These elements are discussed in Sect 4 1 14 3 2 16 Shorthand commands LOOKATALL and TRANSPORTALL CHECKALL KPP defines a couple of shorthand commands The commands that fall into this category are CHECKALL LOOKATALL and TRANSPORTALL All of them have been described in the previous sections 3 3 Inlined code In order to offer maximum flexibility KPP allows the user to include pieces of code in the kinetic description file Inlined code begins on a new line with INLINE and the inline_type Next one or more lines of code follow written in the target language Fortran90 Fortran77 C or Mat lab as specified by the inline_type The inlined code ends with ENDINLINE The code is insert
32. e 13 These sparse data structures are initialized in four named block data statements JACOBIAN_SPARSE_ DATA in ROOT_HessianSP f HESSIAN_SPARSE_DATA in ROOT_HessianSP f JVRP_SPARSE_DATA and STOICM_ MATRIX in ROOT_StoichiomSP f The code for the ODE function Sect 4 1 10 is in ROOT_Function f The code for the ODE Jaco bian and sparse multiplications Sect 4 1 11 is in ROOT_Jacobian f The Hessian function and as sociated sparse multiplications Sect 4 1 12 are in ROOT_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 19 and initialization of the stoichiometric matrix and the as sociated sparse data structures Tables 12 and 13 is done in the STOICM_MATRIX block data statement Sparse linear algebra routines Sect 4 1 13 are in the file ROOT_LinearAlgebra f The code to update the rate constants is in ROOT_Rates f and the utility and in put output functions Sect 4 1 16 are in ROOT_Util f and 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 numerical computations and data analysis and visualization The KPP generated Matlab code allows for a rapid
33. e checking only for the list of atoms specified in the CHECK section e g CHECK N C 0 The balance checking for all atoms can be enabled by using the CHECKALL command Without CHECK or CHECKALL no checking is performed The IGNORE atom can also be used to control mass balance checking Sandu amp Sander KPP User Manual 3 1 3 Species definitions DEFVAR and DEFFIX There are two ways to declare new species together with their atom composition DEFVAR and DEFFIX These sections define all the species that will be used in the chem ical mechanism Species can be variable or fixed The type is implicitly specified by defining the species in the appropriate sections A species can be considered fixed if its concentration does not vary too much The vari able species are medium or short lived species and their concentrations vary in time This division of species into different categories is helpful for integrators that benefit from 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 declare the predefined atom IGNORE as being part of the species composition Examples for these sections are DEFVAR NO2 N 20 CH300H C 4H 20 HSO4m IGNORE RCHO IGNORE DEFFIX C02 C 20 3 1 4 Equations EQUATIONS The c
34. e next reaction in the system is the j reaction StochasticRates converts deterministic rates to stochas tic The stochastic rate coefficients SCT are obtained through a scaling of the deterministic rate coefficients RCT The scaling depends on the Volume of the reaction container and on the number of molecules which react MoleculeChange calculates changes in the number of molecules 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 is updated by the function These functions are used by the Gillespie numerical in tegrators direct stochastic simulation algorithm These integrators are provided in both Fortran90 and C imple mentations the template file name is gillespie Drivers for 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 in ROOT_Util f90 In addition to the chemical system description routines discussed above KPP generates several utility routines some of which are summarized in Table 7 The subroutines InitSaveData SaveData and CloseSaveData can be used to print the concentra tion of the species that were selected with LOOKAT to the file ROOT dat Sandu amp Sander KPP User Manual 4 1 17 ROOT_mex_Fun f90 ROOT _mex_Jac_SP 90 and ROOT_mex_Hessian f90 Mex is a Matlab extension KP
35. e precompiled executable file that is in the bin di rectory of the distribution Then you only have to define the KPP_HOME environment variable 1 Define the KPP_HOME environment variable to point to the complete path where KPP is installed Also add the path of the KPP executable to the PATH environment variable If for example KPP is in stalled in HOME kpp under the C shell you have to edit the file HOME cshrc and add setenv KPP_HOME HOME kpp setenv PATH PATH KPP_HOME bin If you use the bash shell edit HOME bashrc and add export KPP_HOME HOME kpp export PATH PATH KPP_HOME bin After editing cshrc or bashrc start a new shell to make 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 installed on your machine Type flex version to test this Note down the exact path name where the flex library is installed The library is called libfl a or libf1 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 the flex library etc
36. ecies_definition species_definition_list species_name species_name species_list species_name_plus species_name_plus species_list_plus species_name VAR_SPEC FIX_SPEC ALL_SPEC number species_name species_name hv 29
37. ed into the KPP out put at a position which is also determined by inline_type as explained in Table 3 If two inline commands with the same inline type are declared then the contents of the 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 F77_ C_ or MATLAB_ respectively 3 3 1 Inline type F90_DATA This inline type was introduced in a previous version of KPP to initialize variables It is now obsolete but kept for compatibility For Fortran90 F90_GLOBAL should be used instead 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_GLOBAL REAL dp k_DMS_OH ENDINLINE Sandu amp Sander KPP User Manual 3 3 3 Inline type F90_INIT F90_INIT can be used to define initial values before the start of the integartion e g INLINE F90_INIT TSTART 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_RATES REAL FUNCTION k_SIV_H202 k_298 tdep cHp temp special rate function for S IV H202 REAL INTENT IN k_298 tdep cHp temp k_SIV_H202 k_298 amp EXP tdep 1 temp 3 3540E 3 amp cHp cHp 0 1 END FUNCTION k_SIV_H202 ENDINLINE
38. ements 18 KPP_LU_NONZERO number of Jacobian nonzero elements with LU fill in 19 KPP_NHESS number of Hessian nonzero elements 10 circumstances as specified in the third column Optional files are only produced under certain File Description Only if see Sect ROOT_Main f90 Driver DRIVER 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 f 90 Utility input output 4 1 16 ROOT_Jacobian f90 ODE Jacobian 4 1 11 ROOT_JacobianSP f90 Jacobian sparsity JACOBIAN SPARSE_x 4 1 11 ROOT_Hessian f90 ODE Hessian HESSIAN ON 4 1 12 ROOT_HessianSP f90 Sparse Hessian data HESSIAN ON and JACOBIAN SPARSE_x 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_x 4 1 17 ROOT_mex_Hessian f90 Matlab interface Hess MEX ON and HESSIAN ON 4 1
39. g general rules define the structure of a kinetic description file e A KPP program is composed of KPP sections KPP commands and inlined code Their syntax is pre sented in the appendix e Comments are either enclosed between the curly braces and or written in a line starting with two slashes e Any name given by the user to denote an atom or a species is restricted to be less than 32 character in length and can only contain letters numbers or the underscore character The first character cannot be a 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 accepts only one of these files as input but using the INCLUDE command code from separate files cn be combined The include files can be nested up to 10 levels KPP will parse these files as if they were a single big file By carefully splitting the chemical description KPP can be configured for a broad range of users In this way the users can have direct access to that part of the model that they are in terested in and all the other details can be hidden inside several include files Often a file with atom definitions is included first then species definitions and finally the equations of the chemical mechanism 3 1 KPP sections A sign at the beginning of a line followed by a section name star
40. hemical mechanism is specified in the EQUATIONS section Each equation is written in the natural way in which a chemist would write it e g EQUATIONS NO2 hv NO 0 0 533xSUN OH N02 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 each equation separated by a colon The rate coefficient does not necessarily need to be a numerical value Instead it can be a valid expression in the target language If there are several EQUATIONS sections in the input their contents 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 reaction rate For example the oxidation of methane can be writ ten as CH4 OH CH300 H20 02 k_CH4_0H 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 amp Sander KPP User Manual CH4 01D 75 CH302 75 OH 25 HCHO 4 H 05 H2 k_CH4_01D One restriction is that the list of products must not be empty If you have such a reaction e g the dry deposition of atmospheric species to the surface you can define a DUMMY species as the product 03 DUMMY v_d_03 The same equation must not occur twice in the EQUATIONS section For example yo
41. hich can be used as templates for building simulations with KPP Sandu amp Sander KPP User Manual 21 Table 14 List of Matlab model files File Description ROOT m driver ROOT_parameter_defs m ROOT_global_defs m ROOT_monitor_defs m ROOT_sparse_defs m Global parameters Global variables Global monitor variables Global sparsity data ROOT_Fun_Chem m ROOT_Fun m Template for ODE function ODE function ROOT_Jac_Chem m ROOT_Jac_SP m ROOT_JacobianSP m Template for ODE Jacobian ODE Jacobian in sparse format Sparsity data structures ROOT_Hessian m ROOT_HessianSP m ROOT_HessTR_Vec m ROOT_Hess_Vec m ODE Hessian in sparse format Sparsity data structures Hessian action on vectors Transposed Hessian action on vectors ROOT_stoichiom m ROOT_StoichiomSP m ROOT_ReactantProd m ROOT_JacReactantProd m Derivatives of Fun and Jac with respect to rate coefficients Sparse data Reactant products Jacobian of reactant products ROOT_rates m ROOT_Update_PHOTO m ROOT_Update_RCONST m ROOT_Update_SUN m User defined reaction rate laws Update photolysis rate coefficients Update all rate coefficients Update solar intensity ROOT_GetMass m ROOT_Initialize m ROOT_Shuffle_kpp2user m ROOT_Shuffle_user2kpp m Check mass balance for selected atoms Set initial values Shuffle concentration vector Shuffle concentration vector e site lisp Contains the file kpp el which provides a KPP m
42. his chapter is mainly concerned with describing the in ternal architecture of the KPP preprocessor It describes the basic modules and their functionalities and all the preprocessing analysis performed on the input files KPP can be very easily configured to suit a broad class of users 5 1 KPP directory structure The KPP distribution will unfold a directory KPP_HOME with the following subdirectories e src Contains the KPP source code files as listed in Table 15 e bin Contains the KPP executable The path to this directory needs to be added to the environment PATH variable e util Contains different function templates useful for the simulation Each template file has a suffix that matches the appropriate target language 90 f c or m KPP will run the template files through the substitution preprocessor The user can define their own auxiliary functions by inserting them into the files Sandu amp Sander KPP User Manual Table 15 Source code files File Description kpp c main program code c generic code generation functions code h header file code_c c generation of C code code_f77 c generation of Fortran77 code code_f90 c generation of Fortran90 code code_matlab c generation of matlab code debug c debugging output gdata h header file gdef h header file gen c generic code generation functions lex yy c flex yacc generated file scan h input for flex yacc scan l input for flex yacc scan y in
43. ian does not change during the computation Two other KPP generated routines Jac_SP_Vec and JacTR_SP_Vec are useful for direct and adjoint sensitivity analysis They perform sparse multiplication of JVS or its transpose for JacTR_SP_Vec with the user supplied vector UV without any indirect addressing Sandu amp Sander KPP User Manual Table 11 Sparse Hessian Data Variable Represents HESS NHESS IHESS_I NHESS IHESS_J NHESS IHESS_K NHESS Hessian nonzero elements H j k Index 7 of element H j k Index j of element Hi j k Index k of element H j k 4 1 12 ROOT_Hessian f90 and ROOT HessianSP f90 The sparse data structures for the Hessian are declared and initialized in ROOT_HessianSP f90 The Hessian 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 actly the Hessian is a 3 tensor such that 02 dc dt I kis Nyra 0c ock i ds Hizk 11 KPP generates the routine Hessian Using the variable 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 sian for our small_strato example is visualized in Fig 3 KPP computes the number of nonzero Hessian entries and saves it in the variable NHESS The Hessian itself is rep resented in coordinate sparse format The real vector H
44. le At the end of the integration the concentration of NO2 is computed by substraction 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 of an 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 for these sections are SETVAR ALL_SPEC SETFIX H20 C02 3 1 9 Transport TRANSPORT The TRANSPORT section is only used for transport chem istry models It specifies the list of species that needs to be 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 DUMMY INDEX 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 N02 C02 03 N One may use a more complex chemical model from which only a couple of species are considered for the transport calculations The TRANSPORTALL command is also avail able as a shorthand for specifying that all the species used in the chemical model have to be included in the tran
45. n Each reaction is described 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 zero at night EQUATIONS Stratospheric Mechanism lt Ri gt 02 hv 20 2 643E 10 SUN lt R2 gt 0 02 03 8 018E 17 lt R3 gt 03 hv 0 02 6 120E 04 SUN lt R4 gt 0 03 202 1 576E 15 lt R5 gt 03 hv 01D 02 1 070E 03 SUN lt R6 gt O1D M O M 7 110E 11 lt R7 gt 01D 03 202 1 200E 10 lt R8 gt NO 03 NO2 02 6 062E 15 lt R9 gt N02 0 NO 02 1 069E 11 lt R10 gt N02 hv NO 0 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 are in 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 initial values of each of the species involved the integration pa rameters and many other options The KPP preprocessor parses the kinetic description files and generates several output files Files that are written in KPP syntax have one of the suffixes kpp spc eqn or def An exception is the file atoms which has no suffix The followin
46. ncentration at t dy tangent linear solution at t A Adjoint numerical solution at t f The ODE derivative function y f t y fel Partial time derivative f t y Of t y 0t J The Jacobian J t y Of t y 0y Jr Partial time derivative of Jacobian J t y 0J t y 0t A The system matrix H The Hessian H t y 0 f t y Oy T Internal stage time moment for Runge Kutta and Rosenbrock methods Y Internal stage solution for Runge Kutta and Rosenbrock methods ki lis Ui Vi Internal stage vectors for Runge Kutta and Rosenbrock methods their tangent linear and adjoint models Qi Qij Qij bi Ci Cij i Mi Method coefficients and more The exact meaning of the elements depends on the integrator and may change in the future Please read 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 are both arrays of 20 elements and contain the length of the last time step the number of accepted and rejected steps the number of miscellaneous function calls and more 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 e
47. nitialization of the stoichiometric matrix and the associated sparse data structures is done in ROOT_StoichiomSP f90 The stoichiometric matrix is constant sparse For our example the matrix has NSTOICM 22 nonzero entries out of 50 entries KPP produces the stoichiometric matrix in sparse column compressed format as shown in Table 12 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_STOICM respectively The vector CCOL_STOICM contains point ers to the start of each column For example column j Table 12 Sparse Stoichiometric Matrix Global variable STOICM NSTOICM IROW_STOICM NSTOICM ICOL_STOICM NSTOICM CCOL_STOICM NREACT 1 Represents Stoichiometric matrix Row indices Column indices Start of columns Table 13 Sparse Data for Jacobian of Reactant Products Global variable JVRP NJVRP ICOL_JVRP NJVRP IROW_JVRP NJVRP CROW_JVRP NREACT 1 Represents Nonzero elements of JVRP Column indices in JVRP Row indices in JVRP 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 of sparse data structures The subroutine ReactantProd computes the reactant products ARP for each reaction and the subroutine JacReactantProd computes the Jacobian of reactant products vector
48. ode for emacs with color highlighting 5 2 KPP environment variables In order for KPP to find its components it has to know the path to the location where the KPP distribution is installed This is achieved by requiring the KPP_HOME environment variable to be set to the path where KPP is installed 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 the code generation phase We make use of the flex and yacc generic tools in implementing our own scanner and parser Using these tools this module gathers information from the input files and fills in the following data structures in memory e The atom list e The species list The left hand side matrix of coefficients The right hand side matrix of coefficients The equation rates 22 Sandu amp 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 KP
49. of order 5 based on Radau ILA 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 T Yy s 6 2 2 Discrete Adjoint Model where the coefficients a j b and c are prescribed for The first order Runge Kutta adjoint is the desired accuracy and stability properties The stage derivative values k are defined implicitly and require solv a 1 8 ing a set of nonlinear system s Newton type methods u RIT Y bAt 5 QjiUj 21 solve coupled linear systems of dimension at most n x s j 1 KPP numerical library implements a Radau5 a Runge yo yty D Kutta method of order 5 based on Radau IIA quadrature ze A J Hairer and Wanner 1991 Section IV 10 This numeri cal method is stiffly accurate The KPP implementation follows the original implementation of Hairer and Wanner 19
50. ons as well as declarations and initializations of global variables The generated C code includes three header files which are include d in other files as appropriate The global parameters Table 8 are define d in the header file ROOT_Parameters h The global variables Table 9 are extern declared in ROOT_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 Table 10 Hessian Table 11 stoichiometric matrix Table 12 and the Jacobian of reaction products Table 13 The actual declarations of each data structures is done in the corresponding files The code for the ODE function Sect 4 1 10 is in ROOT_Function c The code for the ODE Jaco bian and sparse multiplications Sect 4 1 11 is in ROOT_Jacobian c and the declaration and initialization of the Jacobian sparse data structures Table 10 is in the file ROOT_JacobianSP c Similarly the Hessian func tion and associated sparse multiplications Section 4 1 12 Sandu amp Sander KPP User Manual are in ROOT_Hessian c and the declaration and initial ization of Hessian sparse data structures Table 11 in ROOT_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 declaration and initialization of the stoichiometric matrix and the as sociated sparse da
51. proto typing of chemical kinetic schemes and for a convenient 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 numerical solutions which are then compared against the results obtained with user supplied numerical techniques Last but not least Matlab is an excellent environment for educational purposes KPP Matlab can be used to teach students fundamentals of chemical kinetics and chemical numerical 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 one m 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 The names of the m function files are the same as the names of the functions prefixed by the model name ROOT The Matlab syntax for calling each function is Vdot Fun V F RCT IVS Jac_SP V F RCT HESS Hessian V F RCT The global parameters Table 8 are defined as Matlab global variables and initialized in the file ROOT_parameter_defs m The variables of Table 9 are declared as Matlab global variables in the file ROOT_Global_defs m They can be accessed from within each Matlab function by using global declarations of the variables of interest The sparse data structures for the Jacobian Table 10 the Hessi
52. put for flex yacc scanner c evaluate parsed input scanutil c y tab c y tab h evaluate parsed input flex yacc generated file flex yacc generated header file models Contains the description of the chemical 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 mospheric chemistry which can be used as templates for model definitions drv Contains driver templates for chemical simula tions Each driver has a suffix that matches the ap propriate target language 90 f c or m KPP will 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 sets the function type the Jacobian sparsity type the target language etc Each integrator template is found in a file that ends with the appropriate suffix 90 f c or m The selected template is pro cessed by the substitution preprocessor Users can define here their own numerical integration routines examples Contains several model description ex amples kpp files w
53. rocessor what are the species for which the evolution of the concentration should be saved in a data file By default if no LOOKAT section is present all the species are saved If an atom is specified in the LOOKAT list then the total mass of the particular atom is reported This allows to check how the mass of a specific atom was conserved by the integration method The LOOKATALL command can be used to specify all the species Output of LOOKAT can be directed to the file ROOT dat using the utility subroutines described in Sect 4 1 16 The MONITOR section defines a different list of species and atoms 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 of the selected species during the integration The syntax is similar to the LOOKAT section With the driver general output of MONITOR goes to the screen STDOUT The order of the output is first variable species then fixes species finally atoms It is not the order in the MONITOR command Examples for these sections are LOOKAT NO2 C02 03 N MONITOR 03 N 3 1 7 Lump species definitions LUMP To reduce the stiffness of some models various lumping of species may be defined in the LUMP section The ex ample below shows how the concentration of NO2 can be replaced by the sum of concentrations for NO2 and NO which is considered to be a single variab
54. s the mex interface routines for the ODE function Jacobian and Hessian for the tar get languages C Fortran77 and Fortran90 The default is ON With OFF no Mex files are generated 3 2 12 Selcting a chemical model 4MODEL The chemical model contains the description of the atoms species and chemical equations It also contains default initial values for the species and default options including the 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 selecting the model KPP tries to find a file with the name of the model and the suffix def in the KPP_HOME models subdi rectory This file is then parsed The content of the model definition file is written in the KPP language The model definition file points to a species file and an equation file The species file includes further the atom definition file All default values regarding the model are automatically selected For convenience the best integrator and driver for the given model are also automatically selected The MODEL command is optional and intended for using a predefined model Users who supply their own reaction mechanism do not need it 3 2 13 Reordering REORDER Reordering of the species is performed in order to mini mize the fill in during the LU factorization and therefore preserve the sparsity structure and increase efficiency The reordering is
55. same specific calling sequence Normally KPP tries to find the selected integrator file in the directory KPP_HOME int However if the supplied file name contains a slash it is assumed to be absolute To access an integrator in the current directory the prefix can be used e g INTEGRATOR mydeffile INTFILE myintegrator If the INTEGRATOR command occurs twice the second replaces the first 3 2 9 The Jacobian JACOBIAN The JACOBIAN command controls which functions are generated to compute the Jacobian The option OFF in hibits the generation of the Jacobian routine The option FULL generates the Jacobian as a square NVARXNVAR 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 The format used is compressed on rows With SPARSE_LU_ROW KPP extends the number of nonzeros to account for the fill in due to the LU decomposition 3 2 10 Target language selection LANGUAGE The LANGUAGE command selects the target language in which the code file is to be generated Available options are Fortran90 Fortran77 C or Matlab 3 2 11 Mex files MEX Mex is a matlab extension that allows to call functions written in Fortran and C directly from within the Matlab environment KPP generate
56. sparse format is required Using the variable species V the fixed species F and the rate coeffi cients RCT as input the subroutine calculates the Jacobian JVS The default data structures for the sparse compressed on rows Jacobian representation are shown in Table 10 for the case where the LU fill in is accounted for JVS stores the LU_NONZERO elements of the Jacobian in row order Each row I starts at position LU_CROW I and 16 Jac df dy 1 2 3 4 5 1 2 a 4 5 Figure 2 The sparsity pattern of the Jacobian for the small_strato example Table 10 Sparse Jacobian Data Structures Global variable JVS LU_NONZERO LU_IROW LU_NONZERO LU_ICOL LU_NONZERO LU_CROW NVAR 1 LU_DIAG NVAR 1 Represents Jacobian nonzero elements Row indices Column indices Start of rows Diagonal entries LU_CROW NVAR 1 LU_NONZERO 1 The location of the I th diagonal element is LU_DIAG I The sparse element JVS K is the Jacobian entry in row LU_IROW K and col umn LU_ICOL K For the small_strato example KPP generates the following Jacobian sparse data structure LU_ICOL 1 3 1 2 3 5 1 2 3 4 amp 5 2 3 4 5 2 3 4 5 LU_IROW 1 1 2 2 2 2 3 3 3 3 amp 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 These vectors are constant as the sparsity pattern of the Jaco b
57. sport calculations 3 2 KPP commands A command begins on a new line with a sign followed by acommand 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 precision arithmetique 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 from which the main function is to be taken The parameter is a file name without suffix The appropriate suffix f90 f c or m is automatically appended Sandu amp Sander KPP User Manual Normally KPP tries to find the selected driver file in the directory KPP_HOME drv However if the supplied file name contains a slash it is assumed to be absolute To access a driver in the current directory the prefix can be used e g DRIVER mydriver It is possible to choose the empty dummy driver none if the user wants to include the KPP generated modules into a larger model e g a general circulation or a chemical transport model instead of creating a stand alone version of the chemical integrator The driver none is also selected when the DRIVER command is missing If the DRIVER command occurs twice the second replaces the first 3 2 3 Dummy indices
58. ta structures Tables 12 and 13 is done in ROOT_StoichiomSP c Sparse linear algebra routines Sect 4 1 13 are in the file ROOT_LinearAlgebra c The code to update the rate constants and user defined code for rate laws is in ROOT_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 be called 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 the layout of the C code The driver file ROOT f contains the main driver and numerical integrator functions The generated Fortran77 code includes three header files The global parameters Table 8 are defined as parameters and initialized in the header file ROOT_Parameters h The global variables Table 9 are declared in ROOT_Global h as common block variables There are global common blocks for real GDATA integer INTGDATA and charac ter CHARGDATA global data They can be accessed from within each program unit that includes the global header file The header file ROOT_Sparse h contains common block declarations of sparse data structures for the Jacobian Table 10 Hessian Table 11 stoichiometric matrix Table 12 and the Jacobian of reaction products Ta bl
59. tangent linear and adjoint methods The KPP generated Fortran90 code has a different file structure than the C or Fortran77 output see Sects 4 2 and 4 3 An automatically generated Makefile facilitates the compilation of the KPP generated code see Sect 4 1 18 Equation tags provide a convenient way to refer to specific chemical reactions see Sect 4 1 5 The dummy index allows to test if a certain species occurs in the current chemistry mechanism see Sect 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 to KPP 2 1 need to make a few modifications to their input files To select the target language change the previous command 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 the preliminary version 1 1 f90 alphal2 from Sander et al 2005 these changes are also necessary Change USE Fortran95 to LANGUAGE Fortran90 Change the names of the indices of the species from kpp_x to ind_ Rename all inline types from F95_ to F9O_ Since the name of the initialization subroutine has changed replace USE ROOT_Init ONLY CALL initval initval
60. ts a new KPP section Then a list of items sepa rated by semicolons follows A section ends when another KPP section or command occurs i e when another sign occurs at the beginning of a line The syntax of an item definition is different for each particular section Table 1 shows all the sections defined in the KPP language Each of 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 in the periodic table of elements For this table there is a predefined file containing all definitions that can be used by the command INCLUDE atoms This should be the first line in a KPP input file because it allows to use any atom in the periodic table of elements throughout 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 all atoms and this might still be correct from a chemical point of view To accommodate for this KPP can perform mass balanc
61. u may have both the gas phase reaction of N2O5 with water in your mechanism and also the heterogeneous reaction on aerosols N205 H20 N205 H20 2 HNO3 2 HNO3 k_gas k_aerosol These reactions must be merged by adding the rate coef ficients N205 H20 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 INITVALUES CFACTOR 2 5E19 NO2 1 4E 9 C02 MyC02Func ALL_SPEC 0 0 If no value is specified for a particular species the default value zero is used One can set the default values using 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 value by a constant factor This factor can be set by using the generic name CFACTOR Each of the initial values will be multiplied by this factor before being used If CFACTOR is 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 more complex 3D models the initial values are usually taken from some input files or some global data structures In this case INITVALUES may not be needed 3 1 6 Output data selection and MONITOR LOOKAT There are two sections in this category LOOKAT and MONITOR The LOOKAT section instructs the prep
62. xed species spc in FIX Table 9 List of important global variables Global variable Represents C NSPEC Concentrations all species VAR NVAR Concentrations variable species FIX NFIX Concentrations fixed species RCONST NREACT Rate coefficient values TIME Current integration time SUN Sun intensity between 0 and 1 TEMP Temperature RTOLS Relative tolerance scalar TSTART TEND Simulation start end time DT Simulation step ATOL NSPEC Absolute tolerances RTOL NSPEC Relative tolerances STEPMIN Lower bound for time step STEPMAX Upper bound for time step CFACTOR Conversion factor SPC_NAMES NSPEC EQN_NAMES NREACT Names of chemical species Names of chemical equations 4 1 9 ROOT_Global f90 The global variables Table 9 are declared in ROOT_Global f90 Global variables are presented in Table 9 Both variable and fixed species are stored in the one dimensional array C The first part indices from 1 to NVAR 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 and NFIX The parts can also be accessed separately through the arrays VAR and FIX VAR 1 NVAR FIX 1 NFIX C 1 NVAR C NVAR 1 NSPEC 15 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 NVA
63. xplained 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 gs y 5 miki Err 5 eiki 16 i 1 i 1 4 1 T h Yi y akj i j 1 A rr hy i 1 Cij n n P Ti Vi Fk hafe t y j l Aki where s is the number of stages a gt gt Cj and g Jj ij The formula coefficients aij and yj give the or der of consistency and the stability properties A is the system matrix in the linear systems to be solved during implicit integration or in the Newton s method used to solve the nonlinear systems It is the scaled identity ma trix minus the Jacobian The coefficients of the methods implemented in KPP are shown in Table 18 6 1 1 Tangent Linear Model The method 16 is combined with the sensitivity egua tions One step of the method reads syt by 5 mili 17 i 1 i 1 T 4t ajh 5 OY dy X ayh j 1 ae Afi Ti Yi oY adi J T Yi ee KU Hlt y x ki by hyde t y dy The method requires a single n x n LU decomposition per step to obtain both the concentrations and the sensitivi ties 24 Sandu amp 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 y 1 4 1 V2 a21 1 7 c21 2 7

KPP-2.1 User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents