KPP.jl is a KPP (Kinetics PreProcessor)-compatible chemical kinetics model code generator for Julia. It interfaces with DifferentialEquations.jl
and optionally the DiffEqBiological.jl
to import mass-action kinetics equation descriptions to generate time-stepping models solved by the broader numerical computing infrastructure provided by Julia.
This package aims to provide KPP-like compatibility, in the sense that pre-processing for species and equations are provided and a model code abstracting the ODE generation, solving and time-stepping is generated according to descriptions in a format compatible with the original Kinetics PreProcessor (KPP), which generates FORTRAN, C and MATLAB code. This project is a clean re-implementation of KPP with no original code and no affiliation with the original authors, who may be cited below:
Damian, V., Sandu, A., Damian, M., Potra, F. and Carmichael, G.R., 2002. The kinetic preprocessor KPP-a software environment for solving chemical kinetics. Computers & Chemical Engineering, 26(11), pp.1567-1579.
Not all features by KPP are supported and model code generated adheres to Julia standards, given KPP is more than a dozen years old. Please see the "Deprecated" section for details.
KPP.jl
is developed by Haipeng Lin at hplin as seas dot harvard dot edu
originally for the MIT 18.337 final project.
KPP.jl
provides multiple "driver" packages enabling differing kinds of functionality. By default, it provides a simple DiffEqBiological.jl
-based driver, DiffBioEq
, which creates the reaction network using said package. KPP.jl is essentially a parser in this case.
For high performance applications KPP.jl
incorporates the Native
driver, which builds the species array manually and aims to support advanced developments in solving chemical equations specific to atmospheric chemistry:
- Diagnostics: Production/Loss for species at each time-step
- Adaptive approximations for reducing the complexity of the chemical mechanism, based on:
Santillana M., P. Le Sager, D. J. Jacob, and M. P. Brenner, An adaptive reduction algorithm for efficient chemical calculations in global atmospheric chemistry models. Atmos. Environ., 44, 4426-4431, 2010
and possibly in the future an optimization as described in:
Shen, L., D.J. Jacob, M. Santillana, X. Wang, and W. Chen, An adaptive method for speeding up the numerical integration of chemical mechanisms in atmospheric chemistry models: application to GEOS-Chem version 12.0.0, Geophys. Model Dev. Discuss., https://doi.org/10.5194/gmd-2019-2792019, in review, 2019.
Experimental features will also leverage ModelingToolkit.generate_jacobian
to take the symbolic Jacobian, which can greatly improve performance. This is a work-in-progress.
TBD
-
KPP.jl
is not a package, it is a pre-processor that generates full model code. Run-time building of the model is too slow. -
To run, simply configure the scheme you want to use and other options in
./KPP.jl
. Input files are located in./inputs/
and are in standard-KPP format, with.def
,.spc
and.eqn
files. -
Models are generated based on a template in
./template
. Ignore./template_adv
for now. -
In the generated model,
jlkpp_Model()
is the pseudo-main function of the model and can be edited freely. All chemical kinetics solver routines are in the generated model'sCore/kpp.jl
; species descriptions are inHeaders/registry.jl
. The main stepping function isjlkpp_Timestep!
, a mutating form that is parallel-safe.
Generated code is a full time-stepped model jlkpp_MECHANISM_NAME
which performs time-stepping from start to end solving chemical kinetic equations step-by-step until completion.
-
Variables are not handled in a global scope like in FORTRAN (COMMON blocks).
-
Legacy parameters such as
TEMP
,CFACTOR
andSUN
have their replacement Julia routines / hard-coded shims for compatibility. -
Legacy rate functions such as
FALL
,ARR
,EP2
have hard-coded Julia version shims for compatibility. Currently functions for rate coefficients require work directly modifyingKPP.jl
. Submit an issue if you want to work on this. -
Extensibility is made possible by providing clear code points to implement other processes and a main non-KPP specific time stepping loop.
- Debug IO: Using
JLD.jl
, a Julia-native format variant of HDF5 is used to save out debug output at specific time intervals defined at pre-processor generation time. It is fixed to discourage production use and only used for easy debugging of outputs.
The following features are currently unsupported in KPP.jl
and will be implemented as infrastructure is ready.
-
Fixed species (e.g.
O2
or generic species likeM
). Their concentrations are not fixed in internal solver time-steps and are currently re-set with a kludge at every model time-step. -
As a result of the above,
#DEFVAR
,#DEFFIX
may not behave as expected. -
Mass balance checks via chemical atoms (when defined via
.spc
files, e.g.PAN = 2C + 3H + 5O + N;
) is unsupported. -
The integrator option e.g.
#INTEGRATOR rodas4
is ignored;DifferentialEquations.jl
is used with algorithm hintingalg_hints = [:stiff]
by default.
The following features are deprecated and will remain indefinitely unsupported.
-
The
#DRIVER
option specifying the language version is obviously unsupported. All code will be Julia code. -
The
#MONITOR
option to choose output species. The generated model does NOT contain production IO functionality. Users are encouraged to implement their own.
We acknowledge the authors of the following packages (and Julia itself!) without which KPP.jl
is not possible:
DifferentialEquations.jl
DiffEqBiological.jl
Additionally the demo input
files are directly from KPP-2.1
by original authors (Damien et al., 2002; Sandu et al., 2006).