research/cantera
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Moved more general documentation to ReST/Sphinx

Browse source
This commit is contained in:
Ray Speth 2012-04-04 18:46:02 +00:00
parent 0d991f5251
commit 545e258eb3
10 changed files with 231 additions and 233 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
doc/doxygen/Cantera.txt
View file

@ -1,13 +1,6 @@
/**
\mainpage Cantera Reference
\mainpage Cantera C++ Reference
<p>Choose one of the links below for an introduction to %Cantera, or use
the menu at the top to view detailed documentation of the code.
</p>
<ul>
<li>\subpage languages</li>
<ul><li>\subpage matlab-tutorial</li></ul>
<li>\subpage thermopage</li>
</ul>
Use the menu at the top to view detailed documentation of the code.
*/

38
doc/doxygen/cxx-headers.txt
View file

@ -1,38 +0,0 @@
/**
\page cxx-headers C++ Header Files
Cantera provides some header files designed for
use in C++ application programs. These are designed to include those
portions of the Cantera kernel needed for particular types of
calculations. For example, the header file equilibrium.h includes
header files from the kernel needed to do equilibrium calculations
(specifically, files ChemEquil.h and MultiPhaseEquil.h).
These headers are designed for use in C++ application programs, and
are not included by the Cantera kernel. The headers and their functions are:
These are:
- equilibrium.h
- Chemical equilibrium.
- GRI30.h
- Provides class GRI30.
- IdealGasMix.h
- Provides class IdealGasMix.
- Interface.h
- Provides class Interface.
- integrators.h
- ODE Integrators.
- kinetics.h
- Chemical kinetics.
- numerics.h
- Classes for matrices.
- onedim.h
- One-dimensional reacting flows.
- reactionpaths.h
- Reaction path diagrams.
- transport.h
- Transport properties.
- zerodim.h
- Zero-dimensional reactor networks.
*/

51
doc/doxygen/languages.txt
View file

@ -1,51 +0,0 @@
/**
\page languages Language Interfaces
Although most of Cantera is written in C++, interfaces are provided to
allow users to work with Cantera from several different languages or
environments, including Fortran 90/95, Python, and MATLAB. Which
language should you choose? The basic rule of thumb is this: use
Python or MATLAB if possible; use C++ or Fortran if necessary.
- \b Python. Python is a free scripting language that is designed to
be easy to use. If you are familiar with any other programming
language, you can probably learn Python in a couple of hours. It
is also an elegant language, and provides a user-friendly
introduction to the concepts of object-oriented programming.
Python is great for solving problems quickly, and Cantera provides
example Python scripts to do calculations ranging from simple
evaluation of thermodynamic or transport properties, on up to
chemical equilibrium in multiphase mixtures, 1D laminar flames,
reactor networks, and more. If your problem can be solved by
using Cantera from Python, you'll almost certainly solve it faster
with Python than by writing programs in Fortran or C++. \see
http://www.python.org.
- \b MATLAB. The comments above for Python apply to MATLAB too, except
that Python is free and MATLAB isn't. If you have MATLAB already and
are familiar with it, this is a good choice for an environment from
which to run Cantera. It is probably the most popular Cantera
application environment. \see http://www.mathworks.com.
- \b Fortran. Cantera provides an interface to Fortran 90/95, and can
even be used from Fortran 77 programs. Use this if you have existing
Fortran code you want to port to Cantera, or if you simply prefer working
in Fortran rather than C++.
- \b C++. If you find that you need full access to the internals of
Cantera, or want to extend and customize Cantera, then C++ is the
language for you. Most of Cantera is itself written in C++, and so
C++ application programs have more direct access to the Cantera
"kernel" than do programs written in other languages, which access
Cantera through a library of C-like functions. From C++, you can
implement new equations of state, new models for transport
properties, and many other things that simply can't be done through
the other language interfaces. If you are doing substantial code
development with Cantera, rather than simply using it to solve a few
problems, then you will probably want to use it from C++.
\see \ref start \n\ref cxx-ctnew
*/

103
doc/doxygen/thermo.txt
View file

@ -1,103 +0,0 @@
/**
\page thermopage Thermodynamic Properties
%Cantera can be used to compute thermodynamic properties of pure substances, solutions, and mixtures of various types, including ones containing multiple phases. The first step is to create an object that
represents each phase. A simple complete program that creates an object representing a gas mixture and prints its temperature is shown below.
\include ex1.cpp
Class \link Cantera::ThermoPhase ThermoPhase \endlink
is the base class for %Cantera classes that represent
phases of matter. It defines the public interface for all classes that
represent phases. For example, it specifies that they all have a
method \c temperature() that returns the current temperature, a method
\c setTemperature(double T) that sets the temperature, a method \c
getChemPotentials(double* mu) that writes the species chemical
potentials into array \c mu, and so on.
Class ThermoPhase can be used to represent the intensive state of any
single-phase solution of multiple species. The phase may be a bulk,
three-dimensional phase (a gas, a liquid, or a solid), or it may be a
two-dimensional surface phase, or even a one-dimensional "edge"
phase. The specific attributes of each type of phase are specified by
deriving a class from %ThemoPhase and providing implementations for the
virtual methods of %ThermoPhase.
%Cantera has a wide variety of models for bulk phase currently. Special
attention (in terms of the speed of execution) has been paid to an ideal gas phase implementation, where the
species thermodynamic polynomial representations adhere to either the NASA
polynomial form or to the Shomate polynomoial form. This is widely used in
combustion applications, the origin application that %Cantera was
designed for. Recently, a lot of effort has been placed into constructing non-ideal
liquid phase thermodynamics models that are used in electrochemistry and
battery applications. These models include a Pitzer implementation for brines
solutions and a Margules excess Gibbs free energy implementation for molten
salts.
\section The Intensive Thermodynamic State
Class %ThermoPhase and classes derived from it work only with the
intensive thermodynamic state. That is, all extensive properties
(enthalpy, entropy, internal energy, volume, etc.) are computed for a
unit quantity (on a mass or mole basis). For example, there is a
method enthalpy_mole() that returns the molar enthalpy (J/kmol), and a
method enthalpy_mass() that returns the specific enthalpy (J/kg), but
no method enthalpy() that would return the total enthalpy (J). This is
because class ThermoPhase does not store the total amount (mass or
mole) of the phase.
From thermodynamics, it may be shown that the intensive state of a
single-component phase in equilibrium is fully specified by the values
of any r+1 independent thermodynamic properties, where r is the number
of reversible work modes. If the only reversible work mode is
compression (a "simple compressible substance"), then two properties
suffice to specify the intensive state.
In principle, any two independent p
specified, the values of all other intensive properties may be
computed. For example, specifying the pressure and molar entropy
consisting of a solution of K species
in equilibrium is fully specified by the values of any two independent
thermodynamic properties, in addition to in
Class ThermoPhase stores internally the values of the temperature, the
mass density, and the mass fractions of all species. These values are
sufficient to fix the intensive thermodynamic state of the phase. All
properties for a unit amount (on a mass or mole basis) are determined
once the intensive state is specified. For the extensive properties, class ThermoPhase provides methods that return property values on a molar basis (e.g. enthalpy_mole(), with units J/kmol) or on a mass basis (e.g. enthalpy_mass(), with units J/kg). Since the total mass or total number of moles is not stored,
Note that the total mass or number of moles is not stored
Given these values, any other intensive thermodynamic property may
Note that the total mass or total number of moles is not stored -- therefore the values of all extensive properties (mass, volume, energy) are
This choice is arbitrary, and for most purposes you can't tell which properties are stored and which are computed.
The classes that derive from ThermoPhase compute o
For example, suppose we want to create a class to use to compute the properties of ideal gas mixtures.
Many of the methods of ThermoPhase are declared virtual, and are meant to be
overloaded in classes derived from ThermoPhase. For example, class \link Cantera::IdealGasPhase IdealGasPhase \endlink
derives from ThermoPhase, and represents ideal gas mixtures.
Although class ThermoPhase defines the interface for all classes
representing phases, it only provides implementations for a few of the
methods. This is because ThermoPhase does not actually know the
equation of state of any phase -- this information is provided by
classes that derive from ThermoPhase.
The methods implemented by ThermoPhase are ones that apply to all phases, independent of
the equation of state. For example, it implements methods temperature() and setTemperature(),
since the temperature value is stored internally. Also, the mass density is stored internally, so
There is a list of classes which inherit from the ThermoPhase class (see \ref
thermoprops "Thermodynamic Properties")
There is a list of classes which handle standard states for species (see
\ref spthermo "Species Standard-State Thermodynamic Properties").
*/

46
doc/sphinx/cxx-guide/headers.rst Normal file
View file

@ -0,0 +1,46 @@
****************
C++ Header Files
****************
Cantera provides some header files designed for use in C++ application
programs. These are designed to include those portions of Cantera needed for
particular types of calculations. For example, the header file ``equilibrium.h``
includes header files needed to do equilibrium calculations (specifically, files
``ChemEquil.h`` and ``MultiPhaseEquil.h``).
These headers are designed for use in C++ application programs, and are not
included by the Cantera core. The headers and their functions are:
``equilibrium.h``
Chemical equilibrium.
``GRI30.h``
Provides class :ct:`GRI30`.
``IdealGasMix.h``
Provides class :ct:`IdealGasMix`.
``Interface.h``
Provides class :ct:`Interface`.
``integrators.h``
ODE Integrators.
``kinetics.h``
Chemical kinetics.
``numerics.h``
Classes for matrices.
``onedim.h``
One-dimensional reacting flows.
``reactionpaths.h``
Reaction path diagrams.
``transport.h``
Transport properties.
``zerodim.h``
Zero-dimensional reactor networks.

3
doc/sphinx/cxx-guide/index.rst
View file

@ -7,6 +7,7 @@ C++ Interface User's Guide
:maxdepth: 2
compiling
headers
thermo
simple-example
thermo-example
equil-example

30
doc/sphinx/cxx-guide/thermo-example.rst
View file

@ -1,30 +0,0 @@
********************************
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.

125
doc/sphinx/cxx-guide/thermo.rst Normal file
View file

@ -0,0 +1,125 @@
**********************************
Computing Thermodynamic Properties
**********************************
Class ThermoPhase
=================
Cantera can be used to compute thermodynamic properties of pure substances,
solutions, and mixtures of various types, including ones containing multiple
phases. The first step is to create an object that represents each phase. A
simple, complete program that creates an object representing a gas mixture and
prints its temperature is shown below:
.. code-block:: c++
#include "cantera/thermo.h"
#include <iostream>
int main(int argc, char** argv)
{
Cantera::ThermoPhase* gas = Cantera::newPhase("h2o2.cti","ohmech");
std::cout << gas->temperature() << std::endl;
return 0;
}
Class :ct:`ThermoPhase` is the base class for Cantera classes that represent
phases of matter. It defines the public interface for all classes that represent
phases. For example, it specifies that they all have a method :ct:`temperature
<ThermoPhase::temperature>` that returns the current temperature, a method
:ct:`setTemperature(double T) <ThermoPhase::setTemperature>` that sets the
temperature, a method :ct:`getChemPotentials(double* mu)
<ThermoPhase::getChemPotentials>` that writes the species chemical potentials
into array ``mu``, and so on.
Class ThermoPhase can be used to represent the intensive state of any
single-phase solution of multiple species. The phase may be a bulk,
three-dimensional phase (a gas, a liquid, or a solid), or it may be a
two-dimensional surface phase, or even a one-dimensional "edge" phase. The
specific attributes of each type of phase are specified by deriving a class from
:ct:`ThermoPhase` and providing implementations for its virtual methods.
Cantera has a wide variety of models for bulk phase currently. Special attention
(in terms of the speed of execution) has been paid to an ideal gas phase
implementation, where the species thermodynamic polynomial representations
adhere to either the NASA polynomial form or to the Shomate polynomoial
form. This is widely used in combustion applications, the original application
that Cantera was designed for. Recently, a lot of effort has been placed into
constructing non-ideal liquid phase thermodynamics models that are used in
electrochemistry and battery applications. These models include a Pitzer
implementation for brines solutions and a Margules excess Gibbs free energy
implementation for molten salts.
The Intensive Thermodynamic State
---------------------------------
Class :ct:`ThermoPhase` and classes derived from it work only with the intensive
thermodynamic state. That is, all extensive properties (enthalpy, entropy,
internal energy, volume, etc.) are computed for a unit quantity (on a mass or
mole basis). For example, there is a method :ct:`enthalpy_mole()` that returns
the molar enthalpy (J/kmol), and a method :ct:`enthalpy_mass()` that returns the
specific enthalpy (J/kg), but no method *enthalpy()* that would return the total
enthalpy (J). This is because class ThermoPhase does not store the total amount
(mass or mole) of the phase.
The intensive state of a single-component phase in equilibrium is fully
specified by the values of any *r*+1 independent thermodynamic properties, where
*r* is the number of reversible work modes. If the only reversible work mode is
compression (a "simple compressible substance"), then two properties suffice to
specify the intensive state. Class ThermoPhase stores internally the values of
the *temperature*, the *mass density*, and the *mass fractions* of all
species. These values are sufficient to fix the intensive thermodynamic state of
the phase, and to compute any other intensive properties. This choice is
arbitrary, and for most purposes you can't tell which properties are stored and
which are computed.
Derived Classes
---------------
Many of the methods of ThermoPhase are declared virtual, and are meant to be
overloaded in classes derived from ThermoPhase. For example, class
:ct:`IdealGasPhase` derives from :ct:`ThermoPhase`, and represents ideal gas
mixtures.
Although class ThermoPhase defines the interface for all classes representing
phases, it only provides implementations for a few of the methods. This is
because ThermoPhase does not actually know the equation of state of any
phase---this information is provided by classes that derive from ThermoPhase.
The methods implemented by ThermoPhase are ones that apply to all phases,
independent of the equation of state. For example, it implements methods
``temperature()`` and ``setTemperature()``, since the temperature value is
stored internally.
* `Classes which inherit from ThermoPhase <../../../doxygen/html/group__thermoprops.html>`_
* `Classes which handle standard states for species <../../../doxygen/html/group__spthermo.html>`_
Example 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.

2
doc/sphinx/index.rst
View file

@ -11,7 +11,7 @@ Contents
:maxdepth: 2
Compiliation Instructions <compiling>
language-interfaces
cti/index
python/index
cxx-guide/index

55
doc/sphinx/language-interfaces.rst Normal file
View file

@ -0,0 +1,55 @@
*******************
Language Interfaces
*******************
Although most of Cantera is written in C++, interfaces are provided to
allow users to work with Cantera from several different languages or
environments, including Fortran 90/95, Python, and MATLAB. Which
language should you choose? The basic rule of thumb is this: use
Python or MATLAB if possible; use C++ or Fortran if necessary.
Python
======
Python is a free scripting language that is designed to be easy to use. If you
are familiar with any other programming language, you can probably learn Python
in a couple of hours. It is also an elegant language, and provides a
user-friendly introduction to the concepts of object-oriented programming.
Python is great for solving problems quickly, and Cantera provides example
Python scripts to do calculations ranging from simple evaluation of
thermodynamic or transport properties, on up to chemical equilibrium in
multiphase mixtures, 1D laminar flames, reactor networks, and more. If your
problem can be solved by using Cantera from Python, you'll almost certainly
solve it faster with Python than by writing programs in Fortran or C++.
See http://www.python.org
Matlab
======
The comments above for Python apply to MATLAB too, except hat Python is free and
MATLAB isn't. If you have MATLAB already and are familiar with it, this is a
good choice for an environment from which to run Cantera. It is probably the
most popular Cantera application environment. http://www.mathworks.com.
C++
===
If you find that you need full access to the internals of Cantera, or want to
extend and customize Cantera, then C++ is the language for you. Most of Cantera
is itself written in C++, and so C++ application programs have more direct
access to Cantera's core functionality than do programs written in other
languages, which access Cantera through a library of C-like functions. From C++,
you can implement new equations of state, new models for transport properties,
and many other things that simply can't be done through the other language
interfaces. If you are doing substantial code development with Cantera, rather
than simply using it to solve a few problems, then you will probably want to use
it from C++.
Fortran
=======
Cantera provides an interface to Fortran 90/95, and can even be used from
Fortran 77 programs. Use this if you have existing Fortran code you want to port
to Cantera.