From 96ad13e4f8cfd1b48a57491117e784012b384946 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 30 Mar 2012 23:46:53 +0000 Subject: [PATCH] Moved docs for basic C++ program to Sphinx --- doc/sphinx/cxx-intro.rst | 79 ++++++++++++++++++++++++++++++ doc/{doxygen => sphinx}/demo1a.cpp | 0 doc/sphinx/index.rst | 1 + 3 files changed, 80 insertions(+) create mode 100644 doc/sphinx/cxx-intro.rst rename doc/{doxygen => sphinx}/demo1a.cpp (100%) diff --git a/doc/sphinx/cxx-intro.rst b/doc/sphinx/cxx-intro.rst new file mode 100644 index 000000000..9023579a6 --- /dev/null +++ b/doc/sphinx/cxx-intro.rst @@ -0,0 +1,79 @@ + +*********************************** +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. + +.. literalinclude:: demo1a.cpp + :language: c++ + +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. + +Catching :ct:`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 :ct:`CanteraError`. Cantera +throws exceptions of this type, so it is always a good idea to catch them. In +the ``catch`` block, function :ct:`showErrors` may be called to print the error +message associated with the exception. + +The ``report`` function +----------------------- + +The :ct:`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. + +.. cxx-equildemo +.. cxx-thermodemo + +cxx-ctnew + diff --git a/doc/doxygen/demo1a.cpp b/doc/sphinx/demo1a.cpp similarity index 100% rename from doc/doxygen/demo1a.cpp rename to doc/sphinx/demo1a.cpp diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 826ef2159..611188b07 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -12,6 +12,7 @@ Contents Compiliation Instructions python/index + C++ Introduction C++ API Documentation Cantera Development Homepage