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

Remove pages moved to the new website

Browse source
This commit is contained in:
Bryan W. Weber 2018-06-18 14:25:29 -04:00 • committed by Ray Speth
parent 9670c5dac6
commit 3fae1c1a9a
36 changed files with 0 additions and 6509 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
doc/sphinx/about.rst
View file

@ -1,98 +0,0 @@
.. _sec-about:
*************
About Cantera
*************
Cantera is an open source scientific computing project, that allows users to
quickly and efficiently incorporate and execute fundamental thermodynamic,
chemical kinetic, and species transport calculations in their work. This can be
achieved by interactive calls to core Cantera functions, incorporating these
calls into bespoke code or software, or by using any of the solvers or examples
distributed with the Cantera software package.
Cantera was originally started by Prof. David G. Goodwin at the California
Institute of Technology. Building on Prof. Goodwin's legacy, Cantera is licensed
under a `permissive 3-Clause BSD license
<https://github.com/Cantera/cantera/blob/master/License.txt>`_, ensuring that the
software will remain available for all to use.
Cantera is developed openly on GitHub. Contributions are welcomed from anyone in
the community; please see the `Contributors guide
<https://github.com/Cantera/cantera/blob/master/CONTRIBUTING.md>`_ for
assistance in getting started.
All online and in-person interactions and communications related to Cantera are
governed by the `Cantera Code of Conduct
<https://github.com/Cantera/cantera/blob/master/CODE_OF_CONDUCT.md>`_. This code
of conduct sets expectations for the community to ensure that users and
contributors are able to participate in a respectful and welcoming environment.
Steering Committee
==================
The role of the steering committee is to ensure the long-term health of the
Cantera project. This includes overseeing the development of the Cantera code
and community in a way that most benefits the entire community of users and
contributors. The steering committee can be contacted at `steering@cantera.org
<mailto:steering@cantera.org>`_ The current steering committee (in alphabetical
order) is:
* Steven DeCaluwe, Colorado School of Mines
* \C. Franklin Goldsmith, Brown University
* Kyle Niemeyer, Oregon State University
* Raymond Speth, Massachusetts Institute of Technology
* Bryan Weber, University of Connecticut
* Richard West, Northeastern University
Citing Cantera
==============
If you use Cantera in a publication, we would appreciate if you cited the
version of Cantera that you used. This helps to improve the reproducibility of
your work, as well as giving credit to the many `authors
<https://github.com/Cantera/cantera/blob/master/AUTHORS>`_ who have contributed
their time to developing Cantera. The recommended citation for Cantera is as
follows:
David G. Goodwin, Harry K. Moffat, and Raymond L. Speth. *Cantera: An object-
oriented software toolkit for chemical kinetics, thermodynamics, and
transport processes*. http://www.cantera.org, 2017. Version 2.4.0.
doi:10.5281/zenodo.170284
The following BibTeX entry may also be used::
@misc{cantera,
author = "David G. Goodwin and Harry K. Moffat and Raymond L. Speth",
title = "Cantera: An Object-oriented Software Toolkit for Chemical
Kinetics, Thermodynamics, and Transport Processes",
year = 2018,
note = "Version 2.4.0",
howpublished = "\url{http://www.cantera.org}",
doi = {10.5281/zenodo.1174508}
}
If you are using a different version of Cantera, update the ``version`` and
``year`` fields accordingly.
Donations
=========
Cantera is a fiscally sponsored project of NumFOCUS, a 501(c)3 nonprofit
dedicated to supporting the open source scientific computing community. If you
have found Cantera to be useful to your research or company, please consider
making a `donation <https://www.flipcause.com/secure/cause_pdetails/Mjk3MjU=>`_
to support our efforts. All donations will be used exclusively to fund the
development of Cantera's source code, documentation, or community.
.. image:: /_static/images/SponsoredProject.png
:alt: Powered by NumFOCUS
:target: https://numfocus.org
:align: center
:scale: 50%
.. raw:: html
<div style="text-align:center">
<a href="https://www.flipcause.com/secure/cause_pdetails/Mjk3MjU=" class="button">Donate to Cantera</a>
</div>

572
doc/sphinx/compiling/config-options.rst
View file

@ -1,572 +0,0 @@
.. _scons-config:
*********************
Configuration Options
*********************
This document lists the options available for compiling Cantera with SCons. The
default values are operating-system dependent. To see the defaults for your
current operating system, run the command::
scons help
from the command prompt.
The following options can be passed to SCons to customize the Cantera
build process. They should be given in the form::
scons build option1=value1 option2=value2
Variables set in this way will be stored in the ``cantera.conf`` file and reused
automatically on subsequent invocations of SCons. Alternatively, the
configuration options can be entered directly into ``cantera.conf`` before
running ``scons build``. The format of this file is::
option1 = 'value1'
option2 = 'value2'
Options List
^^^^^^^^^^^^
.. _msvc-version:
* ``msvc_version``: [ ``string`` ]
Version of Visual Studio to use. The default is the newest
installed version. Specify ``12.0`` for Visual Studio 2013 or ``14.0``
for Visual Studio 2015. Windows MSVC only.
- default: ``''``
.. _target-arch:
* ``target_arch``: [ ``string`` ]
Target architecture. The default is the same architecture as the
installed version of Python. Windows only.
- default: ``''``
.. _toolchain:
* ``toolchain``: [ ``msvc`` | ``mingw`` | ``intel`` ]
The preferred compiler toolchain. Windows only.
- default: ``'msvc'``
.. _CXX:
* ``CXX``: [ ``string`` ]
The C++ compiler to use.
- default: ``''``
.. _CC:
* ``CC``: [ ``string`` ]
The C compiler to use. This is only used to compile CVODE.
- default: ``''``
.. _prefix:
* ``prefix``: [ ``/path/to/prefix`` ]
Set this to the directory where Cantera should be installed.
- default: ``''``
.. _python-package:
* ``python_package``: [ ``y`` | ``n`` | ``full`` | ``minimal`` | ``none`` | ``default`` ]
If you plan to work in Python, then you need the ``full`` Cantera Python
package. If, on the other hand, you will only use Cantera from some
other language (e.g. MATLAB or Fortran 90/95) and only need Python
to process CTI files, then you only need a ``minimal`` subset of the
package and Cython and NumPy are not necessary. The ``none`` option
doesn't install any components of the Python interface. The default
behavior is to build the full Python module for whichever version of
Python is running SCons if the required prerequisites (NumPy and
Cython) are installed. Note: ``y`` is a synonym for ``full`` and ``n``
is a synonym for ``none``.
- default: ``'default'``
.. _python-cmd:
* ``python_cmd``: [ ``/path/to/python_cmd`` ]
Cantera needs to know where to find the Python interpreter. If the
``python_cmd`` option is not set, then the configuration
process will use the same Python interpreter being used by SCons.
- default: ``''``
.. _python-array-home:
* ``python_array_home``: [ ``/path/to/python_array_home`` ]
If NumPy was installed using the ``--home`` option, set this to the home
directory for NumPy for Python.
- default: ``''``
.. _python-prefix:
* ``python_prefix``: [ ``/path/to/python_prefix`` ]
Use this option if you want to install the Cantera Python package to
an alternate location. On Unix-like systems, the default is the same
as the ``prefix`` option. If the ``python_prefix`` option is set to
the empty string or the ``prefix`` option is not set, then the package
will be installed to the system default ``site-packages`` directory.
To install to the current user's ``site-packages`` directory, use
``python_prefix=USER``.
- default: ``''``
.. _python2-package:
* ``python2_package``: [ ``y`` | ``n`` | ``full`` | ``minimal`` | ``none`` | ``default`` ]
Controls whether or not the Python 2 module will be built. By
default, the module will be built if the Python 2 interpreter
and the required dependencies (NumPy for Python 2 and Cython
for the version of Python for which SCons is installed) can be
found.
- default: ``'default'``
.. _python2-cmd:
* ``python2_cmd``: [ ``/path/to/python2_cmd`` ]
The path to the Python 2 interpreter. The default is
``python2``; if this executable cannot be found, this
value must be specified to build the Python 2 module.
- default: ``'python2'``
.. _python2-array-home:
* ``python2_array_home``: [ ``/path/to/python2_array_home`` ]
If NumPy was installed using the ``--home`` option, set this to the home
directory for NumPy for Python 2.
- default: ``''``
.. _python2-prefix:
* ``python2_prefix``: [ ``/path/to/python2_prefix`` ]
Use this option if you want to install the Cantera Python 2 package to
an alternate location. On Unix-like systems, the default is the same
as the ``prefix`` option. If the ``python_prefix`` option is set to
the empty string or the ``prefix`` option is not set, then the package
will be installed to the system default ``site-packages`` directory.
To install to the current user's ``site-packages`` directory, use
``python2_prefix=USER``.
- default: ``''``
.. _python3-package:
* ``python3_package``: [ ``y`` | ``n`` | ``full`` | ``minimal`` | ``none`` | ``default`` ]
Controls whether or not the Python 3 module will be built. By
default, the module will be built if the Python 3 interpreter
and the required dependencies (NumPy for Python 3 and Cython
for the version of Python for which SCons is installed) can be
found.
- default: ``'default'``
.. _python3-cmd:
* ``python3_cmd``: [ ``/path/to/python3_cmd`` ]
The path to the Python 3 interpreter. The default is
``python3``; if this executable cannot be found, this
value must be specified to build the Python 3 module.
- default: ``'python3'``
.. _python3-array-home:
* ``python3_array_home``: [ ``/path/to/python3_array_home`` ]
If NumPy was installed using the ``--home`` option, set this to the home
directory for NumPy for Python 3.
- default: ``''``
.. _python3-prefix:
* ``python3_prefix``: [ ``/path/to/python3_prefix`` ]
Use this option if you want to install the Cantera Python 3 package to
an alternate location. On Unix-like systems, the default is the same
as the ``prefix`` option. If the ``python_prefix`` option is set to
the empty string or the ``prefix`` option is not set, then the package
will be installed to the system default ``site-packages`` directory.
To install to the current user's ``site-packages`` directory, use
``python3_prefix=USER``.
- default: ``''``
.. _matlab-toolbox:
* ``matlab_toolbox``: [ ``y`` | ``n`` | ``default`` ]
This variable controls whether the MATLAB toolbox will be built. If
set to ``y``, you will also need to set the value of the ``matlab_path``
variable. If ``matlab_toolbox`` is set to ``default``, the MATLAB toolbox
will be built if ``matlab_path`` is set.
- default: ``'default'``
.. _matlab-path:
* ``matlab_path``: [ ``/path/to/matlab_path`` ]
Path to the MATLAB install directory. This should be the directory
containing the ``extern``, ``bin``, etc. subdirectories. Typical values
are: ``C:/Program Files/MATLAB/R2011a`` on Windows,
``/Applications/MATLAB_R2011a.app`` on OS X, or ``/opt/MATLAB/R2011a``
on Linux.
- default: ``''``
.. _f90-interface:
* ``f90_interface``: [ ``y`` | ``n`` | ``default`` ]
This variable controls whether the Fortran 90/95 interface will be
built. If set to ``default``, the builder will look for a compatible
Fortran compiler in the ``PATH`` environment variable, and compile
the Fortran 90 interface if one is found.
- default: ``'default'``
.. _FORTRAN:
* ``FORTRAN``: [ ``/path/to/FORTRAN`` ]
The Fortran (90) compiler. If unspecified, the builder will look for
a compatible compiler (gfortran, ifort, g95) in the ``PATH`` environment
variable. Used only for compiling the Fortran 90 interface.
- default: ``''``
.. _FORTRANFLAGS:
* ``FORTRANFLAGS``: [ ``string`` ]
Compilation options for the Fortran (90) compiler.
- default: ``'-O3'``
.. _coverage:
* ``coverage``: [ ``yes`` | ``no`` ]
Enable collection of code coverage information with gcov. Available
only when compiling with gcc.
- default: ``'no'``
.. _doxygen-docs:
* ``doxygen_docs``: [ ``yes`` | ``no`` ]
Build HTML documentation for the C++ interface using Doxygen.
- default: ``'no'``
.. _sphinx-docs:
* ``sphinx_docs``: [ ``yes`` | ``no`` ]
Build HTML documentation for Cantera using Sphinx.
- default: ``'no'``
.. _sphinx-cmd:
* ``sphinx_cmd``: [ ``/path/to/sphinx_cmd`` ]
Command to use for building the Sphinx documentation.
- default: ``'sphinx-build'``
.. _system-eigen:
* ``system_eigen``: [ ``default`` | ``y`` | ``n`` ]
Select whether to use Eigen from a system installation (``y``), from a
Git submodule (``n``), or to decide automatically (``default``). If
Eigen is not installed directly into a system include directory,
e.g. it is installed in ``/opt/include/eigen3/Eigen``, then you will
need to add ``/opt/include/eigen3`` to the ``extra_inc_dirs`` option.
- default: ``'default'``
.. _system-fmt:
* ``system_fmt``: [ ``default`` | ``y`` | ``n`` ]
Select whether to use the fmt library from a system installation
(``y``), from a Git submodule (``n``), or to decide automatically
(``default``).
- default: ``'default'``
.. _system-sundials:
* ``system_sundials``: [ ``default`` | ``y`` | ``n`` ]
Select whether to use SUNDIALS from a system installation (``y``),
from a Git submodule (``n``), or to decide automatically (``default``).
Specifying ``sundials_include`` or ``sundials_libdir`` changes the
default to ``y``.
- default: ``'default'``
.. _sundials-include:
* ``sundials_include``: [ ``/path/to/sundials_include`` ]
The directory where the SUNDIALS header files are installed. This
should be the directory that contains the ``cvodes``, ``nvector``, etc.
subdirectories. Not needed if the headers are installed in a
standard location, e.g., ``/usr/include``.
- default: ``''``
.. _sundials-libdir:
* ``sundials_libdir``: [ ``/path/to/sundials_libdir`` ]
The directory where the SUNDIALS static libraries are installed. Not
needed if the libraries are installed in a standard location, e.g.,
``/usr/lib``.
- default: ``''``
.. _blas-lapack-libs:
* ``blas_lapack_libs``: [ ``string`` ]
Cantera can use BLAS and LAPACK libraries available on your system
if you have optimized versions available (e.g., Intel MKL).
Otherwise, Cantera will use Eigen for linear algebra support. To use
BLAS and LAPACK, set ``blas_lapack_libs`` to the the list of libraries
that should be passed to the linker, separated by commas, e.g.,
``"lapack,blas"`` or ``"lapack,f77blas,cblas,atlas"``.
- default: ``''``
.. _blas-lapack-dir:
* ``blas_lapack_dir``: [ ``/path/to/blas_lapack_dir`` ]
Directory containing the libraries specified by ``blas_lapack_libs``. Not
needed if the libraries are installed in a standard location, e.g.
``/usr/lib``.
- default: ``''``
.. _lapack-names:
* ``lapack_names``: [ ``lower`` | ``upper`` ]
Set depending on whether the procedure names in the specified
libraries are lowercase or uppercase. If you don't know, run ``nm`` on
the library file (e.g., ``nm libblas.a``).
- default: ``'lower'``
.. _lapack-ftn-trailing-underscore:
* ``lapack_ftn_trailing_underscore``: [ ``yes`` | ``no`` ]
Controls whether the LAPACK functions have a trailing underscore
in the Fortran libraries.
- default: ``'yes'``
.. _lapack-ftn-string-len-at-end:
* ``lapack_ftn_string_len_at_end``: [ ``yes`` | ``no`` ]
Controls whether the LAPACK functions have the string length
argument at the end of the argument list (``yes``) or after
each argument (``no``) in the Fortran libraries.
- default: 'yes'
.. _system-googletest:
* ``system_googletest``: [ ``default`` | ``y`` | ``n`` ]
Select whether to use gtest from system installation (``y``), from a
Git submodule (``n``), or to decide automatically (``default``).
- default: 'default'
.. _env-vars:
* ``env_vars``: [ ``string`` ]
Environment variables to propagate through to SCons. Either the
string ``all`` or a comma separated list of variable names, e.g.
``LD_LIBRARY_PATH,HOME``.
- default: ``'LD_LIBRARY_PATH,PYTHONPATH'``
.. _use-pch:
* ``use_pch``: [ ``yes`` | ``no`` ]
Use a precompiled-header to speed up compilation
- default: ``'yes'``
.. _cxx-flags:
* ``cxx_flags``: [ ``string`` ]
Compiler flags passed to the C++ compiler only. Separate multiple
options with spaces, e.g., ``cxx_flags='-g -Wextra -O3 --std=c++11'``
- default: ``''``
.. _cc-flags:
* ``cc_flags``: [ ``string`` ]
Compiler flags passed to both the C and C++ compilers, regardless of
optimization level
- default: ``''``
.. _thread-flags:
* ``thread_flags``: [ ``string`` ]
Compiler and linker flags for POSIX multithreading support.
- default: ``''``
.. _optimize:
* ``optimize``: [ ``yes`` | ``no`` ]
Enable extra compiler optimizations specified by the
``optimize_flags`` variable, instead of the flags specified by the
``no_optimize_flags`` variable.
- default: ``'yes'``
.. _optimize-flags:
* ``optimize_flags``: [ ``string`` ]
Additional compiler flags passed to the C/C++ compiler when
``optimize=yes``.
- default: ``''``
.. _no-optimize-flags:
* ``no_optimize_flags``: [ ``string`` ]
Additional compiler flags passed to the C/C++ compiler when
``optimize=no``.
- default: ``''``
.. _debug:
* ``debug``: [ ``yes`` | ``no`` ]
Enable compiler debugging symbols.
- default: ``'yes'``
.. _debug-flags:
* ``debug_flags``: [ ``string`` ]
Additional compiler flags passed to the C/C++ compiler when
``debug=yes``.
- default: ``''``
.. _no-debug-flags:
* ``no_debug_flags``: [ ``string`` ]
Additional compiler flags passed to the C/C++ compiler when
``debug=no``.
- default: ``''``
.. _debug-linker-flags:
* ``debug_linker_flags``: [ ``string`` ]
Additional options passed to the linker when ``debug=yes``.
- default: ``''``
.. _no-debug-linker-flags:
* ``no_debug_linker_flags``: [ ``string`` ]
Additional options passed to the linker when ``debug=no``.
- default: ``''``
.. _warning-flags:
* ``warning_flags``: [ ``string`` ]
Additional compiler flags passed to the C/C++ compiler to enable
extra warnings. Used only when compiling source code that is part of
Cantera (e.g. excluding code in the 'ext' directory).
- default: ``''``
.. _extra-inc-dirs:
* ``extra_inc_dirs``: [ ``string`` ]
Additional directories to search for header files (colon-separated
list).
- default: ``''``
.. _extra-lib-dirs:
* ``extra_lib_dirs``: [ ``string`` ]
Additional directories to search for libraries (colon-separated
list).
- default: ``''``
.. _boost-inc-dir:
* ``boost_inc_dir``: [ ``/path/to/boost_inc_dir`` ]
Location of the Boost header files. Not needed if the headers are
installed in a standard location, e.g. ``/usr/include``.
- default: ``''``
.. _stage-dir:
* ``stage_dir``: [ ``/path/to/stage_dir`` ]
Directory relative to the Cantera source directory to be used as a
staging area for building e.g., a Debian package. If specified,
``scons install`` will install files to ``stage_dir/prefix/...``.
- default: ``''``
.. _VERBOSE:
* ``VERBOSE``: [ ``yes`` | ``no`` ]
Create verbose output about what SCons is doing.
- default: ``'no'``
.. _gtest-flags:
* ``gtest_flags``: [ ``string`` ]
Additional options passed to each GTest test suite, e.g.
`--gtest_filter=*pattern*`. Separate multiple options with spaces.
.. _renamed-shared-libraries:
* ``renamed_shared_libraries``: [ ``yes`` | ``no`` ]
If this option is turned on, the shared libraries that are created
will be renamed to have a ``_shared`` extension added to their base
name. If not, the base names will be the same as the static
libraries. In some cases this simplifies subsequent linking
environments with static libraries and avoids a bug with using
valgrind with the ``-static`` linking flag.
- default: ``'yes'``
.. _versioned-shared-library:
* ``versioned_shared_library``: [ ``yes`` | ``no`` ]
If enabled, create a versioned shared library, with symlinks to the
more generic library name, e.g. ``libcantera_shared.so.2.4.0`` as the
actual library and ``libcantera_shared.so`` and ``libcantera_shared.so.2``
as symlinks.
- default: ``'no'``
.. _layout:
* ``layout``: [ ``standard`` | ``compact`` | ``debian`` ]
The layout of the directory structure. 'standard' installs files to
several subdirectories under 'prefix', e.g. $prefix/bin,
$prefix/include/cantera, $prefix/lib. This layout is best used in
conjunction with 'prefix'='/usr/local'. 'compact' puts all installed
files in the subdirectory defined by 'prefix'. This layout is best
with a prefix like '/opt/cantera'. 'debian' installs to the
stage directory in a layout used for generating Debian packages.
- default: ``'standard'``

278
doc/sphinx/compiling/configure-build.rst
View file

@ -1,278 +0,0 @@
.. _sec-determine-config:
Determine configuration options
===============================
* Run ``scons help`` to see a list all configuration options for Cantera, or
see :ref:`scons-config`.
* Configuration options are specified as additional arguments to the ``scons``
command, e.g.::
scons command option=value
where ``scons`` is the program that manages the build steps, and ``command``
is most commonly one of
* ``build``
* ``test``
* ``clean``
Other commands are possible, and are explained in :ref:`sec-build-commands`.
* SCons saves configuration options specified on the command line in the file
``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::
scons command option_name=
* Sometimes, changes in your environment can cause SCons's configuration tests
(e.g., checking for libraries or compiler capabilities) to unexpectedly fail.
To force SCons to re-run these tests rather than trusting the cached results,
run scons with the option ``--config=force``.
* The following lists of options are not complete, they show only some commonly
used options. The entire list of options can be found in :ref:`scons-config`.
Common Options
^^^^^^^^^^^^^^^
* :ref:`blas_lapack_libs <blas-lapack-libs>`
* On OS X, the Accelerate framework is automatically used to provide
optimized versions of BLAS and LAPACK, so the ``blas_lapack_libs``
option should generally be left unspecified.
* :ref:`blas_lapack_dir <blas-lapack-dir>`
* :ref:`boost_inc_dir <boost-inc-dir>`
* :ref:`debug <debug>`
* :ref:`optimize <optimize>`
* :ref:`prefix <prefix>`
* :ref:`sundials_include <sundials-include>`
* :ref:`sundials_libdir <sundials-libdir>`
General Python Module Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, SCons will try to build the full Python interface for
whichever version of Python is running SCons. This requires that
NumPy is installed for that version of Python, and that Cython is
installed for whichever Python is running SCons. The following SCons
options control how the Python module is built:
* :ref:`python_cmd <python-cmd>`
* :ref:`python_package <python-package>`
* :ref:`python_prefix <python-prefix>`
Note that these general options should not be used at the same time
as the Python-version specific options discussed below. If SCons
detects that it is being run with Python 2, and the
:ref:`python2_package <python2-package` option is set, the build will
raise an error and exit; or if SCons detects that it is being run with
Python 3, and the :ref:`python3_package <python3-package` option is
set, the build will raise an error and exit.
If a user wishes to build multiple Python interfaces, or a Python
interface for the version of Python that is not running SCons, they
should use the version-specific options below, and set the
:ref:`python_package <python-package>` option to ``none``.
Python 2 Module Options
^^^^^^^^^^^^^^^^^^^^^^^
By default, if SCons detects a Python 2 interpreter installed in a
default location (i.e., ``python2`` is on the ``PATH`` environment
variable) or ``python2_package`` is ``full``, SCons will try to build
the Python module for Python 2. The following SCons options control how
the Python 2 module is built:
* :ref:`python2_cmd <python2-cmd>`
* :ref:`python2_package <python2-package>`
* :ref:`python2_prefix <python2-prefix>`
Python 3 Module Options
^^^^^^^^^^^^^^^^^^^^^^^
By default, if SCons detects a Python 3 interpreter installed in a
default location (i.e., ``python3`` is on the ``PATH`` environment
variable) or ``python3_package`` is ``full``, SCons will try to build
the Python module for Python 3. The following SCons options control how
the Python 3 module is built:
* :ref:`python3_cmd <python3-cmd>`
* :ref:`python3_package <python3-package>`
* :ref:`python3_prefix <python3-prefix>`
Windows Only Options
^^^^^^^^^^^^^^^^^^^^
.. note::
The ``cantera.conf`` file uses the backslash character ``\`` as an escape
character. When modifying this file, backslashes in paths need to be escaped
like this: ``boost_inc_dir = 'C:\\Program Files (x86)\\boost\\include'``
This does not apply to paths specified on the command line. Alternatively,
you can use forward slashes (``/``) in paths.
* In Windows there aren't any proper default locations for many of the packages
that Cantera depends on, so you will need to specify these paths explicitly.
* Remember to put double quotes around any paths with spaces in them, e.g.
``"C:\Program Files"``.
* By default, SCons attempts to use the same architecture as the copy of Python
that is running SCons, and the most recent installed version of the Visual
Studio compiler. If you aren't building the Python module, you can override
this with the configuration options ``target_arch`` and ``msvc_version``.
* To compile with MinGW, specify the :ref:`toolchain <toolchain>` option::
toolchain=mingw
* :ref:`msvc_version <msvc-version>`
* :ref:`target_arch <target-arch>`
* :ref:`toolchain <toolchain>`
MATLAB Toolbox Options
^^^^^^^^^^^^^^^^^^^^^^
Building the MATLAB toolbox requires an installed copy of MATLAB, and the path
to the directory where MATLAB is installed must be specified using the following
option:
* :ref:`matlab_path <matlab-path>`
Fortran Module Options
^^^^^^^^^^^^^^^^^^^^^^
Building the Fortran module requires a compatible Fortran comiler. SCons will
attempt to find a compatible compiler by default in the ``PATH`` environment
variable. The following options control how the Fortran module is built:
* :ref:`f90_interface <f90-interface>`
* :ref:`FORTRAN <FORTRAN>`
Documentation Options
^^^^^^^^^^^^^^^^^^^^^
The following options control if the documentation is built:
* :ref:`doxygen_docs <doxygen-docs>`
* :ref:`sphinx_docs <sphinx-docs>`
Less Common Options
^^^^^^^^^^^^^^^^^^^
* :ref:`CC <CC>`
* :ref:`CXX <CXX>`
* :ref:`env_vars <env-vars>`
* :ref:`layout <layout>`
* :ref:`VERBOSE <VERBOSE>`
* :ref:`gtest_flags <gtest-flags>`
.. _sec-build-commands:
Build Commands
==============
The following options are possible as commands to SCons, i.e., the first
argument after ``scons``::
scons command
* ``scons help``
Print a description of user-specifiable options.
* ``scons build``
Compile Cantera and the language interfaces using
default options.
* ``scons clean``
Delete files created while building Cantera.
* ``[sudo] scons install``
Install Cantera.
* ``[sudo] scons uninstall``
Uninstall Cantera.
* ``scons test``
Run all tests which did not previously pass or for which the
results may have changed.
* ``scons test-reset``
Reset the passing status of all tests.
* ``scons test-clean``
Delete files created while running the tests.
* ``scons test-help``
List available tests.
* ``scons test-NAME``
Run the test named "NAME".
* ``scons <command> dump``
Dump the state of the SCons environment to the
screen instead of doing ``<command>``, e.g.
``scons build dump``. For debugging purposes.
* ``scons samples``
Compile the C++ and Fortran samples.
* ``scons msi``
Build a Windows installer (.msi) for Cantera.
* ``scons sphinx``
Build the Sphinx documentation
* ``scons doxygen``
Build the Doxygen documentation
Compile Cantera & Test
======================
* Run SCons with the list of desired configuration options::
scons build ...
* If Cantera compiles successfully, you should see a message that looks like::
*******************************************************
Compilation completed successfully.
- To run the test suite, type 'scons test'.
- To install, type '[sudo] scons install'.
*******************************************************
* If you do not see this message, check the output for errors to see what went
wrong.
* Cantera has a series of tests that can be run with the command::
scons test
* When the tests finish, you should see a summary indicating the number of
tests that passed and failed.
* If you have tests that fail, try looking at the following to determine the
source of the error:
* Messages printed to the console while running ``scons test``
* Output files generated by the tests
Building Documentation
^^^^^^^^^^^^^^^^^^^^^^
* To build the Cantera HTML documentation, run the commands::
scons doxygen
scons sphinx
or append the options ``sphinx_docs=y`` and ``doxygen_docs=y`` to the build
command, e.g.::
scons build doxygen_docs=y sphinx_docs=y

167
doc/sphinx/compiling/dependencies.rst
View file

@ -1,167 +0,0 @@
.. _sec-dependencies:
Software used by Cantera
========================
This section lists the versions of third-party software that are required to
build and use Cantera.
Compilers
---------
You must have one of the following C++ compilers installed on your system. A
Fortran compiler is required only if you plan to build the Fortran module.
* GNU compilers (C/C++/Fortran)
* Known to work with version 4.8; Expected to work with version >= 4.6
* Clang/LLVM (C/C++)
* Known to work with versions 3.5 and 3.8. Expected to work with version
>= 3.1.
* Works with the version included with Xcode 8.2.1.
* Intel compilers (C/C++/Fortran)
* Known to work with version 14.0.
* Microsoft compilers (C/C++)
* Known to work with versions 12.0 (Visual Studio 2013) and 14.0 (Visual
Studio 2015).
* MinGW (C/C++/Fortran)
* http://mingw-w64.sourceforge.net/ (64-bit and 32-bit)
* http://tdm-gcc.tdragon.net/ (64-bit and 32-bit)
* Known to work with Mingw-w64 3.0, which provides GCC 4.8. Expected to work
with any version that provides a supported version of GCC and includes C++11
thread support.
Other Required Software
-----------------------
* SCons:
* http://scons.org/tag/releases.html
* Linux & OS X: Known to work with SCons 2.4.1; Expected to work with versions >= 1.0.0
* Version 2.3.6 or newer is required to use Visual Studio 2015.
* Python:
* http://python.org/download/
* Known to work with 2.7 and 3.5. Expected to work with versions >= 3.3.
* The Cython module supports Python 2.7 and 3.x.
* Boost
* http://www.boost.org/users/download/
* Known to work with version 1.54; Expected to work with versions >= 1.48
* Only the "header-only" portions of Boost are required. Cantera does not
currently depend on any of the compiled Boost libraries.
* SUNDIALS
* If SUNDIALS is not installed, it will be automatically downloaded and the
necessary portions will be compiled and installed with Cantera.
* https://computation.llnl.gov/casc/sundials/download/download.html
* Known to work with versions 2.4, 2.5, 2.6, and 2.7.
* To use SUNDIALS with Cantera on a Linux/Unix system, it must be compiled
with the ``-fPIC`` flag. You can specify this flag when configuring
SUNDIALS (2.4 or 2.5)::
configure --with-cflags=-fPIC
or SUNDIALS 2.6 or 2.7::
cmake -DCMAKE_C_FLAGS=-fPIC <other command-line options>
.. note:: If you are compiling SUNDIALS 2.5.0 on Windows using CMake, you need
to edit the ``CMakeLists.txt`` file first and change the lines::
SET(PACKAGE_STRING "SUNDIALS 2.4.0")
SET(PACKAGE_VERSION "2.4.0")
to read::
SET(PACKAGE_STRING "SUNDIALS 2.5.0")
SET(PACKAGE_VERSION "2.5.0")
instead, so that Cantera can correctly identify the version of
SUNDIALS.
* Eigen
* If Eigen is not installed, it will be automatically downloaded and installed
with Cantera.
* http://eigen.tuxfamily.org/
* Known to work with version 3.2.8.
* fmt
* If fmt (previously known as cppformat) is not installed, it will be
automatically downloaded and the necessary portions will be compiled and
installed with Cantera.
* http://fmtlib.net/latest/index.html
* Version 3.0.1 or newer is required.
* Google Test
* If Google Test is not installed, it will be automatically downloaded and the
necessary portions will be compiled as part of the Cantera build process.
* https://github.com/google/googletest
* Known to work with version 1.7.0.
Optional Programs
-----------------
* `Numpy <http://www.numpy.org/>`_
* Required to build the Cantera Python module, and to run significant portions
of the test suite.
* Known to work with versions 1.8.1-1.14.0. Expected to work with
versions >= 1.8.1.
* `Cython <http://cython.org/>`_
* Required version >=0.23 to build the Python module. Must be installed for
the same Python where SCons is installed.
* `3to2 <http://pypi.python.org/pypi/3to2>`_
* Used to convert Python examples to Python 2 syntax.
* Known to work with version 1.0
* Matlab
* Required to build the Cantera Matlab toolbox.
* Known to work with 2009a and 2014b. Expected to work with versions >= 2009a.
* `Windows Installer XML (WiX) toolset <http://wixtoolset.org/>`_
* Required to build MSI installers on Windows.
* Known to work with versions 3.5 and 3.8.
* `Pip <https://pip.pypa.io/en/stable/installing>`_ (Python)
* Provides the ``pip`` command which can be used to install most of
the other Python modules.
* Packages required for building Sphinx documentation
* `Sphinx <http://www.sphinx-doc.org/en/stable/>`_
* `Pygments <http://pygments.org/>`_
* `pyparsing <http://sourceforge.net/projects/pyparsing/>`_
* `doxylink <https://pythonhosted.org/sphinxcontrib-doxylink/>`_
* `matlabdomain <https://pypi.python.org/pypi/sphinxcontrib-matlabdomain>`_
* `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
* Required for building the C++ API Documentation
* Version 1.8 or newer is recommended.
* `Graphviz <https://www.graphviz.org/>`_
* Required to build the dependency graph images in the C++ API Documentation
* Known to work with version 2.40.1, expected to work with versions >=2.40.1

19
doc/sphinx/compiling/index.rst
View file

@ -1,19 +0,0 @@
.. _sec-compiling:
*************************
Cantera Compilation Guide
*************************
This guide contains instructions for compiling Cantera on supported operating
systems and provides some detail of the possible configuration options.
.. toctree::
:maxdepth: 2
installation-reqs
source-code
configure-build
dependencies
special-cases
config-options

404
doc/sphinx/compiling/installation-reqs.rst
View file

@ -1,404 +0,0 @@
.. contents::
:local:
.. _sec-installation-reqs:
Installation Prerequisites
==========================
.. _sec-linux:
Linux
-----
General Notes
^^^^^^^^^^^^^
* To download the source code, installing ``git`` is highly recommended.
* SCons is only available for Python 2, so building the Python 3 module requires
two installations of Python (one of Python 2 and one of Python 3), even if you
do not intend to build the Python 2 module.
* The following instructions use the system-installed versions of Python, but
alternate installations such as the Anaconda distribution of Python can be
used as well.
* Cython is only required to be installed for the version of Python that also
has SCons installed; following the instructions below will install Cython for
the version of Python 2 installed in the system directories. The minimum
compatible Cython version is 0.23. If your distribution does not contain a
suitable version, you may be able to install a more recent version using
``pip``.
* Users of other distributions should install the equivalent packages, which
may have slightly different names.
* In addition to the below operating systems, Cantera should work on any
Unix-like system where the necessary prerequisites are available, but some
additional configuration may be required.
.. _sec-ubuntu-debian-reqs:
Ubuntu & Debian
^^^^^^^^^^^^^^^
* Ubuntu 12.04 LTS (Precise Pangolin) or newer is required; 16.04 LTS (Xenial Xerus)
or newer is recommended
* Debian 7.0 (Wheezy) or newer; 8.0 (Jessie) or newer is recommended
* The following packages must be installed to build any of the Cantera modules using
your choice of package manager::
g++ python scons libboost-dev
* In addition to the general packages, building the Python 2 module also requires::
cython python-dev python-numpy python-numpy-dev python-setuptools
* In addition to the general packages, building the Python 3 module also requires::
cython python3 python3-dev python3-setuptools python3-numpy
* In addition to the general packages, building the Fortran module also requires::
gfortran
* In addition to the general packages, building the MATLAB toolbox also requires:
* MATLAB version later than 2009a
* Typically installed to::
/opt/MATLAB/R20YYn
where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b``
.. _sec-fedora-reqs:
Fedora & RHEL
^^^^^^^^^^^^^
* The following packages must be installed to build any of the Cantera modules using
your choice of package manager::
gcc-c++ python scons boost-devel
* In addition to the general packages, building the Python 2 module also requires::
python-setuptools python-devel Cython numpy
* In addition to the general packages, building the Python 3 module also requires::
python3 python3-setuptools python3-devel Cython python3-numpy
* In addition to the general packages, building the Fortran module also requires::
gcc-gfortran
* In addition to the general packages, building the MATLAB toolbox also requires:
* MATLAB version later than 2009a
* Typically installed to::
/opt/MATLAB/R20YYn
where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b``
.. _sec-opensuse-reqs:
OpenSUSE & SUSE Linux Enterprise
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* OpenSUSE 13.2 or newer; Leap 42.2 or newer recommended
* The following packages must be installed to build any of the Cantera modules using
your choice of package manager::
gcc-c++ python scons boost-devel
* In addition to the general packages, building the Python 2 module also requires::
python-Cython python-devel python-numpy python-numpy-devel python-setuptools
* In addition to the general packages, building the Python 3 module also requires::
python-Cython python3 python3-devel python3-setuptools python3-numpy python3-numpy-devel
* In addition to the general packages, building the Fortran module also requires::
gcc-fortran
* In addition to the general packages, building the MATLAB toolbox also requires:
* MATLAB version later than 2009a
* Typically installed to::
/opt/MATLAB/R20YYn
where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b``
.. _sec-windows:
Windows
-------
General Notes
^^^^^^^^^^^^^
* SCons is only available for Python 2, so building the Python 3 module requires
two installations of Python (one of Python 2 and one of Python 3), even if you
do not intend to build the Python 2 module.
* The build process will produce a Python module compatible with the version of
Python used for the compilation. To generate different modules for other
versions of Python, you will need to install those versions of Python and
recompile.
* The following instructions use the versions of Python downloaded from
https://www.python.org/downloads, but alternate installations such as the
Anaconda distribution of Python can be used as well.
* If you want to build the Matlab toolbox and you have a 64-bit copy of Windows,
by default you will be using a 64-bit copy of Matlab, and therefore you need
to compile Cantera in 64-bit mode. For simplicity, it is highly recommended
that you use a 64-bit version of Python to handle this automatically. Note
that the default download from the Python website
(https://www.python.org) is for a 32-bit installer, and you will
need to select the 64-bit installer specifically.
* It is generally helpful to have SCons and Python in your ``PATH`` environment
variable. This can be done by checking the appropriate box during the
installation of Python or can be accomplished by adding the top-level Python
directory and the ``Scripts`` subdirectory (e.g.,
``C:\Python27;C:\Python27\Scripts``) to your ``PATH``. The dialog to change
the ``PATH`` is accessible from::
Control Panel > System and Security > System > Advanced System Settings > Environment Variables
Make sure that the installation of Python that has SCons comes first on your
``PATH``.
* In order to use SCons to install Cantera to a system folder (e.g. ``C:\Program
Files\Cantera``) you must run the ``scons install`` command in a command
prompt that has been launched by selecting the *Run as Administrator* option.
.. _sec-windows-reqs:
Windows Requirements
^^^^^^^^^^^^^^^^^^^^^^^
* Windows 7 or later; either 32-bit or 64-bit
* To build any of the Cantera modules, you will need to install
* Python 2.7
* https://www.python.org/downloads/
* Be sure to choose the appropriate architecture for your system - either
32-bit or 64-bit
* When installing, make sure to choose the option to add to your ``PATH``
* SCons
* https://pypi.python.org/pypi/SCons
* Be sure to choose the appropriate architecture for your system - either
32-bit or 64-bit
* One of the following supported compilers
* Microsoft compilers
* https://www.visualstudio.com/downloads/
* Known to work with Visual Studio 2013 (MSVC 12.0) and Visual Studio 2015
(MSVC 14.0)
* MinGW compilers
* http://mingw-w64.org/
* http://tdm-gcc.tdragon.net/
* Known to work with Mingw-w64 3.0, which provides GCC 4.8. Expected to
work with any version that provides a supported version of GCC and
includes C++11 thread support.
* The version of MinGW from http://www.mingw.org/ cannot be used to build
Cantera. Users must use MinGW-w64 or TDM-GCC.
* The Boost headers
* http://www.boost.org/doc/libs/1_63_0/more/getting_started/windows.html#get-boost
* It is not necessary to compile the Boost libraries since Cantera only uses
the headers from Boost
* In addition to the general software, building the Python 2 module also requires
* Pip
* Pip should be distributed with Python version 2.7.9 and higher.
If you are using an older version of Python, see
`these instructions to install pip <http://stackoverflow.com/a/12476379>`_
* Most packages will be downloaded as Wheel (``*.whl``) files. To install
these files, type::
pip install C:\Path\to\downloaded\file\package-file-name.whl
* Cython
* http://www.lfd.uci.edu/~gohlke/pythonlibs/#cython
* Download the ``*.whl`` file for your Python architecture (32-bit or 64-bit)
and Python 2.7 (indicated by ``cp27`` in the file name).
* Cython must be installed in the version of Python that has SCons installed
* NumPy
* http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy
* Download the ``*.whl`` file for your Python architecture (32-bit or 64-bit)
and Python 2.7 (indicated by ``cp27`` in the file name).
* In addition to the general software, building the Python 3 module also requires
* Python 3
* https://www.python.org/downloads/
* Cantera supports Python 3.3 and higher
* Be sure to choose the appropriate architecture for your system - either
32-bit or 64-bit
* Be careful that the installation of Python 3 does not come before Python 2
on your ``PATH`` environment variable
* Pip
* Pip should be distributed with Python version 3.4 and higher.
If you are using an older version of Python, see
`these instructions to install pip <http://stackoverflow.com/a/12476379>`_
* Most packages will be downloaded as Wheel (``*.whl``) files. To install
these files, type::
pip3 install C:\Path\to\downloaded\file\package-file-name.whl
* Cython
* http://www.lfd.uci.edu/~gohlke/pythonlibs/#cython
* Download the ``*.whl`` file for your Python architecture (32-bit or 64-bit)
and Python 2.7 (indicated by ``cp27`` in the file name).
* Cython must be installed in the version of Python that has SCons installed
* NumPy
* http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy
* Download the ``*.whl`` file for your Python architecture (32-bit or 64-bit)
and Python 3.x (indicated by ``cp3x`` in the file name, where x matches
your version of Python).
* In addition to the general software, building the MATLAB toolbox also requires:
* MATLAB version later than 2009a
* Typically installed to::
C:\Program Files\MATLAB\R20YYn
where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b``/Applications/MATLAB_R2011a.app
.. _sec-macos:
OS X & macOS
------------
General Notes
^^^^^^^^^^^^^
* It is not recommended to use the system-installed version of Python to build
Cantera. Instead, the following instructions use Homebrew to install a
separate copy of Python, independent from the system Python.
* To download the source code, installing ``git`` via HomeBrew is highly recommended.
* SCons is only available for Python 2, so building the Python 3 module requires
two installations of Python (one of Python 2 and one of Python 3), even if you
do not intend to build the Python 2 module.
* Cython is only required to be installed for the version of Python that also
has SCons installed; following the instructions below will install Cython for
the version of Python 2 installed in the system directories. The minimum
compatible Cython version is 0.23.
.. _sec-mac-os-reqs:
OS X & macOS Requirements
^^^^^^^^^^^^^^^^^^^^^^^^^
* OS X 10.9 (Mavericks) or newer required; 10.10 (Yosemite) or newer is recommended
* To build any of the Cantera modules, you will need to install
* Xcode
* Download and install from the App Store
* From a Terminal, run::
sudo xcode-select --install
and agree to the Xcode license agreement
* Homebrew
* http://brew.sh
* From a Terminal, run::
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
* Once Homebrew is installed, the rest of the dependencies can be installed with::
brew install python scons boost
* In addition to the general software, building the Python 2 module also requires::
pip install cython numpy
* In addition to the general software, building the Python 3 module also requires::
brew install python3
pip install cython
pip3 install numpy
Note that Cython should be installed into the version of Python that has SCons
installed.
* In addition to the general software, building the Fortran module also requires::
brew install gcc
* In addition to the general software, building the MATLAB toolbox also requires:
* MATLAB version later than 2009a
* Typically installed to::
/Applications/MATLAB_R20YYn.app
where ``YY`` is a two digit year and ``n`` is either ``a`` or ``b``

68
doc/sphinx/compiling/source-code.rst
View file

@ -1,68 +0,0 @@
.. _sec-source-code:
Downloading the Cantera source code
===================================
Stable Release
--------------
* **Option 1**: Check out the code using Git::
git clone --recursive https://github.com/Cantera/cantera.git
cd cantera
Then, check out the tag of the most recent stable version::
git checkout tags/v2.4.0
git submodule update
A list of all the tags can be shown by::
git tag --list
* **Option 2**: Download the most recent source tarball from `Github
<https://github.com/Cantera/cantera/releases>`_ and extract the
contents.
Beta Release
------------
* Check out the code using Git::
git clone --recursive https://github.com/Cantera/cantera.git
cd cantera
Then pick either **Option 1** or **Option 2** below.
* **Option 1**: Check out the tag with the most recent beta release::
git checkout tags/v2.4.0b1
git submodule update
Note that the most recent beta version might be older than the most recent
stable release. A list of all the tags, including stable and beta versions can
be shown by::
git tag --list
* **Option 2**: Check out the branch with all the bug fixes leading to the
next minor release of the stable version::
git checkout 2.4
git submodule update
This branch has all the work on the 2.4.x version of the software.
Development Version
-------------------
Check out the code using Git::
git clone --recursive https://github.com/Cantera/cantera.git
cd cantera
Note that by default, the ``master`` branch is checked out, containing all of
the feature updates and bug fixes to the code since the previous stable release.
The master branch is usually an "alpha" release, corresponding to the ``a`` in
the version number, and does not usually get a tag.

52
doc/sphinx/compiling/special-cases.rst
View file

@ -1,52 +0,0 @@
.. _sec-special-compiling-cases:
***********************
Special Compiling Cases
***********************
This guide explains some of the less common ways to build Cantera
.. contents::
:local:
.. _sec-intel-compilers:
Intel Compilers
===============
* Before compiling Cantera, you may need to set up the appropriate environment
variables for the Intel compiler suite, e.g.::
source /opt/intel/bin/compilervars.sh intel64
* For the Intel compiler to work with SCons, these environment variables need
to be passed through SCons by using the command line option::
env_vars=all
* If you want to use the Intel MKL versions of BLAS and LAPACK, you will need
to provide additional options. The following are typically correct on
64-bit Linux systems::
blas_lapack_libs=mkl_rt blas_lapack_dir=$(MKLROOT)/lib/intel64
Your final SCons call might then look something like::
scons build env_vars=all CC=icc CXX=icpc FORTRAN=ifort blas_lapack_libs=mkl_rt blas_lapack_dir=$(MKLROOT)/lib/intel64
* When installing Cantera after building with the Intel compiler, the normal
method of using ``sudo`` to install Cantera to the system default directories
will not work because ``sudo`` does not pass the environment variables needed
by the Intel compiler. Instead, you will need to do something like::
scons build ...
sudo -s
source /path/to/compilervars.sh intel64
scons install
exit
Another option is to set the :ref:`prefix <prefix>` option to a directory
for which you have write permissions, and specify the ``USER`` value to the
:ref:`python2_prefix <python2-prefix>` or :ref:`python3_prefix <python3-prefix>`
option.

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

@ -1,18 +0,0 @@
.. _sec-defining-phases:
***************
Defining Phases
***************
*A guide to Cantera's input file format*
.. toctree::
:maxdepth: 2
intro
input-files
phases
species
reactions
classes

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

@ -1,716 +0,0 @@
.. py:currentmodule:: cantera.ctml_writer
.. _sec-input-files:
************************
Working with Input Files
************************
Before we can describe how to define phases, interfaces, and their components
(elements, species, and reactions), we need to go over a few points about the
mechanics of writing and processing input files.
Input File Syntax
=================
An input file consists of *entries* and *directives*, both of which have a
syntax much like functions. An entry defines an object---for example, a
reaction, or a species, or a phase. A directive sets options that affect how the
entry parameters are interpreted, such as the default unit system, or how
certain errors should be handled.
Cantera's input files follow the syntax rules for Python, so if you're familiar
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)::
species(name='C60', atoms='C:60')
Most entries have some fields that are required; these must be assigned values,
or else processing of the file will abort and an error message will be
printed. Other fields may be optional, and take default values if not assigned.
An entry may be either a *top-level entry* or an *embedded entry*. Top-level
entries specify a phase, an interface, an element, a species, or a reaction, and
begin in the first (leftmost) column. Embedded entries specify a model, or a
group of parameters for a top-level entry, and are usually embedded in a field
of another entry.
The fields of an entry are specified in the form ``<field_name> = <value>``, and may
be listed on one line, or extend across several. For example, two entries for
graphite are shown below. The first is compact::
stoichiometric_solid(name='graphite', species='C(gr)', elements='C', density=(2.2, 'g/cm3'))
and the second is formatted to be easier to read::
stoichiometric_solid(
name = 'graphite',
elements = 'C',
species = 'C(gr)',
density = (2.2, 'g/cm3')
)
Both are completely equivalent.
The species ``C(gr)`` that appears in the definition of the graphite phase is
also defined by a top-level entry. If the heat capacity of graphite is
approximated as constant, then the following definition could be used::
species(name='C(gr)',
atoms='C:1',
thermo=const_cp(t0=298.15,
h0=0.0,
s0=(5.6, 'J/mol/K'), # NIST
cp0=(8.43, 'J/mol/K'))) # Taylor and Groot (1980)
Note that the thermo field is assigned an embedded entry of type
:class:`const_cp`. Entries are stored as they are encountered when the file is
read, and only processed once the end of the file has been reached. Therefore,
the order in which they appear is unimportant.
Comments
--------
The character ``#`` is the comment character. Everything to the right of this
character on a line is ignored::
# set the default units
units(length = 'cm', # use centimeters for length
quantity = 'mol') # use moles for quantity
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 quotes::
string1 = 'A string.'
string2 = "Also a 'string'"
string3 = """This is
a
string too."""
The multi-line form is useful when specifying a phase containing a large number
of species::
species = """ H2 H O O2 OH H2O HO2 H2O2 C CH
CH2 CH2(S) CH3 CH4 CO CO2 HCO CH2O CH2OH CH3O
CH3OH C2H C2H2 C2H3 C2H4 C2H5 C2H6 HCCO CH2CO HCCOH
N NH NH2 NH3 NNH NO NO2 N2O HNO CN
HCN H2CN HCNN HCNO HOCN HNCO NCO N2 AR C3H7
C3H8 CH2CHO CH3CHO """
Sequences
---------
A sequence of multiple items is specified by separating the items by commas and
enclosing them in square brackets or parentheses. The individual items can have
any type---strings, integers, floating-point numbers (or even entries or other
lists). Square brackets are often preferred, since parentheses are also used for
other purposes in the input file, but either can be used::
s0 = (3.5, 'J/mol/K') # these are
s0 = [3.5, 'J/mol/K'] # equivalent
Variables
---------
Another way to specify the species C(gr) is shown here::
graphite_thermo = const_cp(t0=298.15,
h0=0.0,
s0=(5.6, 'J/mol/K'), # NIST
cp0=(8.43, 'J/mol/K')) # Taylor and Groot (1980)
species(name='C(gr)', atoms='C:1', thermo=graphite_thermo)
In this form, the ``const_cp`` entry is stored in a variable, instead of being
directly embedded within the species entry. The *thermo* field is assigned this
variable.
Variables can also be used for any other parameter type. For example, if you are
defining several phases in the file, and you want to set them all to the same
initial pressure, you could define a pressure variable::
P_initial = (2.0, 'atm')
and then set the pressure field in each embedded state entry to this variable.
Omitting Field Names
--------------------
Field names may be omitted if the values are entered in the order specified in
the entry declaration. (Entry declarations are the text printed on a colored
background in the following chapters.) It is also possible to omit only some of
the field names, as long as these fields are listed first, in order, before any
named fields.
For example, The first four entries below are equivalent, while the last two are
incorrect and would generate an error when processed::
element(symbol="Ar", atomic_mass=39.948) # OK
element(atomic_mass=39.948, symbol='Ar') # OK
element('Ar', atomic_mass=39.948) # OK
element("Ar", 39.948) # OK
element(39.948, "Ar") # error
element(symbol="Ar", 39.948) # error
Validation
----------
Normally, Cantera will make some checks for errors in the definitions of species
and reactions, such as checking for duplicate reactions. To slightly speed up
processing (if a mechanism has previously been validated), or in case of
spurious validation errors, validation can be disabled using the
:func:`validate` function. For example, to disable validation of reactions, add
the following to the CTI file::
validate(reactions='no')
.. _sec-dimensions:
Dimensional Values
==================
Many fields have numerical values that represent dimensional quantities---a
pressure, or a density, for example. If these are entered without specifying the
units, the default units (set by the :class:`units` directive described in
:ref:`sec-default-units`) will be used. However, it is also possible to specify
the units for each individual dimensional quantity (unless stated
otherwise). All that is required is to group the value in parentheses or square
brackets with a string specifying the units::
pressure = 1.0e5 # default is Pascals
pressure = (1.0, 'bar') # this is equivalent
density = (4.0, 'g/cm3')
density = 4000.0 # kg/m3
Compound unit strings may be used, as long as a few rules are followed:
1. Units in the denominator follow ``/``.
2. Units in the numerator follow ``-``, except for the first one.
3. Numerical exponents follow the unit string without a ``^`` character, and must
be in the range 2--6. Negative values are not allowed.
Examples of compound units::
A = (1.0e20, 'cm6/mol2/s') # OK
h = (6.626e-34, 'J-s') # OK
density = (3.0, 'g/cm3') # OK
A = (1.0e20, 'cm^6/mol/s') # error (^)
A = (1.0e20, 'cm6/mol2-s') # error ('s' should be in denominator)
density = (3.0, 'g-cm-3') # error (negative exponent)
.. _sec-default-units:
Setting the Default Units
-------------------------
The default unit system may be set with the :func:`units` directive. Note
that unit conversions are not done until the entire file has been read. Only one
units directive should be present in a file, and the defaults it specifies apply
to the entire file. If the file does not contain a units directive, the default
units are meters, kilograms, kilomoles, and seconds.
Shown below are two equivalent ways of specifying the site density for an
interface. In the first version, the site density is specified without a units
string, and so its units are constructed from the default units for quantity and
length, which are set with a units directive::
units(length = 'cm', quantity = 'molec')
interface(name = 'Si-100',
site_density = 1.0e15, # molecules/cm2 (default units)
# ...
)
The second version uses a different default unit system, but overrides the
default units by specifying an explicit units string for the site density::
units(length = 'cm', quantity = 'mol')
interface(name = 'Si-100',
site_density = (1.0e15, 'molec/cm2') # override default units
# ...
)
The second version is equivalent to the first, but would be very different if
the units of the site density were not specified!
The *length*, *quantity* and *time* units are used to construct the units for
reaction pre-exponential factors. The *energy* units are used for molar
thermodynamic properties, in combination with the units for *quantity*.
Since activation energies are often specified in units other than those used for
thermodynamic properties, a separate field is devoted to the default units for
activation energies::
units(length = 'cm', quantity = 'mol', act_energy = 'kcal/mol')
kf = Arrhenius(A = 1.0e14, b = 0.0, E = 54.0) # E is 54 kcal/mol
See :func:`units` for the declaration of the units directive.
Recognized Units
----------------
Cantera recognizes the following units in various contexts:
=========== ==============
field allowed values
=========== ==============
length ``'cm', 'm', 'mm'``
quantity ``'mol', 'kmol', 'molec'``
time ``'s', 'min', 'hr', 'ms'``
energy ``'J', 'kJ', 'cal', 'kcal'``
act_energy ``'kJ/mol', 'J/mol', 'J/kmol', 'kcal/mol', 'cal/mol', 'eV', 'K'``
pressure ``'Pa', 'atm', 'bar'``
=========== ==============
Processing Input Files
======================
A Two-step Process
------------------
From the point of view of the user, it appears that a Cantera application that
imports a phase definition reads the input file, and uses the information there
to construct the object representing the phase or interface in the
application. While this is the net effect, it is actually a two-step
process. When a constructor like ``Solution`` is called to import a phase definition
from a file, a preprocessor runs automatically to read the input file and create
a string that contains the same information but in an XML-based format called
CTML. After the preprocessor finishes, Cantera imports the phase definition from
this CTML data.
Two File Formats
----------------
Why two file formats? There are several reasons. XML is a widely-used standard
for data files, and it is designed to be relatively easy to parse. This makes it
possible for other applications to use Cantera CTML data files, without
requiring the substantial chemical knowledge that would be required to use .cti
files. For example, "web services" (small applications that run remotely over a
network) are often designed to accept XML input data over the network, perform a
calculation, and send the output in XML back across the network. Supporting an
XML-based data file format facilitates using Cantera in web services or other
network computing applications.
The difference between the high-level description in a .cti input file and the
lower-level description in the CTML file may be illustrated by how reactions are
handled. In the input file, the reaction stoichiometry and its reversibility or
irreversibility are determined from the reaction equation. For example::
O + HCCO <=> H + 2 CO
specifies a reversible reaction between an oxygen atom and the ketenyl radical
HCCO to produce one hydrogen atom and two carbon monoxide molecules. If ``<=>``
were replaced with ``=>``, then it would specify that the reaction should be
treated as irreversible.
Of course, this convention is not spelled out in the input file---the parser
simply has to know it, and has to also know that a "reactant" appears on the
left side of the equation, a "product" on the right, that the optional number in
front of a species name is its stoichiometric coefficient (but if missing the
value is one), etc. The preprocessor does know all this, but we cannot expect
the same level of knowledge of chemical conventions by a generic XML parser.
Therefore, in the CTML file, reactions are explicitly specified to be reversible
or irreversible, and the reactants and products are explicitly listed with their
stoichiometric coefficients. The XML file is, in a sense, a "dumbed-down"
version of the input file, spelling out explicitly things that are only implied
in the input file syntax, so that "dumb" (i.e., easy to write) parsers can be
used to read the data with minimal risk of misinterpretation.
The reaction definition::
reaction( "O + HCCO <=> H + 2 CO", [1.00000E+14, 0, 0])
in the input file is translated by the preprocessor to the following CTML text:
.. code-block:: xml
<reaction id="0028" reversible="yes">
<equation>O + HCCO [=] H + 2 CO</equation>
<rateCoeff>
<Arrhenius>
<A units="cm3/mol/s"> 1.000000E+14</A>
<b>0</b>
<E units="cal/mol">0.000000</E>
</Arrhenius>
</rateCoeff>
<reactants>HCCO:1 O:1</reactants>
<products>H:1 CO:2</products>
</reaction>
The CTML version is much more verbose, and would be much more tedious to write
by hand, but is much easier to parse, particularly since it is not necessary to
write a custom parser---virtually any standard XML parser, of which there are
many, can be used to read the CTML data.
So in general files that are easy for knowledgeable users (you) to write are more
difficult for machines to parse, because they make use of high-level
application-specific knowledge and conventions to simplify the
notation. Conversely, files that are designed to be easily parsed are tedious to
write because so much has to be spelled out explicitly. A natural solution is to
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 Internals: the ``ctml_writer`` Module
--------------------------------------------------
If you are interested in seeing the internals of how the preprocessing works,
take a look at file ``ctml_writer.py`` in the Cantera Python package. Or simply
start Python, and type::
>>> import cantera.ctml_writer
>>> help(cantera.ctml_writer)
The ``ctml_writer.py`` module can also be run as a script to convert input .cti
files to CTML. For example, if you have an input file ``phasedefs.cti``, then
simply type at the command line::
python -m cantera.ctml_writer phasedefs.cti
to create CTML file ``phasedefs.xml``. On systems which support running Python
scripts directly, a script to run ``ctml_writer`` directly is also installed. If
the Cantera ``bin`` directory is on your ``PATH``, you can also do the
conversion by running::
ctml_writer phasedefs.cti
This can be used to generate XML input files for use on systems where the
Cantera Python package is not installed. Of course, most of the time creation of
the CTML file will happen behind the scenes, and you will not need to be
concerned with CTML files at all.
Error Handling
==============
During processing of an input file, errors may be encountered. These could be
syntax errors, or could be ones that are flagged as errors by Cantera due to
some apparent inconsistency in the data---an unphysical value, a species that
contains an undeclared element, a reaction that contains an undeclared species,
missing species or element definitions, multiple definitions of elements,
species, or reactions, and so on.
Syntax Errors
-------------
Syntax errors are caught by the Python preprocessor, not by Cantera, and must be
corrected before proceeding further. Python prints a "traceback" that allows
you to find the line that contains the error. For example, consider the
following input file, which is intended to create a gas with the species and
reactions of GRI-Mech 3.0, but has a misspelled the field name ``reactions``::
ideal_gas(name = 'gas',
elements = 'H O',
species = 'gri30: all',
reactionss = 'gri30: all')
When this definition is imported into an application, an error message like the
following would be printed to the screen, and execution of the program or script
would terminate. ::
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/some/path/Cantera/importFromFile.py", line 18, in importPhase
return importPhases(file, [name], loglevel, debug)[0]
File "/some/path/Cantera/importFromFile.py", line 25, in importPhases
s.append(solution.Solution(src=file,id=nm,loglevel=loglevel,debug=debug))
File "/some/path/solution.py", line 39, in __init__
preprocess = 1, debug = debug)
File "/some/path/Cantera/XML.py", line 35, in __init__
self._xml_id = _cantera.xml_get_XML_File(src, debug)
cantera.error:
************************************************
Cantera Error!
************************************************
Procedure: ct2ctml
Error: Error converting input file "./gas.cti" to CTML.
Python command was: '/usr/bin/python'
The exit code was: 4
-------------- start of converter log --------------
TypeError on line 4 of './gas.cti':
__init__() got an unexpected keyword argument 'reactionss'
| Line |
| 1 | ideal_gas(name = 'gas',
| 2 | elements = 'H O',
| 3 | species = 'gri30: all',
> 4 > reactionss = 'gri30: all')
| 5 |
--------------- end of converter log ---------------
The top part of the error message shows the chain of functions that were called
before the error was encountered. For the most part, these are internal Cantera
functions not of direct concern here. The relevant part of this error message is
the part starting with the "Cantera Error" heading, and specifically the
contents of the *converter log* section. This message says that that on line 4
of ``gas.cti``, the the keyword argument ``reactionss`` was not
recognized. Seeing this message, it is clear that the problem is that
*reactions* is misspelled.
Cantera Errors
--------------
Now let's consider the other class of errors---ones that Cantera, not Python,
detects. Continuing the example above, suppose that the misspelling is
corrected, and the input file processed again. Again an error message results,
but this time it is from Cantera::
cantera.error:
Procedure: installSpecies
Error: species C contains undeclared element C
The problem is that the phase definition specifies that all species are to be
imported from dataset gri30, but only the elements H and O are declared. The
gri30 datset contains species composed of the elements H, O, C, N, and Ar. If
the definition is modified to declare these additional elements::
ideal_gas(name = 'gas',
elements = 'H O C N Ar',
species = 'gri30: all',
reactions = 'gri30: all')
it may be imported successfully.
Errors of this type do not have to be fatal, as long as you tell Cantera how you
want to handle them. You can, for example, instruct Cantera to quietly skip
importing any species that contain undeclared elements, instead of flagging them
as errors. You can also specify that reactions containing undeclared species
(also usually an error) should be skipped. This allows you to very easily
extract a portion of a large reaction mechanism, as described in :ref:`sec-phase-options`.
.. _sec-ck-format-conversion:
Converting CK-format files
==========================
Many existing reaction mechanism files are in "CK format," by which we mean
the input file format developed for use with the Chemkin-II software package
as specified in the report describing the Chemkin software [SAND89]_.
Cantera comes with a converter utility program ``ck2cti`` (or ``ck2cti.py``)
that converts CK format into Cantera format. This program should be run from
the command line first to convert any CK files you plan to use into Cantera
format (CTI format).
Usage::
ck2cti [--input=<filename>]
[--thermo=<filename>]
[--transport=<filename>]
[--surface=<filename>]
[--id=<phase-id>]
[--output=<filename>]
[--permissive]
[-d | --debug]
Each of the terms in square brackets is an option that can be passed on the
command line to ``ck2cti``. ``--input`` is the chemistry input file, containing
a list of all the element names that are used, a list of all the species names,
and a list of all the reactions to be considered between the species. This file
can also optionally contain thermodynamic information for the species. If the
``--input`` file does not contain the thermodynamic data, a separate file
containing this information must be specified to the `--thermo`` option. Finally,
the ``--input`` file can also optionally contain transport information for the
species. If it does not, and the user wishes to use a part of Cantera that relies
on some transport properties, the ``--transport`` option must be used to specify
the file containing all the transport data for the species.
For the case of a surface mechanism, the gas phase input file should be
specified as ``--input`` and the surface phase input file should be specified as
``--surface``.
Example::
ck2cti --input=chem.inp --thermo=therm.dat --transport=tran.dat
If the output file name is not given, an output file with the same name as the
input file, with the extension changed to '.cti'.
If the ck2cti script is not on your path but the Cantera Python module is,
ck2cti can also be used by running::
python -m cantera.ck2cti --input=chem.inp --thermo=therm.dat --transport=tran.dat
An input file containing only species definitions (which can be referenced from
phase definitions in other input files) can be created by specifying only a
thermo file.
Many existing CK format files cause errors in ``ck2cti`` when they are
processed. Some of these errors may be avoided by specifying the
``--permissive`` option. This option allows certain recoverable parsing errors
(e.g. duplicate transport or thermodynamic data) to be ignored. Other errors
may be caused by incorrect formatting of lines in one or more of the input files.
Debugging common errors in CK files
-----------------------------------
When ``ck2cti`` encounters an error, it attempts to print the surrounding
information to help you to locate the error. Many of the most common errors
are due to an inconsistency of the input files from their standard, as defined
in the report for Chemkin referenced above. These errors include:
* Each section of the input files must be started with a keyword representing that
section and ending with the keyword ``END``. Keywords that may begin a section
include:
- ``ELEMENTS`` or ``ELEM``
- ``SPECIES`` or ``SPEC``
- ``THERMO`` or ``THERMO ALL``
- ``REACTIONS`` or ``REAC``
- ``TRANSPORT``
* The thermodynamic data is read in a fixed format. This means that each
column of the input has a particular meaning. *Many common errors are
generated because information is missing or in the wrong column. Check
thoroughly for extraneous or missing spaces.* The format for each
thermodynamic entry should be as follows::
N2 N 2 G200.000 6000.000 1000.00 1
2.95258000E+00 1.39690000E-03-4.92632000E-07 7.86010000E-11-4.60755000E-15 2
-9.23949000E+02 5.87189000E+00 3.53101000E+00-1.23661000E-04-5.02999000E-07 3
2.43531000E-09-1.40881000E-12-1.04698000E+03 2.96747000E+00 4
The following table is adapted from the Chemkin manual [SAND89]_ to describe the
column positioning of each required part of the entry. Empty columns should be
filled with spaces.
+---------+-------------------------------------+--------+
|Line No. | Contents | Column |
+=========+=====================================+========+
| 1 | Species Name | 1--18 |
+---------+-------------------------------------+--------+
| 1 | Date (Optional) | 19--24 |
+---------+-------------------------------------+--------+
| 1 | Atomic Symbols and formula | 25--44 |
+---------+-------------------------------------+--------+
| 1 | Phase of species (S, L, G) | 45 |
+---------+-------------------------------------+--------+
| 1 | Low temperature | 46--55 |
+---------+-------------------------------------+--------+
| 1 | High temperature | 56--65 |
+---------+-------------------------------------+--------+
| 1 | Common temperature | 66--73 |
+---------+-------------------------------------+--------+
| 1 | Additional Atomic Symbols | 74--78 |
+---------+-------------------------------------+--------+
| 1 | The integer ``1`` | 80 |
+---------+-------------------------------------+--------+
| 2 | Coefficients :math:`a_1` | 1--75 |
| | to :math:`a_5` for the upper | |
| | temperature interval | |
+---------+-------------------------------------+--------+
| 2 | The integer ``2`` | 80 |
+---------+-------------------------------------+--------+
| 3 | Coefficients :math:`a_6,\ a_7` | 1--75 |
| | for the upper temperature interval, | |
| | and :math:`a_1,\ a_2,\ a_3` for | |
| | the lower temperature interval | |
+---------+-------------------------------------+--------+
| 3 | The integer ``3`` | 80 |
+---------+-------------------------------------+--------+
| 4 | Coefficients :math:`a_4` through | 1--60 |
| | :math:`a_7` for the lower | |
| | temperature interval | |
+---------+-------------------------------------+--------+
| 4 | The integer ``4`` | 80 |
+---------+-------------------------------------+--------+
The first 18 columns are reserved for the species name. The name assigned
to the species in the thermodynamic data must be the same as the species
name defined in the ``SPECIES`` section. If the species name is shorter
than 18 characters, the rest of the characters should be filled by spaces.
The next six columns (columns 19--24) are typically used to write a date;
they are not used further. The next 20 columns (25--44) are used to
specify the elemental composition of the species. In column 45, the phase
of the species (``S``, ``L``, or ``G`` for solid, liquid, or gas
respectively) should be specified. The next 28 columns are reserved for
the temperatures that delimit the ranges of the polynomials specified on
the next several lines. The first two temperatures have a width of 10
columns each (46--55 and 56--65), and represent the lowest temperature and
highest temperature for which the polynomials are valid. The last
temperature has a width of 8 columns (66--73) and is the "common"
temperature, where the switch from low to high occurs. The next 5 columns
(74--78) are reserved for atomic symbols and are usually left blank for
the default behavior. Column 79 is blank and finally, the row is ended in
column 80 with the integer ``1``.
The next three lines of the thermodynamic entry have a similar format.
They contain the coefficients of the polynomial described in
:ref:`sec-thermo-models` for the NASA 7-coefficient polynomial formulation.
The second row of the thermo entry (the first after the information row)
contains the first five coefficients that apply the the temperature range
between the midpoint and the upper limit. 15 columns are alloted for each
coefficient (for a total of 75 columns), with no spaces between them.
Although the entry above shows spaces between positive coefficients, it is
to be noted that this is done only for formatting consistency with other
lines that contain negative numbers. After the coefficients, four spaces
in columns 76--79 are followed by the integer ``2`` in column 80. On the
next line, the last two coefficients for the upper temperature range and
the first three coefficients for the lower temperature range are
specified. Once again, this takes up the first 75 columns, columns 76--79
are blank, and the integer ``3`` is in column 80. Finally, on the last
line of a particular entry, the last four coefficients of the lower
temperature range are specified in columns 1--60, 19 blank spaces are
present, and the integer ``4`` is in column 80. The 19 blank spaces in the
last line are part of the standard. However, since the original Chemkin
interpreter ignored those spaces, researchers began using that space to
store additional information that was not necessary for the input file.
Although these numbers create an error in ``ck2cti`` if present, they are
harmless and can be ignored by using the ``--permissive`` option.
* It may be the case that scientific formatted numbers are missing the ``E``.
In this case, numbers often show up as ``1.1+01``, when they should be
``1.1E+01``. You can fix this with a simple Regular Expression find and
replace::
Find: (\d+\.\d+)([+-]\d+)
Replace: \1E\2
* The transport data file also has a specified format, as described in
[SAND98]_, although the format is not as strict as for the thermodynamic
entries. In particular, the first 15 columns of a line are reserved for
the species name. *One common source of errors is a species that is present
in the transport data file, but not in the thermodynamic data or in
the species list; or a species that is present in the species list but
not the transport data file.* The rest of the columns on a given line have
no particular format, but must be present in the following order:
+------------------+------------------------------------------------------+
| Parameter Number | Parameter Name |
+==================+======================================================+
| 1 | An integer with value 0, 1, or 2 indicating |
| | monatomic, linear, or non-linear molecular geometry. |
+------------------+------------------------------------------------------+
| 2 | The Lennard-Jones potential well depth |
| | :math:`\varepsilon/k_B` in Kelvin |
+------------------+------------------------------------------------------+
| 3 | The Lennard-Jones collision diameter :math:`\sigma` |
| | in Angstrom |
+------------------+------------------------------------------------------+
| 4 | The dipole moment :math:`\mu` in Debye |
+------------------+------------------------------------------------------+
| 5 | The polarizability :math:`\alpha` in Angstrom |
+------------------+------------------------------------------------------+
| 6 | The rotational relaxation collision number |
| | :math:`Z_{rot}` at 298 K |
+------------------+------------------------------------------------------+
Another common error is if all 6 of these numbers are not present for every
species.
.. [SAND89] See R. J. Kee, F. M. Rupley, and J. A. Miller, Sandia National
Laboratories Report SAND89-8009 (1989).
http://www.osti.gov/scitech/biblio/5681118
.. [SAND98] See R. J. Kee, G. Dixon-Lewis, J. Warnatz, M. E. Coltrin, J. A. Miller,
H. K. Moffat, Sandia National Laboratories Report SAND86-8246B (1998).

40
doc/sphinx/cti/intro.rst
View file

@ -1,40 +0,0 @@
************
Introduction
************
Virtually every Cantera simulation involves one or more phases of
matter. Depending on the calculation being performed, it may be necessary to
evaluate thermodynamic properties, transport properties, and/or homogeneous
reaction rates for the phase(s) present. In problems with multiple phases, the
properties of the interfaces between phases, and the heterogeneous reaction
rates at these interfaces, may also be required.
Before the properties can be evaluated, each phase must be defined, meaning that
the models to use to compute its properties and reaction rates must be
specified, along with any parameters the models require. For example, a solid
phase might be defined as being incompressible, with a specified density and
composition. A gaseous phase for a combustion simulation might be defined as an
ideal gas consisting of a mixture of many species that react with one another
via a specified set of reactions.
For phases containing multiple species and reactions, a large amount of data is
required to define the phase, since the contribution of each species to the
thermodynamic and transport properties must be specified, and rate information
must be given for each reaction. While this could be done directly in an
application program, a better approach is put the phase and interface
definitions in a text file that can be read by the application, so that a given
phase model can be re-used for other simulations.
This guide describes how to write such files to define phases and interfaces for
use in Cantera simulations. Section :ref:`sec-input-files` contains a summary of
some basic rules for writing input files, a discussion of how they are
processed, and of how errors are handled. In Section :ref:`sec-phases`, we will
go over how to define phases and interfaces, including how to import species and
reactions from external files. Then in :ref:`sec-species` and
:ref:`sec-reactions`, we'll look in depth at how to specify the component parts
of phase and interface models---the elements, species, and reactions.
.. In Section ##REF##, we'll put it all together, and present some complete,
realistic example problems, showing the input file containing the definitions
of all phases and interfaces, the application code to use the input file to
solve a problem, and the resulting output.

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

@ -1,500 +0,0 @@
.. py:currentmodule:: cantera.ctml_writer
.. _sec-phases:
***************************
Phases and their Interfaces
***************************
Now that we have covered how to write syntactically-correct input files, we can
turn our attention to the content of the file. We'll start by describing the
entries for phases of various types, and the look at how to define interfaces
between phases.
Phases
======
For each phase that appears in a problem, a corresponding entry should be
present in the input file(s). For example, suppose we want to conduct a
simulation with detailed chemistry of an idealized solid-oxide fuel cell shown
below. The problem involves three solid phases (A nickel anode, a
platinum cathode, and an oxygen-conducting yttrium-stabilized zirconia
electrolyte), and two different gas phases (a fuel mixture on the anode side,
and air on the cathode side). The problem also involves a number of interfaces
at which heterogeneous chemistry may occur---two gas-metal interfaces, two
gas-electrolyte interfaces, and two metal-electrolyte interfaces.
.. figure:: /_static/images/sofc-phases.png
:align: center
**Phases entering into a hypothetical microkinetic simulation of an
idealized solid-oxide fuel cell.**
How to carry out this fuel cell simulation is beyond the scope of this document;
we introduce it here only to give an example of the types of phases and
interfaces that might need to be defined in order to carry out a simulation. (Of
course, many simulations with Cantera only require defining a single phase.)
There are several different types of entries, corresponding to different types
of phases. Phases are created using one of the directives corresponding to an
implemented phase type:
* :class:`ideal_gas`
* :class:`stoichiometric_solid`
* :class:`stoichiometric_liquid`
* :class:`metal`
* :class:`semiconductor`
* :class:`incompressible_solid`
* :class:`lattice`
* :class:`lattice_solid`
* :class:`liquid_vapor`
* :class:`redlich_kwong`
* :class:`ideal_interface`
* :class:`edge`
These phase typese share many common features, however, and so we will begin by
discussing those aspects common to all entries for phases. The :class:`phase`
class contains the features common to all phase types.
Phase Attributes
----------------
Phase Name
^^^^^^^^^^
The ``name`` field is a string that identifies the phase. It must not contain
any whitespace characters or reserved XML characters, and must be unique within
the file among all phase definitions of any type.
Phases are referenced by name when importing them into an application program,
or when defining an interface between phases.
Declaring the Elements
^^^^^^^^^^^^^^^^^^^^^^
The elements that may be present in the phase are declared in the elements
field. This must be a string of element symbols separated by spaces. Each symbol
must either match one listed in the database file ``elements.xml``, or else
match the symbol of an element entry defined elsewhere in the input file (See
:ref:`sec-elements`).
The ``elements.xml`` database contains most elements of the periodic table, with
their natural-abundance atomic masses. It also contains a few isotopes (D, Tr),
and an "element" for an electron (E). This pseudo-element can be used to specify
the composition of charged species. Note that two-character symbols should have
an uppercase first letter, and a lowercase second letter (e.g. ``Cu``, not ``CU``).
It should be noted that the order of the element symbols in the string
determines the order in which they are stored internally by Cantera. For
example, if a phase definition specifies the elements as::
ideal_gas(name = "gasmix",
elements = "H C O N Ar",
# ...
)
then when this definition is imported by an application, element-specific
properties will be ordered in the same way::
>>> import cantera as ct
>>> gas = ct.Solution('example.cti', 'gasmix')
>>> for n in range(gas.nElements()):
... print n, gas.elementSymbol(n)
0 H
1 C
2 O
3 N
4 Ar
For some calculations, such as multi-phase chemical equilibrium, it is important
to synchronize the elements among multiple phases, so that each phase contains
the same elements with the same ordering. In such cases, simply use the same
string in the elements field for all phases.
.. _sec-defining-species:
Defining the Species
^^^^^^^^^^^^^^^^^^^^
The species in the phase are declared in the species field. They are not defined
there, only declared. Species definitions may be imported from other files, or
species may be defined locally using species entries elsewhere in the file.
If a single string of species symbols is given, then it is assumed that these
are locally defined. For each one, a corresponding species entry must be present
somewhere in the file, either preceding or following the phase entry. Note that
the string may extend over multiple lines by delimiting it with triple quotes::
species = 'AR SI Si2 SiH SiH2 SiH3 SiH4'
# include all species defined in this file
species = 'all'
# a multi-line species declaration
species = """ H2 H O O2 OH H2O HO2 H2O2 C CH
CH2 CH2(S) CH3 CH4 CO CO2 HCO CH2O CH2OH CH3O
CH3OH C2H C2H2 C2H3 C2H4 C2H5 C2H6 HCCO CH2CO HCCOH
N NH NH2 NH3 NNH NO NO2 N2O HNO CN
HCN H2CN HCNN HCNO HOCN HNCO NCO N2 AR C3H7
C3H8 CH2CHO CH3CHO """
If the species are imported from another file, instead of being defined locally,
then the string should begin with the file name (without extension), followed by
a colon::
# import selected species from silicon.xml
species = "silicon: SI SI2 SIH SIH2 SIH3 SIH4 SI2H6"
# import all species from silicon.xml
species = "silicon: all"
In this case, the species definitions will be taken from file ``silicon.xml``,
which must exist either in the local directory or somewhere on the Cantera
search path.
It is also possible to import species from several sources, or mix local
definitions with imported ones, by specifying a sequence of strings::
species = ["CL2 CL F F2 HF HCL", # defined in this file
"air: O2 N2 NO", # imported from 'air.xml'
"ions: CL- F-"] # imported from 'ions.xml'
Note that the strings must be separated by commas, and enclosed in square
brackets or parentheses.
.. _sec-declaring-reactions:
Declaring the Reactions
^^^^^^^^^^^^^^^^^^^^^^^
The reactions among the species are declared in the ``reactions`` field. Just as
with species, reactions may be defined locally in the file, or may be imported
from one or more other files. All reactions must only involve species that have
been declared for the phase.
Unlike species, reactions do not have a name, but do have an optional ``ID``
field. If the ``ID`` field is not assigned a value, then when the reaction entry
is read it will be assigned a four-digit string encoding the reaction number,
beginning with ``'0001'`` for the first reaction in the file, and incrementing
by one for each new reaction.
If all reactions defined locally in the input file are to be included in the
phase definition, then assign the ``reactions`` field the string ``'all'``::
reactions = 'all'
If, on the other hand, only some of the reactions defined in the file are to be
included, then a range can be specified using the reaction ``ID`` fields::
reactions = 'nox-12 to nox-24'
In determining which reactions to include, a lexical comparison of id strings is
performed. This means, for example, that ``'nox-8'`` is greater than
``'nox-24'``. (If it is rewritten ``'nox-08'``, however, then it would be lexically
less than ``'nox-24'``.)
Just as described above for species, reactions can be imported from another
file, and reactions may be imported from several sources. Examples::
# import all reactions defined in this file
reactions = "all"
# import all reactions defined in rxns.xml
reactions = "rxns: all"
# import reactions 1-14 in rxns.xml
reactions = "rxns: 0001 to 0014"
# import reactions from several sources
reactions = ["all", # all local reactions
"gas: all", # all reactions in gas.xml
"nox: n005 to n008"] # reactions 5 to 8 in nox.xml
The Kinetics Model
^^^^^^^^^^^^^^^^^^
A *kinetics model* is a set of equations to use to compute reaction rates. In
most cases, each type of phase has an associated kinetics model that is used by
default, and so the ``kinetics`` field does not need to be assigned a value. For
example, the :class:`ideal_gas` entry has an associated kinetics model called
``GasKinetics`` that implements mass-action kinetics, computes reverse rates
from thermochemistry for reversible reactions, and provides various
pressure-independent and pressure-dependent reaction types. Other models could
be implemented, and this field would then be used to select the desired
model. For now, the ``kinetics`` field can be safely ignored.
The Transport Model
^^^^^^^^^^^^^^^^^^^
A *transport model* is a set of equations used to compute transport
properties. For :class:`ideal_gas` phases, multiple transport models are
available; the one desired can be selected by assigning a string to this
field. See :ref:`sec-gas-transport-models` for more details.
The Initial State
^^^^^^^^^^^^^^^^^
The phase may be assigned an initial state to which it will be set when the
definition is imported into an application and an object created. This is done
by assigning field ``initial_state`` an embedded entry of type :class:`state`,
described in :ref:`sec-state-entry`.
Most of the attributes defined here are "immutable," meaning that once the
definition has been imported into an application, they cannot be changed by the
application. For example, it is not possible to change the elements or the
species. The temperature, pressure, and composition, however, are "mutable"---
they can be changed. This is why the field defining the state is called the
``initial_state``; the object in the application will be initially set to this
state, but it may be changed at any time.
.. _sec-phase-options:
Special Processing Options
^^^^^^^^^^^^^^^^^^^^^^^^^^
The options field is used to indicate how certain conditions should be handled
when importing the phase definition. The options field may be assigned a string
or a sequence of strings from the table below.
================================== ========================================================
Option String Meaning
================================== ========================================================
``'skip_undeclared_elements'`` When importing species, skip any containing undeclared
elements, rather than flagging them as an error.
``'skip_undeclared_species'`` When importing reactions, skip any containing undeclared
species, rather than flagging them as an error.
``'skip_undeclared_third_bodies'`` When importing reactions with third body efficiencies,
ignore any efficiencies for undeclared species, rather
than flagging them as an error.
``'allow_discontinuous_thermo'`` Disable the automatic adjustment of NASA polynomials to
eliminate discontinuities in enthalpy and entropy at the
midpoint temperature.
================================== ========================================================
Using the ``options`` field, it is possible to extract a sub-mechanism from a large
reaction mechanism, as follows::
ideal_gas(name = 'hydrogen_mech',
elements = 'H O',
species = 'gri30:all',
reactions = 'gri30:all',
options = ('skip_undeclared_elements',
'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:
.. code-block:: matlabsession
>> gas = Solution('gas.cti', 'hydrogen_mech')
hydrogen_mech:
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
[ +7 minor] 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'
Ideal Gas Mixtures
------------------
Now we turn to the specific entry types for phases, beginning with
:class:`ideal_gas`.
Many combustion and CVD simulations make use of reacting ideal gas
mixtures. These can be defined using the :class:`ideal_gas` entry. The Cantera
ideal gas model allows any number of species, and any number of reactions among
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::
ideal_gas(name='air8',
elements='N O Ar',
species='gri30: N2 O2 N O NO NO2 N2O AR',
reactions='all',
transport='Mix',
initial_state=state(temperature=500.0,
pressure=(1.0, 'atm'),
mole_fractions='N2:0.78, O2:0.21, AR:0.01'))
This entry defines an ideal gas mixture that contains 8 species, the definitions
of which are imported from dataset gri30 (file ``gri30.xml``). All reactions
defined in the file are to be included, transport properties are to be computed
using mixture rules, and the state of the gas is to be set initially to 500 K, 1
atm, and a composition that corresponds to air.
.. _sec-gas-transport-models:
Transport Models
^^^^^^^^^^^^^^^^
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'``::
ideal_gas(name="gas1",
# ...
transport="Multi", # use multicomponent formulation
# ...
)
ideal_gas(name="gas2",
# ...
transport="Mix", # use mixture-averaged formulation
# ...
)
Stoichiometric Solid
--------------------
A :class:`stoichiometric_solid` is one that is modeled as having a precise,
fixed composition, given by the composition of the one species present. A
stoichiometric solid can be used to define a condensed phase that can
participate in heterogeneous reactions. (Of course, there cannot be homogeneous
reactions, since the composition is fixed.) ::
stoichiometric_solid(name='graphite',
elements='C',
species='C(gr)',
density=(2.2, 'g/cm3'),
initial_state=state(temperature=300.0,
pressure=(1.0, 'atm')))
In the example above, the definition of the species ``'C(gr)'`` must appear
elsewhere in the input file.
Stoichiometric Liquid
---------------------
A stoichiometric liquid differs from a stoichiometric solid in only one respect:
the transport manager computes the viscosity as well as the thermal
conductivity.
.. _sec-interfaces:
Interfaces
==========
Now that we have seen how to define bulk, three-dimensional phases, we can
describe the procedure to define an interface between phases.
Cantera presently implements a simple model for an interface that treats it as a
two-dimensional ideal solution of interfacial species. There is a fixed site
density :math:`n^0`, and each site may be occupied by one of several adsorbates,
or may be empty. The chemical potential of each species is computed using the
expression for an ideal solution:
.. math::
\mu_k = \mu^0_k + \hat{R}T \log \theta_k,
where :math:`\theta_k` is the coverage of species :math:`k` on the surface. The
coverage is related to the surface concentration :math:`C_k` by
.. math::
\theta_k = \frac{C_k n_k}{n^0} ,
where :math:`n_k` is the number of sites covered or blocked by species
:math:`k`.
The entry type for this interface model is
:class:`ideal_interface`. (Additional interface models may be added to allow
non-ideal, coverage-dependent properties.)
Defining an interface is much like defining a phase. There are two new fields:
``phases`` and ``site_density``. The ``phases`` field specifies the bulk phases that
participate in the heterogeneous reactions. Although in most cases this string
will list one or two phases, no limit is placed on the number. This is
particularly useful in some electrochemical problems, where reactions take place
near the triple-phase boundary where a gas, an electrolyte, and a metal all meet.
The ``site_density`` field is the number of adsorption sites per unit area.
Another new aspect is in the embedded :class:`state` entry in the
``initial_state`` field. When specifying the initial state of an interface, the
:class:`state` entry has a field *coverages*, which can be assigned a string
specifying the initial surface species coverages::
ideal_interface(name='silicon_surface',
elements='Si H',
species='s* s-SiH3 s-H',
reactions='all',
phases='gas bulk-Si',
site_density=(1.0e15, 'molec/cm2'),
initial_state=state(temperature=1200.0,
coverages='s-H:1'))
.. _sec-state-entry:
The :class:`state` entry
========================
The initial state of either a phase or an interface may be set using an embedded
:class:`state` entry. Note that only one of (``pressure``, ``density``) may be
specified, and only one of (``mole_fractions``, ``mass_fractions``, ``coverages``).
.. rubric:: References
.. [#Kee1989] R. J. Kee, F. M. Rupley, and J. A. Miller. Chemkin-II: A Fortran
chemical kinetics package for the analysis of gasphase chemical
kinetics. Technical Report SAND89-8009, Sandia National Laboratories, 1989.
.. [#dl68] G. Dixon-Lewis. Flame structure and flame reaction kinetics,
II: Transport phenomena in multicomponent systems. *Proc. Roy. Soc. A*,
307:111--135, 1968.
.. [#Kee2003] R. J. Kee, M. E. Coltrin, and P. Glarborg. *Chemically Reacting
Flow: Theory and Practice*. John Wiley and Sons, 2003.

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

@ -1,557 +0,0 @@
.. py:currentmodule:: cantera.ctml_writer
.. _sec-reactions:
*********
Reactions
*********
Cantera supports a number of different types of reactions, including several
types of homogeneous reactions, surface reactions, and electrochemical
reactions. For each, there is a corresponding entry type. The simplest entry
type is :class:`reaction`, which can be used for any homogeneous reaction that
has a rate expression that obeys the law of mass action, with a rate coefficient
that depends only on temperature.
Common Attributes
=================
All of the entry types that define reactions share some common features. These
are described first, followed by descriptions of the individual reaction types
in the following sections.
The Reaction Equation
---------------------
The reaction equation determines the reactant and product stoichiometry. A
relatively simple parsing strategy is currently used, which assumes that all
coefficient and species symbols on either side of the equation are delimited by
spaces::
2 CH2 <=> CH + CH3 # OK
2 CH2<=>CH + CH3 # OK
2CH2 <=> CH + CH3 # error
CH2 + CH2 <=> CH + CH3 # OK
2 CH2 <=> CH+CH3 # error
The incorrect versions here would generate "undeclared species" errors and would
halt processing of the input file. In the first case, the error would be that
the species ``2CH2`` is undeclared, and in the second case it would be species
``CH+CH3``.
Whether the reaction is reversible or not is determined by the form of the
equality sign in the reaction equation. If either ``<=>`` or ``=`` is found,
then the reaction is regarded as reversible, and the reverse rate will be
computed from detailed balance. If, on the other hand, ``=>`` is found, the
reaction will be treated as irreversible.
The rate coefficient is specified with an embedded entry corresponding to the
rate coefficient type. At present, the only implemented type is the modified
Arrhenius function
.. math::
k_f(T) = A T^b \exp(-E/\hat{R}T)
which is defined with an :class:`Arrhenius` entry::
rate_coeff = Arrhenius(A=1.0e13, b=0, E=(7.3, 'kcal/mol'))
rate_coeff = Arrhenius(1.0e13, 0, (7.3, 'kcal/mol'))
As a shorthand, if the ``rate_coeff`` field is assigned a sequence of three numbers, these are assumed to be :math:`(A, b, E)` in the modified Arrhenius function::
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
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
reactions), it is usually best not to specify units for *A*, in which case they
will be computed taking all of these factors into account.
Note: if :math:`b \ne 0`, then the term :math:`T^b` should have units of
:math:`K^b`, which would change the units of *A*. This is not done, however, so
the units associated with A are really the units for :math:`k_f` . One way to
formally express this is to replace :math:`T^b` by the non-dimensional quantity
:math:`[T/(1 K)]^b`.
The ID String
-------------
An optional identifying string can be entered in the ``ID`` field, which can
then be used in the ``reactions`` field of a :class:`phase` or interface entry
to identify this reaction. If omitted, the reactions are assigned ID strings as
they are read in, beginning with ``'0001'``, ``'0002'``, etc.
Note that the ID string is only used when selectively importing reactions. If
all reactions in the local file or in an external one are imported into a phase
or interface, then the reaction ``ID`` field is not used.
.. _sec-reaction-options:
Options
-------
Certain conditions are normally flagged as errors by Cantera. In some cases,
they may not be errors, and the options field can be used to specify how they
should be handled.
``skip``
The ``'skip'`` option can be used to temporarily remove this reaction from
the phase or interface that imports it, just as if the reaction entry were
commented out. The advantage of using skip instead of commenting it out is
that a warning message is printed each time a phase or interface definition
tries to import it. This serves as a reminder that this reaction is not
included, which can easily be forgotten when a reaction is "temporarily"
commented out of an input file.
``duplicate``
Normally, when a reaction is imported into a phase, it is checked to see
that it is not a duplicate of another reaction already present in the phase,
and an error results if a duplicate is found. But in some cases, it may be
appropriate to include duplicate reactions, for example if a reaction can
proceed through two distinctly different pathways, each with its own rate
expression. Another case where duplicate reactions can be used is if it is
desired to implement a reaction rate coefficient of the form:
.. math::
k_f(T) = \sum_{n=1}^{N} A_n T^{b_n} exp(-E_n/\hat{R}T)
While Cantera does not provide such a form for reaction rates, it can be
implemented by defining *N* duplicate reactions, and assigning one rate
coefficient in the sum to each reaction. If the ``'duplicate'`` option is
specified, then the reaction not only *may* have a duplicate, it *must*. Any
reaction that specifies that it is a duplicate, but cannot be paired with
another reaction in the phase that qualifies as its duplicate generates an
error.
``negative_A``
If some of the terms in the above sum have negative :math:`A_n`, this scheme
fails, since Cantera normally does not allow negative pre-exponential
factors. But if there are duplicate reactions such that the total rate is
positive, then negative *A* parameters are acceptable, as long as the
``'negative_A'`` option is specified.
``negative_orders``
Reaction orders are normally required to be non-negative, since negative
orders are non-physical and undefined at zero concentration. Cantera allows
negative orders for a global reaction only if the ``negative_orders``
override option is specified for the reaction.
Reactions with Pressure-Independent Rate
========================================
The :class:`reaction` entry is used to represent homogeneous reactions with
pressure-independent rate coefficients and mass action kinetics. Examples of
reaction entries that implement some reactions in the GRI-Mech 3.0 natural gas
combustion mechanism [#Smith1997]_ are shown below::
units(length = 'cm', quantity = 'mol', act_energy = 'cal/mol')
...
reaction( "O + H2 <=> H + OH", [3.87000E+04, 2.7, 6260])
reaction( "O + HO2 <=> OH + O2", [2.00000E+13, 0.0, 0])
reaction( "O + H2O2 <=> OH + HO2", [9.63000E+06, 2.0, 4000])
reaction( "O + HCCO <=> H + 2 CO", [1.00000E+14, 0.0, 0])
reaction( "H + O2 + AR <=> HO2 + AR", kf=Arrhenius(A=7.00000E+17, b=-0.8, E=0))
reaction( equation = "HO2 + C3H7 <=> O2 + C3H8", kf=Arrhenius(2.55000E+10, 0.255, -943))
reaction( equation = "HO2 + C3H7 => OH + C2H5 + CH2O", kf=[2.41000E+13, 0.0, 0])
Three-Body Reactions
====================
A three-body reaction is a gas-phase reaction of the form:
.. math::
{\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*
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
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
:math:`\epsilon` for each species, defined such that the forward reaction rate is
.. math::
k_f(T)[A][B][M]
where
.. math::
[M] = \sum_k \epsilon_k C_k
where :math:`C_k` is the concentration of species *k*. Since any constant
collision efficiency can be absorbed into the rate coefficient :math:`k_f(T)`, the
default collision efficiency is 1.0.
A three-body reaction may be defined using the :class:`three_body_reaction` entry. The equation string for a three-body
reaction must contain an ``'M'`` or ``'m'`` on both the reactant and product sides of the equation. The collision
efficiencies are specified as a string, with the species name followed by a colon and the efficiency.
Some examples from GRI-Mech 3.0 are shown below::
three_body_reaction( "2 O + M <=> O2 + M", [1.20000E+17, -1, 0],
" AR:0.83 C2H6:3 CH4:2 CO:1.75 CO2:3.6 H2:2.4 H2O:15.4 ")
three_body_reaction( "O + H + M <=> OH + M", [5.00000E+17, -1, 0],
efficiencies = " AR:0.7 C2H6:3 CH4:2 CO:1.5 CO2:2 H2:2 H2O:6 ")
three_body_reaction(
equation = "H + OH + M <=> H2O + M",
rate_coeff = [2.20000E+22, -2, 0],
efficiencies = " AR:0.38 C2H6:3 CH4:2 H2:0.73 H2O:3.65 "
)
As always, the field names are optional *if* the field values are entered in the
declaration order.
Falloff Reactions
=================
A *falloff reaction* is one that has a rate that is first-order in [M] at low
pressure, like a three-body reaction, but becomes zero-order in [M] as [M]
increases. Dissociation / association reactions of polyatomic molecules often
exhibit this behavior.
The simplest expression for the rate coefficient for a falloff reaction is the
Lindemann form [#Lindemann1922]_:
.. math::
k_f(T, [{\rm M}]) = \frac{k_0[{\rm M}]}{1 + \frac{k_0{\rm [M]}}{k_\infty}}
In the low-pressure limit, this approaches :math:`k0{\rm [M]}`, and in the
high-pressure limit it approaches :math:`k_\infty`.
Defining the non-dimensional reduced pressure:
.. math::
P_r = \frac{k_0 {\rm [M]}}{k_\infty}
The rate constant may be written as
.. math::
k_f(T, P_r) = k_\infty \left(\frac{P_r}{1 + P_r}\right)
More accurate models for unimolecular processes lead to other, more complex,
forms for the dependence on reduced pressure. These can be accounted for by
multiplying the Lindemann expression by a function :math:`F(T, P_r)`:
.. math::
k_f(T, P_r) = k_\infty \left(\frac{P_r}{1 + P_r}\right) F(T, P_r)
This expression is used to compute the rate coefficient for falloff
reactions. The function :math:`F(T, P_r)` is the *falloff function*, and is
specified by assigning an embedded entry to the ``falloff`` field.
The Troe Falloff Function
-------------------------
A widely-used falloff function is the one proposed by Gilbert et
al. [#Gilbert1983]_:
.. math::
\log_{10} F(T, P_r) = \frac{\log_{10} F_{cent}(T)}{1 + f_1^2}
F_{cent}(T) = (1-A) \exp(-T/T_3) + A \exp (-T/T_1) + \exp(-T_2/T)
f_1 = (\log_{10} P_r + C) / (N - 0.14 (\log_{10} P_r + C))
C = -0.4 - 0.67\; \log_{10} F_{cent}
N = 0.75 - 1.27\; \log_{10} F_{cent}
The :class:`Troe` directive requires specifying the first three parameters
:math:`(A, T_3, T_1)`. The fourth parameter, :math:`T_2`, is optional, defaulting to 0.0.
.. _sec-sri-falloff:
The SRI Falloff Function
------------------------
This falloff function is based on the one originally due to Stewart et
al. [#Stewart1989]_, which required three parameters :math:`(a, b, c)`. Kee et
al. [#Kee1989]_ generalized this function slightly by adding two more parameters
:math:`(d, e)`. (The original form corresponds to :math:`d = 1, e = 0`.) Cantera
supports the extended 5-parameter form, given by:
.. math::
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. [#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
function, which has a C++ implementation, but doesn't appear to be implemented
in the CTI or CTML parsers.
Chemically-Activated Reactions
==============================
For these reactions, the rate falls off as the pressure increases, due to
collisional stabilization of a reaction intermediate. Example:
.. math::
\mathrm{Si + SiH_4 (+M) \leftrightarrow Si_2H_2 + H_2 (+M)}
which competes with:
.. math::
\mathrm{Si + SiH_4 (+M) \leftrightarrow Si_2H_4 (+M)}
Like falloff reactions, chemically-activated reactions are described by
blending between a "low pressure" and a "high pressure" rate expression. The
difference is that the forward rate constant is written as being proportional
to the *low pressure* rate constant:
.. math::
k_f(T, P_r) = k_0 \left(\frac{1}{1 + P_r}\right) F(T, P_r)
and the optional blending function *F* may described by any of the
parameterizations allowed for falloff reactions. Chemically-activated
reactions can be defined using the :class:`chemically_activated_reaction`
directive.
An example of a reaction specified with this parameterization::
chemically_activated_reaction('CH3 + OH (+ M) <=> CH2O + H2 (+ M)',
kLow=[2.823201e+02, 1.46878, (-3270.56495, 'cal/mol')],
kHigh=[5.880000e-14, 6.721, (-3022.227, 'cal/mol')],
falloff=Troe(A=1.671, T3=434.782, T1=2934.21, T2=3919.0))
In this example, the units of :math:`k_0` (`kLow`) are m^3/kmol/s and the
units of :math:`k_\infty` (`kHigh`) are 1/s.
Pressure-Dependent Arrhenius Rate Expressions (P-Log)
=====================================================
The :class:`pdep_arrhenius` class represents pressure-dependent reaction rates
by logarithmically interpolating between Arrhenius rate expressions at various
pressures. Given two rate expressions at two specific pressures:
.. math::
P_1: k_1(T) = A_1 T^{b_1} e^{E_1 / RT}
P_2: k_2(T) = A_2 T^{b_2} e^{E_2 / RT}
The rate at an intermediate pressure :math:`P_1 < P < P_2` is computed as
.. math::
\log k(T,P) = \log k_1(T) + \bigl(\log k_2(T) - \log k_1(T)\bigr)
\frac{\log P - \log P_1}{\log P_2 - \log P_1}
Multiple rate expressions may be given at the same pressure, in which case the
rate used in the interpolation formula is the sum of all the rates given at that
pressure. For pressures outside the given range, the rate expression at the nearest
pressure is used.
An example of a reaction specified in this format::
pdep_arrhenius('R1 + R2 <=> P1 + P2',
[(0.001315789, 'atm'), 2.440000e+10, 1.04, 3980.0],
[(0.039473684, 'atm'), 3.890000e+10, 0.989, 4114.0],
[(1.0, 'atm'), 3.460000e+12, 0.442, 5463.0],
[(10.0, 'atm'), 1.720000e+14, -0.01, 7134.0],
[(100.0, 'atm'), -7.410000e+30, -5.54, 12108.0],
[(100.0, 'atm'), 1.900000e+15, -0.29, 8306.0])
The first argument is the reaction equation. Each subsequent argument is a
sequence of four elements specifying a pressure and the Arrhenius parameters at
that pressure.
Chebyshev Reaction Rate Expressions
===================================
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:
.. math:: \log k(T,P) = \sum_{t=1}^{N_T} \sum_{p=1}^{N_P} \alpha_{tp}
\phi_t(\tilde{T}) \phi_p(\tilde{P})
where :math:`\alpha_{tp}` are the constants defining the rate, :math:`\phi_n(x)`
is the Chebyshev polynomial of the first kind of degree :math:`n` evaluated at
:math:`x`, and
.. math::
\tilde{T} \equiv \frac{2T^{-1} - T_\mathrm{min}^{-1} - T_\mathrm{max}^{-1}}
{T_\mathrm{max}^{-1} - T_\mathrm{min}^{-1}}
\tilde{P} \equiv \frac{2 \log P - \log P_\mathrm{min} - \log P_\mathrm{max}}
{\log P_\mathrm{max} - \log P_\mathrm{min}}
are reduced temperature and reduced pressures which map the ranges
:math:`(T_\mathrm{min}, T_\mathrm{max})` and :math:`(P_\mathrm{min},
P_\mathrm{max})` to :math:`(-1, 1)`.
A Chebyshev rate expression is specified in terms of the coefficient matrix
:math:`\alpha` and the temperature and pressure ranges. An example of a
Chebyshev rate expression where :math:`N_T = 6` and :math:`N_P = 4` is::
chebyshev_reaction('R1 + R2 <=> P1 + P2',
Tmin=290.0, Tmax=3000.0,
Pmin=(0.001, 'atm'), Pmax=(100.0, 'atm'),
coeffs=[[-1.44280e+01, 2.59970e-01, -2.24320e-02, -2.78700e-03],
[ 2.20630e+01, 4.88090e-01, -3.96430e-02, -5.48110e-03],
[-2.32940e-01, 4.01900e-01, -2.60730e-02, -5.04860e-03],
[-2.93660e-01, 2.85680e-01, -9.33730e-03, -4.01020e-03],
[-2.26210e-01, 1.69190e-01, 4.85810e-03, -2.38030e-03],
[-1.43220e-01, 7.71110e-02, 1.27080e-02, -6.41540e-04]])
Note that the Chebyshev polynomials are not defined outside the interval
:math:`(-1,1)`, and therefore extrapolation of rates outside the range of
temperatures and pressure for which they are defined is strongly discouraged.
Surface Reactions
=================
Heterogeneous reactions on surfaces are represented by an extended Arrhenius-
like rate expression, which combines the modified Arrhenius rate expression with
further corrections dependent on the fractional surface coverages
:math:`\theta_k` of one or more surface species. The forward rate constant for a
reaction of this type is:
.. math::
k_f = A T^b \exp \left( - \frac{E_a}{RT} \right)
\prod_k 10^{a_k \theta_k} \theta_k^{m_k}
\exp \left( \frac{- E_k \theta_k}{RT} \right)
where :math:`A`, :math:`b`, and :math:`E_a` are the modified Arrhenius
parameters and :math:`a_k`, :math:`m_k`, and :math:`E_k` are the coverage
dependencies from species *k*. A reaction of this form with a single coverage
dependency (on the species ``H(S)``) can be written using class
:class:`surface_reaction` with the ``coverage`` keyword argument supplied to the
class :class:`Arrhenius`::
surface_reaction("2 H(S) => H2 + 2 PT(S)",
Arrhenius(A, b, E_a,
coverage=['H(S)', a_1, m_1, E_1]))
For a reaction with multiple coverage dependencies, the following syntax is
used::
surface_reaction("2 H(S) => H2 + 2 PT(S)",
Arrhenius(A, b, E_a,
coverage=[['H(S)', a_1, m_1, E_1],
['PT(S)', a_2, m_2, E_2]]))
Sticking Coefficients
---------------------
Collisions between gas-phase molecules and surfaces which result in the gas-
phase molecule sticking to the surface can be described as a reaction which is
parameterized by a sticking coefficient:
.. math::
\gamma = a T^b e^{-c/RT}
where :math:`a`, :math:`b`, and :math:`c` are constants specific to the
reaction. The values of these constants must be specified so that the sticking
coefficient :math:`\gamma` is between 0 and 1 for all temperatures.
The sticking coefficient is related to the forward rate constant by the
formula:
.. math::
k_f = \frac{\gamma}{\Gamma_\mathrm{tot}^m} \sqrt{\frac{RT}{2 \pi W}}
where :math:`\Gamma_\mathrm{tot}` is the total molar site density, :math:`m` is
the sum of all the surface reactant stoichiometric coefficients, and :math:`W`
is the molecular weight of the gas phase species.
A reaction of this form can be written as::
surface_reaction("H2O + PT(S) => H2O(S)", stick(a, b, c))
Additional Options
==================
Reaction Orders
---------------
Explicit reaction orders different from the stoichiometric coefficients are
sometimes used for non-elementary reactions. For example, consider the global
reaction:
.. math::
\mathrm{C_8H_{18} + 12.5 O_2 \rightarrow 8 CO_2 + 9 H_2O}
the forward rate constant might be given as [#Westbrook1981]_:
.. math::
k_f = 4.6 \times 10^{11} [\mathrm{C_8H_{18}}]^{0.25} [\mathrm{O_2}]^{1.5}
\exp\left(\frac{30.0\,\mathrm{kcal/mol}}{RT}\right)
This reaction could be defined as::
reaction("C8H18 + 12.5 O2 => 8 CO2 + 9 H2O", [4.6e11, 0.0, 30.0],
order="C8H18:0.25 O2:1.5")
Special care is required in this case since the units of the pre-exponential
factor depend on the sum of the reaction orders, which may not be an integer.
Note that you can change reaction orders only for irreversible reactions.
Normally, reaction orders are required to be positive. However, in some cases
negative reaction orders are found to be better fits for experimental data. In
these cases, the default behavior may be overridden by adding
``negative_orders`` to the reaction options, e.g.::
reaction("C8H18 + 12.5 O2 => 8 CO2 + 9 H2O", [4.6e11, 0.0, 30.0],
order="C8H18:-0.25 O2:1.75", options=['negative_orders'])
Some global reactions could have reactions orders for non-reactant species. One
should add ``nonreactant_orders`` to the reaction options to use this feature::
reaction("C8H18 + 12.5 O2 => 8 CO2 + 9 H2O", [4.6e11, 0.0, 30.0],
order="C8H18:-0.25 CO:0.15",
options=['negative_orders', 'nonreactant_orders'])
.. rubric:: References
.. [#Gilbert1983] R. G. Gilbert, K. Luther, and
J. Troe. *Ber. Bunsenges. Phys. Chem.*, 87:169, 1983.
.. [#Lindemann1922] F. Lindemann. *Trans. Faraday Soc.*, 17:598, 1922.
.. [#Smith1997] Gregory P. Smith, David M. Golden, Michael Frenklach, Nigel
W. Moriarty, Boris Eiteneer, Mikhail Goldenberg, C. Thomas Bowman, Ronald
K. Hanson, Soonho Song, William C. Gardiner, Jr., Vitali V. Lissianski, , and
Zhiwei Qin. GRI-Mech version 3.0, 1997. see
http://www.me.berkeley.edu/gri_mech.
.. [#Stewart1989] P. H. Stewart, C. W. Larson, and D. Golden.
*Combustion and Flame*, 75:25, 1989.
.. [#Kee1989] R. J. Kee, F. M. Rupley, and J. A. Miller. Chemkin-II: A Fortran
chemical kinetics package for the analysis of gas-phase chemical
kinetics. Technical Report SAND89-8009, Sandia National Laboratories, 1989.
.. [#Westbrook1981] C. K. Westbrook and F. L. Dryer. Simplified reaction
mechanisms for the oxidation of hydrocarbon fuels in flames. *Combustion
Science and Technology* **27**, pp. 31--43. 1981.

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

@ -1,340 +0,0 @@
.. py:currentmodule:: cantera.ctml_writer
.. _sec-species:
********************
Elements and Species
********************
.. _sec-elements:
Elements
========
The :class:`element` entry defines an element or an isotope of an element. Note that
these entries are not often needed, since the the database file ``elements.xml``
is searched for element definitions when importing phase and interface
definitions. An explicit element entry is needed only if an isotope not in
``elements.xml`` is required::
element(symbol='C-13',
atomic_mass=13.003354826)
element("O-18", 17.9991603)
Species
=======
For each species, a :class:`species` entry is required. Species are defined at
the top-level of the input file---their definitions are not embedded in a phase
or interface entry.
Species Name
------------
The name field may contain embedded parentheses, ``+`` or ``-`` signs to
indicate the charge, or just about anything else that is printable and not a
reserved character in XML. Some example name specifications::
name = 'CH4'
name = 'methane'
name = 'argon_2+'
name = 'CH2(singlet)'
Elemental Composition
---------------------
The elemental composition is specified in the atoms entry, as follows::
atoms = "C:1 O:2" # CO2
atoms = "C:1, O:2" # CO2 with optional comma
atoms = "Y:1 Ba:2 Cu:3 O:6.5" # stoichiometric YBCO
atoms = "" # a surface species representing an empty site
atoms = "Ar:1 E:-2" # Ar++
For gaseous species, the elemental composition is well-defined, since the
species represent distinct molecules. For species in solid or liquid solutions,
or on surfaces, there may be several possible ways of defining the species. For
example, an aqueous species might be defined with or without including the water
molecules in the solvation cage surrounding it.
For surface species, it is possible to omit the ``atoms`` field entirely, in
which case it is composed of nothing, and represents an empty surface site. This
can also be done to represent vacancies in solids. A charged vacancy can be
defined to be composed solely of electrons::
species(name = 'ysz-oxygen-vacancy',
atoms = 'O:0, E:2',
# ...,
)
Note that an atom number of zero may be given if desired, but is completely
equivalent to omitting that element.
The number of atoms of an element must be non-negative, except for the special
"element" ``E`` that represents an electron.
Thermodynamic Properties
------------------------
The :class:`phase` and :class:`ideal_interface` entries discussed in the last
chapter implement specific models for the thermodynamic properties appropriate
for the type of phase or interface they represent. Although each one may use
different expressions to compute the properties, they all require thermodynamic
property information for the individual species. For the phase types implemented
at present, the properties needed are:
1. the molar heat capacity at constant pressure :math:`\hat{c}^0_p(T)` for a
range of temperatures and a reference pressure :math:`P_0`;
2. the molar enthalpy :math:`\hat{h}(T_0, P_0)` at :math:`P_0` and a reference
temperature :math:`T_0`;
3. the absolute molar entropy :math:`\hat{s}(T_0, P_0)` at :math:`(T_0, P_0)`.
See: :ref:`sec-thermo-models`
.. _sec-species-transport-models:
Species Transport Coefficients
------------------------------
Transport property models in general require coefficients that express the
effect of each species on the transport properties of the phase. The
``transport`` field may be assigned an embedded entry that provides
species-specific coefficients.
Currently, the only entry type is :class:`gas_transport`, which supplies
parameters needed by the ideal-gas transport property models. The field values
and their units of the :class:`gas_transport` entry are compatible with the
transport database parameters described by Kee et al. [#Kee1986]_. Entries in
transport databases in the format described in their report can be used directly
in the fields of the :class:`gas_transport` entry, without requiring any unit
conversion. The numeric field values should all be entered as pure numbers, with
no attached units string.
.. _sec-thermo-models:
Thermodynamic Property Models
=============================
The entry types described in this section can be used to provide data for the
``thermo`` field of a :class:`species`. Each implements a different
*parameterization* (functional form) for the heat capacity. Note that there is
no requirement that all species in a phase use the same parameterization; each
species can use the one most appropriate to represent how the heat capacity
depends on temperature.
Currently, several types are implemented which provide species properties
appropriate for models of ideal gas mixtures, ideal solutions, and pure
compounds.
The NASA 7-Coefficient Polynomial Parameterization
--------------------------------------------------
The NASA 7-coefficient polynomial parameterization is used to compute the
species reference-state thermodynamic properties :math:`\hat{c}^0_p(T)`,
:math:`\hat{h}^0(T)` and :math:`\hat{s}^0(T)`.
The NASA parameterization represents :math:`\hat{c}^0_p(T)` with a fourth-order
polynomial:
.. math::
\frac{c_p^0(T)}{R} = a_0 + a_1 T + a_2 T^2 + a_3 T^3 + a_4 T^4
\frac{h^0(T)}{RT} = a_0 + \frac{a1}{2}T + \frac{a_2}{3} T^2 +
\frac{a_3}{4} T^3 + \frac{a_4}{5} T^4 + \frac{a_5}{T}
\frac{s^0(T)}{R} = a_0 \ln T + a_1 T + \frac{a_2}{2} T^2 + \frac{a_3}{3} T^3 +
\frac{a_4}{4} T^4 + a_6
Note that this is the "old" NASA polynomial form, used in the original NASA
equilibrium program and in Chemkin, which uses 7 coefficients in each of two
temperature regions. It is not compatible with the form used in the most recent
version of the NASA equilibrium program, which uses 9 coefficients for each
temperature region.
A NASA parameterization is defined by an embedded :class:`NASA` entry. Very
often, two NASA parameterizations are used for two contiguous temperature
ranges. This can be specified by assigning the ``thermo`` field of the
``species`` entry a sequence of two :class:`NASA` entries::
# use one NASA parameterization for T < 1000 K, and another for T > 1000 K.
species(name = "O2",
atoms = " O:2 ",
thermo = (
NASA( [ 200.00, 1000.00], [ 3.782456360E+00, -2.996734160E-03,
9.847302010E-06, -9.681295090E-09, 3.243728370E-12,
-1.063943560E+03, 3.657675730E+00] ),
NASA( [ 1000.00, 3500.00], [ 3.282537840E+00, 1.483087540E-03,
-7.579666690E-07, 2.094705550E-10, -2.167177940E-14,
-1.088457720E+03, 5.453231290E+00] ) ) )
The NASA 9-Coefficient Polynomial Parameterization
--------------------------------------------------
The NASA 9-coefficient polynomial parameterization [#McBride2002]_ ("NASA9" for
short) is an extension of the NASA 7-coefficient polynomial parameterization
which includes two additional terms in each temperature region, as well as
supporting an arbitrary number of temperature regions.
The NASA9 parameterization represents the species thermodynamic properties with
the following equations:
.. math::
\frac{C_p^0(T)}{R} = a_0 T^{-2} + a_1 T^{-1} + a_2 + a_3 T
+ a_4 T^2 + a_5 T^3 + a_6 T^4
\frac{H^0(T)}{RT} = - a_0 T^{-2} + a_1 \frac{\ln T}{T} + a_2
+ \frac{a_3}{2} T + \frac{a_4}{3} T^2 + \frac{a_5}{4} T^3 +
\frac{a_6}{5} T^4 + \frac{a_7}{T}
\frac{s^0(T)}{R} = - \frac{a_0}{2} T^{-2} - a_1 T^{-1} + a_2 \ln T
+ a_3 T + \frac{a_4}{2} T^2 + \frac{a_5}{3} T^3 + \frac{a_6}{4} T^4 + a_8
The following is an example of a species defined using the NASA9
parameterization in three different temperature regions::
species(name=u'CO2',
atoms='C:1 O:2',
thermo=(NASA9([200.00, 1000.00],
[ 4.943650540E+04, -6.264116010E+02, 5.301725240E+00,
2.503813816E-03, -2.127308728E-07, -7.689988780E-10,
2.849677801E-13, -4.528198460E+04, -7.048279440E+00]),
NASA9([1000.00, 6000.00],
[ 1.176962419E+05, -1.788791477E+03, 8.291523190E+00,
-9.223156780E-05, 4.863676880E-09, -1.891053312E-12,
6.330036590E-16, -3.908350590E+04, -2.652669281E+01]),
NASA9([6000.00, 20000.00],
[-1.544423287E+09, 1.016847056E+06, -2.561405230E+02,
3.369401080E-02, -2.181184337E-06, 6.991420840E-11,
-8.842351500E-16, -8.043214510E+06, 2.254177493E+03])),
note='Gurvich,1991 pt1 p27 pt2 p24. [g 9/99]')
Thermodynamic data for a range of species can be obtained from the `NASA
ThermoBuild <http://cearun.grc.nasa.gov/cea/index_ds.html>`_ tool. Using the web
interface, an input file can be obtained for a set of species. This input file
should then be modified so that the first line reads "`thermo nasa9`", as in the
following example::
thermo nasa9
200.000 1000.000 6000.000 20000.000 9/09/04
CO Gurvich,1979 pt1 p25 pt2 p29.
3 tpis79 C 1.00O 1.00 0.00 0.00 0.00 0 28.0101000 -110535.196
200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104
1.489045326D+04-2.922285939D+02 5.724527170D+00-8.176235030D-03 1.456903469D-05
-1.087746302D-08 3.027941827D-12 -1.303131878D+04-7.859241350D+00
1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104
4.619197250D+05-1.944704863D+03 5.916714180D+00-5.664282830D-04 1.398814540D-07
-1.787680361D-11 9.620935570D-16 -2.466261084D+03-1.387413108D+01
6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104
8.868662960D+08-7.500377840D+05 2.495474979D+02-3.956351100D-02 3.297772080D-06
-1.318409933D-10 1.998937948D-15 5.701421130D+06-2.060704786D+03
CO2 Gurvich,1991 pt1 p27 pt2 p24.
3 g 9/99 C 1.00O 2.00 0.00 0.00 0.00 0 44.0095000 -393510.000
200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469
4.943650540D+04-6.264116010D+02 5.301725240D+00 2.503813816D-03-2.127308728D-07
-7.689988780D-10 2.849677801D-13 -4.528198460D+04-7.048279440D+00
1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469
1.176962419D+05-1.788791477D+03 8.291523190D+00-9.223156780D-05 4.863676880D-09
-1.891053312D-12 6.330036590D-16 -3.908350590D+04-2.652669281D+01
6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469
-1.544423287D+09 1.016847056D+06-2.561405230D+02 3.369401080D-02-2.181184337D-06
6.991420840D-11-8.842351500D-16 -8.043214510D+06 2.254177493D+03
END PRODUCTS
END REACTANTS
This file (saved for example as `nasathermo.dat`) can then be converted to the
CTI format using the `ck2cti` script::
ck2cti --thermo=nasathermo.dat
To generate a full phase definition, create an input file defining the phase as
well, saved for example as `nasa.inp`::
elements
C O
end
species
CO CO2
end
The two input files can then be converted together by calling::
ck2cti --input=nasa.inp --thermo=nasathermo.dat
The Shomate Parameterization
----------------------------
The Shomate parameterization is:
.. math::
\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
\hat{s}^0(T) = A \ln t + B t + \frac{Ct^2}{2} + \frac{Dt^3}{3} -
\frac{E}{2t^2} + G
where :math:`t = T / 1000 K`. It requires 7 coefficients A, B, C, D, E, F, and
G. This parameterization is used to represent reference-state properties in the
`NIST Chemistry WebBook <http://webbook.nist.gov/chemistry>`_. The values of 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::
# use a single Shomate parameterization.
species(name = "O2",
atoms = " O:2 ",
thermo = Shomate( [298.0, 6000.0],
[29.659, 6.137261, -1.186521, 0.09578, -0.219663,
-9.861391, 237.948] ) )
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 can be used for the thermodynamic
properties. The :class:`const_cp` parameterization computes the properties as
follows:
.. math::
\hat{c}_p^0(T) = \hat{c}_p^0(T_0)
\hat{h}^0(T) = \hat{h}^0(T_0) + \hat{c}_p^0\cdot(T-T_0)
\hat{s}^0(T) = \hat{s}^0(T_0) + \hat{c}_p^0 \ln (T/T_0)
The parameterization uses four constants: :math:`T_0, \hat{c}_p^0(T_0),
\hat{h}^0(T_0), \hat{s}^0(T)`. The default value of :math:`T_0` is 298.15 K; the
default value for the other parameters is 0.0.
Example::
thermo = const_cp(h0=(-393.51, 'kJ/mol'),
s0=(213.785, 'J/mol/K'),
cp0=(37.12, 'J/mol/K'))
Assuming that the :func:`units` function has been used to set the default energy
units to Joules and the default quantity unit to kmol, this may be equivalently
written as::
thermo = const_cp(h0=-3.9351e8, s0=2.13785e5, cp0=3.712e4)
.. See ##REF## for more examples of use of this parameterization.
.. rubric:: References
.. [#Kee1986] R. J. Kee, G. Dixon-Lewis, J. Warnatz, M. E. Coltrin, and J. A. Miller.
A FORTRAN Computer Code Package for the Evaluation of Gas-Phase, Multicomponent
Transport Properties. Technical Report SAND86-8246, Sandia National Laboratories, 1986.
.. [#Mcbride2002] B. J. McBride, M. J. Zehe, S. Gordon. "NASA Glenn Coefficients
for Calculating Thermodynamic Properties of Individual Species,"
NASA/TP-2002-211556, Sept. 2002.

147
doc/sphinx/cxx-guide/compiling.rst
View file

@ -1,147 +0,0 @@
******************************
Compiling Cantera C++ Programs
******************************
In general, it should be possible to use Cantera with any build system by
specifying the appropriate header and library paths, and specifying the required
libraries when linking. It is also necessary to specify the paths for libraries
used by Cantera, e.g. Sundials, BLAS, and LAPACK.
pkg-config
==========
On systems where the ``pkg-config`` program is installed, it can be used to
determine the correct compiler and linker flags for use with Cantera. For
example:
.. code-block:: bash
g++ myProgram.cpp -o myProgram $(pkg-config --cflags --libs cantera)
It can also be used to populate variables in a Makefile:
.. code-block:: make
CFLAGS += $(shell pkg-config --cflags cantera)
LIBS += $(shell pkg-config --libs cantera)
Or in an SConstruct file::
env.ParseConfig("pkg-config --cflags --libs cantera")
Note that ``pkg-config`` will work only if it can find the ``cantera.pc``
file. If Cantera's libraries are not installed in a standard location such as
``/usr/lib`` or ``/usr/local/lib``, you may need to set the ``PKG_CONFIG_PATH``
environment variable appropriately before using ``pkg-config``.
SCons
=====
SCons is a multi-platform, Python-based build system. It is the build system
used to compile Cantera. The description of how to build a project is contained
in a file named ``SConstruct``. The ``SConstruct`` file is actually a Python
script, which makes it very straightforward to add functionality to a
SCons-based build system.
A typical ``SConstruct`` file for compiling a program that uses Cantera might
look like this::
env = Environment()
env.Append(CCFLAGS='-g',
CPPPATH=['/usr/local/cantera/include',
'/usr/local/sundials/include'],
LIBS=['cantera', 'sundials_cvodes', 'sundials_ida',
'sundials_nvecserial', 'lapack', 'blas'],
LIBPATH=['/usr/local/cantera/lib',
'/usr/local/sundials/lib'],
LINKFLAGS=['-g', '-pthread'])
sample = env.Program('sample', 'sample.cpp')
Default(sample)
This script establishes what SCons refers to as a "construction environment"
named ``env``, and sets the header (``CPPPATH``) and library (``LIBPATH``) paths
to include the directories containing the Cantera headers and libraries, as well
as libraries that Cantera depends on, such as Sundials, BLAS, and LAPACK. Then,
a program named ``sample`` is compiled using the single source file
``sample.cpp``.
Several other example ``SConstruct`` files are included with the C++ examples
contained in the ``samples`` subdirectory of the Cantera installation directory.
For more information on SCons, see the `SCons Wiki <http://scons.org/wiki/>`_
and the `SCons homepage <http://www.scons.org>`_.
CMake
=====
CMake is a multi-platform build system which uses a high-level project
description to generate platform-specific build scripts (i.e. on Linux, CMake
will generate Makefiles). The configuration file for a CMake project is called
``CMakeLists.txt``. A typical ``CMakeLists.txt`` file for compiling a program
that uses Cantera might look like this:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.1)
project (sample)
set(CMAKE_VERBOSE_MAKEFILE ON)
set(CMAKE_CXX_STANDARD 11)
find_package(Threads REQUIRED)
include_directories("/opt/cantera/include" "/opt/sundials-2.7.0/include")
link_directories("/opt/cantera/lib" "/opt/sundials-2.7.0/lib")
add_executable(sample sample.cpp)
target_link_libraries(sample cantera sundials_cvodes sundials_ida sundials_nvecserial fmt Threads::Threads)
Several example ``CMakeLists.txt`` files are included with the C++ examples
contained in the ``samples`` subdirectory of the Cantera installation directory,
which have the paths and lists of libraries correctly configured for system on
which they are installed.
Make
====
Cantera is distributed with an "include Makefile" that can be used with
Make-based build systems. This file ``Cantera.mak`` is located in the
``samples`` subdirectory of the Cantera installation directory. To use it, add a
line referencing this file to the top of your Makefile::
include path/to/Cantera.mak
The path specified should be the relative path from the ``Makefile`` to
``Cantera.mak``. This file defines several variables which can be used in your
Makefile. The following is an example ``Makefile`` that uses the definitions
contained in ``Cantera.mak``:
.. code-block:: makefile
include ../../Cantera.mak
CC=gcc
CXX=g++
RM=rm -f
CCFLAGS=-g
CPPFLAGS=$(CANTERA_INCLUDES)
LDFLAGS=
LDLIBS=$(CANTERA_LIBS)
SRCS=sample.cpp
OBJS=$(subst .cpp,.o,$(SRCS))
all: sample
kinetics1: $(OBJS)
$(CXX) $(LDFLAGS) -o sample $(OBJS) $(LDLIBS)
clean:
$(RM) $(OBJS)
dist-clean: clean
$(RM) *~

34
doc/sphinx/cxx-guide/demo1a.cpp
View file

@ -1,34 +0,0 @@
#include "cantera/thermo.h"
#include <iostream>
using namespace Cantera;
// The actual code is put into a function that
// can be called from the main program.
void simple_demo()
{
// Create a new phase
std::unique_ptr<ThermoPhase> gas(newPhase("h2o2.cti","ohmech"));
// Set its state by specifying T (500 K) P (2 atm) and the mole
// fractions. Note that the mole fractions do not need to sum to
// 1.0 - they will be normalized internally. Also, the values for
// any unspecified species will be set to zero.
gas->setState_TPX(500.0, 2.0*OneAtm, "H2O:1.0, H2:8.0, AR:1.0");
// Print a summary report of the state of the gas
std::cout << gas->report() << std::endl;
}
// the main program just calls function simple_demo within
// a 'try' block, and catches CanteraError exceptions that
// might be thrown
int main()
{
try {
simple_demo();
} catch (CanteraError& err) {
std::cout << err.what() << std::endl;
}
}

66
doc/sphinx/cxx-guide/demo1b.cpp
View file

@ -1,66 +0,0 @@
#include "cantera/thermo.h"
#include "cantera/kinetics.h"
#include "cantera/transport.h"
using namespace Cantera;
// The actual code is put into a function that can be called from the main
// program.
void simple_demo2()
{
// Create a new phase
std::unique_ptr<ThermoPhase> gas(newPhase("gri30.cti", "gri30_mix"));
// List of phases participating in reactions (just one for homogeneous
// kinetics)
std::vector<ThermoPhase*> phases{gas.get()};
// Create the Kinetics object. Based on the phase definition used, this will
// be a GasKinetics object.
std::unique_ptr<Kinetics> kin(newKineticsMgr(gas->xml(), phases));
// Set an "interesting" mixture state where we will observe non-zero reacton
// rates.
gas->setState_TPX(500.0, 2.0*OneAtm, "CH4:1.0, O2:1.0, N2:3.76");
gas->equilibrate("HP");
gas->setState_TP(gas->temperature() - 100, gas->pressure());
// Get the net reaction rates
vector_fp wdot(kin->nReactions());
kin->getNetRatesOfProgress(wdot.data());
writelog("Net reaction rates for reactions involving CO2\n");
size_t kCO2 = gas->speciesIndex("CO2");
for (size_t i = 0; i < kin->nReactions(); i++) {
if (kin->reactantStoichCoeff(kCO2, i)
|| kin->productStoichCoeff(kCO2, i)) {
writelog("{:3d} {:30s} {: .8e}\n",
i, kin->reactionString(i), wdot[i]);
}
}
writelog("\n");
// Create a Transport object. Based on the transport model specified in the
// "gri30_mix" phase, this will be a MixGasTransport object.
std::unique_ptr<Transport> trans(newDefaultTransportMgr(gas.get()));
writelog("T viscosity thermal conductivity\n");
writelog("------ ----------- --------------------\n");
for (size_t n = 0; n < 5; n++) {
double T = 300 + 100 * n;
gas->setState_TP(T, gas->pressure());
writelog("{:.1f} {:.4e} {:.4e}\n",
T, trans->viscosity(), trans->thermalConductivity());
}
}
// the main program just calls function simple_demo2 within a 'try' block, and
// catches exceptions that might be thrown
int main()
{
try {
simple_demo2();
} catch (std::exception& err) {
std::cout << err.what() << std::endl;
}
}

20
doc/sphinx/cxx-guide/demoequil.cpp
View file

@ -1,20 +0,0 @@
#include "cantera/thermo.h"
using namespace Cantera;
void equil_demo()
{
std::unique_ptr<ThermoPhase> gas(newPhase("h2o2.cti","ohmech"));
gas->setState_TPX(1500.0, 2.0*OneAtm, "O2:1.0, H2:3.0, AR:1.0");
gas->equilibrate("TP");
std::cout << gas->report() << std::endl;
}
int main()
{
try {
equil_demo();
} catch (CanteraError& err) {
std::cout << err.what() << std::endl;
}
}

57
doc/sphinx/cxx-guide/equil-example.rst
View file

@ -1,57 +0,0 @@
************************************
Chemical Equilibrium Example Program
************************************
In the program below, the `equilibrate` method is called to set the gas to a
state of chemical equilibrium, holding the temperature and pressure fixed.
.. 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::ThermoPhase::equilibrate>`
function really works.

47
doc/sphinx/cxx-guide/factories.rst
View file

@ -1,47 +0,0 @@
Creating ThermoPhase, Kinetics, and Transport objects
=====================================================
The following program demonstrates the general method for creating the following
object types:
- `ThermoPhase` - represents the thermodynamic properties of mixtures containing
one or more species)
- `Kinetics` - represents a kinetic mechanism involving one or more phases)
- `Transport` - computes transport properties for a `ThermoPhase`
This program uses "factory" functions to create derived objects objects of the
appropriate type which are specified in the input file `gri30.cti`.
.. literalinclude:: demo1b.cpp
:language: c++
This program produces the output below::
Net reaction rates for reactions involving CO2
11 CO + O (+M) <=> CO2 (+M) 3.54150724e-08
13 HCO + O <=> CO2 + H 1.95680014e-11
29 CH2CO + O <=> CH2 + CO2 3.45366988e-17
30 CO + O2 <=> CO2 + O 2.70102522e-13
41 CO2 + 2 H <=> CO2 + H2 3.45305359e-08
98 CO + OH <=> CO2 + H 6.46935907e-03
119 CO + HO2 <=> CO2 + OH 1.86807529e-10
131 CH + CO2 <=> CO + HCO 9.41365695e-14
151 CH2(S) + CO2 <=> CH2 + CO2 3.11161382e-12
152 CH2(S) + CO2 <=> CH2O + CO 2.85339329e-11
225 NCO + O2 <=> CO2 + NO 3.74127282e-19
228 NCO + NO <=> CO2 + N2 6.25672779e-14
261 HNCO + O <=> CO2 + NH 6.84524890e-13
267 HNCO + OH <=> CO2 + NH2 7.78871264e-10
279 CO2 + NH <=> CO + HNO -3.30333658e-09
281 NCO + NO2 <=> CO2 + N2O 2.14286686e-20
282 CO2 + N <=> CO + NO 6.42658283e-10
289 CH2 + O2 => CO2 + 2 H 1.51032319e-18
304 CH2CHO + O => CH2 + CO2 + H 1.00331734e-19
T viscosity thermal conductivity
------ ----------- --------------------
300.0 1.6658e-05 4.2089e-02
400.0 2.0861e-05 5.2537e-02
500.0 2.4681e-05 6.2451e-02
600.0 2.8218e-05 7.2157e-02
700.0 3.1534e-05 8.1754e-02

41
doc/sphinx/cxx-guide/headers.rst
View file

@ -1,41 +0,0 @@
****************
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.
These headers are designed for use in C++ application programs, and are not
included by the Cantera core. The headers and their functions are:
``IdealGasMix.h``
Provides class :ct:`IdealGasMix`.
``Interface.h``
Provides class :ct:`Interface`.
``integrators.h``
ODE Integrators.
``kinetics.h``
Base kinetics classes and functions for creating :ct:`Kinetics` objects from
input files.
``onedim.h``
One-dimensional reacting flows.
``reactionpaths.h``
Reaction path diagrams.
``thermo.h``
Base thermodynamic classes and functions for creating :ct:`ThermoPhase`
objects from input files.
``transport.h``
Base transport property classes and functions for creating :ct:`Transport`
objects from input files.
``zerodim.h``
Zero-dimensional reactor networks.

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

@ -1,14 +0,0 @@
**************************
C++ Interface User's Guide
**************************
.. toctree::
:maxdepth: 2
compiling
headers
thermo
simple-example
equil-example
factories

76
doc/sphinx/cxx-guide/simple-example.rst
View file

@ -1,76 +0,0 @@
.. _sec-cxx-simple-example:
*************************
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++
Before you can run this program, it first needs to be compiled. On a Linux
system using the GCC compiler, a typical command line for compiling this program
might look like this::
g++ -o combustor -pthread -O3 -std=c++0x -I/opt/cantera-2.4.0/include -L/opt/cantera-2.4.0/lib -lcantera -lsundials_cvodes -lsundials_ida -lsundials_nvecserial combustor.cpp
The locations of the Cantera header files (specified by the `-I` option) and the
libraries (specified by the `-L` option) will vary depending on where you
installed Cantera, and the list of libraries (such as `sundials_cvodes`) will
vary depending on what options you used when compiling Cantera. For more
advanced and flexible methods of compiling programs which use the Cantera C++
library, see :doc:`compiling`.
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.
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.

126
doc/sphinx/cxx-guide/thermo.rst
View file

@ -1,126 +0,0 @@
**********************************
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)
{
std::unique_ptr<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
<Phase::temperature>` that returns the current temperature, a method
:ct:`setTemperature(double T) <Phase::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 polynomial
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 :math:`r+1` independent thermodynamic properties,
where :math:`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.

42
doc/sphinx/cxx-guide/thermodemo.cpp
View file

@ -1,42 +0,0 @@
#include "cantera/thermo.h"
using namespace Cantera;
void thermo_demo(const std::string& file, const std::string& phase)
{
shared_ptr<ThermoPhase> gas(newPhase(file, phase));
gas->setState_TPX(1500.0, 2.0*OneAtm, "O2:1.0, H2:3.0, AR:1.0");
// temperature, pressure, and density
std::cout << gas->temperature() << std::endl;
std::cout << gas->pressure() << std::endl;
std::cout << gas->density() << std::endl;
// molar thermodynamic properties
std::cout << gas->enthalpy_mole() << std::endl;
std::cout << gas->entropy_mole() << std::endl;
// specific (per unit mass) thermodynamic properties
std::cout << gas->enthalpy_mass() << std::endl;
std::cout << gas->entropy_mass() << std::endl;
// chemical potentials of the species
int numSpecies = gas->nSpecies();
vector_fp mu(numSpecies);
gas->getChemPotentials(&mu[0]);
int n;
for (n = 0; n < numSpecies; n++) {
std::cout << gas->speciesName(n) << " " << mu[n] << std::endl;
}
}
int main(int argc, char** argv)
{
try {
thermo_demo("h2o2.cti","ohmech");
} catch (CanteraError& err) {
std::cout << err.what() << std::endl;
return 1;
}
return 0;
}

3
doc/sphinx/cython/index.rst
View file

@ -8,7 +8,6 @@ Contents:
.. toctree::
:maxdepth: 2
tutorial
importing
thermo
kinetics
@ -16,5 +15,3 @@ Contents:
zerodim
onedim
constants
Application Examples as Jupyter Notebooks <https://github.com/Cantera/cantera-jupyter#cantera-jupyter>

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

@ -1,442 +0,0 @@
.. py:currentmodule:: cantera
Tutorial
========
Getting Started
---------------
Start by opening an interactive Python session, e.g., by running `IPython
<http://ipython.org/>`_. Import the Cantera Python module and NumPy by running::
>>> import cantera as ct
>>> import numpy as np
When using Cantera, the first thing you usually need is an object representing
some phase of matter. Here, we'll create a gas mixture::
>>> gas1 = ct.Solution('gri30.xml')
To view the state of the mixture, *call* the `gas1` object as if it were a
function::
>>> gas1()
You should see something like this::
gri30:
temperature 300 K
pressure 101325 Pa
density 0.0818891 kg/m^3
mean mol. weight 2.01588 amu
1 kg 1 kmol
----------- ------------
enthalpy 26470.1 5.336e+04 J
internal energy -1.21087e+06 -2.441e+06 J
entropy 64913.9 1.309e+05 J/K
Gibbs function -1.94477e+07 -3.92e+07 J
heat capacity c_p 14311.8 2.885e+04 J/K
heat capacity c_v 10187.3 2.054e+04 J/K
X Y Chem. Pot. / RT
------------- ------------ ------------
H2 1 1 -15.7173
[ +52 minor] 0 0
What you have just done is to create an object, `gas1` that implements GRI-
Mech 3.0, the 53-species, 325-reaction natural gas combustion mechanism
developed by Gregory P. Smith, David M. Golden, Michael Frenklach, Nigel W.
Moriarty, Boris Eiteneer, Mikhail Goldenberg, C. Thomas Bowman, Ronald K.
Hanson, Soonho Song, William C. Gardiner, Jr., Vitali V. Lissianski, and
Zhiwei Qin. See http://www.me.berkeley.edu/gri_mech/ for more information.
The `gas1` object has properties you would expect for a gas mixture - it has a
temperature, a pressure, species mole and mass fractions, etc. As we'll soon
see, it has many more properties.
The summary of the state of `gas1` printed above shows that new objects
created from the `gri30.xml` input file start out with a temperature of 300 K,
a pressure of 1 atm, and have a composition that consists of only one species,
in this case hydrogen. There is nothing special about H2 - it just happens to
be the first species listed in the input file defining GRI-Mech 3.0. In
general, whichever species is listed first will initially have a mole fraction
of 1.0, and all of the others will be zero.
Setting the State
~~~~~~~~~~~~~~~~~
The state of the object can easily be changed. For example::
>>> gas1.TP = 1200, 101325
sets the temperature to 1200 K and the pressure to 101325 Pa (Cantera always
uses SI units). After this statement, calling ``gas1()`` results in::
gri30:
temperature 1200 K
pressure 101325 Pa
density 0.0204723 kg/m^3
mean mol. weight 2.01588 amu
1 kg 1 kmol
----------- ------------
enthalpy 1.32956e+07 2.68e+07 J
internal energy 8.34619e+06 1.682e+07 J
entropy 85227.6 1.718e+05 J/K
Gibbs function -8.89775e+07 -1.794e+08 J
heat capacity c_p 15377.9 3.1e+04 J/K
heat capacity c_v 11253.4 2.269e+04 J/K
X Y Chem. Pot. / RT
------------- ------------ ------------
H2 1 1 -17.9775
[ +52 minor] 0 0
Notice that the temperature has been changed as requested, but the pressure
has changed too. The density and composition have not.
Thermodynamics generally requires that *two* properties in addition to
composition information be specified to fix the intensive state of a substance
(or mixture). The state of the mixture can be set using several combinations
of two properties. The following are all equivalent::
>>> gas1.TP = 1200, 101325 # temperature, pressure
>>> gas1.TD = 1200, 0.0204723 # temperature, density
>>> gas1.HP = 1.32956e7, 101325 # specific enthalpy, pressure
>>> gas1.UV = 8.34619e6, 1/0.0204723 # specific internal energy, specific volume
>>> gas1.SP = 85227.6, 101325 # specific entropy, pressure
>>> gas1.SV = 85227.6, 1/0.0204723 # specific entropy, specific volume
In each case, the values of the extensive properties must be entered *per unit
mass*.
Properties may be read independently or together::
>>> gas1.T
1200.0
>>> gas1.h
13295567.68
>>> gas1.UV
(8346188.494954427, 48.8465747765848)
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'
Mass and mole fractions can also be set using `dict` objects, for cases where
the composition is stored in a variable or being computed::
>>> phi = 0.8
>>> gas1.X = {'CH4':1, 'O2':2/phi, 'N2':2*3.76/phi}
When the composition alone is changed, the temperature and density are held
constant. This means that the pressure and other intensive properties will
change. The composition can also be set in conjunction with the intensive
properties of the mixture::
>>> gas1.TPX = 1200, 101325, 'CH4:1, O2:2, N2:7.52'
>>> gas1()
results in::
gri30:
temperature 1200 K
pressure 101325 Pa
density 0.280629 kg/m^3
mean mol. weight 27.6332 amu
1 kg 1 kmol
----------- ------------
enthalpy 861943 2.382e+07 J
internal energy 500879 1.384e+07 J
entropy 8914.3 2.463e+05 J/K
Gibbs function -9.83522e+06 -2.718e+08 J
heat capacity c_p 1397.26 3.861e+04 J/K
heat capacity c_v 1096.38 3.03e+04 J/K
X Y Chem. Pot. / RT
------------- ------------ ------------
O2 0.190114 0.220149 -28.7472
CH4 0.095057 0.0551863 -35.961
N2 0.714829 0.724665 -25.6789
[ +50 minor] 0 0
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.
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
same value, do this::
>>> gas1.X = np.ones(53) # NumPy array of 53 ones
Or, to set all the mass fractions to equal values::
>>> gas1.Y = np.ones(53)
When setting the state, you can control what properties are held constant by
passing the special value `None` to the property setter. For example, to
change the specific volume to 2.1 m^3/kg while holding entropy constant::
>>> gas1.SV = None, 2.1
Or to set the mass fractions while holding temperature and pressure constant::
>>> gas1.TPX = None, None, 'CH4:1.0, O2:0.5'
Working with a Subset of Species
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many properties of a `Solution` provide values for each species present in the
phase. If you want to get values only for a subset of these species, you can use
Python's "slicing" syntax to select data for just the species of interest. To
get the mole fractions of just the major species in `gas1`, in the order
specified, you can write:
>>> Xmajor = gas1['CH4','O2','CO2','H2O','N2'].X
If you want to use the same set of species repeatedly, you can keep a reference
to the sliced phase object:
>>> major = gas1['CH4','O2','CO2','H2O','N2']
>>> cp_major = major.partial_molar_cp
>>> wdot_major = major.net_production_rates
The slice object and the original object share the same internal state, so
modifications to one will affect the other.
Working With Mechanism Files
----------------------------
In previous example, we created an object that models an ideal gas mixture
with the species and reactions of GRI-Mech 3.0, using the ``gri30.xml`` input
file included with Cantera. This is a "pre-processed" XML input file written
in a format that is easy for Cantera to parse. Cantera also supports an input
file format that is easier to write, called *CTI*. Several reaction mechanism
files in this format are included with Cantera, including ones that model
high- temperature air, a hydrogen/oxygen reaction mechanism, and a few surface
reaction mechanisms. These files are usually located in the ``data``
subdirectory of the Cantera installation directory, e.g. ``C:\\Program
Files\\Cantera\\data`` on Windows or ``/usr/local/cantera/data/`` on
Unix/Linux/Mac OS X machines, depending on how you installed Cantera and the
options you specified.
If for some reason Cantera has difficulty finding where these files are on your
system, set environment variable ``CANTERA_DATA`` to the directory or
directories (separated using ``;`` on Windows or ``:`` on other operating
systems) where they are located. Alternatively, you can call function
`add_directory` to add a directory to the Cantera search path::
>>> 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.
A Cantera input file may contain more than one phase specification, or may
contain specifications of interfaces (surfaces). Here we import definitions of
two bulk phases and the interface between them from file ``diamond.cti``::
>>> gas2 = ct.Solution('diamond.cti', 'gas')
>>> diamond = ct.Solution('diamond.cti', 'diamond')
>>> diamond_surf = ct.Interface('diamond.cti' , 'diamond_100',
[gas2, diamond])
Note that the bulk (i.e., 3D or homogeneous) phases that participate in the
surface reactions must also be passed as arguments to `Interface`.
Converting CK-format files
~~~~~~~~~~~~~~~~~~~~~~~~~~
See :ref:`sec-ck-format-conversion` in the :ref:`sec-input-files` documentation.
Getting Help
------------
In addition to the Sphinx-generated :ref:`sec-cython-documentation`,
documentation of the Python classes and their methods can be accessed from
within the Python interpreter as well.
Suppose you have created a Cantera object and want to know what methods are
available for it, and get help on using the methods::
>>> g = ct.Solution('gri30.xml')
To get help on the Python class that this object is an instance of::
>>> help(g)
For a simple list of the properties and methods of this object::
>>> dir(g)
To get help on a specific method, e.g. the ``species_index`` method::
>>> help(g.species_index)
For properties, getting the documentation is slightly trickier, as the usual
method will give you the help for the *result*, e.g.::
>>> help(g.T)
will provide help on Python's ``float`` class. To get the help for the
temperature property, ask for the attribute of the class object itself::
>>> help(g.__class__.T)
If you are using the IPython shell, help can also be obtained using the `?`
syntax::
In[1]: g.species_index?
Chemical Equilibrium
--------------------
To set a gas mixture to a state of chemical equilibrium, use the equilibrate
method::
>>> import cantera as ct
>>> g = ct.Solution('gri30.xml')
>>> 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
equilibrium holding temperature and pressure fixed. Alternatively, the
specific enthalpy and pressure can be held fixed::
>>> g.TPX = 300.0, ct.one_atm, 'CH4:0.95,O2:2,N2:7.52'
>>> g.equilibrate('HP')
Other options are:
- 'UV' fixed specific internal energy and specific volume
- '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
state? One way is verify that the net rates of progress of all reversible
reactions are zero. Here is the code to do this:
>>> g.TPX = 300.0, ct.one_atm, 'CH4:0.95,O2:2,N2:7.52'
>>> g.equilibrate('HP')
>>> rf = g.forward_rates_of_progress
>>> rr = g.reverse_rates_of_progress
>>> for i in range(g.n_reactions):
>>> if g.is_reversible(i) and rf[i] != 0.0:
>>> print(' %4i %10.4g ' % (i, (rf[i] - rr[i])/rf[i]))
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
an element potential method. The element potential method is one of a class of
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*
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
information on the various algorithms and their characteristics.
Cantera uses a damped Newton method to solve these equations, and does a few
other things to generate a good starting guess and to produce a reasonably
robust algorithm. If you want to know more about the details, look at the on-
line documented source code of Cantera C++ class 'ChemEquil.h'.
Chemical Kinetics
-----------------
`Solution` objects are also `Kinetics` objects, and provide all of the methods
necessary to compute the thermodynamic quantities associated with each reaction,
reaction rates, and species creation and destruction rates. They also provide
methods to inspect the quantities that define each reaction such as the rate
constants and the stoichiometric coefficients. The rate calculation functions
are used extensively within Cantera's :ref:`reactor network model
<sec-cython-zerodim>` and :ref:`1D flame model <sec-cython-onedim>`.
Information about individual reactions that is independent of the thermodynamic
state can be obtained by accessing `Reaction` objects with the
`Kinetics.reaction` method::
>>> g = ct.Solution('gri30.cti')
>>> r = g.reaction(2) # get a Reaction object
>>> r
<ElementaryReaction: H2 + O <=> H + OH>
>>> r.reactants
{'H2': 1.0, 'O': 1.0}
>>> r.products
{'H': 1.0, 'OH': 1.0}
>>> r.rate
Arrhenius(A=38.7, b=2.7, E=2.61918e+07)
If we are interested in only certain types of reactions, we can use this
information to filter the full list of reactions to find the just the ones of
interest. For example, here we find the indices of just those reactions which
convert `CO` into `CO2`::
>>> II = [i for i,r in enumerate(g.reactions())
if 'CO' in r.reactants and 'CO2' in r.products]
>>> for i in II:
... print(g.reaction(i).equation)
CO + O (+M) <=> CO2 (+M)
CO + O2 <=> CO2 + O
CO + OH <=> CO2 + H
CO + HO2 <=> CO2 + OH
(Actually, we should also include reactions where the reaction is written such
that ``CO2`` is a reactant and ``CO`` is a product, but for this example, we'll
just stick to this smaller set of reactions.) Now, let's set the composition to
an interesting equilibrium state::
>>> g.TPX = 300, 101325, {'CH4':0.6, 'O2':1.0, 'N2':3.76}
>>> g.equilibrate('HP')
We can verify that this is an equilibrium state by seeing that the net reaction
rates are essentially zero::
>>> g.net_rates_of_progress[II]
array([ 4.06576e-20, -5.50571e-21, 0.00000e+00, -4.91279e-20])
Now, let's see what happens if we decrease the temperature of the mixture::
>>> g.TP = g.T-100, None
>>> g.net_rates_of_progress[II]
array([ 3.18645e-05, 5.00490e-08, 1.05965e-01, 2.89503e-06])
All of the reaction rates are positive, favoring the formation of ``CO2`` from
``CO``, with the third reaction, ``CO + OH <=> CO2 + H`` proceeding the fastest.
If we look at the enthalpy change associated with each of these reactions::
>>> g.delta_enthalpy[II]
array([ -5.33035e+08, -2.23249e+07, -8.76650e+07, -2.49170e+08])
we see that the change is negative in each case, indicating a net release of
thermal energy. The total heat release rate can be computed either from the
reaction rates::
>>> np.dot(g.net_rates_of_progress, g.delta_enthalpy)
-58013370.720881931
or from the species production rates::
>>> np.dot(g.net_production_rates, g.partial_molar_enthalpies)
-58013370.720881805
The contribution from just the selected reactions is:
>>> np.dot(g.net_rates_of_progress[II], g.delta_enthalpy[II])
-9307123.2625651453
Or about 16% of the total heat release rate.

114
doc/sphinx/faq.rst
View file

@ -1,114 +0,0 @@
**************************
Frequently Asked Questions
**************************
Installation & Compilation
--------------------------
**How do I install Cantera?**
Please see the instructions in the :ref:`sec-install` section.
**What do I do if compiling Cantera fails?**
- Examine the output of the ``scons build`` command, especially anything
identified as a ``WARNING`` or ``ERROR``. Check for discrepancies
with your expected configuration (e.g. not finding SUNDIALS even though
you have it installed).
- Check the contents of ``cantera.conf`` to make sure they are correct.
- If any of the configuration tests (``Checking for...``) fail unexpectedly,
look at the contents of ``config.log`` to determine the reason.
- If none of these help identify the cause of the failure, consider asking
for help on the Cantera Users' Group. If you decide to make a post, please
include the following information:
* The contents of ``cantera.conf`` and ``config.log``
* The output of the ``scons build`` and ``scons build dump`` commands
(you can direct this output to a file by running ``scons build >buildlog.txt 2>&1``)
* The exact version of Cantera you are trying to compile, and how it was
obtained (i.e. downloaded source tarball or the specific Git commit)
* Your operating system, compiler versions, and the versions of any other
relevant software.
**How do I debug issues with the SCons build system?**
Sometimes, it is helpful to see all of the internal variables defined by
SCons, either automatically or by the Cantera build scripts. To do this, add
``dump`` to your SCons command line. For example::
$ scons build dump
will show the variables that would be set during the ``build`` step. Note
that in this case, the ``build`` step will not be executed.
Alternatively, it is also possible to run SCons through the Python debugger, and set a breakpoint in the ``SConstruct`` file. For example::
$ scons --debug=pdb build
(Pdb) b /full/path/to/SConstruct:33
(Pdb) cont
General
-------
**Which Cantera interface should I use?**
If you're new to Cantera, the best interface to get started with is
probably the Python interface. It offers most of the features of the
C++ core in a much more flexible environment. Since all of the
calculations are still done in C++, there is very little performance
penalty to using the high-level language interfaces.
**Where can I find examples of how to use Cantera?**
Examples of how to use Cantera are available in our online documentation.
For Python, visit the :ref:`sec-cython-examples` or the Jupyter Notebook
examples on `GitHub <https://github.com/Cantera/cantera-jupyter>`_. For
Matlab visit the :ref:`sec-matlab-examples`, and for a simple C++ example
see :ref:`sec-cxx-simple-example`.
In addition, Cantera is distributed with many examples for the Python and Matlab
interfaces, and a smaller number of examples for the C++ and Fortran
interfaces. The Matlab, C++, and Fortran examples should be
installed in the ``samples`` subdirectory of the Cantera installation
directory, or they can be found in the ``samples`` subdirectory of the
Cantera source directory.
Examples for the Python interface can be found in the ``examples``
subdirectory of the Cantera Python module installation directory, or in
the ``interfaces/cython/cantera/examples`` subdirectory of the Cantera
source directory.
Support and Bug Reporting
-------------------------
**What should I do if I think I've found a bug in Cantera?**
- Check to see if you're using the most recent version of Cantera, and
upgrade if not.
- Check the `Issue Tracker
<https://github.com/Cantera/cantera/issues>`_ to see if the issue
has already been reported.
- Try to generate a `minimal, complete, and verifiable example
<http://stackoverflow.com/help/mcve>`_ that demonstrates the observed bug.
- Create a new issue on the tracker. Include as much information as
possible about your system configuration (operating system, compiler
versions, Python versions, installation method, etc.)
**What information should I include in my bug report?**
- The version of Cantera are you using, and how you installed it
- 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
- The necessary *input* to generate the reported behavior
- The full text of any error message you receive
**What should I do if I need help using Cantera?**
You can join the `Cantera Users' Group
<https://groups.google.com/forum/#!forum/cantera-users>`_ on Google
Groups and ask a question there. Please use the search feature before
posting to see if your question has been answered before. This group is
moderated, so it may take some time for your posts to appear if you are a
new member.

213
doc/sphinx/flames.rst
View file

@ -1,213 +0,0 @@
.. default-role:: math
.. py:currentmodule:: cantera
**********************
One-Dimensional Flames
**********************
Cantera includes a set of models for representing steady-state, quasi-one-
dimensional reacting flows, which can be used to simulate a number of common
flames, such as:
- freely-propagating premixed laminar flames
- burner-stabilized premixed flames
- counterflow diffusion flames
- counterflow (strained) premixed flames
Additional capabilities include simulation of surface reactions, which can be
used to represent processes such as combustion on a catalytic surface or
chemical vapor deposition processes.
All of these configurations are simulated using a common set of governing
equations within a 1D "flow" domain, with the differences between the models
being represented by differences in the boundary conditions applied. Here, we
describe the governing equations and the various boundary conditions which can
be applied.
Stagnation Flow Governing Equations
===================================
Cantera models flames which are stabilized in an axisymmetric stagnation flow,
and computes the solution along the stagnation streamline (`r=0`), using a
similarity solution to reduce the three-dimensional governing equations to a
single dimension.
The governing equations for a steady axisymmetric stagnation flow follow those
derived in Section 6.2 of [KCG2003]_:
*Continuity*:
.. math::
\frac{\partial\rho u}{\partial z} + 2 \rho V = 0
*Radial momentum*:
.. math::
\rho u \frac{\partial V}{\partial z} + \rho V^2 =
- \Lambda
+ \frac{\partial}{\partial z}\left(\mu \frac{\partial V}{\partial z}\right)
*Energy*:
.. math::
\rho c_p u \frac{\partial T}{\partial z} =
\frac{\partial}{\partial z}\left(\lambda \frac{\partial T}{\partial z}\right)
- \sum_k j_k c_{p,k} \frac{\partial T}{\partial z}
- \sum_k h_k W_k \dot{\omega}_k
*Species*:
.. math::
\rho u \frac{\partial Y_k}{\partial z} = - \frac{\partial j_k}{\partial z}
+ W_k \dot{\omega}_k
where `\rho` is the density, `u` is the axial velocity, `v` is the radial
velocity, `V = v/r` is the scaled radial velocity, `\Lambda` is the pressure
eigenvalue (independent of `z`), `\mu` is the dynamic viscosity, `c_p` is the
heat capacity at constant pressure, `T` is the temperature, `\lambda` is the
thermal conductivity, `Y_k` is the mass fraction of species `k`, `j_k` is the
diffusive mass flux of species `k`, `c_{p,k}` is the specific heat capacity of
species `k`, `h_k` is the enthalpy of species `k`, `W_k` is the molecular weight
of species `k`, and `\dot{\omega}_k` is the molar production rate of species
`k`.
The tangential velocity `w` has been assumed to be zero, and the fluid has been
assumed to behave as an ideal gas.
To help in the solution of the discretized problem, it is convenient to write a
differential equation for the scalar `\Lambda`:
.. math::
\frac{d\Lambda}{dz} = 0
Diffusive Fluxes
----------------
The species diffusive mass fluxes `j_k` are computed according to either a
mixture-averaged or multicomponent formulation. If the mixture-averaged
formulation is used, the calculation performed is:
.. math::
j_k^* = \rho \frac{W_k}{\overline{W}} D_{km}^\prime \frac{\partial X_k}{\partial z}
j_k = j_k^* - Y_k \sum_i j_i^*
where `\overline{W}` is the mean molecular weight of the mixture, `D_{km}^\prime` is the
mixture-averaged diffusion coefficient for species `k`, and `X_k` is the mole
fraction for species `k`. The diffusion coefficients used here are those
computed by the method :ct:`GasTransport::getMixDiffCoeffs`. The correction
applied by the second equation ensures that the sum of the mass fluxes is zero,
a condition which is not inherently guaranteed by the mixture-averaged
formulation.
When using the multicomponent formulation, the mass fluxes are computed
according to:
.. math::
j_k = \frac{\rho W_k}{\overline{W}^2} \sum_i W_i D_{ki} \frac{\partial X_i}{\partial z}
- \frac{D_k^T}{T} \frac{\partial T}{\partial z}
where `D_{ki}` is the multicomponent diffusion coefficient and `D_k^T` is the
Soret diffusion coefficient (used only if calculation of this term is
specifically enabled).
Boundary Conditions
===================
Inlet boundary
--------------
For a boundary located at a point `z_0` where there is an inflow, values are
supplied for the temperature `T_0`, the species mass fractions `Y_{k,0}` the
scaled radial velocity `V_0`, and the mass flow rate `\dot{m}_0` (except in the
case of the freely-propagating flame).
The following equations are solved at the point `z = z_0`:
.. math::
T(z_0) = T_0
V(z_0) = V_0
\dot{m}_0 Y_{k,0} - j_k(z_0) - \rho(z_0) u(z_0) Y_k(z_0) = 0
If the mass flow rate is specified, we also solve:
.. math::
\rho(z_0) u(z_0) = \dot{m}_0
Otherwise, we solve:
.. math::
\Lambda(z_0) = 0
Outlet boundary
---------------
For a boundary located at a point `z_0` where there is an outflow, we solve:
.. math::
\Lambda(z_0) = 0
\left.\frac{\partial T}{\partial z}\right|_{z_0} = 0
\left.\frac{\partial Y_k}{\partial z}\right|_{z_0} = 0
V(z_0) = 0
Symmetry boundary
-----------------
For a symmetry boundary located at a point `z_0`, we solve:
.. math::
\rho(z_0) u(z_0) = 0
\left.\frac{\partial V}{\partial z}\right|_{z_0} = 0
\left.\frac{\partial T}{\partial z}\right|_{z_0} = 0
j_k(z_0) = 0
Reacting surface
----------------
For a surface boundary located at a point `z_0` on which reactions may occur,
the temperature `T_0` is specified. We solve:
.. math::
\rho(z_0) u(z_0) = 0
V(z_0) = 0
T(z_0) = T_0
j_k(z_0) + \dot{s}_k W_k = 0
where `\dot{s}_k` is the molar production rate of the gas-phase species `k` on
the surface. In addition, the surface coverages `\theta_i` for each surface
species `i` are computed such that `\dot{s}_i = 0`.
References
==========
.. [KCG2003] Kee, Coltrin, Glarborg: *Chemically Reacting Flow*.
Wiley-Interscience, 2003

26
doc/sphinx/glossary.rst
View file

@ -1,26 +0,0 @@
********
Glossary
********
The following abbreviations are used in Cantera, both in documentation and in
the names of variables and classes:
* **CK**: Chemkin
* **CT**: Cantera
* **CTI**: Cantera input
* **CTML**: Cantera markup language
* **HKFT**: Helgeson-Kirkham-Flowers-Tanger
* **HMW**: Harvie, Møller, and Weare
* **IAPWS**: International Association for the Properties of Water and Steam
* **MFTP**: Mixture fugacity ThermoPhase
* **PDSS**: Pressure-dependent standard state
* **RT**: Product of the gas constant (R) and the temperature
* **SHE**: Single half-electrode
* **SP**: "Surface Problem"
* **SS**: Standard state
* **SSTP**: SingleSpeciesTP (ThermoPhase)
* **STIT**: SpeciesThermoInterpType
* **VCS**: Villars Cruise Smith
* **VPSS**: Variable pressure standard state
* **VPSSTP**: variable pressure standard state ThermoPhase
* **wrt**: with respect to

457
doc/sphinx/install.rst
View file

@ -1,457 +0,0 @@
.. _sec-install:
******************
Installing Cantera
******************
.. contents::
:local:
:depth: 2
.. _sec-install-conda:
Conda
=====
`Anaconda <https://www.continuum.io/downloads>`_ and `Miniconda
<http://conda.pydata.org/miniconda.html>`_ are Python distributions for which
Cantera is available through the `conda` package manager. Both distributions are
available for Linux, OS X, and Windows. The base Anaconda distribution includes
a large number of Python packages that are widely used in scientific
applications. Miniconda is a minimal distribution, where all of the packages
available in Anaconda can be installed using the package manager. Note that
installing Cantera using conda will only provide the Cantera Python module. If
you want to use the other Cantera interfaces, see the OS-specific installation
options below.
For more details on how to use conda, see the `conda documentation
<http://conda.pydata.org/docs/intro.html>`_.
**Option 1: Create a new environment for Cantera**
If you have just installed Anaconda or Miniconda, the following instructions
will create a conda environment where you can use Cantera. For this example, the
environment is named ``spam``. From the command line, run::
conda create -n spam -c cantera cantera ipython matplotlib
This will create an environment with Cantera, IPython, Matplotlib, and all their
dependencies installed. Although conda can install a large set of packages by
default, it is also possible to install packages such as Cantera that are
maintained independently. These additional channels from which packages may be
obtained are specified by adding the ``-c`` option in the ``install`` or
``create`` commands. In this case, we want to install Cantera from the
``cantera`` channel, so we add ``-c cantera`` and to tell conda to look at the
``cantera`` channel in addition to the default channels.
If you are running Linux or OS X, you can then activate this environment by
running::
source activate spam
If you are running Windows, the equivalent command is::
activate spam
**Option 2: Install Cantera in an existing environment**
First, activate your environment (assumed to be named ``baked_beans``; if you've
forgotten the name of the conda environment you wanted to use, the command
``conda env list`` can help). For Linux and OS X, this is done by running::
source activate baked_beans
For Windows users, the command is::
activate baked_beans
Then, install Cantera by running::
conda install -c cantera cantera
**Option 3: Install the development version of Cantera**
To install a recent development snapshot (i.e. an alpha or beta version) of
Cantera in an existing environment, run::
conda install -c cantera/label/dev cantera
If you later want to revert back to the stable version, first remove and then
reinstall Cantera::
conda remove cantera
conda install -c cantera cantera
.. _sec-install-win:
Windows
=======
Windows installers are provided for stable versions of Cantera. These
installation instructions are for Cantera 2.4.0. Use these installers if you
want to work with a copy of Python downloaded from `Python.org
<https://www.python.org/>`_. If you are using Anaconda / Miniconda, see the
directions :ref:`above <sec-install-conda>`.
1. **Choose your Python version and architecture**
- On Windows, Installers are provided for Python 2.7, Python 3.4, Python 3.5,
and Python 3.6. Python 3.6 is recommended unless you need to use legacy
code that does not work with Python 3. You can install multiple Cantera
Python modules simultaneously. Note that Cantera 2.4 will be the last
version to support Python 2.7.
- Cantera supports both 32- and 64- bit Python installations.
- You need choose the matching Cantera installer for your Python version and
machine architecture.
- The rest of these instructions will refer to your chosen version of Python
as *X.Y*.
- If you are using Matlab, you must use the same architecture for Cantera and
Matlab. Matlab defaults to 64-bit if you are running a 64-bit operating
system.
2. **Install Python**
- Go to `python.org <https://www.python.org/>`_.
- *64-bit*: Download the most recent "Windows X86-64 MSI Installer" for
Python *X.Y*.
- *32-bit*: Download the most recent "Windows x86 MSI Installer" for
Python *X.Y*.
- Run the installer. The default installation options should be fine.
- Python is required in order to work with `.cti` input files even if you are
not using the Python interface to Cantera.
- Cantera can also be used with alternative Python distributions such as the
Enthought `Canopy <https://www.enthought.com/products/canopy/>`_
distribution. These distributions will generally be based on the 64-bit
version of Python 2.7, and will include Numpy as well as many other
packages useful for scientific users.
3. **Install the Visual C++ Redistributable for Visual Studio 2015**
- If you are using Python 3.5 or Python 3.6 you can skip this step as this
will have already been installed when you installed Python.
- Go to the `Microsoft Visual C++ Redistributable Download Page
<https://www.microsoft.com/en-us/download/details.aspx?id=48145>`_.
- *64-bit*: Download ``vc_redist.x64.exe``
- *32-bit*: Download ``vc_redist.x86.exe``
- Run the installer.
- If this package is not installed, you will encounter the following error
when importing the `cantera` module::
ImportError: DLL load failed: The specified module could not be found.
4. **Install Numpy and optional Python packages**
- Go to the `Unofficial Windows Binaries for Python Extension Packages page
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy>`_.
- Download the most recent release (distributed as a "wheel" archive) of the
1.x series for Python *X.Y* that matches your Python architecture. In the
filename, the digits after "cp" indicate the Python version, e.g.
``numpy‑1.11.2+mkl‑cp35‑none‑win_amd64.whl`` is the installer for 64-bit
Python 3.5. The Windows installers for Cantera 2.4.0 require Numpy 1.10 or
newer.
- From an administrative command prompt, install the downloaded wheel using
pip, e.g.::
c:\python35\scripts\pip.exe install "%USERPROFILE%\Downloads\numpy‑1.11.2+mkl‑cp35‑none‑win_amd64.whl"
- If you plan on using Cantera from Python, you may also want to install
IPython (an advanced interactive Python interpreter) and Matplotlib (a
plotting library), which are also available from the above link (note that
you may also need to download additional dependencies for each of these
packages). Matplotlib is required to run some of the Python examples.
5. **Remove old versions of Cantera**
- Use The Windows "Add/Remove Programs" interface
- Remove both the main Cantera package and the Python module.
- The Python module will be listed as "Python *X.Y* Cantera ..."
6. **Install Cantera**
- Go to the `Cantera Releases <https://github.com/Cantera/cantera/releases>`_
page.
- *64-bit*: Download **Cantera-2.4.0-x64.msi** and
**Cantera-Python-2.4.0-x64-pyX.Y.msi**.
- *32-bit*: Download **Cantera-2.4.0-x86.msi** and
**Cantera-Python-2.4.0-x86-pyX.Y.msi**.
- If you are only using the Python module, you do not need to download and
install the base package.
- Run the installer(s).
7. **Configure Matlab** (optional)
- Set the environment variable ``PYTHON_CMD``
- From the *Start* menu (Windows 7) or the *Start* screen (Windows 8) type
"edit environment" and select "Edit environment variables for your
account".
- Add a *New* variable with ``PYTHON_CMD`` as the *name* and the full path
to the Python executable (e.g. ``C:\python35\python.exe``) as the
*value*.
- Setting ``PYTHON_CMD`` is not necessary if the path to ``python.exe`` is
in your ``PATH`` (which can be set from the same configuration dialog).
- Launch Matlab
- Go to *File->Set Path...*
- Select *Add with Subfolders*
- Browse to the folder ``C:\Program Files\Cantera\matlab\toolbox``
- Select *Save*, then *Close*.
8. **Test the installation**
- Python::
import cantera
gas = cantera.Solution('gri30.cti')
h2o = cantera.PureFluid('liquidvapor.cti', 'water')
- Matlab::
gas = IdealGasMix('gri30.cti')
h2o = Solution('liquidvapor.cti','water')
.. _sec-install-osx:
Mac OS X
========
Cantera can be installed on OS X using either Homebrew or Anaconda /
Miniconda. If you are using Anaconda / Miniconda, see the directions
:ref:`above <sec-install-conda>`. With Homebrew, the current stable, or
development version of Cantera can be installed, and both the Python 2.7 and
Python 3.x modules are available, as well as the Matlab toolbox.
Homebrew
---------
These instructions have been tested on Mac OS X 10.9 (Mavericks) with Xcode 5.1
and Mac OS X 10.10 (Yosemite) with Xcode 6.1. If you've used Homebrew before,
you can skip any steps which have already been completed.
1. **Install Xcode and Homebrew**
- Install Xcode from the App Store
- From a Terminal, run::
sudo xcode-select --install
sudo xcodebuild -license
and agree to the Xcode license agreement.
- Install `Homebrew <http://brew.sh/>`_ by running the following command in a
Terminal::
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
2. **Set up the compilation environment**
- Run the following commands::
brew tap homebrew/science
brew update
brew install python scons
- Verify that your path is set up to use Homebrew's version of Python by
running::
which python
If this command does not print ``/usr/local/bin/python``, add the following
to ``~/.bash_profile`` (creating this file if it doesn't already exist; you
can use the command line editor ``nano`` to edit this file)::
export PATH=/usr/local/bin:$PATH
and then run::
source ~/.bash_profile
- Install Python packages required to compile Cantera by running::
pip install numpy
Note that these packages are required even if you do not plan on using the
Cantera Python 2 module.
- If you plan on using Cantera from Python, you may also want to install
IPython (an advanced interactive Python interpreter) and Matplotlib (a
plotting library). Matplotlib is required to run some of the Python
examples::
pip install ipython matplotlib
- If you want to build the Cantera Python 3 module, run::
brew install python3
pip3 install numpy cython
and, optionally::
pip3 install ipython matplotlib
3. **Compile and install Cantera**
* To compile and install Cantera using the default configuration, run::
brew install cantera
* The following options are supported:
``--HEAD``
Installs the current development version of Cantera.
``--with-python3``
Install the Python 3 module.
``--with-matlab=/Applications/MATLAB_R2014a.app/``
Installs the Matlab toolbox (with the path modified to match your
installed Matlab version)
``--without-sundials``
Do not use an external SUNDIALS version to build Cantera. This option
is set automatically when using Matlab.
``--without-test``
NOT RECOMMENDED! Disable automatic testing of Cantera during the
installation process.
* These options are specified as additional arguments to the ``brew install``
command, e.g.::
brew install cantera --HEAD --with-python3
* If you are installing the Matlab toolbox, the recommended command is::
brew install cantera --with-matlab=/Applications/MATLAB_R2014a.app/
* If something goes wrong with the Homebrew install, re-run the command with
the ``-v`` flag to get more verbose output that may help identify the
source of the problem::
brew install -v cantera
* If Homebrew claims that it can't find a formula named ``cantera``, you may
be able to fix it by running the commands::
brew doctor
brew tap --repair
4. **Test Cantera Installation (Python)**
* The Python examples will be installed in::
/usr/local/lib/pythonX.Y/site-packages/cantera/examples/
where ``X.Y`` is your Python version, e.g. ``2.7``.
* You may find it convenient to copy the examples to your Desktop::
cp -r /usr/local/lib/python2.7/site-packages/cantera/examples ~/Desktop/cantera_examples
* To run an example::
cd cantera_examples/reactors
python reactor1.py
5. **Test Cantera Installation (Matlab)**
* The Matlab toolbox, if enabled, will be installed in::
/usr/local/lib/cantera/matlab
* To use the Cantera Matlab toolbox, run the following commands in Matlab
(each time you start Matlab), or add them to a ``startup.m`` file located
in ``/Users/$USER/Documents/MATLAB``, where ``$USER`` is your username::
addpath(genpath('/usr/local/lib/cantera/matlab'))
setenv('PYTHON_CMD', '/usr/local/bin/python')
* The Matlab examples will be installed in::
/usr/local/share/cantera/samples/matlab
* You may find it convenient to copy the examples to your user directory::
cp -r /usr/local/share/cantera/samples/matlab ~/Documents/MATLAB/cantera_examples
.. _sec-install-ubuntu:
Ubuntu
======
Ubuntu packages are provided for recent versions of Ubuntu using a Personal
Package Archive (PPA). As of Cantera 2.4.0, packages are available for Ubuntu
Ubuntu 16.04 (Xenial Xerus) and Ubuntu 17.10 (Artful Aardvark). To see which
Ubuntu releases and Cantera versions are currently available, visit
https://launchpad.net/~speth/+archive/ubuntu/cantera
The available packages are:
- ``cantera-python`` - The Cantera Python module for Python 2.
- ``cantera-python3`` - The Cantera Python module for Python 3.
- ``cantera-dev`` - Libraries and header files for compiling your own C++ and
Fortran 90 programs that use Cantera.
To add the Cantera PPA::
sudo aptitude install python-software-properties
sudo apt-add-repository ppa:speth/cantera
sudo aptitude update
To install all of the Cantera packages::
sudo aptitude install cantera-python cantera-python3 cantera-dev
or install whichever subset you need by adjusting the above command.
If you plan on using Cantera from Python, you may also want to install IPython
(an advanced interactive Python interpreter) and Matplotlib (a plotting
library), which are also available from the above link. Matplotlib is required
to run some of the Python examples. For Python 2, these packages can be
installed with::
pip2 install ipython matplotlib
And for Python 3, these packages can be installed with::
pip3 install ipython matplotlib
You may need to install ``pip`` first; instructions can be found on the
`pip installation instructions.
<https://pip.pypa.io/en/latest/installing.html#install-pip>`_
You may need to have superuser access to install packages into the system
directories. Alternatively, you can add ``--user`` after ``pip install`` but
before the package names to install into your local user directory. An
alternative method is to use the Ubuntu repositories, but these tend to
be very out of date. For Python 2, the command is::
sudo aptitude install ipython python-matplotlib
And for Python 3, these packages can be installed with::
sudo aptitude install ipython3 python3-matplotlib

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

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

1
doc/sphinx/matlab/index.rst
View file

@ -6,7 +6,6 @@ Matlab Interface User's Guide
.. toctree::
:maxdepth: 2
input-tutorial
importing
thermodynamics
kinetics

62
doc/sphinx/matlab/input-tutorial.rst
View file

@ -1,62 +0,0 @@
**********************************
Tutorial: Working with input files
**********************************
.. highlight:: matlab
CTI files
---------
This is the typical way to create a Cantera "phase" object in Matlab::
gas1 = Solution('gri30.cti', 'gri30');
This statement constructs a ``Solution`` object representing a phase of matter by
reading in attributes of the phase from a file, which in this case is
``gri30.cti``. This file contains several phase specifications; the one we want
here is ``gri30``, which is specified by the second argument. This file contains
a complete specification of the GRI-Mech 3.0 reaction mechanism, including
element data (name, atomic weight), species data (name, elemental composition,
coefficients to compute thermodynamic and transport properties), and reaction
data (stoichiometry, rate coefficient parameters). The file is written in a
format understood by Cantera, which is described in :ref:`sec-defining-phases`.
CTI files distributed with Cantera
----------------------------------
Several reaction mechanism files in this format are included in the Cantera
distribution, including ones that model high-temperature air, a hydrogen/oxygen
reaction mechanism, and a few surface reaction mechanisms. These files are kept
in the ``data`` subdirectory within the Cantera installation directory.
If for some reason Cantera has difficulty finding where these files are on your
system, set environment variable ``CANTERA_DATA`` to the directory or
directories (separated using ``;`` on Windows or ``:`` on other operating
systems) where they are located. Alternatively, you can call function
`add_directory` to add a directory to the Cantera search path::
addDirectory('/usr/local/cantera/my_data_files');
Cantera input files are plain text files, and can be created with any text
editor. See :ref:`sec-defining-phases` for more information.
Importing multiple phases or interfaces
---------------------------------------
A Cantera input file may contain more than one phase specification, or may
contain specifications of interfaces (surfaces). Here we import definitions of
two bulk phases and the interface between them from file ``diamond.cti``::
gas2 = Solution('diamond.cti', 'gas'); % a gas
diamond = Solution('diamond.cti', 'diamond'); % bulk diamond
diamond_surf = importInterface('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 importInterface.
Converting CK-format files
--------------------------
See :ref:`sec-ck-format-conversion` in the :ref:`sec-input-files` documentation.

12
doc/sphinx/old-docs.rst
View file

@ -1,12 +0,0 @@
************************
Historical Documentation
************************
For reference purposes, documentation for previous versions of Cantera is
maintained online. Please note that these versions of Cantera are obsolete,
and users are strongly encouraged to migrate to the current version of Cantera.
* `Cantera 2.3.0 <https://cantera.org/docs-2.3/sphinx/html/index.html>`_
* `Cantera 2.2.1 <https://cantera.org/docs-2.2/sphinx/html/index.html>`_
* `Cantera 2.1.2 <https://cantera.org/docs-2.1/sphinx/html/index.html>`_
* `Cantera 2.0.2 <https://cantera.org/docs-2.0/sphinx/html/index.html>`_

625
doc/sphinx/reactors.rst
View file

@ -1,625 +0,0 @@
.. default-role:: math
.. py:currentmodule:: cantera
*****************************
Reactors and Reactor Networks
*****************************
A Cantera Reactor represents the simplest form of a chemically reacting system.
It corresponds to an extensive thermodynamic control volume `V`, in which all
state variables are homogeneously distributed. The system is generally unsteady,
i.e. all states are functions of time. In particular, transient state changes
due to chemical reactions are possible. However, thermodynamic (but not
chemical) equilibrium is assumed to be present throughout the reactor at all
instants of time.
Reactors can interact with the surrounding environment in multiple ways:
- Expansion/compression work: By moving the walls of the reactor, its volume can
be changed and expansion or compression work can be done by or on the system,
i.e., the Reactor.
- Heat transfer: An arbitrary heat transfer rate can be defined to cross the
boundaries of the reactor.
- Mass transfer: The reactor can have multiple inlets and outlets. For the
inlets, arbitrary states can be defined. Through the outlets, fluid with the
current state of the reactor exits the reactor.
- Surface interaction: One or multiple walls can influence the chemical
reactions in the reactor. This is not just restricted to catalytic reactions,
but mass transfer between the surface and the fluid can also be modeled.
All of these interactions do not have to be constant, but can vary as a function
of time or state. For example, heat transfer can be described as a function of
the temperature difference between the reactor and the environment, or the wall
movement can be modeled depending on the pressure difference. Typically,
interactions of the reactor with the environment are defined on one or multiple
*walls*, *inlets*, and *outlets*.
In addition to single reactors, Cantera is also able to interconnect reactors
into a *Reactor Network*. Each reactor in a network may be connected so that
the contents of one reactor flow into another. Reactors may also be in contact
with one another or the environment via walls which move or conduct heat.
Governing Equations for Single Reactors
=======================================
The state variables for Cantera's general reactor model are
- `m`, the mass of the reactor's contents (in kg)
- `V`, the reactor volume (in m\ :sup:`3`) (not a state variable for
*Constant Pressure Reactor* and *Ideal Gas Constant Pressure Reactor*)
- A state variable describing the energy of the system, depending on the
configuration (see `Energy Conservation`_ for further explanation):
- General *Reactor*: `U`, the total internal energy of the reactors
contents (in J)
- *Constant Pressure Reactor*: `H`, the total enthalpy of the reactors
contents (in J)
- *Ideal Gas Reactor* and *Ideal Gas Constant Pressure Reactor*: `T`, the
temperature (in K)
- `Y_k`, the mass fractions for each species (dimensionless)
Mass Conservation
-----------------
The total mass of the reactor's contents changes as a result of flow through
the reactor's inlets and outlets, and production of homogeneous phase species
on the reactor walls:
.. math::
\frac{dm}{dt} = \sum_{in} \dot{m}_{in} - \sum_{out} \dot{m}_{out} +
\dot{m}_{wall}
Species Conservation
--------------------
The rate at which species `k` is generated through homogeneous phase reactions
is `V \dot{\omega}_k W_k`, and the total rate at which species `k` is generated
is:
.. math::
\dot{m}_{k,gen} = V \dot{\omega}_k W_k + \dot{m}_{k,wall}
The rate of change in the mass of each species is:
.. math::
\frac{d(mY_k)}{dt} = \sum_{in} \dot{m}_{in} Y_{k,in} -
\sum_{out} \dot{m}_{out} Y_k +
\dot{m}_{k,gen}
Expanding the derivative on the left hand side and substituting the equation
for `dm/dt`, the equation for each homogeneous phase species is:
.. math::
m \frac{dY_k}{dt} = \sum_{in} \dot{m}_{in} (Y_{k,in} - Y_k)+
\dot{m}_{k,gen} - Y_k \dot{m}_{wall}
Reactor Volume
--------------
The reactor volume changes as a function of time due to the motion of one or
more walls:
.. math::
\frac{dV}{dt} = \sum_w f_w A_w v_w(t)
where `f_w = \pm 1` indicates the facing of the wall, `A_w` is the surface
area of the wall, and `v_w(t)` is the velocity of the wall as a function of
time.
For *Constant Pressure Reactor* and *Ideal Gas Constant Pressure Reactor*, the
volume is not a state variable, but instead takes on whatever value is
consistent with holding the pressure constant.
Energy Conservation
-------------------
The solution of the energy equation can be enabled or disabled by changing the
``energy_enabled`` flag. It is enabled by default.
The implemented formulation of the energy equation depends on which reactor
model is used.
Standard Reactor
****************
The equation for the total internal energy is found by writing the first law
for an open system:
.. math::
\frac{dU}{dt} = - p \frac{dV}{dt} - \dot{Q} +
\sum_{in} \dot{m}_{in} h_{in} - h \sum_{out} \dot{m}_{out}
Constant Pressure Reactor
*************************
For this reactor model, the pressure is held constant. The volume is not a
state variable, but instead takes on whatever value is consistent with holding
the pressure constant. The total enthalpy replaces the total internal energy
as a state variable. Using the definition of the total enthalpy:
.. math::
H = U + pV
\frac{d H}{d t} = \frac{d U}{d t} + p \frac{dV}{dt} + V \frac{dp}{dt}
Noting that `dp/dt = 0` and substituting into the energy equation yields:
.. math::
\frac{dH}{dt} = - \dot{Q} + \sum_{in} \dot{m}_{in} h_{in}
- h \sum_{out} \dot{m}_{out}
Ideal Gas Reactor
*****************
In case of the Ideal Gas Reactor Model, the reactor temperature `T` is used
instead of the total internal energy `U` as a state variable. For an ideal gas,
we can rewrite the total internal energy in terms of the mass fractions and
temperature:
.. math::
U = m \sum_k Y_k u_k(T)
\frac{dU}{dt} = u \frac{dm}{dt}
+ m c_v \frac{dT}{dt}
+ m \sum_k u_k \frac{dY_k}{dt}
Substituting the corresponding derivatives yields an equation for the
temperature:
.. math::
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)
- \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
derivatives of the species equations are taken at constant temperature instead
of constant internal energy.
Ideal Gas Constant Pressure Reactor
***********************************
As for the Ideal Gas Reactors, we replace the total enthalpy as a state
variable with the temperature by writing the total enthalpy in terms of the
mass fractions and temperature:
.. math::
H = m \sum_k Y_k h_k(T)
\frac{dH}{dt} = h \frac{dm}{dt} + m c_p \frac{dT}{dt}
+ m \sum_k h_k \frac{dY_k}{dt}
Substituting the corresponding derivatives yields an equation for the
temperature:
.. math::
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)
Wall Interactions
-----------------
The total rate of heat transfer through all walls is:
.. math::
\dot{Q} = \sum_w f_w \dot{Q}_w
where `f_w = \pm 1` indicates the facing of the wall (+1 for the reactor on the
left, -1 for the reactor on the right). The heat flux `\dot{Q}_w` through a wall
`k` connecting reactors "left" and "right" is computed as:
.. math::
\dot{Q}_w = U A (T_{\rm left} - T_{\rm right})
+ \epsilon\sigma A (T_{\rm left}^4 - T_{\rm right}^4)
+ A q_0(t)
where `U` is a user-specified heat transfer coefficient (W/m^2-K), `A` is the
wall area (m^2), `\epsilon` is the user-specified emissivity, `\sigma` is the
Stefan-Boltzmann radiation constant, and `q_0(t)` is a user-specified,
time-dependent heat flux (W/m^2). This definition is such that positive `q_0(t)`
implies heat transfer from the "left" reactor to the "right" reactor. Each of
the user-specified terms defaults to 0.
In case of surface reactions, there can be a net generation (or destruction) of
homogeneous (gas) phase species at the wall. The molar rate of production for
each homogeneous phase species `k` on wall `w` is `\dot{s}_{k,w}` (in
kmol/s/m^2). The total (mass) production rate for homogeneous phase species `k`
on all walls is:
.. math::
\dot{m}_{k,wall} = W_k \sum_w A_w \dot{s}_{k,w}
where `W_k` is the molecular weight of species `k` and `A_w` is the area of
each wall. The net mass flux from all walls is then:
.. math::
\dot{m}_{wall} = \sum_k \dot{m}_{k,wall}
For each surface species `i`, the rate of change of the site fraction
`\theta_{i,w}` on each wall `w` is integrated with time:
.. math::
\frac{d\theta_{i,w}}{dt} = \frac{\dot{s}_{i,w} n_i}{\Gamma_w}
where `\Gamma_w` is the total surface site density on wall `w` and `n_i` is the
number of surface sites occupied by a molecule of species `i` (sometimes
referred to within Cantera as the molecule's "size").
Reactor Networks and Devices
============================
While reactors by themselves just define the above governing equations of the
reactor, the time integration is performed in reactor networks. A reactor
network is therefore necessary even if only a single reactor is considered.
The advantage of reactor networks obviously is that multiple reactors can be
interconnected. Not only mass flow from one reactor into another can be
realized, but also heat can be transferred, or the wall between reactors can
move. To set up a network, the following components can be defined in addition
to the reactors previously mentioned:
- **Reservoir**: A reservoir can be thought of as an infinitely large volume, in
which all states are predefined and never change from their initial values.
Typically, it represents a vessel to define temperature and composition of a
stream of mass flowing into a reactor, or the ambient fluid surrounding the
reactor network. Besides, the fluid flow finally finally exiting a reactor
network has to flow into a reservoir. In the latter case, the state of the
reservoir (except pressure) is irrelevant.
- **Wall**: A wall separates two reactors, or a reactor and a reservoir. A wall
has a finite area, may conduct or radiate heat between the two reactors on
either side, and may move like a piston.
Walls are stateless objects in Cantera, meaning that no differential equation
is integrated to determine any wall property. Since it is the wall (piston)
velocity that enters the energy equation, this means that it is the velocity,
not the acceleration or displacement, that is specified. The wall velocity is
computed from
.. math:: v = K(P_{\rm left} - P_{\rm right}) + v_0(t),
where :math:`K` is a non-negative constant, and :math:`v_0(t)` is a specified
function of time. The velocity is positive if the wall is moving to the right.
The heat flux through the wall is computed from
.. math:: q = U(T_{\rm left} - T_{\rm right}) + \epsilon\sigma (T_{\rm left}^4
- T_{\rm right}^4) + q_0(t),
where :math:`U` is the overall heat transfer coefficient for
conduction/convection, and :math:`\epsilon` is the emissivity. The function
:math:`q_0(t)` is a specified function of time. The heat flux is positive when
heat flows from the reactor on the left to the reactor on the right.
A heterogeneous reaction mechanism may be specified for one or both of the
wall surfaces. The mechanism object (typically an instance of class Interface)
must be constructed so that it is properly linked to the object representing
the fluid in the reactor the surface in question faces. The surface
temperature on each side is taken to be equal to the temperature of the
reactor it faces.
Source: `Python <cython/zerodim.html#wall>`_ | :ct:`C++ <Wall>`
- **Valve**: A valve is a flow devices with mass flow rate that is a function of
the pressure drop across it. The default behavior is linear:
.. math:: \dot m = K_v (P_1 - P_2)
if :math:`P_1 > P_2.` Otherwise, :math:`\dot m = 0`. However, an arbitrary
function can also be specified, such that
.. math:: \dot m = F(P_1 - P_2)
if :math:`P_1 > P_2`, or :math:`\dot m = 0` otherwise. It is never possible
for the flow to reverse and go from the downstream to the upstream
reactor/reservoir through a line containing a Valve object.
Valve objects are often used between an upstream reactor and a downstream
reactor or reservoir to maintain them both at nearly the same pressure. By
setting the constant :math:`K_v` to a sufficiently large value, very small
pressure differences will result in flow between the reactors that counteracts
the pressure difference.
- **Mass Flow Controller**: A mass flow controller maintains a specified mass
flow rate independent of upstream and downstream conditions. The equation used
to compute the mass flow rate is
.. math:: \dot m = \max(\dot m_0, 0.0)
where :math:`\dot m_0` is either a constant value or a function of time. Note
that if :math:`\dot m_0 < 0`, the mass flow rate will be set to zero, since
reversal of the flow direction is not allowed.
Unlike a real mass flow controller, a MassFlowController object will maintain
the flow even if the downstream pressure is greater than the upstream
pressure. This allows simple implementation of loops, in which exhaust gas
from a reactor is fed back into it through an inlet. But note that this
capability should be used with caution, since no account is taken of the work
required to do this.
- **Pressure Controller**: A pressure controller is designed to be used in
conjunction with another 'master' flow controller, typically a
MassFlowController. The master flow controller is installed on the inlet of
the reactor, and the corresponding PressureController is installed on on
outlet of the reactor. The PressureController mass flow rate is equal to the
master mass flow rate, plus a small correction dependent on the pressure
difference:
.. math:: \dot m = \dot m_{\rm master} + K_v(P_1 - P_2).
Time Integration
----------------
Cantera provides an ODE solver for solving the stiff equations of reacting
systems. If installed in combination with SUNDIALS, their optimized solver is
used. Starting off the current state of the system, it can be advanced in time
by one of the following methods:
- ``step()``: The step method computes the state of the system at the a priori
unspecified time `t_{\rm new}`. The time `t_{\rm new}` is internally computed
so that all states of the system only change within a (specifiable) band of
absolute and relative tolerances. Additionally, the time step must not be
larger than a predefined maximum time step `\Delta t_{\rm max}`. The new time
`t_{\rm new}` is returned by this function.
- ``advance``\ `(t_{\rm new})`: This method computes the state of the system at
time `t_{\rm new}`. `t_{\rm new}` describes the absolute time from the initial
time of the system. By calling this method in a for loop for pre-defined
times, the state of the system is obtained for exactly the times specified.
Internally, several ``step()`` calls are typically performed to reach the
accurate state at time `t_{\rm new}`.
- ``advance_to_steady_state(max_steps, residual_threshold, atol,
write_residuals)`` [Python interface only]: If the steady state solution of a
reactor network is of interest, this method can be used. Internally, the
steady state is approached by time stepping. The network is considered to be
at steady state if the feature-scaled residual of the state vector is below a
given threshold value (which by default is 10 times the time step rtol).
The use of the ``advance`` method in a loop has the advantage that it produces
results corresponding to a predefined time series. These are associated with a
predefined memory consumption and well comparable between simulation runs with
different parameters. However, some detail (e.g. a fast ignition process) might
not be resolved in the output data due to the typically large time steps.
The ``step`` method results in much more data points because of the small
timesteps needed. Additionally, the absolute time has to be kept tracked of
manually.
Even though Cantera comes pre-defined with typical parameters for tolerances
and the maximum internal time step, the solution sometimes diverges. To solve
this problem, three parameters can be tuned: The absolute time stepping
tolerances, the relative time stepping tolerances, and the maximum time step. A
reduction of the latter value is particularly useful when dealing with abrupt
changes in the boundary conditions (e.g. opening/closing valves, see also
example :ref:`py-example-ic_engine.py`).
General Usage in Cantera
========================
In Cantera, the following steps are typically necessary to investigate a
reactor network:
1. Define ``Solution`` objects for the fluids to be flowing through your reactor
network.
2. Define the reactor type(s) and reservoir(s) that describe your system. Chose
Ideal Gas (Constant Pressure) Reactor(s) if you only consider ideal gas
phases.
3. *Optional:* Set up the boundary conditions and flow devices between reactors
or reservoirs.
4. Define a reactor network which contains all the reactors previously created.
5. Advance the simulation in time, typically in a for- or while-loop. Note that
only the current state is stored in Cantera by default. If you want to
observe the transient states, you manually have to keep track of them.
6. Analyze the data.
Note that Cantera always solves a transient problem. If you are interested in
steady-state conditions, you can run your simulation for a long time until the
states are converged (see e.g. example :ref:`py-example-surf_pfr.py`,
:ref:`py-example-combustor.py`).
Cantera comes with a broad variety of well-commented example scrips for reactor
networks. Please refer to them for further information (:ref:`Python <sec-cython-examples>`, :ref:`Matlab <sec-matlab-examples>`).
Common Reactor Types and their Implementation in Cantera
========================================================
Batch Reactor at Constant Volume or at Constant Pressure
--------------------------------------------------------
If you are interested in how a homogeneous chemical composition changes in time
when it is left to its own, a simple batch reactor can be used. Two versions
are commonly considered: A rigid vessel with fixed volume but variable
pressure, or a system idealized at constant pressure but varying volume.
In Cantera, such a simulation can be performed very easily. The initial state
of the solution can be specified by composition and a set of thermodynamic
parameters (like temperature and pressure) as a standard Cantera solution
object. Upon its base, a general (Ideal Gas) Reactor or an (Ideal Gas) Constant
Pressure Reactor can be created, depending on if a constant volume or constant
pressure batch reactor should be considered, respectively. The behavior of the
solution in time can be simulated as a very simple Reactor Network containing
only the formerly created reactor.
An example for such a Batch Reactor is :ref:`py-example-reactor1.py`.
Continuously Stirred Tank Reactor
---------------------------------
A Continuously Stirred Tank Reactor (CSTR), also often referred to as
Well-Stirred Reactor (WSR), Perfectly Stirred Reactor (PSR), or Longwell
Reactor, is essentially a single Cantera reactor with an inlet, an outlet, and
constant volume. Therefore, the `Governing Equations for Single Reactors`_
defined above apply accordingly.
Steady state solutions to CSTRs are often of interest. In this case, the mass
flow rate `\dot{m}` is constant and equal at inlet and outlet. The mass
contained in the confinement `m` divided by `\dot{m}` defines the mean
residence time of the fluid in the confinement.
At steady state, the time derivatives in the governing equations become zero,
and the system of ordinary differential equations can be reduced to a set of
coupled nonlinear algebraic equations. A Newton solver could be used to solve
this system of equations. However, a sophisticated implementation might be
required to account for the strong nonlinearities and the presence of multiple
solutions.
Cantera does not have such a Newton solver implemented. Instead, steady CSTRs
are simulated by considering a time-dependent constant volume reactor with
specified in- and outflow conditions. Starting off at an initial solution, the
reactor network containing this reactor is advanced in time until the state of
the solution is converged. An example for this procedure is
:ref:`py-example-combustor.py`.
A problem can be the ignition of a CSTR: If the reactants are not reactive
enough, the simulation can result in the trivial solution that inflow and
outflow states are identical. To solve this problem, the reactor can be
initialized with a high temperature and/or radical concentration. A good
approach is to use the equilibrium composition of the reactants (which can be
computed using Cantera's ``equilibrate`` function) as an initial guess.
Plug-Flow Reactor
-----------------
A Plug-Flow Reactor (PFR) represents a steady-state channel with a
cross-sectional area `A`. Typically an ideal gas flows through it at a constant
mass flow rate `\dot{m}`. Perpendicular to the flow direction, the gas is
considered to be completely homogeneous. In the axial direction `z`, the states
of the gas is allowed to change. However, all diffusion processes are neglected.
Plug-Flow Reactors are often used to simulate ignition delay times, emission
formation, and catalytic processes.
The governing equations of Plug-Flow Reactors are [KCG2003]_:
- Mass conservation:
.. math:: \frac{d(\rho u A)}{dz} = P' \sum_k \dot{s}_k W_k
where `u` is the axial velocity in (m/s) and `P'` is the chemically active
channel perimeter in (m) (chemically active perimeter per unit length).
- Continuity equation of species `k`:
.. math:: \rho u \frac{d Y_k}{dz} + Y_k P' \sum_k \dot{s}_k W_k =
\dot{\omega}_k W_k + P' \dot{s}_k W_k
- Energy conservation:
.. math:: \rho u A c_p \frac{d T}{d z} =
- A \sum_k h_k \dot{\omega}_k W_k
- P' \sum_k h_k \dot{s}_k W_k
+ U P (T_w - T)
where `U` is the heat transfer coefficient in (W/m/K), `P` is the perimeter of
the duct in (m), and `T_w` is the wall temperature in (K). Kinetic and
potential energies are neglected.
- Momentum conservation in the axial direction:
.. math:: \rho u A \frac{d u}{d z} + u P' \sum_k \dot{s}_k W_k =
- \frac{d (p A)}{dz} - \tau_w P
where `\tau_w` is the wall friction coefficient (which might be computed from
Reynolds number based correlations).
Even though this problem extends geometrically in one direction, it can be
modeled via zero-dimensional reactors: Due to the neglecting of diffusion,
downstream parts of the reactor have no influence on upstream parts. Therefore,
PFRs can be modeled by marching from the beginning to the end of the reactor.
Cantera does not (yet) provide dedicated class to solve the PFR equations (The
``FlowReactor`` class is currently under development). However, there are two
ways to simulate a PFR with the reactor elements previously presented. Both
rely on the assumption that pressure is approximately constant throughout the
Plug-Flow Reactor and that there is no friction. The momentum conservation
equation is thus neglected.
PFR Modeling by Considering a Lagrangian Reactor
************************************************
A Plug-Flow Reactor can also be described from a Lagrangian point of view: An
unsteady fluid particle is considered which travels along the axial streamline
through the PFR. Since there is no information traveling upstream, the state
change of the fluid particle can be computed by a forward (upwind) integration
in time. Using the continuity equation, the speed of the particle can be
derived. By integrating the velocity in time, the temporal information can be
translated into the spatial resolution of the PFR.
An example for this procedure can be found in :ref:`py-example-pfr.py`.
PFR Modeling as a Series of CSTRs
*********************************
The Plug-Flow Reactor is spatially discretized into a large number of axially
distributed volumes. These volumes are modeled to be steady-state CSTRs.
The only reason to use this approach as opposed to the Lagrangian one is if you
need to include surface reactions, because the system of equations ends up
being a DAE system instead of an ODE system.
In Cantera, it is sufficient to consider a single reactor and march it forward
in time, because there is no information traveling upstream. The mass flow rate
`\dot{m}` through the PFR enters the reactor from an upstream reservoir. For
the first reactor, the reservoir conditions are the inflow boundary conditions
of the PFR. By performing a time integration as described in `Continuously
Stirred Tank Reactor`_ until the state of the reactor is converged, the
steady-state CSTR solution is computed. The state of the CSTR is the inlet
boundary condition for the next CSTR downstream.
An example for this procedure can be found in :ref:`py-example-pfr.py` and
:ref:`py-example-surf_pfr.py`.
Advanced Concepts
=================
In some cases, Cantera's solver is insufficient to describe a certain
configuration. In this situation, Cantera can still be used to provide chemical
and thermodynamic computations, but external ODE solvers can be applied. See
example :ref:`py-example-custom.py`.
Literature
==========
For further reading, the following books are recommended:
.. [KCG2003] Kee, Coltrin, Glarborg: *Chemically Reacting Flow*.
Wiley-Interscience, 2003
.. [Tur2000] Turns: *An Introduction to Combustion: Concepts and Applications*,
McGraw Hill, 2000