Skip to content

Changes

Page history
james created page: home authored by James Sutherland's avatar James Sutherland
Hide whitespace changes
Inline Side-by-side
home.markdown 0 → 100644
View page @ f23a69a5
# Installing TabProps
## Installing Dependencies
TabProps has several software dependencies
* [Cantera](http://sourceforge.net/projects/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](http://www.boost.org), specifically, [boost::serialization](http://www.boost.org/doc/libs/release/libs/serialization/doc/index.html). This library provides I/O capabilities for TabProps.
TabProps uses the [CMake](http://www.cmake.org) 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:
1. 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.
2. 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 when `cmake` 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 |
3. Type `make` - this will build the TabProps library and the following executables:
* `mixrxn` - If the `TabProps_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 tables `BoostOutput=ON`)
4. 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>
```
* <CanteraGroupName>`
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 | <ReactionModel> | - | x | x | x | x | x | x |
| CanteraGroupName | <ReactionModel> | prefix of the cantera input file | x | x | x | x | x | x |
| order | <ReactionModel> | 1 | x | x | x | x | x | x |
| <FuelComposition type=""> | <ReactionModel> | - | x | x | x | x | x | |
| <OxidizerComposition type=""> | <ReactionModel> | - | x | x | x | x | x | |
| FuelTemperature | <ReactionModel> | - | x | x | x | x | x | |
| OxidizerTemperature | <ReactionModel> | - | x | x | x | x | x | |
| SelectForOutput | <ReactionModel> | - | x | x | x | x | x | x |
| SelectSpeciesForOutput | <ReactionModel> | - | x | x | x | x | x | x |
| SelectMoleFracForOutput | <ReactionModel> | - | x | x | x | x | x | x |
| npts | <ReactionModel> | 101 | x | x | x | x | x | |
| GridStretchFactor | <ReactionModel> | 3.0 | x | x | x | x | x | |
| NHeatLossPts | <ReactionModel> | 51 | | | x | | x | |
| <Species name=""> | FuelComposition, OxidizerComposition | - | x | x | x | x | x | |
| <Species name=""> | 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.
# Using `tablequery`
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)]] If we run `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.
## The `plot_table` Script
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.
\ No newline at end of file