# Output from KPP¶

This chapter describes the source code files that are generated by KPP.

## The Fortran90 code¶

The code generated by KPP is organized in a set of separate files. Each has a complete description of how it was generated at the begining of the file. The files associated with root are named with a corresponding prefix ROOT_ A short description of each file is contained in the following sections.

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 module names for better readability. Dotted boxes show optional files that are only produced under certain circumstances.

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 .f90 or .F90. Figure 1 (above) shows how these modules are related to each other. The generated code is consistent with the Fortran90 standard. It may, however, exceed the official maximum number of 39 continuation lines.

Tip

The default Fortran90 file suffix is .f90. To have KPP generate Fortran90 code ending in .F90 instead, add the command #UPPERCASEF90 ON to the KPP definition file.

### ROOT_Main¶

ROOT_Main.f90 (or .F90) root is the main Fortran90 program. It contains the driver after modifications by the substitution preprocessor. The name of the file is computed by KPP by appending the suffix to the root name.

Using #DRIVER none will skip generating this file.

### ROOT_Model¶

The file ROOT_Model.f90 (or .F90) unifies all model definitions in a single module. This simplifies inclusion into external Fortran programs.

### ROOT_Initialize¶

The file ROOT_Initialize.f90 (or .F9O) contains the subroutine Initialize, which defines initial values of the chemical species. The driver calls the subroutine once before the time integration loop starts.

### ROOT_Integrator¶

The file ROOT_Integrator.f90 (or .F90) contains the subroutine Integrate, which is called every time step during the integration. The integrator that was chosen with the #INTEGRATOR command is also included in this file. In case of an unsuccessful integration, the module root provides a short error message in the public variable IERR_NAME.

### ROOT_Monitor¶

The file ROOT_Monitor.f90 (.F90) contains arrays with information about the 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 (cf. #EQNTAGS) that each reaction in the section may start with an equation tag which is enclosed in angle brackets, e.g.:

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


If the equation tags are switched on, KPP also generates the PARAMETER array EQN_TAGS. In combination with EQN_NAMES and the function tag2num that converts the equation tag to the KPP-internal tag number, this can be used to describe a reaction:

PRINT*, ’Reaction 1 is:’, EQN_NAMES( tag2num( ’R1’ ) )


### ROOT_Precision¶

Fortran90 code uses parameterized real types. ROOT_Precision.f90 (or .F90) contains the following real kind definitions:

! KPP_SP - Single precision kind
INTEGER, PARAMETER :: &
SP = SELECTED_REAL_KIND(6,30)
! KPP_DP - Double precision kind
INTEGER, PARAMETER :: &
DP = SELECTED_REAL_KIND(12,300)


Depending on the choice of the #DOUBLE command, the real variables are of type double (REAL(kind=dp)) or single precision (REAL(kind=sp)). Changing the parameters of the SELECTED_REAL_KIND function in this module will cause a change in the working precision for the whole model.

### ROOT_Rates¶

The code to update the rate constants is in ROOT_Rates.f90 (or .F90). The user defined rate law functions (cf. Fortran90 subrotutines in ROOT_Rates) are also placed here.

Fortran90 subrotutines in ROOT_Rates

Function

Description

Update_PHOTO

Update photolysis rate coefficients

Update_RCONST

Update all rate coefficients

Update_SUN

Update sun intensity

### ROOT_Parameters¶

Global parameters are defined and initialized in ROOT_Parameters.f90 (or .F90):

Parameters Declared in ROOT_Parameters

Parameter

Represents

Example

NSPEC

No. chemical species (NVAR + NFIX)

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 fixed species spc in FIX

Example values listed in the 3rd column are taken from the small_strato mechanism (cf. Running KPP with an example stratospheric mechanism).

KPP orders the variable species such that the sparsity pattern of the Jacobian is maintained after an LU decomposition. For our example there are five variable species (NVAR = 5) ordered as

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


and two fixed species (NFIX = 2)

ind_M = 6, ind_O2 = 7.


KPP defines a complete set of simulation parameters, including the numbers of variable and fixed species, the number of chemical reactions, the number of nonzero entries in the sparse Jacobian and in the sparse Hessian, etc.

### ROOT_Global¶

Several global variables are declared in ROOT_Global.f90 (or .F90):

Global Variables Declared in ROOT_Global

Global variable

Represents

C(NSPEC)

Concentrations, all species

VAR(:)

Concentrations, variable species (pointer)

FIX(:)

Concentrations, fixed species (pointer)

RCONST(NREACT)

Rate coefficient values

TIME

Current integration time

SUN

Sun intensity between 0 and 1

TEMP

Temperature

TSTART, TEND

Simulation start/end time

DT

Simulation time step

ATOL(NSPEC)

Absolute tolerances

RTOL(NSPEC)

Relative tolerances

STEPMIN

Lower bound for time step

STEPMAX

Upper bound for time step

CFACTOR

Conversion factor

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 to NVAR+1 to NSPEC) the fixed species. The total number of species is the sum of the NVAR and NFIX. The parts can also be accessed separately through pointer variables VAR and FIX, which point to the proper elements in C.

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


Important

In previous versions of KPP, Fortran90 code was generated with VAR and FIX being linked to the C array with an EQUIVALENCE statement. This construction, however, is not thread-safe, and it prevents KPP-generated Fortran90 code from being used within parallel environments (e.g. such as an OpenMP parallel loop).

### ISTATUS¶

Summary of ISTATUS usage in the f90 integrators. Here, Y = used.

ISTATUS

1

2

3

4

5

6

7

8

9

beuler

Y

Y

Y

Y

Y

Y

Y

Y

dvode

exponential

feuler

gillespie

lsode

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

rosenbrock

Y

Y

Y

Y

Y

Y

Y

Y

rosenbrock_tlm

Y

Y

Y

Y

Y

Y

Y

Y

Y

rosenbrock_autoreduce

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

runge_kutta

Y

Y

Y

Y

Y

Y

Y

Y

runge_kutta_tlm

Y

Y

Y

Y

Y

Y

Y

Y

sdirk4

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

sdirk

Y

Y

Y

Y

Y

Y

Y

Y

sdirk_tlm

Y

Y

Y

Y

Y

Y

Y

Y

seulex

Y

Y

Y

Y

Y

Y

Y

tau_leap

ISTATUS(1)

Number of function calls.

ISTATUS(2)

Number of Jacobian calls.

ISTATUS(3)

Number of steps.

ISTATUS(4)

Number of accepted steps.

ISTATUS(5)

Number of rejected steps (except at very beginning).

ISTATUS(6)

Number of LU decompositions.

ISTATUS(7)

Number of forward/backward substitutions.

ISTATUS(8)

Number of singular matrix decompositions.

ISTATUS(9)

Number of Hessian calls.

ISTATUS(10) ... ISTATUS(20)

Currently not used.

### RSTATUS¶

Summary of RSTATUS usage in the f90 integrators. Here, Y = used, s = solver specific usage.

RSTATUS

1

2

3

4

beuler

Y

Y

Y

dvode

exponential

feuler

gillespie

lsode

Y

Y

Y

Y

Y

rosenbrock

Y

Y

Y

rosenbrock_tlm

Y

Y

Y

rosenbrock_autoreduce

Y

Y

Y

s

Y

Y

Y

runge_kutta

Y

Y

Y

runge_kutta_tlm

Y

Y

Y

sdirk4

Y

Y

Y

Y

Y

sdirk

Y

Y

Y

sdirk_tlm

Y

Y

Y

seulex

tau_leap

RSTATUS(1)

Texit, the time corresponding to the computed $$Y$$ upon return.

RSTATUS(2)

Hexit: the last accepted step before exit.

RSTATUS(3)

Hnew: The last predicted step (not yet taken. For multiple restarts, use Hnew as Hstart in the subsequent run.

RSTATUS(4)

(Solver-specific for rosenbrock_autoreduce) AR_thr: used to output the calculated (used) auto-reduction threshold for the integration. Useful when ICNTRL(10) > 0 where the threshold is dynamically determined based on a given species.

RSTATUS(5) ... RSTATUS(20)

Currently not used.