The Matlab code

Important

Some run-time options for Matlab-language integrators (specified in the ICNTRL and RCNTRL arrays) do not exactly correspond to the Fortran90 run-time options. We will standardize run-time integrator options across all target languages in a future KPP release.

Matlab provides a high-level programming environment that allows algorithm development, numerical computations, and data analysis and visualization. The KPP-generated Matlab code allows for a rapid prototyping of chemical kinetic schemes, and for a convenient analysis and visualization of the results. Differences between different kinetic mechanisms can be easily understood. The Matlab code can be used to derive reference numerical solutions, which are then compared against the results obtained with user-supplied numerical techniques. KPP/Matlab can also 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 reference the function. Consequently, KPP generates one m-function-file for each of the functions discussed in the sections entitled ROOT_Function , ROOT_Jacobian and ROOT_JacobianSP, ROOT_Hessian and ROOT_HessianSP, ROOT_Stoichiom and ROOT_StoichiomSP, ROOT_Util. The names of the m-function-files are the same as the names of the functions (prefixed by the model name ROOT.

The variables of Parameters Declared in ROOT_Parameters are defined as Matlab global variables and initialized in the file ROOT_parameter_defs.m. The variables of Global Variables Declared in ROOT_Global are declared as Matlab global variables in the file ROOT_global_defs.m. They can be accessed from within each Matlab function by using declarations of the variables of interest.

The sparse data structures for the Jacobian (cf. Sparse Jacobian Data Structures), the Hessian (cf. Sparse Hessian Data), the stoichiometric matrix (cf. Sparse Stoichiometric Matrix), and the Jacobian of reaction (see Sparse Data for Jacobian of Reactant Products) 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.

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 integrators. Specifically, the syntax of the wrapper calls matches the syntax required by Matlab’s integrators like ode15s. Moreover, the Jacobian wrapper converts the sparse KPP format into a Matlab sparse matrix.

List of Matlab model files

Function	Description
ROOT.m	Driver
ROOT_parameter_defs.m	Global parameters
ROOT_global_defs.m	Global 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	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_Hess_Vec.m	Hessian action on vectors
ROOT_HessTR_Vec.m	Transposed Hessian action on vectors
ROOT_stoichiom.m	Derivatives of Fun and Jac w/r/t rate coefficients
ROOT_stoichiomSP.m	Sparse data
ROOT_ReactantProd.m	Reactant products
ROOT_JacReactantProd.m	Jacobian of reactant products
ROOT_Rates.m	User-defined rate reaction laws
ROOT_Update_PHOTO.m	Update photolysis rate coefficients
ROOT_Update_RCONST.m	Update all rate coefficients
ROOT_Update_SUN.m	Update sola 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