SpeedCHEM documentation

References. The SpeedCHEM library has been used in a number of studies. The following papers need to be referenced to when using the code. They describe the math underlying the SpeedCHEM solver. Here they are listed per categories:

SpeedCHEM numerics and math

F. Perini, E. Galligani, R.D. Reitz, "An analytical Jacobian approach to sparse reaction kinetics for computationally efficient combustion modelling with large reaction mechanisms", Energy&Fuels 26 (8), 4804-4822, 2012. [PDF, Publisher] [main reference]

F. Perini, E. Galligani, R.D. Reitz, "A study of direct and Krylov iterative solver techniques to approach linear scaling of the integration of Chemical Kinetics with detailed combustion mechanims", Combustion and Flame 161(5):1180-1195, 2014.
[PDF, Publisher]

SpeedCHEM validation and computational efficiency

F. Perini, B. Das Adhikary, J.H. Lim, X. Su, Y. Ra, H. Wang, R.D. Reitz, "Improved Chemical Kinetics Numerics for the Efficient Simulation of Advanced Combustion Strategies" , SAE Int. J. Engines 7(1):2014, doi:10.4271/2014-01-1113.
[PDF, Publisher]

F. Perini, A. Krishnasamy, Y. Ra, R.D. Reitz, "Computationally efficient simulation of multi-component fuel combustion using a sparse analytical Jacobian chemistry solver and high-dimensional clustering", ASME J. Eng. Gas Turbines Power 136(9), 091515, 2014. doi: 10.1115/1.4027280
[PDF, Publisher]

F. Perini, E. Galligani, G. Cantore, R.D. Reitz, "Validation of a Sparse Analytical Jacobian Chemistry Solver for
Heavy-Duty Diesel Engine Simulations with Comprehensive Reaction Mechanisms", SAE Technical paper 2012-01-1974, SAE 2012 Commercial Vehicle Engineering Congress, Rosemont, IL, 2012. [Publisher]

Description of the (optional) chemistry settings input file, itapeChem

The "itapeChem" file contains the settings for the chemistry ODE solution. It is not mandatory, but in case it is included in the solver's runtime folder, it will be loaded at the initialization to set up the solution. Here is a description of the options that can be set:

1) Chemistry solver: set "SpeedCHEM" to solve chemistry using this chemistry
library. This item may be extended in the future with other packages.

2) ODE solver choice. The common ones are: LSODES, VODES, RADAU5, DASPK,
VODE, GAM, LSODE. For efficiency, it is suggested using LSODES at both small and large mechanism dimensions. LSODES, VODES, RADAU5 feature full sparse matrix algebra. VODES can be a good choice too, especially for small mechanisms (<50 species). RADAU5 has sparse algebra too, and is acknowledged to be the most accurate one, but also more memory-intensive.

3) Analytical Jacobian option: set "1" to compute the Jacobian analytically,
or "0" to let the solver evaluate it approximately. This option should always be active ("1").

4) Tabulated data option: set a non-zero number to use tabulated temperature-dependent functions.
Gives a significant CPU time speedup. Further details for data tabulation have to be
given next (see points 13), 14), 15) , 17).
- set -1 to let the program decide the interpolation tolerance based on the requested accuracy at pt. 17)
- set 0 not to use tabulation-interpolation
- set 1, 2, 3, 4 to choose linear, parabolic, cubic, quadric interpolation of the tabulated data.

5) Save time-intensive functions between subsequent calls to the subroutines.
This feature is currently not active. "0" recommended.

6) Sparse formulation for Jacobian: activates a sparse Jacobian formulation
for three-body and pressure-dependent reactions. Activation ("1") suggested.
Only active when analytical Jacobian option of pt. 2) is active.

7) Print jacobian pattern to "dat.jacobian" file at the mechanism parsing phase.

8) Check atom conservation for every reaction in the mechanism. This is a basic check
that is just run at the initialisation, and should always be active to be sure that
the mechanism has been correctly set.

9) Separate absolute tolerance: if this option is selected, the user can set two different
integration tolerance values for 1. Temperature and 2. Species mass fractions during
the integration (see points 11) and 12) ). Usually not active.

10) Relative integration tolerance. Default value: 1.0d-04
11) Absolute integration tolerance (species). Default value: 1.0d-15
12) Absolute integration tolerance (temperature). Active if point 9) is active. Default
value: 1.0d-01 [K]

13) Temperature sampling step for tabulated data. If option no. 4) is active, sets
the interval at which temperature tabulation points are evaluated. Default is between
5.0 K and 10.0 K.

14-15) Maximum and minimum temperature tabulation ranges. These values should
include all the possible temperatures that can occur during the chemistry solver
integration. This range should be broader than the limiting values set in KIVA,
as the chemistry solver can encounter more extreme conditions. Usually, 300 K to
3000 K or 3500 K is a good selection. The code will evaluate those functions analytically
if temperature falls outside this range.

16) This option is only used in the constant volume program to decide the number of output points (=integration restarts) to subdivide the integration interval in.

17) Requested relative accuracy of the interpolated datum in comparison with the
exact one. Suggested value: 1.0d-10 (i.e., 10 exact digits). Only works if
order of tabulation is chosen by the program, or point 4. is set to -1.

18) EXPERIMENTAL: further options are currently not supported but need to be
read by the interpreter. Default values suggested.

The SpeedCHEM distribution contains a sample itapeChem file.

Last modification, 05/19/2013

The included Constant-Volume standalone integrator


Included with the SpeedCHEM library is a sample constant-volume standalone application, that can be used to calculate adiabatic constant volume reactors in a computationally efficient way. In order to run, the application (SpeedCHEM_CONV.exe) will need:

  1. A reaction mechanism, in cklink or chem.bin form
  2. An (optional) itapeChem file containing the solver's settings and the desired number of output point per initial value problem
  3. An itapeSC file containing the number of integrations to be performed, their initial conditions (initial pressure, temperature and composition in mole fractions) according to the format described below.


The itapeSC input file is only used by the SpeedCHEM_CONV.exe program, and is not requested by normal integration of SpeedCHEM into another program (such as KIVA, for example). Its input is required if a batch of constant volume integration has to be made during a single program run.

line 1: number of cases => the number of CONV integrations to be performed
lines 2:number of cases + 1 => the initial setup for every conV integration.

Initial settings for every conV integration are read using default input
(e.g., read(iunit, *)), thus the user can choose its input format.
The code requires input in the following order:

(P0, T0, delta_t, X0(j, j=1,ns) )

- P0 = initial reactor pressure [Pa]
- T0 = initial reactor temperature [K]
- delta_t = total integration time [s]
- X0 = species mole fractions in the order the species appear in the
reaction mechanism [-]


The sample CONV program prints output for the requested simulations in a
binary file, named 'output.bin'. Attached is the Matlab function
SC_gather_results that can be used to convert the file into readable

Typical usage from Matlab is:

>   results = SC_gather_results(folder_name);

If the current folder is the one that contains the CONV output,
it is enough to run

>   results = SC_gather_results('.');