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

[Doc] Cherry-pick of corrections to the documentation

Browse source 
Cherry pick of trunk revisions: r2607, r2608, r2620, r2621, r2622, r2623, r2624,
r2625, r2628, r2630, r2632, r2633, r2635, r2636.
This commit is contained in:
Ray Speth 2014-01-23 02:45:23 +00:00
parent d190633c47
commit 5fbbd30747
10 changed files with 101 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/sphinx/compiling.rst
View file

@ -126,7 +126,7 @@ Stable Release
* Option 3: Check out the code using Git::
git svn clone --std-layout http://cantera.googlecode.com/svn/cantera cantera
git svn clone --stdlayout http://cantera.googlecode.com/svn/cantera cantera
git checkout 2.0
Development Version
@ -138,7 +138,7 @@ Development Version
* Option 2: Check out the code using Git::
git svn clone --std-layout http://cantera.googlecode.com/svn/cantera cantera
git svn clone --stdlayout http://cantera.googlecode.com/svn/cantera cantera
Determine configuration options
===============================
@ -166,7 +166,7 @@ General
The above paths are typical defaults on Linux, Windows, and OS X,
respectively.
* SCons saves configuration options specified on the command line in the file
\b cantera.conf in the root directory of the source tree, so generally it is
**cantera.conf** in the root directory of the source tree, so generally it is
not necessary to respecify configuration options when rebuilding Cantera. To
unset a previously set configuration option, either remove the corresponding
line from cantera.conf or use the syntax::

9
doc/sphinx/cti/input-files.rst
View file

@ -24,7 +24,7 @@ with Python syntax you already understand many of the details and can probably
skip ahead to :ref:`sec-dimensions`.
Entries have fields that can be assigned values. A species entry is shown below
that has fields name and atoms (plus several others)::
that has fields *name* and *atoms* (plus several others)::
species(name='C60', atoms='C:60')
@ -84,11 +84,6 @@ character on a line is ignored::
Strings
-------
Strings may be enclosed in single quotes or double quotes, but they must
match. To create a string containing single quotes, enclose it in double quotes,
and vice versa. If you want to create a string to extend over multiple lines,
enclose it in triple double quotes.
Strings may be enclosed in single quotes or double quotes, but they must
match. To create a string containing single quotes, enclose it in double quotes,
and vice versa. If you want to create a string to extend over multiple lines,
@ -361,7 +356,7 @@ use two formats, one designed for writing by humans, the other for reading by
machines, and provide a preprocessor to convert the human-friendly format to the
machine-friendly one.
Preprocessor Intenals: the ``ctml_writer`` Module
Preprocessor Internals: the ``ctml_writer`` Module
-------------------------------------------------
If you are interested in seeing the internals of how the preprocessing works,

109
doc/sphinx/cti/phases.rst
View file

@ -278,10 +278,12 @@ Using the ``options`` field, it is possible to extract a sub-mechanism from a la
reaction mechanism, as follows::
ideal_gas(name = 'hydrogen_mech',
species = 'gri30: all',
elements = 'H O',
species = 'gri30:all',
reactions = 'gri30:all',
options = ('skip_undeclared_elements',
'skip_undeclared_species'))
'skip_undeclared_species',
'skip_undeclared_third_bodies'))
If we import this into Matlab, for example, we get a gas mixture containing the
8 species (out of 53 total) that contain only H and O:
@ -290,53 +292,64 @@ If we import this into Matlab, for example, we get a gas mixture containing the
>> gas = importPhase('gas.cti', 'hydrogen_mech')
temperature 300 K
pressure 1237.28 Pa
density 0.001 kg/m^3
mean mol. weight 2.01588 amu
hydrogen_mech:
X Y
------------ ------------
H2 1.000000e+00 1.000000e+00
H 0.000000e+00 0.000000e+00
O 0.000000e+00 0.000000e+00
O2 0.000000e+00 0.000000e+00
OH 0.000000e+00 0.000000e+00
H2O 0.000000e+00 0.000000e+00
HO2 0.000000e+00 0.000000e+00
H2O2 0.000000e+00 0.000000e+00
temperature 0.001 K
pressure 0.00412448 Pa
density 0.001 kg/m^3
mean mol. weight 2.01588 amu
1 kg 1 kmol
----------- ------------
enthalpy -3.786e+006 -7.632e+006 J
internal energy -3.786e+006 -7.632e+006 J
entropy 6210.88 1.252e+004 J/K
Gibbs function -3.786e+006 -7.632e+006 J
heat capacity c_p 9669.19 1.949e+004 J/K
heat capacity c_v 5544.7 1.118e+004 J/K
X Y Chem. Pot. / RT
------------- ------------ ------------
H2 1 1 -917934
H 0 0
O 0 0
O2 0 0
OH 0 0
H2O 0 0
HO2 0 0
H2O2 0 0
>> eqs = reactionEqn(gas)
eqs =
'2 O + M <=> O2 + M'
'O + H + M <=> OH + M'
'O + H2 <=> H + OH'
'O + HO2 <=> OH + O2'
'O + H2O2 <=> OH + HO2'
'H + O2 + M <=> HO2 + M'
'H + 2 O2 <=> HO2 + O2'
'H + O2 + H2O <=> HO2 + H2O'
'H + O2 <=> O + OH'
'2 H + M <=> H2 + M'
'2 H + H2 <=> 2 H2'
'2 H + H2O <=> H2 + H2O'
'H + OH + M <=> H2O + M'
'H + HO2 <=> O + H2O'
'H + HO2 <=> O2 + H2'
'H + HO2 <=> 2 OH'
'H + H2O2 <=> HO2 + H2'
'H + H2O2 <=> OH + H2O'
'OH + H2 <=> H + H2O'
'2 OH (+ M) <=> H2O2 (+ M)'
'2 OH <=> O + H2O'
'OH + HO2 <=> O2 + H2O'
'OH + H2O2 <=> HO2 + H2O'
'OH + H2O2 <=> HO2 + H2O'
'2 HO2 <=> O2 + H2O2'
'2 HO2 <=> O2 + H2O2'
'OH + HO2 <=> O2 + H2O'
'O + H + M <=> OH + M'
'O + H2 <=> H + OH'
'O + HO2 <=> OH + O2'
'O + H2O2 <=> OH + HO2'
'H + O2 + M <=> HO2 + M'
'H + 2 O2 <=> HO2 + O2'
'H + O2 + H2O <=> HO2 + H2O'
'H + O2 <=> O + OH'
'2 H + M <=> H2 + M'
'2 H + H2 <=> 2 H2'
'2 H + H2O <=> H2 + H2O'
'H + OH + M <=> H2O + M'
'H + HO2 <=> O + H2O'
'H + HO2 <=> O2 + H2'
'H + HO2 <=> 2 OH'
'H + H2O2 <=> HO2 + H2'
'H + H2O2 <=> OH + H2O'
'OH + H2 <=> H + H2O'
'2 OH (+ M) <=> H2O2 (+ M)'
'2 OH <=> O + H2O'
'OH + HO2 <=> O2 + H2O'
'OH + H2O2 <=> HO2 + H2O'
'OH + H2O2 <=> HO2 + H2O'
'2 HO2 <=> O2 + H2O2'
'2 HO2 <=> O2 + H2O2'
'OH + HO2 <=> O2 + H2O'
Ideal Gas Mixtures
------------------
@ -351,13 +364,13 @@ them. It supports all of the options in the widely-used model described by Kee
et al. [#Kee1989]_, plus some additional options for species thermodynamic
properties and reaction rate expressions.
An example of an ideal_gas entry is shown below::
An example of an ``ideal_gas`` entry is shown below::
ideal_gas(name='air8',
elements='N O Ar',
species='gri30: N2 O2 N O NO NO2 N2O AR',
reactions='all',
transport='mix',
transport='Mix',
initial_state=state(temperature=500.0,
pressure=(1.0, 'atm'),
mole_fractions='N2:0.78, O2:0.21, AR:0.01'))
@ -377,17 +390,17 @@ Two transport models are available for use with ideal gas mixtures. The first is
a multicomponent transport model that is based on the model described by
Dixon-Lewis [#dl68]_ (see also Kee et al. [#Kee2003]_). The second is a model that uses
mixture rules. To select the multicomponent model, set the transport field to
the string ``'multi'``, and to select the mixture-averaged model, set it to the
string ``'mix'``::
the string ``'Multi'``, and to select the mixture-averaged model, set it to the
string ``'Mix'``::
ideal_gas(name="gas1",
...,
transport="multi", # use multicomponent formulation
transport="Multi", # use multicomponent formulation
...)
ideal_gas(name="gas2",
...,
transport="mix", # use mixture-averaged formulation
transport="Mix", # use mixture-averaged formulation
...)
Stoichiometric Solid

18
doc/sphinx/cti/reactions.rst
View file

@ -63,8 +63,8 @@ As a shorthand, if the ``rate_coeff`` field is assigned a sequence of three numb
rate_coeff = [1.0e13, 0, (7.3, 'kcal/mol')] # equivalent to above
The units of the pre-exponential factor *A* can be specified explicitly if
desired. If not specified, they will be constructed using the *quantity*, length,
and time units specified in the units directive. Since the units of *A* depend on
desired. If not specified, they will be constructed using the *quantity*, *length*,
and *time* units specified in the units directive. Since the units of *A* depend on
the reaction order, the units of each reactant concentration (different for bulk
species in solution, surface species, and pure condensed-phase species), and the
units of the rate of progress (different for homogeneous and heterogeneous
@ -158,15 +158,15 @@ A three-body reaction is a gas-phase reaction of the form:
.. math::
{\rm A + B} \rightleftharpoons {\rm AB + M}
{\rm A + B + M} \rightleftharpoons {\rm AB + M}
Here M is an unspecified collision partner that carries away excess energy to
stabilize the AB molecule (forward direction) or supplies energy to break the AB
Here *M* is an unspecified collision partner that carries away excess energy to
stabilize the *AB* molecule (forward direction) or supplies energy to break the *AB*
bond (reverse direction).
Different species may be more or less effective in acting as the collision partner. A species that is much lighter than
A and B may not be able to transfer much of its kinetic energy, and so would be inefficient as a collision partner. On
the other hand, a species with a transition from its ground state that is nearly resonant with one in the AB* activated
*A* and *B* may not be able to transfer much of its kinetic energy, and so would be inefficient as a collision partner. On
the other hand, a species with a transition from its ground state that is nearly resonant with one in the *AB** activated
complex may be much more effective at exchanging energy than would otherwise be expected.
These effects can be accounted for by defining a collision efficiency
@ -284,7 +284,7 @@ supports the extended 5-parameter form, given by:
F(T, P_r) = d \bigl[a \exp(-b/T) + \exp(-T/c)\bigr]^{1/(1+\log_{10}^2 P_r )} T^e
In keeping with the nomenclature of [Kee et al., 1989], we will refer to this as
In keeping with the nomenclature of Kee et al.[#Kee1989]_, we will refer to this as
the "SRI" falloff function. It is implemented by the :class:`SRI` directive.
.. :: NOTE: "definingphases.pdf" contains documentation for the Wang-Frenklach falloff
@ -371,7 +371,7 @@ that pressure.
Chebyshev Reaction Rate Expressions
===================================
Class :class:`chebyshev` represents a phenomenological rate coefficient
Class :class:`chebyshev_reaction` represents a phenomenological rate coefficient
:math:`k(T,P)` in terms of a bivariate Chebyshev polynomial. The rate constant
can be written as:

6
doc/sphinx/cti/species.rst
View file

@ -176,7 +176,7 @@ The Shomate parameterization is:
.. math::
\hat{c}_p^0(T) = A + Bt + Ct^2 + Dt^3 | \frac{E}{t^2}
\hat{c}_p^0(T) = A + Bt + Ct^2 + Dt^3 + \frac{E}{t^2}
\hat{h}^0(T) = At + \frac{Bt^2}{2} + \frac{Ct^3}{3} + \frac{Dt^4}{4} -
\frac{E}{t} + F
@ -190,7 +190,7 @@ G. This parameterization is used to represent reference-state properties in the
coefficients A through G should be entered precisely as shown there, with no
units attached. Unit conversions to SI will be handled internally.
Example usage of the :class:`shomate` directive::
Example usage of the :class:`Shomate` directive::
# use a single Shomate parameterization.
species(name = "O2",
@ -204,7 +204,7 @@ Constant Heat Capacity
In some cases, species properties may only be required at a single temperature
or over a narrow temperature range. In such cases, the heat capacity can be
approximated as constant, and simpler expressions used for the thermodynamic
approximated as constant, and simpler expressions can be used for the thermodynamic
properties. The :class:`const_cp` parameterization computes the properties as
follows:

2
doc/sphinx/cython/migrating.rst
View file

@ -107,7 +107,7 @@ should be replaced with::
>>> gas.P
>>> gas.Y
For pure fluid phases, the property `X` refers to the vapor mass fraction or "quality" of the phase. The following::
For pure fluid phases, the property ``X`` refers to the vapor mass fraction or "quality" of the phase. The following::
>>> w = Cantera.liquidvapor.Water()
>>> w.set(T=400, Vapor=0.5)

24
doc/sphinx/cython/tutorial.rst
View file

@ -173,8 +173,8 @@ Properties may be read independently or together::
>>> gas1.UV
(8346188.494954427, 48.8465747765848)
The composition can be set in terms of either mole fractions (`X`) or mass
fractions (`Y`)::
The composition can be set in terms of either mole fractions (``X``) or mass
fractions (``Y``)::
>>> gas1.X = 'CH4:1, O2:2, N2:7.52'
@ -264,7 +264,7 @@ The composition above was specified using a string. The format is a comma-
separated list of ``<species name>:<relative mole numbers>`` pairs. The mole
numbers will be normalized to produce the mole fractions, and therefore they
are "relative" mole numbers. Mass fractions can be set in this way too by
changing 'X' to 'Y' in the above statements.
changing ``X`` to ``Y`` in the above statements.
The composition can also be set using an array, which must have the same size
as the number of species. For example, to set all 53 mole fractions to the
@ -307,7 +307,7 @@ your system, set environment variable ``CANTERA_DATA`` to the directory where
they are located. Alternatively, you can call function `add_directory` to add
a directory to the Cantera search path::
>>> add_directory('/usr/local/cantera/my_data_files')
>>> ct.add_directory('/usr/local/cantera/my_data_files')
Cantera input files are plain text files, and can be created with any text
editor. See the document :ref:`sec-defining-phases` for more information.
@ -321,8 +321,8 @@ two bulk phases and the interface between them from file ``diamond.cti``::
>>> diamond_surf = ct.Interface('diamond.cti' , 'diamond_100',
[gas2, diamond])
Note that the bulk (i.e., 3D) phases that participate in the surface reactions
must also be passed as arguments to `Interface`.
Note that the bulk (i.e., 3D or homogeneous) phases that participate in the
surface reactions must also be passed as arguments to `Interface`.
When Cantera reads a ``.cti`` input file, wherever it is located, it always
writes a file of the same name but with extension ``.xml`` *in the local
@ -398,7 +398,7 @@ method::
>>> g.TPX = 300.0, ct.one_atm, 'CH4:0.95,O2:2,N2:7.52'
>>> g.equilibrate('TP')
The above statement sets the state of object 'g' to the state of chemical
The above statement sets the state of object ``g`` to the state of chemical
equilibrium holding temperature and pressure fixed. Alternatively, the
specific enthalpy and pressure can be held fixed::
@ -411,7 +411,7 @@ Other options are:
- 'SV' fixed specific entropy and specific volume
- 'SP' fixed specific entropy and pressure
How can you tell if 'equilibrate' has correctly found the chemical equilibrium
How can you tell if ``equilibrate`` has correctly found the chemical equilibrium
state? One way is verify that the net rates of progress of all reversible
reactions are zero. Here is the code to do this:
@ -428,12 +428,12 @@ If the magnitudes of the numbers in this list are all very small, then each
reversible reaction is very nearly equilibrated, which only occurs if the gas
is in chemical equilibrium.
You might be wondering how 'equilibrate' works. (Then again, you might not).
Method 'equilibrate' invokes Cantera's chemical equilibrium solver, which uses
You might be wondering how ``equilibrate`` works. (Then again, you might not).
Method ``equilibrate`` invokes Cantera's chemical equilibrium solver, which uses
an element potential method. The element potential method is one of a class of
equivalent 'nonstoichiometric' methods that all have the characteristic that
equivalent *nonstoichiometric* methods that all have the characteristic that
the problem reduces to solving a set of M nonlinear algebraic equations, where
M is the number of elements (not species). The so-called 'stoichiometric'
M is the number of elements (not species). The so-called *stoichiometric*
methods, on the other hand, (including Gibbs minimization), require solving K
nonlinear equations, where K is the number of species (usually K >> M). See
Smith and Missen, "Chemical Reaction Equilibrium Analysis" for more

2
doc/sphinx/cython/zerodim.rst
View file

@ -24,7 +24,9 @@ Reactors
.. autoclass:: Reservoir
.. autoclass:: Reactor
.. autoclass:: IdealGasReactor
.. autoclass:: ConstPressureReactor
.. autoclass:: IdealGasConstPressureReactor
.. autoclass:: FlowReactor
Flow Controllers

2
doc/sphinx/faq.rst
View file

@ -62,7 +62,7 @@ Support and Bug Reporting
**What information should I include in my bug report?**
- The version of Cantera are you using, and how you installed it
- The operating system are you using
- The operating system you are using
- If you compiled Cantera, what compiler you used, and what compilation
options you specified
- The version of Python or Matlab are you using, if applicable

14
doc/sphinx/reactors.rst
View file

@ -106,8 +106,8 @@ for `dm/dt`, the equation for each homogeneous phase species is:
.. math::
m \frac{dY}{dt} = \sum_{in} \dot{m}_in (Y_{k,in} - Y_k)+
\dot{m}_{k,gen} - Y_k \dot{m}_{gen}
m \frac{dY}{dt} = \sum_{in} \dot{m}_{in} (Y_{k,in} - Y_k)+
\dot{m}_{k,gen} - Y_k \dot{m}_{wall}
Energy Conservation
-------------------
@ -117,7 +117,7 @@ for an open system:
.. math::
\frac{dU}{dt} = - p \frac{dV}{dt} - Q +
\frac{dU}{dt} = - p \frac{dV}{dt} - \dot{Q} +
\sum_{in} \dot{m}_{in} h_{in} - h \sum_{out} \dot{m}_{out}
Ideal Gas Reactor
@ -141,9 +141,9 @@ temperature:
.. math::
m c_v \frac{dT}{dt} = - p \frac{dV}{dt} - Q
m c_v \frac{dT}{dt} = - p \frac{dV}{dt} - \dot{Q}
+ \sum_{in} \dot{m}_{in} \left( h_{in} - \sum_k u_k Y_{k,in} \right)
- p V \sum_{out} \dot{m}_{out} - \sum_k \dot{m}_{k,gen} u_k
- \frac{p V}{m} \sum_{out} \dot{m}_{out} - \sum_k \dot{m}_{k,gen} u_k
While this form of the energy equation is somewhat more complicated, it
significantly reduces the cost of evaluating the system Jacobian, since the
@ -168,7 +168,7 @@ Noting that `dp/dt = 0` and substituting into the energy equation yields:
.. math::
\frac{dH}{dt} = - Q + \sum_{in} \dot{m}_{in} h_{in}
\frac{dH}{dt} = - \dot{Q} + \sum_{in} \dot{m}_{in} h_{in}
- h \sum_{out} \dot{m}_{out}
The species and continuity equations are the same as for the general reactor
@ -193,5 +193,5 @@ temperature:
.. math::
m c_p \frac{dT}{dt} = - Q - \sum_k h_k \dot{m}_{k,gen}
m c_p \frac{dT}{dt} = - \dot{Q} - \sum_k h_k \dot{m}_{k,gen}
+ \sum_{in} \dot{m}_{in} \left(h_{in} - \sum_k h_k Y_{k,in} \right)