From 3fae1c1a9aaa6c26945d71bcb81be7a9af808697 Mon Sep 17 00:00:00 2001 From: "Bryan W. Weber" Date: Mon, 18 Jun 2018 14:25:29 -0400 Subject: [PATCH] Remove pages moved to the new website --- doc/sphinx/about.rst | 98 --- doc/sphinx/compiling/config-options.rst | 572 ---------------- doc/sphinx/compiling/configure-build.rst | 278 -------- doc/sphinx/compiling/dependencies.rst | 167 ----- doc/sphinx/compiling/index.rst | 19 - doc/sphinx/compiling/installation-reqs.rst | 404 ------------ doc/sphinx/compiling/source-code.rst | 68 -- doc/sphinx/compiling/special-cases.rst | 52 -- doc/sphinx/cti/index.rst | 18 - doc/sphinx/cti/input-files.rst | 716 --------------------- doc/sphinx/cti/intro.rst | 40 -- doc/sphinx/cti/phases.rst | 500 -------------- doc/sphinx/cti/reactions.rst | 557 ---------------- doc/sphinx/cti/species.rst | 340 ---------- doc/sphinx/cxx-guide/compiling.rst | 147 ----- doc/sphinx/cxx-guide/demo1a.cpp | 34 - doc/sphinx/cxx-guide/demo1b.cpp | 66 -- doc/sphinx/cxx-guide/demoequil.cpp | 20 - doc/sphinx/cxx-guide/equil-example.rst | 57 -- doc/sphinx/cxx-guide/factories.rst | 47 -- doc/sphinx/cxx-guide/headers.rst | 41 -- doc/sphinx/cxx-guide/index.rst | 14 - doc/sphinx/cxx-guide/simple-example.rst | 76 --- doc/sphinx/cxx-guide/thermo.rst | 126 ---- doc/sphinx/cxx-guide/thermodemo.cpp | 42 -- doc/sphinx/cython/index.rst | 3 - doc/sphinx/cython/tutorial.rst | 442 ------------- doc/sphinx/faq.rst | 114 ---- doc/sphinx/flames.rst | 213 ------ doc/sphinx/glossary.rst | 26 - doc/sphinx/install.rst | 457 ------------- doc/sphinx/language-interfaces.rst | 55 -- doc/sphinx/matlab/index.rst | 1 - doc/sphinx/matlab/input-tutorial.rst | 62 -- doc/sphinx/old-docs.rst | 12 - doc/sphinx/reactors.rst | 625 ------------------ 36 files changed, 6509 deletions(-) delete mode 100644 doc/sphinx/about.rst delete mode 100644 doc/sphinx/compiling/config-options.rst delete mode 100644 doc/sphinx/compiling/configure-build.rst delete mode 100644 doc/sphinx/compiling/dependencies.rst delete mode 100644 doc/sphinx/compiling/index.rst delete mode 100644 doc/sphinx/compiling/installation-reqs.rst delete mode 100644 doc/sphinx/compiling/source-code.rst delete mode 100644 doc/sphinx/compiling/special-cases.rst delete mode 100644 doc/sphinx/cti/index.rst delete mode 100644 doc/sphinx/cti/input-files.rst delete mode 100644 doc/sphinx/cti/intro.rst delete mode 100644 doc/sphinx/cti/phases.rst delete mode 100644 doc/sphinx/cti/reactions.rst delete mode 100644 doc/sphinx/cti/species.rst delete mode 100644 doc/sphinx/cxx-guide/compiling.rst delete mode 100644 doc/sphinx/cxx-guide/demo1a.cpp delete mode 100644 doc/sphinx/cxx-guide/demo1b.cpp delete mode 100644 doc/sphinx/cxx-guide/demoequil.cpp delete mode 100644 doc/sphinx/cxx-guide/equil-example.rst delete mode 100644 doc/sphinx/cxx-guide/factories.rst delete mode 100644 doc/sphinx/cxx-guide/headers.rst delete mode 100644 doc/sphinx/cxx-guide/index.rst delete mode 100644 doc/sphinx/cxx-guide/simple-example.rst delete mode 100644 doc/sphinx/cxx-guide/thermo.rst delete mode 100644 doc/sphinx/cxx-guide/thermodemo.cpp delete mode 100644 doc/sphinx/cython/tutorial.rst delete mode 100644 doc/sphinx/faq.rst delete mode 100644 doc/sphinx/flames.rst delete mode 100644 doc/sphinx/glossary.rst delete mode 100644 doc/sphinx/install.rst delete mode 100644 doc/sphinx/language-interfaces.rst delete mode 100644 doc/sphinx/matlab/input-tutorial.rst delete mode 100644 doc/sphinx/old-docs.rst delete mode 100644 doc/sphinx/reactors.rst diff --git a/doc/sphinx/about.rst b/doc/sphinx/about.rst deleted file mode 100644 index 622335d50..000000000 --- a/doc/sphinx/about.rst +++ /dev/null @@ -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 -`_, 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 -`_ for -assistance in getting started. - -All online and in-person interactions and communications related to Cantera are -governed by the `Cantera Code of Conduct -`_. 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 -`_ 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 -`_ 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 `_ -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 - - diff --git a/doc/sphinx/compiling/config-options.rst b/doc/sphinx/compiling/config-options.rst deleted file mode 100644 index 190ef6911..000000000 --- a/doc/sphinx/compiling/config-options.rst +++ /dev/null @@ -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'`` diff --git a/doc/sphinx/compiling/configure-build.rst b/doc/sphinx/compiling/configure-build.rst deleted file mode 100644 index d7e80d61d..000000000 --- a/doc/sphinx/compiling/configure-build.rst +++ /dev/null @@ -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 ` - - * 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 ` -* :ref:`boost_inc_dir ` -* :ref:`debug ` -* :ref:`optimize ` -* :ref:`prefix ` -* :ref:`sundials_include ` -* :ref:`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 ` -* :ref:`python_package ` -* :ref:`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 ` 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 ` -* :ref:`python2_package ` -* :ref:`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 ` -* :ref:`python3_package ` -* :ref:`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 ` option:: - - toolchain=mingw - -* :ref:`msvc_version ` -* :ref:`target_arch ` -* :ref:`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 ` - -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 ` -* :ref:`FORTRAN ` - -Documentation Options -^^^^^^^^^^^^^^^^^^^^^ - -The following options control if the documentation is built: - -* :ref:`doxygen_docs ` -* :ref:`sphinx_docs ` - -Less Common Options -^^^^^^^^^^^^^^^^^^^ - -* :ref:`CC ` -* :ref:`CXX ` -* :ref:`env_vars ` -* :ref:`layout ` -* :ref:`VERBOSE ` -* :ref:`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 dump`` - Dump the state of the SCons environment to the - screen instead of doing ````, 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 diff --git a/doc/sphinx/compiling/dependencies.rst b/doc/sphinx/compiling/dependencies.rst deleted file mode 100644 index 3f8b08001..000000000 --- a/doc/sphinx/compiling/dependencies.rst +++ /dev/null @@ -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 - - .. 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 `_ - - * 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 `_ - - * Required version >=0.23 to build the Python module. Must be installed for - the same Python where SCons is installed. - -* `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 `_ - - * Required to build MSI installers on Windows. - * Known to work with versions 3.5 and 3.8. - -* `Pip `_ (Python) - - * Provides the ``pip`` command which can be used to install most of - the other Python modules. - -* Packages required for building Sphinx documentation - - * `Sphinx `_ - * `Pygments `_ - * `pyparsing `_ - * `doxylink `_ - * `matlabdomain `_ - -* `Doxygen `_ - - * Required for building the C++ API Documentation - * Version 1.8 or newer is recommended. - -* `Graphviz `_ - - * 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 diff --git a/doc/sphinx/compiling/index.rst b/doc/sphinx/compiling/index.rst deleted file mode 100644 index 6ca001691..000000000 --- a/doc/sphinx/compiling/index.rst +++ /dev/null @@ -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 diff --git a/doc/sphinx/compiling/installation-reqs.rst b/doc/sphinx/compiling/installation-reqs.rst deleted file mode 100644 index 617ca68c4..000000000 --- a/doc/sphinx/compiling/installation-reqs.rst +++ /dev/null @@ -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 `_ - - * 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 `_ - - * 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`` diff --git a/doc/sphinx/compiling/source-code.rst b/doc/sphinx/compiling/source-code.rst deleted file mode 100644 index 6e281dbeb..000000000 --- a/doc/sphinx/compiling/source-code.rst +++ /dev/null @@ -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 - `_ 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. diff --git a/doc/sphinx/compiling/special-cases.rst b/doc/sphinx/compiling/special-cases.rst deleted file mode 100644 index 7e08fb679..000000000 --- a/doc/sphinx/compiling/special-cases.rst +++ /dev/null @@ -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 ` option to a directory - for which you have write permissions, and specify the ``USER`` value to the - :ref:`python2_prefix ` or :ref:`python3_prefix ` - option. diff --git a/doc/sphinx/cti/index.rst b/doc/sphinx/cti/index.rst deleted file mode 100644 index 9da9d6d63..000000000 --- a/doc/sphinx/cti/index.rst +++ /dev/null @@ -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 diff --git a/doc/sphinx/cti/input-files.rst b/doc/sphinx/cti/input-files.rst deleted file mode 100644 index e3e14e1e7..000000000 --- a/doc/sphinx/cti/input-files.rst +++ /dev/null @@ -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 `` = ``, 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 - - - O + HCCO [=] H + 2 CO - - - 1.000000E+14 - 0 - 0.000000 - - - HCCO:1 O:1 - H:1 CO:2 - - -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 "", line 1, in - 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=] - [--thermo=] - [--transport=] - [--surface=] - [--id=] - [--output=] - [--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). diff --git a/doc/sphinx/cti/intro.rst b/doc/sphinx/cti/intro.rst deleted file mode 100644 index b40187ef4..000000000 --- a/doc/sphinx/cti/intro.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/cti/phases.rst b/doc/sphinx/cti/phases.rst deleted file mode 100644 index b2009db79..000000000 --- a/doc/sphinx/cti/phases.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/cti/reactions.rst b/doc/sphinx/cti/reactions.rst deleted file mode 100644 index fe62a3d4d..000000000 --- a/doc/sphinx/cti/reactions.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/cti/species.rst b/doc/sphinx/cti/species.rst deleted file mode 100644 index 20de419b9..000000000 --- a/doc/sphinx/cti/species.rst +++ /dev/null @@ -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 `_ 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 `_. 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. diff --git a/doc/sphinx/cxx-guide/compiling.rst b/doc/sphinx/cxx-guide/compiling.rst deleted file mode 100644 index e461b4ceb..000000000 --- a/doc/sphinx/cxx-guide/compiling.rst +++ /dev/null @@ -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 `_ -and the `SCons homepage `_. - -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) *~ - diff --git a/doc/sphinx/cxx-guide/demo1a.cpp b/doc/sphinx/cxx-guide/demo1a.cpp deleted file mode 100644 index e0883bb5d..000000000 --- a/doc/sphinx/cxx-guide/demo1a.cpp +++ /dev/null @@ -1,34 +0,0 @@ -#include "cantera/thermo.h" -#include - -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 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; - } -} - diff --git a/doc/sphinx/cxx-guide/demo1b.cpp b/doc/sphinx/cxx-guide/demo1b.cpp deleted file mode 100644 index 1923cff79..000000000 --- a/doc/sphinx/cxx-guide/demo1b.cpp +++ /dev/null @@ -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 gas(newPhase("gri30.cti", "gri30_mix")); - - // List of phases participating in reactions (just one for homogeneous - // kinetics) - std::vector phases{gas.get()}; - - // Create the Kinetics object. Based on the phase definition used, this will - // be a GasKinetics object. - std::unique_ptr 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 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; - } -} - diff --git a/doc/sphinx/cxx-guide/demoequil.cpp b/doc/sphinx/cxx-guide/demoequil.cpp deleted file mode 100644 index 4a9df4e5e..000000000 --- a/doc/sphinx/cxx-guide/demoequil.cpp +++ /dev/null @@ -1,20 +0,0 @@ -#include "cantera/thermo.h" - -using namespace Cantera; - -void equil_demo() -{ - std::unique_ptr 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; - } -} diff --git a/doc/sphinx/cxx-guide/equil-example.rst b/doc/sphinx/cxx-guide/equil-example.rst deleted file mode 100644 index 4725268fb..000000000 --- a/doc/sphinx/cxx-guide/equil-example.rst +++ /dev/null @@ -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 ` -function really works. diff --git a/doc/sphinx/cxx-guide/factories.rst b/doc/sphinx/cxx-guide/factories.rst deleted file mode 100644 index 8c713454a..000000000 --- a/doc/sphinx/cxx-guide/factories.rst +++ /dev/null @@ -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 diff --git a/doc/sphinx/cxx-guide/headers.rst b/doc/sphinx/cxx-guide/headers.rst deleted file mode 100644 index 309ab8467..000000000 --- a/doc/sphinx/cxx-guide/headers.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/cxx-guide/index.rst b/doc/sphinx/cxx-guide/index.rst deleted file mode 100644 index 36fc566a5..000000000 --- a/doc/sphinx/cxx-guide/index.rst +++ /dev/null @@ -1,14 +0,0 @@ - -************************** -C++ Interface User's Guide -************************** - -.. toctree:: - :maxdepth: 2 - - compiling - headers - thermo - simple-example - equil-example - factories diff --git a/doc/sphinx/cxx-guide/simple-example.rst b/doc/sphinx/cxx-guide/simple-example.rst deleted file mode 100644 index b0d70f506..000000000 --- a/doc/sphinx/cxx-guide/simple-example.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/cxx-guide/thermo.rst b/doc/sphinx/cxx-guide/thermo.rst deleted file mode 100644 index b1354d791..000000000 --- a/doc/sphinx/cxx-guide/thermo.rst +++ /dev/null @@ -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 - - int main(int argc, char** argv) - { - std::unique_ptr gas( - Cantera::newPhase("h2o2.cti", "ohmech")); - std::cout << gas->temperature() << std::endl; - return 0; - } - -Class :ct:`ThermoPhase` is the base class for Cantera classes that represent -phases of matter. It defines the public interface for all classes that represent -phases. For example, it specifies that they all have a method :ct:`temperature -` that returns the current temperature, a method -:ct:`setTemperature(double T) ` that sets the -temperature, a method :ct:`getChemPotentials(double* mu) -` that writes the species chemical potentials -into array ``mu``, and so on. - -Class ThermoPhase can be used to represent the intensive state of any -single-phase solution of multiple species. The phase may be a bulk, -three-dimensional phase (a gas, a liquid, or a solid), or it may be a -two-dimensional surface phase, or even a one-dimensional "edge" phase. The -specific attributes of each type of phase are specified by deriving a class from -:ct:`ThermoPhase` and providing implementations for its virtual methods. - -Cantera has a wide variety of models for bulk phase currently. Special attention -(in terms of the speed of execution) has been paid to an ideal gas phase -implementation, where the species thermodynamic polynomial representations -adhere to either the NASA polynomial form or to the Shomate 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. diff --git a/doc/sphinx/cxx-guide/thermodemo.cpp b/doc/sphinx/cxx-guide/thermodemo.cpp deleted file mode 100644 index 79d66fc7c..000000000 --- a/doc/sphinx/cxx-guide/thermodemo.cpp +++ /dev/null @@ -1,42 +0,0 @@ -#include "cantera/thermo.h" - -using namespace Cantera; - -void thermo_demo(const std::string& file, const std::string& phase) -{ - shared_ptr 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; -} diff --git a/doc/sphinx/cython/index.rst b/doc/sphinx/cython/index.rst index 3bb9cadd9..46d64065c 100644 --- a/doc/sphinx/cython/index.rst +++ b/doc/sphinx/cython/index.rst @@ -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 diff --git a/doc/sphinx/cython/tutorial.rst b/doc/sphinx/cython/tutorial.rst deleted file mode 100644 index 888c6acd6..000000000 --- a/doc/sphinx/cython/tutorial.rst +++ /dev/null @@ -1,442 +0,0 @@ -.. py:currentmodule:: cantera - -Tutorial -======== - -Getting Started ---------------- - -Start by opening an interactive Python session, e.g., by running `IPython -`_. 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 ``:`` 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 -` and :ref:`1D flame model `. - -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 - 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. diff --git a/doc/sphinx/faq.rst b/doc/sphinx/faq.rst deleted file mode 100644 index 2a8fcedab..000000000 --- a/doc/sphinx/faq.rst +++ /dev/null @@ -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 `_. 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 - `_ to see if the issue - has already been reported. - - Try to generate a `minimal, complete, and verifiable example - `_ 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 - `_ 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. diff --git a/doc/sphinx/flames.rst b/doc/sphinx/flames.rst deleted file mode 100644 index 9b3844847..000000000 --- a/doc/sphinx/flames.rst +++ /dev/null @@ -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 - diff --git a/doc/sphinx/glossary.rst b/doc/sphinx/glossary.rst deleted file mode 100644 index d0dcd63b9..000000000 --- a/doc/sphinx/glossary.rst +++ /dev/null @@ -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 \ No newline at end of file diff --git a/doc/sphinx/install.rst b/doc/sphinx/install.rst deleted file mode 100644 index c84261060..000000000 --- a/doc/sphinx/install.rst +++ /dev/null @@ -1,457 +0,0 @@ -.. _sec-install: - -****************** -Installing Cantera -****************** - -.. contents:: - :local: - :depth: 2 - -.. _sec-install-conda: - -Conda -===== - -`Anaconda `_ and `Miniconda -`_ 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 -`_. - -**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 -`_. If you are using Anaconda / Miniconda, see the -directions :ref:`above `. - -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 `_. - - - *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 `_ - 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 - `_. - - - *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 - `_. - - - 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 `_ - 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 `. 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 `_ 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. -`_ -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 diff --git a/doc/sphinx/language-interfaces.rst b/doc/sphinx/language-interfaces.rst deleted file mode 100644 index f0630afa6..000000000 --- a/doc/sphinx/language-interfaces.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/matlab/index.rst b/doc/sphinx/matlab/index.rst index f97c98a67..585e47ef0 100644 --- a/doc/sphinx/matlab/index.rst +++ b/doc/sphinx/matlab/index.rst @@ -6,7 +6,6 @@ Matlab Interface User's Guide .. toctree:: :maxdepth: 2 - input-tutorial importing thermodynamics kinetics diff --git a/doc/sphinx/matlab/input-tutorial.rst b/doc/sphinx/matlab/input-tutorial.rst deleted file mode 100644 index fd9bb2e5f..000000000 --- a/doc/sphinx/matlab/input-tutorial.rst +++ /dev/null @@ -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. diff --git a/doc/sphinx/old-docs.rst b/doc/sphinx/old-docs.rst deleted file mode 100644 index 7f077cc56..000000000 --- a/doc/sphinx/old-docs.rst +++ /dev/null @@ -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 `_ -* `Cantera 2.2.1 `_ -* `Cantera 2.1.2 `_ -* `Cantera 2.0.2 `_ diff --git a/doc/sphinx/reactors.rst b/doc/sphinx/reactors.rst deleted file mode 100644 index a8ac1215b..000000000 --- a/doc/sphinx/reactors.rst +++ /dev/null @@ -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 `_ | :ct:`C++ ` - -- **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 `, :ref:`Matlab `). - -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