Chemical Reaction Path Diagram Tool
The reaction path diagram tool (ChemPathTool) aids in the generation of chemical path diagrams for reacting flow systems. More generally, ChemPathTool is used to manipulate graphically the layout of a bi-directed graph. For reacting flow systems, the nodes of this graph represent chemical species, and the arrows (or, edges) connecting the nodes represent the flow of a conserved quantity between species, such as the transfer rate of a particular element.
In our systems, atoms are transferred among species through chemical reactions. For example, when the reaction CH4(+M)<=>H+CH3(+M) proceeds, the impact of an arbitrary molecule (M) knocks one H atom from the CH4 molecule. Thus, a carbon atom is "transferred" from the set of all CH4 molecules to the set of CH3. The progress rate of this reaction (and its reverse, ie sticking an H atom onto a CH3 molecule) depends on the local state. In a typical reacting flow calculation there are hundreds of such reactions, and the goal is to understand how the state of the fluid affects the reaction balance. The path diagram turns out to be a good way to visualize the state of the chemical system.
The edges in a path diagram are obtained from a numerically simulated reacting flow using three basic steps:
The chemical species and atomic flux rates are loaded into our tool as graph nodes and directed edges, respectively. The user then manipulates the layout of this graph into a geometry that is visually meaningful. The resulting path diagram is written out as an Encapsulated PostScript file for printing or further manipulation, and the layout of the nodes can be saved and reused with another set of edge strengths. By changing the input data (simulation parameters, region of integration, element of interest, etc), one can generate a series of path diagrams that are useful for identifying patterns in the chemical system.
There are a number of automated path generation tools available on the web. But from our point of view, they all had a serious flaw that rendered them unusable. All the tools were too smart, in that they found optimized ways to arrange the nodes based on the strength and connectivity of the edges. Each run resulted in a different nodal layout, and any two cases were impossible to compare side by side. (Moreover, there are standard species layouts in the combustion literature one might like to emulate). The ChemPathTool allows (or forces, depending your point of view) one to specify the location of the nodes regardless of the edge strengths. Since the user must now design graph layouts, we found it most simple to provide a simple customized drawing tool. In the end, our simple concept led to a piece of software with two aims: easy creation of a nice layout, and application of that layout to multiple sets of edge strengths.
You may have picked up on one omission from the previous paragraph: how to generate the data in practice. Like all analysis, this can be arbitrarily complicated. In a later section, we present a simple example that will guide you in creating your own data.
The node names and edge strengths are loaded into the tool as a file containing a list of names and numbers. This may be done while starting the tool from the python command-line, or after the tool has been started. The main window of the tool features a prominent drawing canvas, and a number of toggle switches and menus. Beginning with a blank canvas, the user makes a subset of the nodes visible and arranges them interactively using the mouse pointer ("align", "distribute", "group", "lock", "nudge" and "rubber-band select" tools, such as those found in common illustration software, make it easy to generate publication-quality results). The directed edges connected to the nodes follow them as they are moved around the canvas. Only edges with strength above a threshold are drawn; the threshold value is controlled with a "slider" widget as a percentage of a reference edge value. The layout may be saved to a file, and recalled for a new dataset. If the new dataset has a different set of species, only those in common with the saved set are placed on the canvas (this allows side-by-side comparisons of results from different mechanism reductions, for example). The remaining nodes may be omitted, or placed on the canvas in a separate step. The resulting path diagram is then saved in EPS format, allowing annotations and touch-ups by fancier illustration packages. Click here for a demonstration of the ChemPathTool in action.
ChemPathTool requires data input in the form of a list of nodes and a list edges. Data for each node includes the text string that will be used as a label. Edge data includes the labels of the "from" and "to" nodes, and the strength of the edge (thickness of the arrow to be drawn). Optionally, two values may be associated with each edge. The data is given to the ChemPathTool in the form of an ascii text file, or "ChemPathTool Edge Data" (CED) file, and is loaded via the "File->Load Edge Data" menu while the tool is running:
|
Line 1->Case ID Line 2->sp1 sp2 sp3 sp4 sp5 sp6 Line 3->sp2 sp4 1.9 -2.3 Line 4->sp1 sp3 2.3 -100 Line 5->... |
The first line of the file contains an ID string that can optionally be printed onto the canvas. The second line contains the set of space-delimited names associated with each node. Each line after that contains two species names (each must be a recognized node from the list on the second line), and one or two values. Often the two values will be of opposite sign and represent the production and depletion of a species--a single value would represent their sum. The ChemPathTool will normalize these values linearly and draw edge arrows connecting the nodes on the canvas using a correspondingly scaled arrow thickness. A toggle on the panel allows one to coalesce the two on the fly. Another toggle allows one to shut off the normalization (when normalization is off, then a weight of 100 produces an arrow 20pts thick). Some nodes may not be connected in a given edge data set.
Generation of the data can be arbitrarily complex, depending of course on the quantity you're trying to visualize. In the simplest case, one has a single state, which includes the pressure, temperature and species distribution. With this state you will associate a chemical reaction mechanism and set of thermodynamic relations between state properties. With these one may compute chemical reaction rates. Then, given a choice for which element to trace through the system, one can form the complete set of path diagram edges, and proceed to evaluate them into the CED file described in the section above.
As this part of the analysis is outside the scope the ChemPathTool intentions, we borrow heavily from Dave Goodwin's Cantera package to ease the generation of sample data. We basically create a python filter that turns a set of state data into a CED file using the appropriate ChemKin(TM) input file and some handy scripts (which are included with the ChemPathTool).
|
Line 1->
from mechinfo import * Line 2-> from CanteraChemEdgeAnalysis import * Line 3-> from Cantera
import OneAtm Line 4-> Line 5-> readMechanism('gri30.inp') Line 6-> Nspec = numSpecies() Line 7-> Line 8-> # Set state Line 9-> X = [1.0 / Nspec]
* Nspec Line
10-> setState(2000.0, OneAtm,
X) Line
11-> Line
12-> # Compute reaction rates Line
13-> qf = fwdRatesOfProgress() Line
14-> qr = revRatesOfProgress() Line
15-> qnet = qf - qr Line
16-> Line
17-> # Decompose reactions into edges Line
20-> edges = getEdges('C') Line
21-> Line
22-> # Dump out nodes and edges Line
23-> print ’Here is a sample label’ Line
24-> print join(speciesNames()) Line
25-> for e in edges: Line
26-> valf
= 0.0 Line
27-> valr
= 0.0 Line
28-> for [r,c]
in e.rateWeightList: Line
29-> valf
+= c*qf[r] Line
30-> valr
+= c*qr[r] Line
31-> print
e.sp1,e.sp2,valf,-valr |
This script is written in the python language, but should be easy to follow for non-Python users. In lines 1-3, we import a number of useful functions from Cantera. We also include CanteraChemEdgeAnalysis provided with this distribution, which includes a special support function to be discussed in momentarily. Line 5 is the Cantera call to read up a ChemKin(TM) style reaction mechanism and thermodynamics database file. Line 6 defines a handy variable, and Line 9 uses it to create a reasonable value for all the species mole fractions (they should sum to 1). Line 10 sets the state inside the Cantera package, and then Lines 13-14 use that state to compute the forward and reverse reaction rates for all the reactions specified in "gri30.inp". The two calls result in two arrays of floating point numbers.
Line 20 uses the reaction data from "gri30.inp" to generate a set of edges that represent the flow of "C" (carbon) through the system. This is accomplished by looking at each reaction involving carbon-containing species, and identifying the atoms shuffled between species as the reaction progress. For all but a very few cases, such a decomposition is unambiguous. There are exceptions in the automatic processing though. For example, when tracing nitrogen, the reaction
HNO + NO2 <=> HONO + NO
may remove an H atom from HNO resulting in NO. Alternatively, HNO could gain an O atom and become HONO. The code in the CanteraChemEdgeAnalysis.py file provided with this distribution arbitrarily chooses to transfer the lighter of the two species. However, such a decision is certain to be wrong in some cases.....buyer beware.
Each edge in the edge list provided by the function "getEdges" contains the "to" and "from" species, and a list of reaction id's and corresponding multipliers to indicate the number of trace atoms transferred on each occurrence of the reaction. The loop in Lines 24-29 sums the forward and reverse atomic fluxes separately for each edge. Finally, Lines 23, 24 and 31 print the desired CED file to the screen.
<Note: A complete install on a Win2K machine takes about 10 minutes or less, depending on your network connection.>
The path tool is fully contained in a simple (albeit somewhat lengthy) Python script. Python is an interpreted, interactive, object-oriented programming language. It is often compared to Tcl, Perl, Scheme or Java. There are Python interfaces to many system calls and libraries, as well as to various windowing systems (X11, Motif, Tk, Mac, MFC). The Python implementation is portable: it runs on many brands of UNIX, on Windows, DOS, OS/2, Mac, Amiga. Therefore, our ChemPathTool should be fully portable across all platforms supported by Python.
A Python script is a text file that is interpreted by the Python interpreter, in a fashion similar to PostScript, MatLab, Mathematica, etc. There is a large body of freely available modules for extending Python's basic functionality. For our puposes, the most useful of these are Tkinter and the Python Mega Widgets (Pmw). Tkinter provides a very simple and uniform interface to the local window system (X-windows, Microsoft, MacOS, etc) to enable simple GUI construction, and is included with the latest Python distribution on most platforms. Pmw provide an even simpler interface to some handy buttons and such, and is installed by copying a directory into a special location in the Python directories built during the default Python install.
To install Cantera's Python interface, it's best to go directly to Dave Goodwin's Cantera site after you finish the first three steps below successfully. See step (4) below for more information.
To install ChemPathTool:
For windows in particular, you will get the windows installer. Double-click on the .exe file you download, verify the default install location, and click finish. There are rpm's for Linux and Mac binaries for the Macintosh that are similarly easy to intall. For other systems, you've got do the the usual "gunzip; tar; configure; make install" deal.
Unzip and untar, and then put the resulting Pmw directory in your Python site-packages area (alternatively be sure that your PYTHONPATH environment variable points to a directory that includes the Pmw directory). On my Windows 2000 machine, all the Pmw stuff ended up in a directory called
C:\Program Files\Python22\Lib\site-packages\Pmw
Unzip and untar ChemPathTool-1.0.tar.gz, and copy the files that end up in the directory "ChemPathTool-1.0" over to the same site-packages directory used for (2) above. On my Win2K machine, I ended up, for example, with the file:
C:\Program Files\Python22\Lib\site-packages\ChemPathTool.py
(For a windows machine, you may alternatively grab the Windows install file, and double-click it. This will not only put the ChemPathTool files in the correct place, but will provide an uninstall capability available from the "Start->Settings->Control Panel->Add/Remove Programs" window to clean out the whole thing later if desired.)
SAMPLE
INPUT AND LAYOUT DATA: The distribution includes a
directory at the top level called “ChemPathToolData”.
This should be installed in the site-packages area, and has example ChemPathTool edge data files, and ChemPathTool
layout files that can be loaded from the ChemPathTool
“File” menu.
C:\Program Files\Python22\Lib\site-packages\Cantera
To run ChemPathTool:
ChemPathTool may be started two ways:
Comments and Acknowledgements
The key to the path diagram tool existence has been in its simplicity. We are not software packagers, and have only put a minimal effort into its development. However, we strongly encourage suggestions or contributions in terms of additional features and bugs reports (email to MSDay@lbl.gov). We hope that you find this drawing and analysis tool useful and inspiring of new analysis techniques and tools.
Also, we should mention that the path tool was developed upon ideas originally programmed by Bill Crutchfield. Bill pointed us to Tkinter and created a first-cut implementation that has evolved into its present shape. Also, Joe and I fleshed out our thoughts on reaction decomposition in part while talking with Dave Goodwin, the developer of the Cantera chemistry package. Without input from these two, we may well have never built the tool.