Getting Started with Cantera in C++

A Very Simple C++ Program

A short C++ program that uses Cantera is shown below. This program reads in a specification of a gas mixture from an input file, and then builds a new object representing the mixture. It then sets the thermodynamic state and composition of the gas mixture, and prints out a summary of its properties.

// This header must alway be included.
#include <cantera/Cantera.h>


// The actual code is put into a function that
// can be called from the main program.
void simple_demo() {

    // Create a new phase 
    ThermoPhase* gas = newPhase("h2o2.cti","ohmech");

    // Set its state by specifying T (500 K) P (2 atm) and the mole
    // fractions. Note that the mole fractions do not need to sum to
    // 1.0 - they will be normalized internally. Also, the values for
    // any unspecified species will be set to zero.
    gas->setState_TPX(500.0, 2.0*OneAtm, "H2O:1.0, H2:8.0, AR:1.0");

    // Print a summary report of the state of the gas
    cout << report(*gas) << endl;

    //  Clean up
    delete gas;
}

// the main program just calls function simple_demo within
// a 'try' block, and catches CanteraError exceptions that
// might be thrown 
int main() {

    try {
        simple_demo();
    }
    catch (CanteraError) {
        showErrors();
    }
}

This program produces the output below:

       temperature             500  K
          pressure          202650  Pa
           density        0.361163  kg/m^3
  mean mol. weight         7.40903  amu

                          1 kg            1 kmol
                       -----------      ------------
          enthalpy    -2.47725e+06       -1.835e+07     J
   internal energy    -3.03836e+06       -2.251e+07     J
           entropy         20700.1        1.534e+05     J/K
    Gibbs function    -1.28273e+07       -9.504e+07     J
 heat capacity c_p         3919.29        2.904e+04     J/K
 heat capacity c_v         2797.09        2.072e+04     J/K

                           X                 Y          Chem. Pot. / RT    
                     -------------     ------------     ------------
                H2            0.8         0.217667         -15.6441
                 H              0                0     
                 O              0                0     
                O2              0                0     
                OH              0                0     
               H2O            0.1         0.243153         -82.9531
               HO2              0                0     
              H2O2              0                0     
                AR            0.1          0.53918         -20.5027

As C++ programs go, this one is very short. It is the Cantera equivalent of the "Hello, World" program most programming textbooks begin with. But it illustrates some important points in writing Cantera C++ programs.

• The Cantera.h header
  Note that the program begins with

  #include <cantera/Cantera.h>
  

  All Cantera application programs must begin by including this header file. The syntax of the include statement shown here is recommended, since usually the Cantera header files are installed within a subdirectory named "cantera" in a directory on the search path used by the compiler. If you need to include additional Cantera headers, always include Cantera.h first.

  See also:

  C++ Header Files

• Catching CanteraError exceptions
  The entire body of the program is put inside a function that is invoked within a try block in the main program. In this way, exceptions thrown in the function or in any procedure it calls may be caught. In this program, a catch block is defined for exceptions of type CanteraError. The Cantera kernel throws exceptions of this type, so it is always a good idea to catch them. In the catch block, function showErrors() may be called to print the error message associated with the exception.

  See also:

  Exception Handling

• The 'report' function The report function generates a nicely-formatted report of the properties of a phase, including its composition in both mole (X) and mass (Y) units. For each species present, the non-dimensional chemical potential is also printed. This is handy particularly when doing equilibrium calculations. This function is very useful to see at a glance the state of some phase.

More Examples

The program above is simple, but doesn't do much. The links listed below show how to build on this demo program to do some useful things.

• A C++ Chemical Equilibrium Program
• A C++ Thermodynamics Properties Program

See also:

Compiling and Linking your C++ Program