Simplified Cantera User Guide

Cantera is an open-source set of C++ codes used for calculating chemical kinetics, thermodynamic and
transport properties of reacting systems. The full functionality is only achieved by using the C++ codes, but
the majority of the features are available through the Python interface. This document will provide a very
basic introduction to using Cantera in the Python environment. Python is an interpreted language, like
Matlab, which means that you can either enter things directly at the command line, which can be inefficient,
or by creating a script.
Full
documentation
about
Cantera
can
be
found
at
http://cantera.github.io/devdocs/sphinx/html/index.html. One of the most useful things will be to look at the examples that are provided
with Cantera that can be found at, depending on your exact installation, c:\pyzo2015a\lib\sitepackages\cantera\examples.

Units
The unit system employed for Cantera is: temperature [K]; pressure [Pa]; mass [kg]; energy [J]; moles
[kmol]; volume [m3]; area [m2],

Setting up Python
In order to use Cantera in Python, you need to import the library so that it is available in Python. This is
done as:
import cantera as ct
This now enables the full use of Cantera functionality by using the ct. prefix as will be shown below.
In practice, it is best to include all of the external libraries that you will use in Python at the top of your
script. For ME 569, these include:
import sys
import csv
import string
import numpy as np
import matplotlib.pyplot as plt

General Overview
For the homework of ME 569 you will only be dealing with ideal gases although Cantera can handle real
gases and multi-phase mixtures. The general structure of Cantera is as follows:
1. A Solution object defines the chemical species available (and their thermochemical and transport
properties) and the chemical reaction mechanism. The Solution object only contains intensive
properties of the mixture (temperature, pressure, internal energy, etc.).

2. A Reactor describes a system that you can have interact with other reactors in ways that you specify.
A reactor is nothing by itself you need to insert a Solution object into the reactor and define the
boundary conditions for the Reactor. In addition to the Solution objects properties, the Reactor has
certain macroscopic properties such as Volume and Mass. A Reactor, however, does not consider
time.
3. The time evolution of a system is calculated by installing all of the Reactors into a Reactor Network.
This Reactor Network can be evolved in time to find the systems properties.

Defining a Gas Mixture

The first step in using Cantera is that you need to define an object containing the information about the
reacting system that you are using, i.e. what species are included, their thermophysical properties, and the
reaction mechanism that governs the evolution of the species. Since we are only interested in gas-phase
reactions we will generally refer to this object using the variable name 'gas'. In Cantera, these are referred
to as solutions. There are multiple ways to define a gas-phase object.
1. The simplest method to define a gas-phase object is to use one of the 'built-in' phases in Cantera
that can be found in:
C:\pyzo2015a\Lib\site-packages\cantera\data
The three most common solution objects are gri30, the Gas Research Institute's methaneair
mechanism that contains 53 species and 325 reactions, h2o2, which describes the hydrogenair system with 9 species and 28 reactions, and air, which contains 8 species. Using a builtin object is easy, just use the command:
gas=ct.Solution(gri30.xml)
gas=ct.Solution(air.cti)
The syntax ct.Solution call the Cantera function (by virtue of the ct.) Solution, and the
argument sent to the function is the file name (the .cti refers to the standard Cantera file format;
the .xml file format is also used by Cantera, and is probably the best one to use if available).
The Solution will be given a default set of properties when it is created.
2. If you are not using a standard Cantera object and you have the .cti or .xml file, the easiest thing
to do is put it in the folders above. The syntax is then the same as shown above.
3. If you want to use a different object (set of species, etc.) and you have the Chemkin input files,
you can convert them to Cantera input files using the ck2cti function (look under utilities).

Inspecting Properties of a Gas Mixture

Once gas is defined, you can look at its properties by simply typing the name followed by a . and then
the property/properties that you are interested from the following lists:
DP, DPX, DPY, HP, HPX, HPY, P, SP, SPX, SPY, SV, SVX, SVY,T, TD, TDX,
TDY, TP, TPX, TPY, UV, UVX, UVY, X, Y, g, h, s, u, v [H,h=enthalpy;
P=pressure; X=mole fraction, Y=mass fraction; S,s=entropy; V,v=specific volume; D=density;
U,u=internal energy; g=Gibbs free energy] NOTE: you need to be sure of the basis that the intensive
properties are being reported in, i.e., mass or mole. To find this type gas.basis.

A more comprehensive report can be obtained by typing

print(gas.report())

In order to ensure that you are reporting the properties on the mass/mole basis that you desire, you can use:
chemical_potentials; concentrations; cp_mass; cp_mole; cv_mass;
cv_mole; density_mass; density_mole; enthalpy_mass; enthalpy_mole;
entropy_mass; entropy_mole; gibbs_mass, gibbs_mole; int_energy_mass;
int_energy_mole; mean_molecular_weight; volume_mass; volume_mole

Information about the species that make up the gas mixture can be found from
name

returns

example

n_species

#of species

gas.n_species

species_names

array of species names

gas.species_names

species_name(k)

name of species k

gas.species_name(5)

reaction_equation(k)

string of reaction k

gas.reaction_equation(13)

species_index(name) index # of species name

gas.species_index(oh)

n_reactions

gas.n_reactions

#of reactions in mechanism

Setting a Thermodynamic State

You can set the thermodynamic state using the same syntax, but as an assignment statement. For example,
gas.AB=value, value
Allowable combinations of A or AB are: DP, HP, SP, SV, TD, TP, UV
Setting the properties in this fashion does not affect the composition of the mixture. The mixture
composition can be set using either the mass fraction or mole fraction. This can be done several ways, and
is best shown by example. In both examples, we are making a stoichiometric methane-air mixture, i.e., 1
mole of CH4, 2 moles of O2 and 2*3.76 moles of N2.
Method 1
This method uses the assignment gas.X=[array], where the array has a number of elements equal to
the number of species in gas, and the array order is based on the definition of gas, which may not be
known to a casual user.
gas=ct.Solution('gri30.xml')
a=np.zeros(gas.X.shape)
fuel=gas.species_index('CH4')
ox=gas.species_index('O2')
nitro=gas.species_index('N2')
a[fuel]=1
a[ox]=2
a[nitro]=2*3.76

#make an array of zeros the right size

#find index for methane in array
#find index for oxygen in array
#find index for nitrogen in array
#set the fuel moles
#set the oxygen moles
#set the nitrogen moles

gas.X=a
print(gas.report())

Method 2
This method uses the assignment gas.X=string, where string has the form species_name:number
of moles; if multiple species are being specified they are separated by a comma. For a stoichiometric
methane-air mixture, the string would be CH4:1, O2:2, N2:7.52.
A=2
#O2:fuel mole ratio for methane
s='CH4:1,O2:', str(A), ',N2:', str(3.76*A)
z=''.join(s)
#concatenate the parts
gas.X=z
# set the mole fractions
print(gas.report())

Finally, you can set the thermodynamic state by a combination of the two-parameter combinations above
with either X or Y, e.g. gas.TPX sets the temperature, pressure and mole fractions.

Calculating Equilibrium
Once the initial thermodynamic state is set, it is very easy to find the equilibrium conditions (including
composition) given the choice of an appropriate constraint. This is accomplished by the following syntax
gas.equilibrate(AB)
where available constraints AB are:
TP constant temperature and pressure
TV constant temperature and volume
HP constant enthalpy and pressure
SP constant entropy and pressure
SV constant entropy and volume
UV constant internal energy and volume

Thermodynamic Calculations with fixed composition

Cantera can also be used for chemically inert, constrained thermodynamic processes. In fact, all of the twoletter combinations given above, e.g., SP, are at a fixed composition. Consider this example, which
isentropically compresses nitrogen to 500 times the initial pressure:
gas=ct.Solution(air.cti)
gas.TPX=300, ct.one_atm,N2:1
gas.SP=gas.s, 500*ct.one_atm
The final temperature is 1569 K, which
accounts
for the temperature variation of , i.e. the standard

1
500 1

P2

= 300 1
= 1774 K assuming a constant = 1:4
isentropic relation gives T2 = T1 P1
but at higher temperature decreases giving rise to the lower final temperature.

Chemical Kinetic Calculations

Cantera can be used to simulate physical devices, including computation of the chemical kinetic evolution
of a gas mixture, by using the construct of a Reactor. Multiple reactors can be defined, and the reactors can
be connected to each other by walls, or through valves that transfer mass. All of the reactors must be solved
'together', i.e., the governing equations are integrated on the same time scale. When single or multiple
reactors are used, they must be installed in a Reactor Network in order to solve.
A major difference between a reactor and a solution object is that the reactor carries information about the
size of the system, i.e., its mass or volume. The solution object in the reactor describes the intensive system
properties, but not the system size.
Before discussing reactors, lets first look at the special case of a time-invariant reactor. This is called a
reservoir in Cantera. The temperature, pressure, and chemical composition in a reservoir never change from
their initial values. A reservoir is defined using:
env=ct.Reservoir(gas)
where gas is a previously defined object and the name env is arbitrary. Because the state of the reservoir
does not change, it does not need to be included in the reactor network.
A reactor, as its name suggests, is a vessel that you put a gas in. The reactor can interact with other reactors
through walls, or by exchanging mass. The syntax to create a reactor is :
r1=ct.Reactor(gas)
this creates a homogeneous zero-dimensional reactor, r1. By default, there are no inlets or outlets, it has
fixed volume equal to 1 m3, and adiabatic, chemically inert walls.
Once a reactor is defined, and gas is put in it, you can determine its mass or volume using r1.mass and
r1.volume, respectively. You can also define these attributes of the reactor using the same syntax, but
as an assignment, e.g., r1.volume=10 sets the reactor volume to 10 m3. You can interrogate the
thermodynamic state of the reactor using available commands, but these attributes are the same as the
solution object that you put in the reactor, so it is just as easy to use the solution function calls given above.
A Walli separates two reactors, or a reactor and a reservoir. A wall has a finite area, may conduct or radiate
heat between the two reactors on either side, and may move like a piston. Walls are stateless objects in
Cantera, meaning that no differential equation is integrated to determine any wall property. Since it is the
wall (piston) velocity that enters the energy equation, the velocity, not the acceleration or displacement,
must be specified. The wall velocity is computed from

where is a non-negative constant, and

wall is moving to the right.

is a specified function of time. The velocity is positive if the

The heat flux through the wall is computed from

where is the overall heat transfer coefficient for conduction/convection, and is the emissivity. The
function
is a specified function of time. The heat flux is positive when heat flows from the reactor on
the left to the reactor on the right.
The syntax for defining a wall is
wall=ct. Wall(left, right, name=__, A=__, K=__, U=__, Q=__, velocity=__)
where the __ indicates an optional parameter:

left Reactor or reservoir on the left. Required.

right Reactor or reservoir on the right. Required.
name Name string if desired
A Wall area [m2]. Defaults to 1.0 m2.
K Wall expansion rate parameter [m/s/Pa]. Defaults to 0.0.
U Overall heat transfer coefficient [W/m2]. Defaults to 0.0 (adiabatic wall).
Q Heat flux function
[W/m2]. Optional. Default:
.
velocity Wall velocity function
[m/s]. Default:
.

By itself, you can not solve for the evolution of species in a reactor; it needs to be installed in a Reactor
Network, and the entire network is then solved. A Reactor Network containing reactors r1 and r2 is defined
as follows:
sim = ct.ReactorNet([r1, r2])
if there was only one reactor in the network, you would use sim = ct.ReactorNet([r1]). The
simulation of this reactor network starts by default at time zero. The simulation time can be found from
sim.time. The simulation can be advanced in time using two methods:
sim.advance(t) integrates the reaction mechanism up to time t. This will include several
intermediate time steps, but the results from these intermediate times is not accessible, only the final state
is returned.
sim.step(t) takes one internal step towards the time t. The size of the time step is determined by
Cantera. This method should be used when you are interested in short time-duration events.
Useful places to look for more information:
http://cantera.github.io/dev-docs/sphinx/html/reactors.html# [General equations solved]
http://cantera.github.io/dev-docs/sphinx/html/cython/zerodim.html# [Reactor syntax]

adapted from http://cantera.github.io/dev-docs/sphinx/html/cython/zerodim.html#cantera.Wall