Moved C++ sample programs into the ReST/Sphinx documentation
This commit is contained in:
Ray Speth
parent
bb2719deec
commit
0783630204
8 changed files with 94 additions and 165 deletions
|
|
@ -1,60 +0,0 @@
|
|||
/**
|
||||
\page cxx-equildemo A C++ Chemical Equilibrium Program
|
||||
|
||||
In the program below, the \c equilibrate function is called to set the
|
||||
gas to a state of chemical equilibrium, holding the temperature and
|
||||
pressure fixed. This function is declared in the equilibrium.h header
|
||||
file.
|
||||
|
||||
\include demoequil.cpp
|
||||
|
||||
The program output is:
|
||||
\verbatim
|
||||
temperature 1500 K
|
||||
pressure 202650 Pa
|
||||
density 0.316828 kg/m^3
|
||||
mean mol. weight 19.4985 amu
|
||||
|
||||
1 kg 1 kmol
|
||||
----------- ------------
|
||||
enthalpy -4.17903e+06 -8.149e+07 J
|
||||
internal energy -4.81866e+06 -9.396e+07 J
|
||||
entropy 11283.3 2.2e+05 J/K
|
||||
Gibbs function -2.1104e+07 -4.115e+08 J
|
||||
heat capacity c_p 1893.06 3.691e+04 J/K
|
||||
heat capacity c_v 1466.65 2.86e+04 J/K
|
||||
|
||||
X Y Chem. Pot. / RT
|
||||
------------- ------------ ------------
|
||||
H2 0.249996 0.0258462 -19.2954
|
||||
H 6.22521e-06 3.218e-07 -9.64768
|
||||
O 7.66933e-12 6.29302e-12 -26.3767
|
||||
O2 7.1586e-12 1.17479e-11 -52.7533
|
||||
OH 3.55353e-07 3.09952e-07 -36.0243
|
||||
H2O 0.499998 0.461963 -45.672
|
||||
HO2 7.30338e-15 1.2363e-14 -62.401
|
||||
H2O2 3.95781e-13 6.90429e-13 -72.0487
|
||||
AR 0.249999 0.51219 -21.3391
|
||||
\endverbatim
|
||||
|
||||
How can we tell that this is really a state of chemical equilibrium? Well, by applying the equation of reaction equilibrium to formation reactions from the elements, it is straightforward to show that
|
||||
\f[
|
||||
\mu_k = \sum_m \lambda_m a_{km}.
|
||||
\f]
|
||||
where \f$\mu_k\f$ is the chemical potential of species \a k, \f$a_{km}\f$ is the number of atoms of element \a m in species \a k, and
|
||||
\f$\lambda_m\f$ is the chemical potential of the elemental species per
|
||||
atom (the so-called "element potential"). In other words, the chemical
|
||||
potential of each species in an equilibrium state is a linear sum of
|
||||
contributions from each atom. We see that this is true in the output
|
||||
above -- the chemical potential of H2 is exactly twice that of H, the
|
||||
chemical potential for OH is the sum of the values for H and O, the value for H2O2 is twice as large as the value for OH, and so
|
||||
on.
|
||||
|
||||
We'll see later how the \c equilibrate function really works. For now, though, the important points are these:
|
||||
- The \c equilibrate procedure operates on an object, setting its state to a
|
||||
chemical equilibrium state.
|
||||
- To use \c equilibrate, you need to include the equilibrium.h header file.
|
||||
|
||||
Return to \ref start
|
||||
|
||||
*/
|
||||
|
|
@ -1,76 +0,0 @@
|
|||
/**
|
||||
|
||||
\page start Getting Started with Cantera in C++
|
||||
|
||||
\section cxxsimpledemo 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.
|
||||
|
||||
\include demo1a.cpp
|
||||
|
||||
This program produces the output below:
|
||||
\verbatim
|
||||
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
|
||||
\endverbatim
|
||||
|
||||
As C++ programs go, this one is \e 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.
|
||||
|
||||
- <b>Catching CanteraError exceptions</b>\n
|
||||
The entire body of the program is put inside a function that is invoked
|
||||
within a \c 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 \c 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 \c catch block, function
|
||||
\c showErrors() may be called to print the error message associated
|
||||
with the exception.
|
||||
\see \ref cxx-exceptions
|
||||
|
||||
- <b>The 'report' function</b> 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.
|
||||
|
||||
\section cxx-examples 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.
|
||||
- \ref cxx-equildemo
|
||||
- \ref cxx-thermodemo
|
||||
|
||||
|
||||
\see \ref cxx-ctnew
|
||||
|
||||
|
||||
*/
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
/**
|
||||
\page cxx-thermodemo A C++ Thermodynamics Properties Program
|
||||
|
||||
In the program below, a gas mixture object is created, and a few thermodynamic properties are computed and printed out.
|
||||
|
||||
\include thermodemo.cpp
|
||||
|
||||
Note that the methods that compute the properties take no input
|
||||
parameters. The properties are computed for the state that has been
|
||||
previously set and stored internally within the object.
|
||||
|
||||
\section cxx-thermonaming Naming Conventions
|
||||
- methods that return molar properties have names that end in \c "_mole".
|
||||
- methods that return properties per unit mass have names that end in
|
||||
\c "_mass".
|
||||
- methods that write an array of values into a supplied output array
|
||||
have names that begin with "get". For example, method \c
|
||||
getChemPotentials(double* mu) writes the species chemical potentials
|
||||
into the output array \a mu.
|
||||
|
||||
The thermodynamic property methods are declared in class ThermoPhase,
|
||||
which is the base class from which all classes that represent any
|
||||
type of phase of matter derive.
|
||||
|
||||
\see ThermoPhase
|
||||
|
||||
Return to \ref start
|
||||
|
||||
*/
|
||||
63
doc/sphinx/cxx-guide/equil-example.rst
Normal file
63
doc/sphinx/cxx-guide/equil-example.rst
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
|
||||
************************************
|
||||
Chemical Equilibrium Example Program
|
||||
************************************
|
||||
|
||||
In the program below, the `equilibrate` function is called to set the gas to a
|
||||
state of chemical equilibrium, holding the temperature and pressure fixed. This
|
||||
function is declared in the `equilibrium.h` header file.
|
||||
|
||||
.. literalinclude:: demoequil.cpp
|
||||
:language: c++
|
||||
|
||||
The program output is::
|
||||
|
||||
temperature 1500 K
|
||||
pressure 202650 Pa
|
||||
density 0.316828 kg/m^3
|
||||
mean mol. weight 19.4985 amu
|
||||
|
||||
1 kg 1 kmol
|
||||
----------- ------------
|
||||
enthalpy -4.17903e+06 -8.149e+07 J
|
||||
internal energy -4.81866e+06 -9.396e+07 J
|
||||
entropy 11283.3 2.2e+05 J/K
|
||||
Gibbs function -2.1104e+07 -4.115e+08 J
|
||||
heat capacity c_p 1893.06 3.691e+04 J/K
|
||||
heat capacity c_v 1466.65 2.86e+04 J/K
|
||||
|
||||
X Y Chem. Pot. / RT
|
||||
------------- ------------ ------------
|
||||
H2 0.249996 0.0258462 -19.2954
|
||||
H 6.22521e-06 3.218e-07 -9.64768
|
||||
O 7.66933e-12 6.29302e-12 -26.3767
|
||||
O2 7.1586e-12 1.17479e-11 -52.7533
|
||||
OH 3.55353e-07 3.09952e-07 -36.0243
|
||||
H2O 0.499998 0.461963 -45.672
|
||||
HO2 7.30338e-15 1.2363e-14 -62.401
|
||||
H2O2 3.95781e-13 6.90429e-13 -72.0487
|
||||
AR 0.249999 0.51219 -21.3391
|
||||
|
||||
|
||||
How can we tell that this is really a state of chemical equilibrium? Well, by
|
||||
applying the equation of reaction equilibrium to formation reactions from the
|
||||
elements, it is straightforward to show that:
|
||||
|
||||
.. math:: \mu_k = \sum_m \lambda_m a_{km}.
|
||||
|
||||
where :math:`\mu_k` is the chemical potential of species *k*, :math:`a_{km}` is
|
||||
the number of atoms of element *m* in species *k*, and :math:`\lambda_m` is the
|
||||
chemical potential of the elemental species per atom (the so-called "element
|
||||
potential"). In other words, the chemical potential of each species in an
|
||||
equilibrium state is a linear sum of contributions from each atom. We see that
|
||||
this is true in the output above---the chemical potential of H2 is exactly
|
||||
twice that of H, the chemical potential for OH is the sum of the values for H
|
||||
and O, the value for H2O2 is twice as large as the value for OH, and so on.
|
||||
|
||||
We'll see later how the :ct:`equilibrate <Cantera::equilibrate(thermo_t&, const
|
||||
char*, int, doublereal, int, int, int)>` function really works. For now, though,
|
||||
the important points are these:
|
||||
|
||||
- The `equilibrate` procedure operates on an object, setting its state to a
|
||||
chemical equilibrium state.
|
||||
- To use `equilibrate`, you need to include the `equilibrium.h` header file.
|
||||
|
|
@ -9,3 +9,4 @@ C++ Interface User's Guide
|
|||
compiling
|
||||
simple-example
|
||||
thermo-example
|
||||
equil-example
|
||||
|
|
|
|||
30
doc/sphinx/cxx-guide/thermo-example.rst
Normal file
30
doc/sphinx/cxx-guide/thermo-example.rst
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
********************************
|
||||
Thermodynamic Properties Program
|
||||
********************************
|
||||
|
||||
In the program below, a gas mixture object is created, and a few thermodynamic
|
||||
properties are computed and printed out:
|
||||
|
||||
.. literalinclude:: thermodemo.cpp
|
||||
:language: c++
|
||||
|
||||
Note that the methods that compute the properties take no input parameters. The
|
||||
properties are computed for the state that has been previously set and stored
|
||||
internally within the object.
|
||||
|
||||
Naming Conventions
|
||||
------------------
|
||||
|
||||
- methods that return *molar* properties have names that end in ``_mole``.
|
||||
- methods that return properties *per unit mass* have names that end in
|
||||
``_mass``.
|
||||
- methods that write an array of values into a supplied output array have names
|
||||
that begin with ``get``. For example, the method
|
||||
:ct:`ThermoPhase::getChemPotentials(double* mu)` writes the species chemical
|
||||
potentials into the output array ``mu``.
|
||||
|
||||
The thermodynamic property methods are declared in class :ct:`ThermoPhase`,
|
||||
which is the base class from which all classes that represent any type of phase
|
||||
of matter derive.
|
||||
|
||||
See :ct:`ThermoPhase` for the full list of available thermodynamic properties.
|
||||
Loading…
Add table
Reference in a new issue