Installing TabProps
Installing Dependencies
TabProps has several software dependencies
- Cantera, a kinetics/transport/thermo solver (IMPORTANT: Due to a namespace change, you will need version 1.7.1 or higher. Note that Cantera is only required if you want to build the preprocessing capability in TabProps. Prof. Sutherland has a CMake-based version of Cantera, which is available by cloning the git repository:
git clone git://software.crsim.utah.edu/Cantera.git
- Boost, specifically, boost::serialization. This library provides I/O capabilities for TabProps.
TabProps uses the CMake build system for cross-platform build capabilities. You will need to have CMake installed on your system.
Downloading TabProps
Once you have installed these software dependencies, you will need to check out a version of TabProps from the git repository.
git clone git://software.crsim.utah.edu/TabProps.git
Building the Code
Now you are ready to build the code. Using CMake, this is pretty simple:
- Create a directory where you want to build the code. This can be anywhere on your machine. However, do not build directly within the source directory.
- From the newly created build directory, run:
cmake [path to TabProps source] [OPTIONS]
Where the supported options are enumerated in the table below. To specify an option, add
-DOPTION=VALUE
on the command line whencmake
is invoked. This generates makefiles.
header 1 | header 2 |
---|---|
cell 1 |
cell 2 |
cell 3 | cell 4 |
Option | Description | Default Value |
---|---|---|
BOOST_ROOT |
(optional) path to the boost installation | N/A |
TabProps_PREPROCESSOR |
ON to build the preprocessing (table creation) part of TabProps. This also requires Cantera. Set to OFF if you only want to build the table reader portion (Cantera not required). |
ON |
TabProps_UTILS |
ON to build the table query utilities. Off to not build them. |
ON |
CMAKE_BUILD_TYPE |
Debug or Release
|
Release |
CMAKE_INSTALL_PREFIX |
The path to install TabProps to | the build directory |
TabProps_CONFIG_INSTALL |
The path to install the TabProps CMake configuration using TabProps with CMake in downstream apps | - |
Cantera_DIR |
The "share" directory where Cantera is installed (required if TabProps_PREPROCESSOR is ON ) |
- |
To build with a non-CMake version of Cantera, use the following options:
Option | Description |
---|---|
Cantera_CMAKE |
OFF to use a Cantera installation that was not built using CMake |
Cantera_Dir |
The path to the Cantera installation directory |
- Type
make
- this will build the TabProps library and the following executables:
-
mixrxn
- If theTabProps_PREPROCESSOR
flag was set to ON during the configuration, this will be installed. It is the preprocessing driver executable used to build tables -
tablequery
- a tool to extract data from the table and dump it into Tecplot and Matlab formats for visualization. -
pointquery
- a tool to perform interactive probing of a table. -
tablecompare
- a tool to compare tables (only works for boost-formatted tablesBoostOutput=ON
)
- You can do
make install
to install the files to the directory you specified with CMAKE_INSTALL_PREFIX
.
Generating Tables
The functionality in TabProps can be divided into two parts: a writer and a reader. The table writer in TabProps interfaces with Cantera to obtain transport and equilibrium data as a function of mixture fraction, heat loss, etc. given a reaction mechanism, species transport data, etc. This data is then fit to curves and the coefficients stored in the table.
Tables are generated using the mixrxn
executable. The basic syntax is
mixrxn -i [input file]
where the input file contains the information that tells mixrxn
what to do.
Reaction Models
There are several supported reaction models, which we cover here.
-
NonReacting implements mixing between two streams of given temperature and composition.
-
AdiabaticFastChem Burke-Schumann chemistry - implements complete reaction between to streams. Parameterized by the mixture fraction.
-
FastChem Burke-Schumann chemistry (infinitely fast with heat loss) - parameterized by mixture fraction and heat loss.
-
AdiabaticEquilibrium Adiabatic chemical equilibrium, parameterized by mixture fraction.
-
Equilibrium chemical equilibrium with heat loss. Parameterized by mixture fraction and heat loss.
-
SLFM Steady Laminary Flamelet Model - reads a flamelet library generated by Dr. Sutherland's code.
To activate a reaction model, use the <ReactionModel type="XXX">
tag as follows:
<ReactionModel type="model spec">
</ReactionModel>
where model spec
is one of the models listed above.
Note that you can use multiple <ReactionModel>
specifications within a single input file.
There are several options that control the behavior of these models
-
<order>
Specifies the interpolant order as an integer. Higher order interpolants are more expensive. Third order is recommended. -
<CanteraInputFile>
The name of the.cti
file that describes the thermodynamic and transport properties of the mixture. This is used to calculate any requested output properties. Example:
<CanteraInputFile>gri30.cti</CanteraInputFile>
- ` The name of the cantera gas definition in the .cti file. By default, this is set to the name of the .cti file. However, if you define multiple gas groups in your cantera input file, you can use this option to select among them. Example:
<CanteraInputFile>gri30.cti</CanteraInputFile>
<CanteraGroupName>gri30_mix</CanteraGroupName> <-- select the "gri30_mix" gas definition rather than the default "gri30" -->
-
<FuelComposition type="MoleFraction|MassFraction">
The composition of the fuel stream. Example:
<FuelComposition type=MassFraction>
<Species name="H2">0.75</Species>
<Species name="N2">0.25</Species>
</FuelComposition>
All entries for FuelComposition must be either mass fraction or mole fraction.
This tag must include the type attribute specifying either MoleFraction
or MassFraction
and then by a valid species name (contained in the CanteraInputFile
).
-
<OxidizerComposition>
The composition of the oxidizer stream. Example:
<OxidizerComposition type=MoleFraction>
<Species name="O2">0.21</Species>
<Species name="N2">0.79</Species>
</OxidizerComposition>
All entries for OxidizerComposition
must be either mass fraction or mole fraction.
This tag ''must'' include the "type" attribute specifying either MoleFraction
or MassFraction
and then by a valid species name (contained in the CanteraInputFile
).
-
<FuelTemperature>
The temperature (Kelvin) of the fuel stream. -
<OxidizerTemperature>
The temperature (Kelvin) of the oxidizer stream. -
SelectForOutput
Select information for output. The following options are currently supported (case insensitive)Temperature
Viscosity
SpecificHeat
Conductivity
density
-
Species
(all species mass fractions) -
MoleFrac
(all species mole fractions) ReactionRate
SpeciesEnthalpy
-
SensibleEnthalpy
(only for models with heat loss) -
AdiabaticEnthalpy
(only for models with heat loss) MolecularWeight
-
<SelectSpeciesForOutput>
Allows selection of specific species mass fractions for output. -
<SelectMoleFracForOutput>
Allows selection of specific species mole fractions for output.
The following table indicates which options are valid for the various reaction models.
Option | Parent Option | Default Value | NonReacting | AdiabaticFastChem | FastChem | AdiabaticEquilibrium | Equilibrium | SLFM |
---|---|---|---|---|---|---|---|---|
CanteraInputFile | - | x | x | x | x | x | x | |
CanteraGroupName | prefix of the cantera input file | x | x | x | x | x | x | |
order | 1 | x | x | x | x | x | x | |
- | x | x | x | x | x | |||
- | x | x | x | x | x | |||
FuelTemperature | - | x | x | x | x | x | ||
OxidizerTemperature | - | x | x | x | x | x | ||
SelectForOutput | - | x | x | x | x | x | x | |
SelectSpeciesForOutput | - | x | x | x | x | x | x | |
SelectMoleFracForOutput | - | x | x | x | x | x | x | |
npts | 101 | x | x | x | x | x | ||
GridStretchFactor | 3.0 | x | x | x | x | x | ||
NHeatLossPts | 51 | x | x | |||||
FuelComposition, OxidizerComposition | - | x | x | x | x | x | ||
FuelComposition, OxidizerComposition | - | x | x | x | x | x |
Here is an example input file that implements an adiabatic equilibrium reaction model.
<-- Specification for the AdiabaticEquilibrium model
<ReactionModel type="AdiabaticEquilibrium" >
<CanteraInputFile>h2o2.cti</CanteraInputFile>
<FuelComposition type=MassFraction">
<Species name="H2" >0.8</Species>
<Species name="H2O">0.2</Species>
</FuelComposition>
<FuelTemperature>300</FuelTemperature>
<OxidizerComposition type=MoleFraction>
<Species name="O2">0.21</Species>
<Species name="AR">0.79</Sepcies>
<OxidizerTemperature>300</OxidizerTemperature>
<SelectForOutput>
temperature density MolecularWeight enthalpy species ReactionRate SpeciesEnthalpy
</SelectForOutput>
<nfpts>176</nfpts> <-- number of points in mixture fraction -->
<GridStretchFactor>4.0</GridStretchFactor> <-- cluster grid more densely near stoichiometric. -->
Mixing Models
TabProps supports presumed PDF mixing models in one independent variable. Currently, the beta-PDF and clipped-Gaussian PDF are supported.
To activate a mixing model, do the following:
<MixingModel type="XXX">
Where type
is one of the supported mixing models. There are several required parameters for the mixing model, as depicted in the following sample input file:
<-- Activate a clipped-Gaussian mixing model -->
<MixingModel type="ClipGauss">
<-- specify the name of the reaction model for use in the mixing model.
Here we use the equilibrium model. This will require that a file
"Equilibrium.tbl" exists in the run directory. -->
<ReactionModelFileName>Equilibrium</ReactionModelFileName>
<-- specify the variable that we are applying the mixing model on.
this variable name comes from the reaction model table. -->
<ConvolutionVariable>MixtureFraction</ConvolutionVariable>
<-- Specify the number of points in each independent variable.
Note that this assumes a range of [0,1] for each variable
unless we set the "min" and "max" values -->
<MixtureFraction><npts>21</npts></MixtureFraction>
<HeatLoss>
<npts>21</npts>
<min>-1.0</min>
<max>1.0</max>
</HeatLoss>
<MixtureFractionVariance><npts>2</npts></MixtureFractionVariance>
</MixingModel>
Examples
In the TabProps/test
directory you will find several input files.
Querying Tables
Because tables are stored as spline coefficients, you cannot easily "see" the information in them. There are two utilities provided to help with this.
-
pointquery
interactively samples the table and prints the values for all dependent variables to the screen. -
tablequery
Extracts the information from the table onto a structured mesh for visualization in Matlab or TecPlot.
tablequery
Using When TabProps creates a table, it stores the coefficients for
the interpolating polynomials rather than the data itself. When
you run tablequery
, you specify the "mesh" that you want your
output on, and then the table is queried at those locations and a
file is written to disk.
To diagnose problems in a table, you may 'subsample' or 'oversample' a table. Recall that a table is constructed by interpolating discrete points. When you sample a table, you are evaluating these interpolants at new points. By "oversampling," you can identify regions in your table that may be underresolved.
As an example, consider a methane equilibrium calculation using gri 3.0 with the following TabProps input file:
<ReactionModel type="AdiabaticEquilibrium">
<CanteraInputFile>gri30.cti</CanteraInputFile>
<FuelComposition type="MoleFraction">
<Species name="CH4">1.0 </Species>
</FuelComposition>
<FuelTemperature>300</FuelTemperature>
<OxidizerComposition type=MoleFraction>
<Species name="O2">0.21</Species>
<Species name="N2">0.79</Species>
</OxidizerComposition>
<OxidizerTemperature>300</OxidizerTemperature>
<SelectForOutput>temperature density MolecularWeight specificheat</SelectForOutput>
<SelectMoleFracForOutput>OH CO2</SelectMoleFracForOutput>
<nfpts>50</nfpts> <-- number of points in mixture fraction -->
<GridStretchFactor>1.0</GridStretchFactor>
Here we turned off grid stretching by setting GridStretchFactor=1.0
. This creates a table from 50 equally spaced points in mixture fraction space.
Image(ch4_lowres_dens.png, 350px, right)tablequery
on the resulting table using 500 points on the interval [0,1], we can produce a matlab file that can be viewed using [TabProps#Theplot_tablescript plot_table] to produce the plot to the right. Notice that the original equilibrium calculation points are "imprinted" on the table, an effect that is easily seen by oversampling the table.
By increasing resolution in the table and using grid stretching, one can improve the quality of the table.
plot_table
Script
The This script is intended to be used in Matlab to load files generated by [TabProps#Usingtablequery tablequery].
AdiabaticEquil; % load the output file
plot_table( ivar, ivarNames, dvar, dvarNames, npts );
This will interactively produce plots of your table.