1. Introduction

The OpenSMOKE++ Suite is a collection of standard solvers for performing kinetic analyses with detailed kinetic mechanisms, with hundreds of species and thousands of reactions. The word "solver" has to be intended as an independent program, built with the aim to perform a specific task (for example to simulate a batch reactor, or to model a shock-wave, etc. ). Thus, in the following, the OpenSMOKE++ Suite definition will be used to refer to the collection of OpenSMOKE++ standard solvers. The list of available solvers (which is continuously growing) includes:

1. a kinetic pre-processor, a utility which is able to read, pre-process and analyze kinetic mechanisms written in the CHEMKIN(R) format. Its main purpose is to rewrite the kinetic scheme in a XML format which can be efficiently used by the OpenSMOKE++ Suite solvers;
2. a collection of solvers (i.e. independent executable files), one for each system to simulate. In other words, the OpenSMOKE++ Suite provides the solver dedicated to the simulation of plug flow reactors, the solver dedicated to the simulation of batch reactors, and so on. These solvers are completely independent from each other, but need the same pre-processed kinetic mechanism in XML format generated by the kinetic pre-processor described above;
3. a graphical post-processor, to easily post-process the simulation results. It is able not only to plot the usual profiles of temperature, pressure, composition, etc. along the time or space coordinate, but it is extremely useful to rapidly perform sensitivity analyses, rate of production analyses, and to draw flux diagrams. The figure below show a schematic diagram of the OpenSMOKE++ Suite.

1.1 Organization

The OpenSMOKE++ Suite consists of several executable files, libraries and utilities which are organized in several folders, as reported in the following:

• bin
• docs
• examples
• kinetic-mechanisms
• lib
• quick-start
• tutorials

bin

The bin folder contains the executable files to pre-process kinetic schemes in CHEMKIN format, to simulate ideal reactors (batch, perfectly stirred, plug-flow reactors, and shock tubes), laminar 1D flames, etc. and to graphically post-process the results.Together with the executables, the bin folder includes the needed dll libraries (for Microsoft Windows users) or the needed shared libraries (for Linux users) are available. We recommend to leave these libraries in the same bin folder containing the executable files.

docs

The docs folder contains documentation files.

examples

The examples folder, as suggested by the name, contains several examples to learn how to run the simulation for the ideal reactors available in the OpenSMOKE++ Suite. We strongly recommend to look at the examples reported in this folder to have more information about the most advanced options. All the examples can be simulated by simply double-clicking on the Run.bat file (for Microsoft Windows users) or running the Run.sh file (for Linux users).

kinetic-mechanisms

The kinetic-mechanisms folder contains several kinetic schemes in CHEMKIN format freely available from the web. Most of them are from the CRECK Modeling Group at Politecnico di Milano and can be downloaded at the following address: http://creckmodeling.chem.polimi.it/. For each kinetic scheme, at least the thermodynamic and the kinetic files are provided.

lib

The lib folder (available only for Linux platforms) contains the shared libraries needed to run the solvers and the graphical post-processor. In particular, the current version of OpenSMOKE++ Suite includes shared libraries for Boost C++, Intel MKL, and Sundials Suite.

quick-start

The quick-start folder contains the examples described in this Quick Start Section

tutorials

The tutorials folder contains the examples described in the Tutorials Section

1.2 How the OpenSMOKE++ Solvers work

All the OpenSMOKE++ Suite solvers, together with the kinetic pre-processor, do not have any graphical interface. They are based on input files in ASCII format. Only the graphical post-processor works with a GUI (Graphical User Interface), based on the QT libraries. This means that if you want to pre-process a kinetic mechanism (together with the thermodynamic and transport properties) or you want to simulate a reactor, your input conditions must be provided through one or more input files. These are simple ASCII files which can be written and modified using a generic text editor, like Notepad, Notepad++, Microsoft Word, gedit, etc. In the following lines, an example of perfectly stirred reactor is reported:

The main rules to write the input files are listed below:

1. The comments must be preceded by the // keyword. A comment can be inserted at the beginning or in the middle of a line. Every word or number reported after the // keyword is considered as a comment and ignored.
2. The input data must be organized in Dictionaries, i.e. homogeneous input data have to be collected together in the same structure (see the example above).
3. Each dictionary is defined by the Dictionary word, followed by the name of the dictionary. The options belonging to this dictionary have to be reported between the { and the } symbols.
4. Each keyword begins with the @ symbol, usually requires one or more options (bool variables, number, strings, etc.)
5. Each input line must end with the ; symbol.

In the example reported above, which refers to a steady-state, perfectly stirred reactor, two different dictionaries were defined, with names equal to PerfectlyStirredReactor and Inlet-Composition, respectively. In each of these two dictionaries, several input data are specified through different keywords. The available options depend on the solver you are using. Please, look at the User's Guide, where the complete list of options available for each kind of reactor are reported and explained.

2. A first example

In this section we describe how to setup and run a typical OpenSMOKE++ simulation. As a first example, the attion will be focused on an adiabatic batch reactor, whose initial composition is a stoichiometric mixture of syngas (40% H2, 60% CO) and air (21% O2, 79% N2) at 10 atm and 600 K.

2.1 Selection of thermodynamic data and kinetic mechanism

In order to run simulations with OpenSMOKE++ Suite solvers, the user needs a kinetic scheme describing the homogeneous (gas-phase) (and, optionally, also the heterogeneous or surface reactions), and the thermodynamic properties for each species included in the kinetic mechanism. The current version of OpenSMOKE++ requires that the kinetic scheme, together with the thermodynamic and (optionally) transport properties, is provided according to the CHEMKIN(R) rules. Kinetic mechanisms and thermodynamic and transport data in CHEMKIN(R) compatible format are available from several research groups. In particular, a non exaustive list (adapted from the CHEMKIN(R) User's Guide) is reported in the following:

• The CRECK Modeling group at Politecnico di Milano provides detailed kinetic mechanisms describing pyrolysis, combustion, and oxidation of several fuels: hydrogen, methane, propane, PRF, diesels, jet-fuels, biofuels, etc.

http://creckmodeling.chem.polimi.it/

• Lawrence Livermore National Laboratory (LLNL) has posted combustion mechanisms, including thermodynamic data, transport data, and reaction sets for flame simulations with hydrogen and various hydrocarbon fuels.

https://www-pls.llnl.gov/?url=science_and_technology-chemistry-combustion-mechanisms

• The Combustion Division of the Center for Energy Research at the University of California-San Diego has posted kinetic mechanisms for combustion qpplications, including nitrogen, JP10, and heptane chemistry.

http://web.eng.ucsd.edu/mae/groups/combustion/mechanism.html

• The Combustion Group at Princeton University provides mechanisms for combustion of chlorinated and fluorinated compound mixtures with methane, and for high-pressure methane and propane flames.

http://www.princeton.edu/mae/people/faculty/dryer/homepage/kinetic_models/

• Professor Alexander Burcat of Technion Israeli Institute of Technology has posted his database of thermodynamic properties. The data has been collected from many sources and is critically reviewed and frequently updated. The BURCAT.THR file is in CHEMKIN format, but contains comments and descriptive text about each species, so that file would require some user manipulation (commenting out text lines) in order to be used directly in OpenSMOKE++.

http://garfield.chem.elte.hu/Burcat/burcat.html

• The Gas Research Institute (GRI) funded development of the GRI-mech, which is a CHEMKIN mechanism for natural gas combustion, including thermodynamic properties and rates. You can download the most recent version of GRI-mech from the GRI-mech website.

http://combustion.berkeley.edu/gri-mech/

Please, look at the CHEMKIN User's Guide to find the syntax rules to correctly write and modify the files describing the kinetic mechanism and the thermodynamic and transport properties.

In this example we will use the POLIMI_H2CO_NOX_1412 kinetic mechanism of CRECK Modeling group at Politecnico di Milano. This is a detailed kinetic mechanism describing the combustion of mixtures of hydrogen and carbon monoxide, consisting of 32 species involved in more than 170 reactions. It is available in the kinetic-mechanisms\POLIMI_1412\Kinetics folder or, alternatively, it can be freely downloaded from the following page: (http://creckmodeling.chem.polimi.it/). The thermodynamic data are available in the kinetic-mechanisms\POLIMI_1412\Thermodynamics folder. In particular, for the purposes of this first example, we need only the thermodynamic data (POLIMI_TOT_NOX_1412.CKT file) and the kinetic mechanism (POLIMI_H2CO_NOX_1412.CKI file). The transport data are not needed for the simulation of a batch reactor.

2.2 Pre-processing of kinetic mechanism

Before using it in OpenSMOKE++ Suite, the kinetic scheme has be be pre-processed and re-written in a new format. This operation can also be performed on-the-fly, i.e. directly when the simulation is started (look at the User's Guide for additional details). However, in this first example, we prefer to perform this pre-processing operation as an independent step. The pre-processing of a kinetic mechanism (together with thermodynamic and transport data, if needed) must be performed only once, using a particular solver of OpenSMOKE++ Suite, which is called OpenSMOKEpp_CHEMKIN_PreProcessor.

1. Create a new folder and copy there the the thermodynamic and kinetic files mentioned above ((POLIMI_TOT_NOX_1412.CKT and POLIMI_H2CO_NOX_1412.CKI, respectively).

2. Create a new input file (kinetics.dic in the following, but in principle the user is free to choose the name he/she prefers) in which you specify the the thermodynamic and kinetic files and the destination folder:

// Example of input file for OpenSMOKE++

3. Run the kinetic pre-processor using the following command (in Microsoft Windows):

%OPENSMOKEPPpp_EXE_FOLDER%\OpenSMOKEpp_CHEMKIN_PreProcessor.exe --input kinetics.dic

or (in Linux and Mac OSX):

OpenSMOKEpp_CHEMKIN_PreProcessor.sh --input kinetics.dic

4. If everything works properly, you will find the result of this pre-processing operation in the folder you specified through the @Output option in the kinetics.dic file.

2.3 Preparation of batch reactor simulation

We are now ready to write the input file (batch.dic in the following) reporting the input data for the batch reactor simulation.

1. In the same folder where the kinetic mechanism has been pre-processed, create a new text file, called batch.dic:

For the meaning of each option and additional/alternative options, please look at the User's Guide.

2. Run the OpenSMOKE++ Suite solver for batch reactors (OpenSMOKEpp_BatchReactor) using the following command (in Microsoft Windows):

%OPENSMOKEPP_EXE_FOLDER%\OpenSMOKEpp_BatchReactor.exe --input batch.dic

or (in Linux and Mac OSX):

OpenSMOKEpp_BatchReactor.sh --input batch.dic

3. If everything works properly, you will find the result of this pre-processing operation in the Output folder.

2.4 Analysis of results (without graphical post-processor)

The results of the simulations are written in the Output folder. In this particular example three files are available:

1. FinalSummary.out: this file reports the initial and final status of the reacting mixture (temperature, pressure, density, composition, etc.)
2. Output.out: it is organized in columns and the first row reports the meaning of each column, together with a number which refers to the column number. Both the mole and mass fractions of species are reported: the mole fractions have the x suffix, while the mass fractions the w suffix. You can easily import this file in Microsoft Excel, Matlab, etc. or you can use Gnuplot to directly plot (also on the fly) the results.
3. Output.xml: XML output file to be used by the OpenSMOKE++ graphical post-processor (see next Section)

The profiles reported in the Output.out file can be easily plotted using Gnuplot, Microsoft Excel, Matlab, etc. In particular, we recommend to use Gnuplot. As an example, if you want to plot the mole fraction profiles of H2 versus time, in Gnuplot you can type:

p 'Output/Output.out' u 1:22 w l t 'H2'

The Figure below shows additional profiles plotted with Gnuplot.

2.5 Analysis of results with OpenSMOKE++ graphical post-processor

In addition, you can analyze the results through the OpenSMOKE++ Graphical PostProcessor.

1. In order to graphically post-process the results you have to run the OpenSMOKEpp_PostProcessor utility (contained in the bin folder of OpenSMOKE++ Suite).

2. Select the folder containing the Output.xml file generated by the simulation by clicking on the Select Results… button. The Profiles button becomes now available. If you click on it, you have the possibility to plot the calculated profiles of species, temperature, pressure, etc. As an example, in the following Figures profiles of selected species are reported.

3. If you want to perform more interesting post-processing analyses, you have to load also the pre-processed kinetic scheme. In order to do this, you should close the Profiles window and click on the Select Mechanism… button. Then, select the folder containing the kinetics.xml file generated by the kinetic pre-processor. The Rate of Production button becomes available. If you click on this button, a new window will be available. Here you have the possibility to plot formation rates for all the species and reaction rates for all the reactions (see Figure below). You can analyze the distribution of characteristic times by looking at the eigenvalues of the Jacobian matrix, by clicking on the Analyze Characteristic Times button.

4. More interestingly, you can perform rate of production analysis for each species in the kinetic scheme through the Plot ROPA bars button (see Figures below).

5. Eventually, you can also draw path diagrams through the Flux Analysis button (this feature is only available if you correctly installed Graphviz and Irfanview, as described in the Installation Section). As an example, in the Type panel select the Local radio button and write 0.022 in the corresponding window (this is the time in seconds at which you want to perform the flux analysis). Select NO from the Species list, N element from the Element list, and Production from the Type panel. If you click on the Flux Analysis button, you should get the flux diagram reported in the following Figure.

2.6 Sensitivity analysis

The OpenSMOKE++ Suite provides several useful tools to perform sensitivity analysis, both for unsteady and steady-state problems. Sensitivity analysis is very important for kinetic studies, since it allows the quantitative understanding of how the numerical solution of the governing equations depends on the various parameters contained in the model itself. Only the first-order sensitivity coefficients with respect to the reaction rate coefficients (pre-exponential factors, activation energy or kinetic constant) can be calculated.

Since the calculation of first-order sensitivity coefficient is very time consuming, the user has to request explicitly the sensitivity analysis before running the simulation. Thus, in order to perform the sensitivity analysis, we modify the batch.dic file by adding a new dictionary:

and by enabling the sensitivity analysis calculation in the main BatchReactor dictionary, through the addition of the following command:

Now you can run the batch reactor simulation using the following command (in Microsoft Windows):

%OPENSMOKEPP_EXE_FOLDER%\OpenSMOKEpp_BatchReactor.exe --input batch.dic

or (in Linux and Mac OSX):

OpenSMOKEpp_BatchReactor.sh --input batch.dic

If everything worked properly, you can now look at the results of sensitivity analysis using the OpenSMOKE++ PostProcessor. In particular, after selecting the folders containing the Output.xml file and the pre-processed kinetic mechanism, the third button, Sensitivity Analysis, will be available. You can now plot the specific sensitivity coefficient profiles for each species and reaction or a bar chart for every species. An example is reported in the following Figures.