Moved Matlab input tutorial into Sphinx documentation
This commit is contained in:
Ray Speth
parent
545e258eb3
commit
3938a6bfa7
6 changed files with 104 additions and 129 deletions
|
|
@ -1,128 +0,0 @@
|
|||
/**
|
||||
|
||||
\page matlab-tutorial MATLAB Cantera Tutorial
|
||||
|
||||
\section tut2 Tutorial 2: Working with input files
|
||||
|
||||
|
||||
Topics:
|
||||
|
||||
- CTI files
|
||||
- CTI files distributed with %Cantera
|
||||
- using functions 'importPhase' and 'importInterface'
|
||||
- input files distributed with %Cantera
|
||||
- the %Cantera search path
|
||||
- CTML files
|
||||
- converting from CK format
|
||||
|
||||
\section cti-files CTI files
|
||||
|
||||
In the last tutorial, we used function GRI30 to create an object that models
|
||||
an ideal gas mixture with the species and reactions of GRI-Mech 3.0. Another
|
||||
way to do this is shown here, with statements added to measure how long this
|
||||
takes:
|
||||
|
||||
\verbatim
|
||||
gas1 = importPhase('gri30.cti', 'gri30');
|
||||
\endverbatim
|
||||
|
||||
Function importPhase constructs an 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 the document "Defining
|
||||
Phases and Interfaces."
|
||||
|
||||
On some systems, processing long CTI files like gri30.cti can be a little
|
||||
slow. For example, using a typical laptop computer running Windows 2000, the
|
||||
statement above takes more than 4 s, while on a Mac Powerbook G4 of similar
|
||||
CPU speed it takes only 0.3 s. In any case, running it again takes much less
|
||||
time, because %Cantera 'remembers' files it has already processed and doesn't
|
||||
need to read them in again.
|
||||
|
||||
See also:
|
||||
Cantera Input File Examples
|
||||
|
||||
\section cti-distrib 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.
|
||||
Under Windows, these files may be located in 'C: Files Files', or in 'C:',
|
||||
depending on how you installed %Cantera and the options you specified. On a
|
||||
unix/linux/Mac OSX machine, they are usually 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 where they
|
||||
are located. Alternatively, you can call function addDirectory to add a
|
||||
directory to the %Cantera search path:
|
||||
\verbatim
|
||||
addDirectory('/usr/local/cantera/my_data_files');
|
||||
\endverbatim
|
||||
|
||||
%Cantera input files are plain text files, and can be created with any text
|
||||
editor. See the document 'Defining Phases and Interfaces' for more
|
||||
information.
|
||||
|
||||
\section mat-import 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:
|
||||
|
||||
\verbatim
|
||||
gas2 = importPhase('diamond.cti', 'gas'); a gas
|
||||
|
||||
diamond = importPhase('diamond.cti','diamond'); bulk diamond
|
||||
|
||||
diamonnd_surf = importInterface('diamond.cti','diamond_100',...
|
||||
gas2, diamond);
|
||||
\endverbatim
|
||||
|
||||
Note that the bulk (i.e., 3D) phases that participate in the surface reactions
|
||||
must also be passed as arguments to importInterface.
|
||||
|
||||
\section ctml-files CTML files
|
||||
|
||||
Note that when %Cantera reads a .cti input file, wherever it is located, it
|
||||
always writes a file of the same name but with extension .xml *in the local
|
||||
directory*. If you happen to have some other file by that name, it will be
|
||||
overwritten. Once the XML file is created, you can use it instead of the .cti
|
||||
file, which will result in somewhat faster startup.
|
||||
|
||||
\verbatim
|
||||
gas4 = importPhase('gri30.xml','gri30');
|
||||
\endverbatim
|
||||
|
||||
Interfaces can be imported from XML files too.
|
||||
|
||||
\verbatim
|
||||
diamonnd_surf2 = importInterface('diamond.xml','diamond_100',...
|
||||
gas2, diamond);
|
||||
\endverbatim
|
||||
|
||||
\section ck-convert 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.
|
||||
[See R. J. Kee, F. M. Rupley, and J. A. Miller, Sandia National Laboratories
|
||||
Report SAND89-8009 (1989).]
|
||||
|
||||
%Cantera comes with a converter utility program 'ck2cti' (or 'ck2cti.exe') 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. This utility program can also be downloaded from the %Cantera User's
|
||||
Group web site.
|
||||
|
||||
Here's an example of how to use it:
|
||||
|
||||
\verbatim
|
||||
ck2cti -i mech.inp -t therm.dat -tr tran.dat -id mymech > mech.cti
|
||||
\endverbatim
|
||||
|
||||
*/
|
||||
|
|
@ -126,7 +126,7 @@ html_theme = 'sphinxdoc'
|
|||
#html_title = None
|
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||
#html_short_title = None
|
||||
html_short_title = "Cantera"
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top
|
||||
# of the sidebar.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,6 @@
|
|||
|
||||
.. _sec-defining-phases:
|
||||
|
||||
***************
|
||||
Defining Phases
|
||||
***************
|
||||
|
|
|
|||
|
|
@ -14,6 +14,7 @@ Contents
|
|||
language-interfaces
|
||||
cti/index
|
||||
python/index
|
||||
matlab/index
|
||||
cxx-guide/index
|
||||
|
||||
Cantera Development Homepage <http://cantera.googlecode.com>
|
||||
|
|
|
|||
9
doc/sphinx/matlab/index.rst
Normal file
9
doc/sphinx/matlab/index.rst
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
|
||||
*****************************
|
||||
Matlab Interface User's Guide
|
||||
*****************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
input-tutorial
|
||||
90
doc/sphinx/matlab/input-tutorial.rst
Normal file
90
doc/sphinx/matlab/input-tutorial.rst
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
|
||||
**********************************
|
||||
Tutorial: Working with input files
|
||||
**********************************
|
||||
|
||||
.. highlight:: matlab
|
||||
|
||||
CTI files
|
||||
---------
|
||||
|
||||
This is the typical way to create a Cantera "phase" object in Matlab::
|
||||
|
||||
gas1 = importPhase('gri30.cti', 'gri30');
|
||||
|
||||
Function ``importPhase`` constructs an 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 where they
|
||||
are located. Alternatively, you can call function ``addDirectory`` 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 = importPhase('diamond.cti', 'gas'); % a gas
|
||||
diamond = importPhase('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.
|
||||
|
||||
CTML files
|
||||
----------
|
||||
|
||||
Note that when Cantera reads a ``.cti`` input file, wherever it is located, it
|
||||
always writes a file of the same name but with extension ``.xml`` *in the local
|
||||
directory*. If you happen to have some other file by that name, it will be
|
||||
overwritten. Once the XML file is created, you can use it instead of the
|
||||
``.cti`` file, which will result in somewhat faster startup::
|
||||
|
||||
gas4 = importPhase('gri30.xml','gri30');
|
||||
|
||||
Interfaces can be imported from XML files too::
|
||||
|
||||
diamonnd_surf2 = importInterface('diamond.xml','diamond_100',...
|
||||
gas2, diamond);
|
||||
|
||||
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. [See
|
||||
R. J. Kee, F. M. Rupley, and J. A. Miller, Sandia National Laboratories Report
|
||||
SAND89-8009 (1989).]
|
||||
|
||||
Cantera comes with a converter utility program ``ck2cti`` (or ``ck2cti.exe``)
|
||||
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.
|
||||
|
||||
Here's an example of how to use it:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ck2cti -i mech.inp -t therm.dat -tr tran.dat -id mymech > mech.cti
|
||||
Loading…
Add table
Reference in a new issue