Shock & Detonation Toolbox
| Code Home | Mechanisms | Win/Matlab | Win/Python | Lin/Python | Lin/ZND | Example | Thermodynamics | Notes | Contact |
- Nov 11, 2007 Toolbox completely rewritten. New version is significantly expanded and function calls are different than older versions.
- Feb 3, 2008 Documentation released for shock and detonation jump conditions. Matlab demo programs enhanced and examples of other applications added.
Thermodynamic fitting Matlab program added.
- Aug 15, 2008 Toolbox matlab source code style rewritten. New version returns more compact data structures. Additional advanced demos also posted.
The Shock & Detonation Toolbox is a software collection that enables
the computation of standard problems for gas-phase explosions using
realistic thermochemistry and detailed chemical kinetics. The SD
Toolbox uses Dave Goodwin's Cantera software for the chemistry
functionality and 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:
This toolbox has been implemented in Matlab and Python for Windows and
Linux operating systems. There are different releases of the toolbox
as described below for each system. Note that due to the differences of
Cantera in Matlab, Python, and C++, not all releases offer the same
functions. The SD Toolbox programs are available free of charge but
are subject to the same license agreement as
- CJ detonation speed computation
- Postshock gas state for frozen composition
- Postshock gas state for equilibrium composition
- Frozen and equilibrium Hugoniot curves
- Constant-volume explosion structure
- ZND detonation structure
- Computation of effective activation energy and 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 and Cantera versions:
The SD Toolbox requires Cantera, Python, and various Python libraries.
If you want to use the Matlab versions, an up-to-date installation of
Matlab is needed. Detailed instructions are given for each
installation. The version of Cantera that you will install depends on
what software and operating system you are using.
- Cantera 1.7 - Use this version
with Matlab R2006b or with Python, as labeled for each case below
- Cantera 1.6.0r3. - We are no longer supporting this version of the toolbox. If you need assistance, please contact us.
Mechanism Files for Cantera: Cantera requires a mechanism (.cti) file with thermodynamic and reaction rate data for the
species of interest. Some files are provided in the original Cantera distribution files and we provide additional files 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 orginal data sets supplied with Cantera.
They are also below in the following zipped file
Creating and Converting Mechanism Files
Information about generating .cti files by converting exiting data from other formats is given in the following links:
Programs for creating thermo data from scratch and extralpolating data from low to higher temperature ranges can be found here
- High Temperature Mechanism ".cti" Files:
- use same files for all operating systems and languages
Getting Started: We have provided a number of demonstration scripts or 'demos' that illustrate
how to use the SD Toolbox. The built-in help functions in Matlab and Python describe the usuage and arguments for each
function. For more details, see the 'Demos' links for each installation.
Installation for Matlab in Windows
- Install Cantera (V1.7)
- Install fixes
- MixMaster Bug Fix: ThermoFrame.py
- Replace current version in Python25\Lib\site-packages\MixMaster\
- Matlab Cantera Toolbox Bug Fix: gibbs_RT.m
- Replace current version in Cantera\MATLAB\toolbox\cantera\@ThermoPhase\
- Test Cantera Installation
- Install Shock & Detonation Toolbox (Installation Instructions)
Installation for Python in Windows
For Cantera V1.7
- Installation Instructions for Cantera, Python, SDToolbox, etc... (txt) (pdf)
- Necessary Zipped Files:
Installation for Python in Linux
For Cantera V1.7
Note: Not all Python scripts for Linux run in the Windows' environment.
- Installation Instructions for Cantera, Python, SDToolbox, etc...
ZND in Linux
ZND has been implemented in C++ using Cantera. Simulations are run using an input file or from a Python script.
For Cantera V1.7
- Cantera V1.7 Installation Instructions
- Compilation Instructions and Input File Description
Examples of Research Carried out with the SD Toolbox
Thermodynamic Data Creation and Input File Manipulation
Thermodynamic data used in the .cti files must either be created from scratch or imported from
existing files that are in other formats. See Windows or Linux for conversion information.
We provide two programs (described below) to generate and extrapolate thermodynamic data based on molecular structure and statistical mechanics.
Fitting Thermodynamic Data to Create New Mechanisms
We have implemented a Matlab demonstration program to fit tabular thermodynamic data with a constrained least squares fit. With this program, output for direct use in a Cantera mechanism and in the CHEMKIN format are created. A user may create new mechanisms or append this output to existing mechanisms, replacing or creating thermodynamic coefficients for a species.
Extrapolating Thermodynamic Data to Higher Temperatures
In detonation and shock computations, we often need thermodynamic data that extends to
higher temperatures than the upper limit of 3000 K used by many researchers today. Sometimes it
is possible to find older specific heat data that extends to 6000 K but in some cases this is not
available. The user must either recompute the specific heat functions and carry out new curve fits
to obtain polynomial coefficients. Since most specific heat data vary smooth between 3000 and 6000 K,
an alternative is to extrapolate the low temperature data to higher temperatures. This is how we
generated the high temperature data supplied with the SD Toolbox.
pages describe how to do this by using a Fortran program developed by Hai Wang.
For ease of use, this Fortran program has been wrapped in a perl script by Shannon Browne.
Notes and Acknowledgments
The SD ToolBox was originally conceived as a way to replace our workhorse Fortran programs and
scripts that we have used for the last 25 years and provided to other researchers free of charge.
The original Fortran programs CV and ZND were developed at Sandia National Labs by Joe Shepherd
in the early 1980s and were based on Bob Kee's gas-phase chemistry software
libraries. One motivation for writing new programs was to develop open source versions since
the underlying chemical kinetics software was commercialized in the
1990s. Another motivation was to modernize the approach and make it
easier to carry out complex sequential computations. In the past, we
had relied on two legacy programs, CEC76 and STANJAN, for equilibrium
computations and manipulating the input and output required extensive
file parsing and complex scripts. With the emergence of open source
software in the last five years, it became feasible to replace all the
legacy software with modules that can easily scripted and
Foremost, we thank Dave Goodwin for writing Cantera, supporting his
users, and making this all possible. The SD Toolbox was written by
Shannon Browne with contributions from Jack Ziegler and Joe Shepherd.
Vaughan Thomas patiently explained the mysteries of using Cantera with
C++ and made our ZND project working software instead of a debugger
example. Hai Wang generously shared his Fortran code and approach to
extrapolating polynomial fits. Mohsin Mohd Sies of the Faculty of
Mechanical Engineering, Universiti Teknologi Malaysia. showed us how
easy it was to port the Python to Windows and that version is based on
We benefited from the efforts of two researchers that are no longer with us. We borrowed
heavily from the algorithms Bill Reynolds developed for STANJAN
and in checking our work, used the thermo libraries and equilibrium programs provided by Bonnie McBride of NASA.
The toolbox administrator can be contacted via email at