diff --git a/doc/doxygen/matlab.txt b/doc/doxygen/matlab.txt deleted file mode 100644 index 0973cb963..000000000 --- a/doc/doxygen/matlab.txt +++ /dev/null @@ -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 - -*/ diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 13eeba1c5..3ad6bd9c6 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -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. diff --git a/doc/sphinx/cti/index.rst b/doc/sphinx/cti/index.rst index 8bc97d645..a3af37a11 100644 --- a/doc/sphinx/cti/index.rst +++ b/doc/sphinx/cti/index.rst @@ -1,3 +1,6 @@ + +.. _sec-defining-phases: + *************** Defining Phases *************** diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 20c0a72a3..2c3edbc67 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -14,6 +14,7 @@ Contents language-interfaces cti/index python/index + matlab/index cxx-guide/index Cantera Development Homepage diff --git a/doc/sphinx/matlab/index.rst b/doc/sphinx/matlab/index.rst new file mode 100644 index 000000000..1758e0a60 --- /dev/null +++ b/doc/sphinx/matlab/index.rst @@ -0,0 +1,9 @@ + +***************************** +Matlab Interface User's Guide +***************************** + +.. toctree:: + :maxdepth: 2 + + input-tutorial diff --git a/doc/sphinx/matlab/input-tutorial.rst b/doc/sphinx/matlab/input-tutorial.rst new file mode 100644 index 000000000..9e4aef7a6 --- /dev/null +++ b/doc/sphinx/matlab/input-tutorial.rst @@ -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