A.J. Simon Chris Edwards

Handout #3 Fall 2009 R.E. Mitchell ME 370A Cantera Tutorial and Installation Instructions * A.J. Simon Chris Edwards Cantera and Stanford-Cantera (SCTv2) are being distributed to the ME370A class to enable thermodynamic property calculation in the MATLAB environment. Cantera is an open-source, object-oriented software package which performs chemical and thermodynamic equilibrium and kinetics calculations. Interfaces to the Cantera package exist for MATLAB, Python, C++ and FORTRAN. Cantera is able to retrieve thermodynamic properties (enthalpy, entropy, pressure, etc.) for some pure simple, compressible substances. It is also able to retrieve properties, compute equilibrium compositions and perform kinetic simulations for mixtures of ideal gases. For those of you familiar with other thermodynamics packages, you will find that Cantera replicates much of the functionality of TPSA, STANJAN and CHEMKIN, but it does all of this within the MATLAB environment. Stanford-Cantera (also referred to as SCTv2) is a layer on top of the MATLAB-Cantera interface which is in development here at Stanford. SCT Cantera fixes some of the shortcomings of the base Cantera package. However, the functionality of Stanford- Cantera is limited to property and equilibrium calculations (not kinetics). More information on Cantera can be found at: http://www.cantera.org Stanford-Cantera vs. Cantera Stanford-Cantera does NOT replicate the full functionality of Cantera, but it DOES extend some functionality which is missing in the current release of Cantera. Cantera is open-source software and is considered to be "under development." The software which this document accompanies (both Stanford-Cantera and Cantera) is stable to the best of our knowledge. However, Stanford-Cantera is being distributed under the same license as Cantera and should be used with the same caution as any other prerelease software. The version of Cantera being distributed to ME370A is "crippled" because you are not being asked to install Python. Python is a very general scripting language, and is used by Cantera to translate thermodynamic data files into a form that Cantera can use. Pretranslated thermodynamic data files will be available through the course website. You may install Python and its required accessories for use with Cantera, but you do not need to do so. * A modified version of the original Cantera Primer designed for ME 370B in Fall 2005-2006

How is Stanford-Cantera better than Cantera? Stanford-Cantera was written specifically to enable keeping track of multiple thermodynamic states. In the original Cantera package, a gas mixture is represented by a large programming object in the computer's memory. In order to compare thermodynamic properties between states, a programmer had two choices: (1) create multiple gas objects (a time and resource intensive process) or (2) continually update a single "gas object," but extract all relevant thermodynamic properties from each state and store them in separate variables. Neither of these options results in efficient or readable code, so we programmed a set of wrapper functions into the Stanford-Cantera package. Stanford-Cantera also fills in some gaps in the original Cantera code. Most notably, Cantera is unable to set some combinations of thermodynamic properties. With Stanford- Cantera, for example, the user can simultaneously set Temperature and Entropy. This was impossible under Cantera. What is missing in this distribution of Cantera/Stanford Cantera? The ability to import thermodynamic input files is absent from this distribution of Cantera. This distribution includes the GRI 3.0 thermodynamic data set, which should be sufficient for most students to work problems on the H, C, O, N system. It also includes a data set suitable for coal gasification simulations, as well as an input file which enables access to Cantera's liquid/vapor water calculations.

Cantera and Ideal Gas Mixtures (cantera_primer1.m) This tutorial explains how Cantera works with properties and equilibrium states of ideal gas mixtures. First, be sure to close all figures and clear the variable space: close all You can initialize a gas mixture by typing: mygasmixture = IdealGasMix('gri30.xml'); 'mygasmixture' is the variable in the workspace that points to the gas mixture. 'IdealGasMix' is Cantera's initialization command. 'gri30.xml' is the file which contains thermodynamic data about a mixture of gases with a pre-specified set of possible components. You can display the state of the gas mixture by typing the variable name: mygasmixture Note that the pressure, temperature and composition have been set somewhat arbitrarily during initialization. You can change the composition to that of "engineering air" (21% O2, 79% N2) using the 'setmolefractions' command. setmolefractions(mygasmixture,'o2:0.21,n2:0.79'); Note that you must first reference the gas mixture, and then input a string representing the new composition. That string could just have easily been: 'O2:21,N2:79' or 'O2:42,N2:158' and Cantera would have normalized the mole fractions such that their sum equals unity. You can also specify the mole fractions with a vector, but you must know which index in the vector corresponds to which to which gas component. The functions 'nspecies', 'speciesindex', and 'getmolefractions' are useful here. However, if you examine the state of the gas: mygasmixture You will note that the pressure changed along with the composition. Thermodynamics tells us that we can always specify two independent intensive properties, and Cantera gives us a way to do this. The 'set' command: set(mygasmixture,'t',300,'p',101325); can set the state of this 'air' to ambient conditions. Temperature is specified in Kelvin; pressure is specified in Pascals. Note the syntax: you must first reference the gas

mixture, then specify a property, then its value, then another property, then that other property's value. NOT ALL PROPERTY PAIRS WILL WORK! (This is one of the things that is fixed in SCT Cantera.) You query individual properties of the gas mixture: T1 = temperature(mygasmixture); stores the temperature in the variable T1. H1 = enthalpy_mass(mygasmixture) retrieves the enthalpy (referenced to molecular species at 298.15K, 1 atm) per unit mass of the mixture and S1 = entropy_mole(mygasmixture) retrieves the entropy per unit mole of the mixture. You can set properties other than T and P. For example, you can set enthalpy and pressure. The following code simulates adding 100 kj/kg enthalpy to our air mixture at constant pressure: H1 = enthalpy_mass(mygasmixture); P1 = pressure(mygasmixture); set(mygasmixture,'h',h1 + 100e3,'P',P1); mygasmixture IMPORTANT: whenever a state variable is set, it is done on a per unit mass basis. However, whenever a state variable is retrieved, you have the option to do so on a per unit mass OR mole basis. To illustrate Cantera's equilibrium solver, we will create a new gas: close all cleanup G = idealgasmix('gri30.xml'); set (G,'T',300.0,'P',101325,'X','CH4:0.95,O2:2,N2:7.52') We now have a slightly lean methane/air mixture represented by the gas object 'g'. We can allow the composition to go to equilibrium at constant Temperature and Pressure by typing: equilibrate(g,'tp') If you change the 'TP' to 'HP', you end up with constant enthalpy and pressure equilibration. Other options are 'SV', 'UV', and 'SP'.

Cantera and Simple Compressible Substances (cantera_primer2.m) Cantera has the ability to perform thermodynamic calculations on liquid/vapor mixtures of pure water. For example, you could represent water at 300 K and 100 kpa by typing: close all cleanup W = importphase('liquidvapor.xml','water'); set(w,'t',300,'p',100000) There is now an object representing water in Matlab's memory space. The variable W points to that object, and its state has been set to 300 K and 100 kpa. However, this object cannot be copied, and once its state has been modified, any information associated with the 300 K, 100 kpa state will be lost. You could retrieve the density of the water by typing: rho1 = density(w) The density should be approximately the density of liquid water at room temperature, and it is now stored in the variable 'rho1'. You can find the internal energy (per unit mass) by typing: u1 = intenergy_mass(w) The internal energy is referenced to molecular reference species at 298.15 K and 101325 Pa, and in this case, stored in the variable 'u1'. You could also change the temperature (to 500 K) and pressure (to 150 kpa), but you will lose all of the information about the initial state. set(w,'t',500,'p',150000) Or, you could double the initial specific volume, while holding the initial specific internal energy constant: set(w,'v',2*(1/rho1),'u',u1); Note that now, some of the water is in the vapor phase. To determine how much, type: vaporfraction(w)

You can also set the state to that of a saturated mixture at a specific pressure or temperature: setstate_psat(w,[101325 1]') setstate_tsat(w,[300 0.5]') Note that the vapor fraction of the mixture must be specified by the 2 nd entry in the state input vector. Here is a list of all of the functions that operate on Cantera gas objects. Many are selfexplanatory and some contain good help text. Others are somewhat cryptic, but you are encouraged to explore To get this list (with some extra functions you will not use) type methods solution full at the command prompt. atomicmasses chempotentials clear cp_r cp_mass cp_mole critdensity critpressure crittemperature cv_mass cv_mole density display elementindex elementname enthalpies_rt enthalpy_mass enthalpy_mole entropies_r entropy_mass entropy_mole eostype equilibrate gibbs_rt gibbs_mass gibbs_mole hndl intenergy_mass intenergy_mole isidealgas massfractions maxtemp meanmolarmass meanmolecularweight mintemp molardensity molarmasses molefraction molefractions molecularweights natoms nelements nspecies ph pressure refpressure satpressure sattemperature set setdensity setmassfractions setmolefractions setpressure setstate setstate_hp setstate_psat setstate_sp setstate_sv setstate_tsat setstate_uv setstate_satliquid setstate_satvapor settemperature soundspeed speciesindex speciesname speciesnames temperature thermo_hndl vaporfraction

Stanford Cantera (SCTv2_primer.m) Stanford Cantera is able to store information about multiple states of gases and simple compressible substances in "lightweight" objects in the Matlab workspace. Each gas mixture or substance "model" must be initialized and assigned an identifier (ID). Once that ID has been created, a state can be built on that model, and subsequent or new states can be created, copied and manipulated. close all cleanup gri30id = newidealgasmix('gri30.xml') To build the state, call the IdealGasMixState constructor, and give it the model identifier, the identifier of the properties which define the state (here 'moletp' means that you will specifiy composition on a mole basis, and then supply Temperature and Pressure), and the properties of the state. State01 = IdealGasMixState(gri30ID,... 'moletp','n2:0.79,o2:0.21',300,100000); State proerties can be retrieved using the 'get' functions. Below, both mass-specific volume and enthalpy per unit mass are retrieved and stored in local variables. v01 = getvolume_mass(state01) h01 = getenthalpy_mass(state01) A new state can be created from the first state by changing temperature (to 400 K) and pressure (to 200 kpa). The nice thing about SCTv2 is that the ALL of the properties from both State01 and State02 are available to be queried, even after creating a new state. State02 = setstate_tp(state01, 400, 200000); A third state can be created, this time holding the specific volume constant at that of State1, and adding 100 kj/kg to the internal energy (a simulation of, for example, constant volume heat addition). State03 = setstate_vu(state01, getvolume_mass(state01),... getintenergy_mass(state01) + 100000); All three states that have been created can be viewed here: State01 State02 State03

A new gas model can be initialized. After that is done, this example creates a new mixture with equal parts carbon monoxide and water. gasificationid = newidealgasmix('gasification.xml') State10 = IdealGasMixState(gasificationID,... 'moletp','h2o:1,co:1', 1000, 100000); The mixture can be equilibrated. CO and H2O are not in equilibrium at 1000K, but the following line creates a new, equilibrated state. Again, the state information from the non-equilibrium mixture is not lost. It is still stored in State10: State11 = Equilibrate(State10, 'TP'); State10 State11 The functionality of SCTv2 extends to multi-phase pure substances, as in the following example with water: waterid = newpuresubstance('water','liquidvapor.xml'); Note that mole fraction no longer needs to be specified (it's a PURE substance!), but two independent, intensive properties are still needed to define the state: State20 = PureSubstanceState(waterID,'TP',300,101325); Saturated states can be set by defining the vapor fraction, along with pressure or temperature: State21 = setstate_tx(state20, 400, 0.33); State22 = setstate_px(state20, 101325, 1); Thermodynamic properties can be retrieved from any state that resides in Matlab's memory space: h21 = getenthalpy_mass(state21) h22 = getenthalpy_mass(state22) cleanup Notes on Stanford Cantera Functions For the most part, the Stanford Cantera functions do what you would think they do, given their names. All functions have help-text associated with them, and so should be fairly self explanatory once you are in the Matlab programming environment. All properties can be retrieved on a mass- or mole-basis. However, properties of a mixture or substance must be set on a mass basis.

Cantera Installation Instructions 1) Download the 'Cantera.msi' file from the Coursework site 2) Run the Cantera.msi installer. When the installer asks for a directory to install to, enter: C:\Cantera161 (Cantera can be installed anywhere, but it's easiest to put it in your root directory). 3) Start Matlab 4) Select File->Set Path 5) Click 'Add With Subfolders...' 6) Browse to C:\Cantera161\MATLAB\toolbox (or the appropriate \toolbox subdirectory where you installed Cantera) 7) Click 'OK' 8) Click 'Save' (in the Set Path dialog box) 9) Click 'Close' (in the Set Path dialog box) You are now ready to use Cantera from Matlab. To test the installation, run the following commands at the Matlab prompt: cantera_primer1 cantera_primer2 SCTv2_primer If a bunch of stuff executes without errors, then Cantera and Stanford Cantera are installed properly.