diff --git a/doc/doxygen/Cantera.txt b/doc/doxygen/Cantera.txt index 470aa6194..63c13a8f8 100644 --- a/doc/doxygen/Cantera.txt +++ b/doc/doxygen/Cantera.txt @@ -1,13 +1,6 @@ /** -\mainpage Cantera Reference +\mainpage Cantera C++ Reference -

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. -

- +Use the menu at the top to view detailed documentation of the code. */ diff --git a/doc/doxygen/cxx-headers.txt b/doc/doxygen/cxx-headers.txt deleted file mode 100644 index 47c3aa184..000000000 --- a/doc/doxygen/cxx-headers.txt +++ /dev/null @@ -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. - -*/ diff --git a/doc/doxygen/languages.txt b/doc/doxygen/languages.txt deleted file mode 100644 index 01e97f761..000000000 --- a/doc/doxygen/languages.txt +++ /dev/null @@ -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 - -*/ diff --git a/doc/doxygen/thermo.txt b/doc/doxygen/thermo.txt deleted file mode 100644 index 8206d9729..000000000 --- a/doc/doxygen/thermo.txt +++ /dev/null @@ -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"). - - -*/ diff --git a/doc/sphinx/cxx-guide/headers.rst b/doc/sphinx/cxx-guide/headers.rst new file mode 100644 index 000000000..ebdff31f1 --- /dev/null +++ b/doc/sphinx/cxx-guide/headers.rst @@ -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. diff --git a/doc/sphinx/cxx-guide/index.rst b/doc/sphinx/cxx-guide/index.rst index 79f2c090d..0527f333d 100644 --- a/doc/sphinx/cxx-guide/index.rst +++ b/doc/sphinx/cxx-guide/index.rst @@ -7,6 +7,7 @@ C++ Interface User's Guide :maxdepth: 2 compiling + headers + thermo simple-example - thermo-example equil-example diff --git a/doc/sphinx/cxx-guide/thermo-example.rst b/doc/sphinx/cxx-guide/thermo-example.rst deleted file mode 100644 index 16e90bb7c..000000000 --- a/doc/sphinx/cxx-guide/thermo-example.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/cxx-guide/thermo.rst b/doc/sphinx/cxx-guide/thermo.rst new file mode 100644 index 000000000..92d6e7f6b --- /dev/null +++ b/doc/sphinx/cxx-guide/thermo.rst @@ -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 + + 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 +` that returns the current temperature, a method +:ct:`setTemperature(double T) ` that sets the +temperature, a method :ct:`getChemPotentials(double* mu) +` 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. diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 3d9b1dd4b..20c0a72a3 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -11,7 +11,7 @@ Contents :maxdepth: 2 Compiliation Instructions - + language-interfaces cti/index python/index cxx-guide/index diff --git a/doc/sphinx/language-interfaces.rst b/doc/sphinx/language-interfaces.rst new file mode 100644 index 000000000..14260c99c --- /dev/null +++ b/doc/sphinx/language-interfaces.rst @@ -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.