Shock & Detonation Toolbox - Cantera 2.1
| Code Home |
Cantera Installation |
SDToolbox with Python |
SDToolbox with MATLAB |
About the SD Toolbox
The Shock & Detonation Toolbox is a collection of numerical
routines that enables the solution of standard problems
for gas-phase explosions using realistic thermochemistry
and detailed chemical kinetics. The SD Toolbox employs
Dave Goodwin's Cantera
software for the chemistry functionality and uses either MATLAB
or Python (and related libraries) for scripting. The
Cantera package provides conversion utilities from legacy formats in
order to make use of existing databases of chemical kinetics and
The focus of the SD Toolbox is not computational fluid dynamics,
which is outside the scope of our project at the present time.
The SD Toolbox includes numerical routines for the computation of:
The SD Toolbox has been implemented in both MATLAB and Python.
There are different releases of the toolbox as described below
for each environment. Because of differences in Cantera within
MATLAB and Python, not all of the releases offer the same
functions. The SD Toolbox programs are available free of charge,
but are subject to the same license
agreement as Cantera.
- CJ detonation speed and post-detonation state
- Postshock gas state for frozen composition
- Postshock gas state for equilibrium composition
- Frozen and equilibrium Hugoniot curves
- Constant-volume explosion structure
- ZND detonation structure
- Effective activation energies and
chemical time scales from detailed reaction mechanisms
- Extrapolation of low temperature thermodynamic
polynomial fits to higher temperatures.
For the theoretical background, details on the algorithms,
and implementations for the SD Toolbox, please read
Installation of Cantera
The SD Toolbox requires Cantera along with either MATLAB or Python.
The recommended version of Cantera is 2.1 or higher.
Instructions for installing and using Cantera under Windows
in either the MATLAB or Python environments can be found
here. Instructions for building and installing Cantera
from source code under Windows, Mac OS X, and Linux are available
Installation of SD Toolbox under Python
The Python interface to Cantera was changed considerably in the
transition from Cantera 2.0 to Cantera 2.1. Many of the changes
are documented here;
these changes include different naming
conventions for constants and thermodynamic properties as
well as new syntax for reporting and setting the thermodynamic
state. The Python interface to the SD Toolbox has been updated
accordingly. However, because of the extensive changes to the
Cantera-Python interface, the new SD Toolbox is NOT backward
compatible with Cantera 2.0 and earlier.
The Python version of the SD Toolbox and a
collection of demo scripts can downloaded from the following links:
After successfully installing both Cantera and Python, the SD Toolbox is
installed using the following procedure:
- Shock and Detonation Toolbox
- Python demo scripts
- Download and install Scipy.
- Create a directory named SDToolbox on the path PYTHONPATH/Lib/site-packages/SDToolbox,
where PYTHONPATH is the location of your Python installation. For Windows, this is usually
C:/Python27 and for Linux it might be /usr/local/lib/python2.7.
- Download the SDToolbox from the link above and unzip the files into
the SDToolbox directory just created.
- For Windows only, go up one directory to PYTHONPATH/Lib/site-packages and create a text file named
"SDToolbox.pth" containing the single line "SDToolbox" (no quotes).
- For Windows only, go up one more directory to PYTHONPATH/Lib and run the python script 'site.py'
The SD Toolbox is now installed. To test the installation, open a terminal window and run python. In the
python environment, execute
from SDToolbox import * to load the toolbox and then use
[cj_speed,_] = CJspeed(101325,300,'H2:2 O2:1','gri30.cti',0)
This will compute the CJ speed for a stoichiometric hydrogen-oxygen detonation at ambient
temperature and pressure. If this call executes with no errors, the installation was successful.
Installation of SD Toolbox under MATLAB
The MATLAB version of the SD Toolbox and a collection of demo scripts can be
After successfully installing Cantera and MATLAB, the SD Toolbox can be installed using the
- Shock and Detonation Toolbox
- MATLAB demo scripts
The SD Toolbox is now installed. You can test it by calling one of the functions,
- Navigate to your MATLAB installation and create the folder R20xxy/toolbox/SDToolbox,
where R20xxy is your MATLAB release, e.g., R2014a.
- Unpack the SD Toolbox zip or tar file downloaded above into the folder just created.
- Start MATLAB. Go to File-->Set Path and click Add with Subfolders.
Select the SDToolbox folder created in step (1).
- Click Save and Close
U = CJspeed(101325, 300, 'H2:2 O2:1', 'gri30.cti', 1)
which will compute the Chapman-Jouguet speed for a stoichiometric hydrogen-oxygen
ZND calculations have been implemented in the MATLAB version of
the toolbox above, but are not available in the python version.
However, on Linux platforms the ZND calculations are implemented
both in C++ and in python scripts that call on a C++ executable.
The source code, makefile, and python scripts are available in
These scripts have been built and tested on Ubuntu 12.04 with GCC-4.6.3 and
The ZND code can be built using the following steps.
The executable is placed in the bin directory. To run the
ZND calculation, execute
- Obtain working installations of Cantera,
Python (version 2.7 recommended), GCC, and pkg-config. The
last three of these can be installed using the package
manager on most linux systems.
- Download and unpack the source code using the command
tar -zxvf znd_Cantera2.1_Python2.7.tgz or
- The unpacked directory tree contains three folders, bin,
build, and src. Navigate to the build directory
make -f znd.make to build the executable.
The program pkg-config should automatically link to the correct
./znd. You will then be asked
to supply the name of an input file which specifies the flow conditions.
Several examples of input files are available in the bin
The bin directory also contains several python scripts which
demonstrate how to call the znd program from python. The scripts
znd_fseries.py, znd_phiseries.py, and znd_Pseries.py
perform ZND calculations for sequences of overdrive values,
equivalence ratios, and pressures.
Mechanism Files for Cantera:
Cantera requires a mechanism (.cti) file with thermodynamic
and reaction rate data for the species of interest. Some files
are included when Cantera is installed, but we provide additional
files below that have been modified by our group for application to shock
and detonation problems. The species thermodynamic data in these
files have coefficients that are valid to much higher temperatures
(5000-6000 K in most cases) than the original data sets supplied
with Cantera. However, it is to be noted that these high temperature
data sets were computed by extrapolation from low temperature
data and have not been extensively validated. Individual mechanism
files are available from the following links:
The entire collection of mechanism files is also
available as a
Please note that these files are only included for use with the demo programs - you will need to either add these files to the \ProgramFiles\Cantera\data\ directory (PC installation) or place them in the working directory for the demo programs. These mechanisms are not intended to be representative of the state of the practice in chemical kinetics or thermodynamics. Many of these are derived from older compilations and we make no guarrantees about the accuracy, particularly in regard to the rate constants. The thermodynamic data is reasonably reliable when used within the intended temperature range although care should be taken at the upper end. The NASA 9-term polynomial fits should be used if very high (>6000 K) temperature thermodynamic properties are required.
There are many newer sets of chemical reaction data and themodynamics which are available for download on the www or as part of supplemental data from archival publications. Users should seek out these newer data sets and use them for any quantitative work that depend on the details of the reaction mechanism.
Many sets of chemistry data are stored in CHEMKIN format instead of the
cti style used by Cantera. These legacy CHEMKIN data sets can be converted
to cti format using the program
ck2cti that is included with
Cantera. Instructions for making this conversion are available from
Cantera web page. Note that the python converter
ck2cti.py is the now the preferred tool for this rather than the previously used compiled program.
Legacy SD Toolbox
Legacy versions of the SD Toolbox which are compatible with Cantera 1.7-2.0 remain available
here, but these versions will no longer be
supported. Note that the MATLAB interface to Cantera and the SD Toolbox was unaffected by the transition
to Cantera 2.1. The legacy webpages are still useful as they have an extensive set of documentation with screen shots of the input and output to demo programs. There are also discussions of how to fit and extrapolate thermodynamic data; some users may find this useful.
Notes and Acknowledgments
The Toolbox was updated in 2014 (Sept 9, 2014 ) for compatability with Python 2.7 and Cantera 2.1. Significant changes to the Cantera-Python interface demanded that the Python interface to the SDToolbox be updated accordingly. The changes are not backward compatible. Byran Schmidt and Neal Bitter carried out the conversion and testing of the new routines.
There have been substantial developments in Cantera since the last major update of the SD_Toolbox. The orginal author of Cantera, Dave Goodwin, lost his battle with cancer and Parkinson's in 2012. Although Dave was not able to actively contribute to development of Cantera for a number of years due to his illness, Dave's vision of an open source tool for energy research continues to be realized through the efforts of the many volunteers that have contributed to the Cantera project. We appreciate all the work by others that has gone into maintaining and extending Cantera so that we can continue to rely on this as the software engine underneath the SD_Toolbox.