From d02ccc53348bf2eb1536c7b4b69f274fbb93cb8b Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Wed, 4 Apr 2012 18:45:15 +0000 Subject: [PATCH] Translated the "Defining Phases" guide to Sphinx/reST format --- doc/sphinx/_static/images/sofc-phases.png | Bin 0 -> 19932 bytes .../{defining-phases.rst => cti/classes.rst} | 24 +- doc/sphinx/cti/example-combustion.rst | 4 + doc/sphinx/cti/index.rst | 16 + doc/sphinx/cti/input-files.rst | 483 ++++++++++++++++++ doc/sphinx/cti/intro.rst | 40 ++ doc/sphinx/cti/phases.rst | 466 +++++++++++++++++ doc/sphinx/cti/reactions.rst | 290 +++++++++++ doc/sphinx/cti/species.rst | 225 ++++++++ doc/sphinx/index.rst | 2 +- 10 files changed, 1537 insertions(+), 13 deletions(-) create mode 100644 doc/sphinx/_static/images/sofc-phases.png rename doc/sphinx/{defining-phases.rst => cti/classes.rst} (91%) create mode 100644 doc/sphinx/cti/example-combustion.rst create mode 100644 doc/sphinx/cti/index.rst create mode 100644 doc/sphinx/cti/input-files.rst create mode 100644 doc/sphinx/cti/intro.rst create mode 100644 doc/sphinx/cti/phases.rst create mode 100644 doc/sphinx/cti/reactions.rst create mode 100644 doc/sphinx/cti/species.rst diff --git a/doc/sphinx/_static/images/sofc-phases.png b/doc/sphinx/_static/images/sofc-phases.png new file mode 100644 index 0000000000000000000000000000000000000000..bf3b84d8f83e101f218d039239d69c49f98485e1 GIT binary patch literal 19932 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 Pwp04L@H>?{cG3R = ``, 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 double quotes. + +Strings may be enclosed in single quotes or double quotes, but they must +match. To create a string containing single quotes, enclose it in double quotes, +and vice versa. If you want to create a string to extend over multiple lines, +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 + +.. _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 function like importPhase is called to import a phase definition +from a file, a preprocessor runs automatically to read the input file and create +a data file that contains the same information but in an XML-based format called +CTML. After the preprocessor finishes, Cantera imports the phase definition from +the CTML data file. + +The CTML file is saved in the same directory as the input file, and has the same +name but with the extension changed to ``.xml``. If the input file has the name +``propane.cti``, for example, then the CTML file will be placed in the same +directory with name ``propane.xml``. If you like, once the CTML file has been +created, you can specify it rather than the ``.cti`` input file in calls to +importPhase (or similar functions). This is slightly faster, since the +preprocessing step can be skipped. It also allows Cantera simulations to be run +on systems that do not have Python, which Cantera uses in the preprocessing step +but does not require to read CTML files. + +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 knowledgable 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 Intenals: 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:: + + >>> from Cantera import ctml_writer + >>> help(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 ctml_writer.py phasedefs.cti + +to create CTML file ``phasedefs.xml``. + +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 quitely 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`. diff --git a/doc/sphinx/cti/intro.rst b/doc/sphinx/cti/intro.rst new file mode 100644 index 000000000..b40187ef4 --- /dev/null +++ b/doc/sphinx/cti/intro.rst @@ -0,0 +1,40 @@ +************ +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 new file mode 100644 index 000000000..7947a88b3 --- /dev/null +++ b/doc/sphinx/cti/phases.rst @@ -0,0 +1,466 @@ +.. py:currentmodule:: 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 and/or +commas. 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:: + + >>> gas = importPhase('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. + +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:: + + # commas are optional + species = 'AR SI Si2 SiH SiH2 SiH3 SiH4' + species = 'H, O, OH, H2O, HO2, H2O2, H2, O2' + + # 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. + +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 one :class:`ideal_gas` phases, multiple transport models are +available; the one desired can be selected by assiging 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 +============================== ================ +``'no_validation'`` Turn off all validation. Use when the definition + has been previously validated to speed up importing + the definition into an application. Use with caution! +``'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. +============================== ================ + +Using the ``options`` field, it is possible to extract a sub-mechanism from a large +reaction mechanism, as follows:: + + ideal_gas(name = 'hydrogen_mech', + species = 'gri30: all', + reactions = 'gri30:all', + options = ('skip_undeclared_elements', + 'skip_undeclared_species')) + +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:: matlab + + >> gas = importPhase('gas.cti', 'hydrogen_mech') + + temperature 300 K + pressure 1237.28 Pa + density 0.001 kg/m^3 + mean mol. weight 2.01588 amu + + X Y + ------------ ------------ + H2 1.000000e+00 1.000000e+00 + H 0.000000e+00 0.000000e+00 + O 0.000000e+00 0.000000e+00 + O2 0.000000e+00 0.000000e+00 + OH 0.000000e+00 0.000000e+00 + H2O 0.000000e+00 0.000000e+00 + HO2 0.000000e+00 0.000000e+00 + H2O2 0.000000e+00 0.000000e+00 + + >> 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. [1989], 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 [1968] (see also Kee et al. [2003]). 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')) + +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. + +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 is 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 bounday 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 (``mole_fractions``, ``mass_fractions``, ``coverages``). diff --git a/doc/sphinx/cti/reactions.rst b/doc/sphinx/cti/reactions.rst new file mode 100644 index 000000000..1a269245a --- /dev/null +++ b/doc/sphinx/cti/reactions.rst @@ -0,0 +1,290 @@ +.. py:currentmodule:: 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^n \exp(-E/\hat{R}T) + +whish is defined with an :class:`Arrhenius` entry:: + + rate_coeff = Arrhenius(A=1.0e13, n=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, n, 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:`n \ne 0`, then the term :math:`T^n` should have units of +:math:`K^n`, 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^n` by the non-dimensional quantity +:math:`[T/(1 K)]^n`. + +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. + +Options +------- + +Certain conditions are normally flagged as errors by Cantera. In some cases, +theey 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. + +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 [Smith et al., 1997] 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", [7.00000E+17, -0.8, 0]) + reaction( "HO2 + C3H7 <=> O2 + C3H8", [2.55000E+10, 0.255, -943]) + reaction( "HO2 + C3H7 => OH + C2H5 + CH2O", [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} \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. + +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 [Lindemann, 1922]: + +.. 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. [1983]: + +.. 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 paramteter, :math:`T_2`, is optional, defaulting to 0.0. + +The SRI Falloff Function +------------------------ + +This falloff function is based on the one originally due to Stewart et +al. [1989], which required three parameters :math:`(a, b, c)`. Kee et al. [1989] +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., 1989], 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. + diff --git a/doc/sphinx/cti/species.rst b/doc/sphinx/cti/species.rst new file mode 100644 index 000000000..576e4c793 --- /dev/null +++ b/doc/sphinx/cti/species.rst @@ -0,0 +1,225 @@ +.. py:currentmodule:: ctml_writer + +.. _sec-species: + +******************** +Elements and Species +******************** + +.. _sec-elements: + +Elements +======== + +The 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-!8", 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` + +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. [1986]. 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, three entry types are implemented, all of which provide species +properties appropriate for models of ideal gas mixtures, ideal solutions, and +pure compounds. Non-ideal phase models are not yet implemented, but may be in +future releases. When they are, additional entry types may also be added that +provide species-specific coefficients required by specific non-ideal equations +of state. + +The NASA Polynomial Parameterization +------------------------------------ + +The NASA 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 + a_5 + + \frac{s^0(T)}{R} = a_o \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. It is not compatible with the form used in +the most recent version of the NASA equilibrium program, which uses 9 +coefficients, not 7. + +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 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 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)`. + +Example:: + + thermo = const_cp( t0 = 1200.0, + h0 = (-5.0, 'kcal/mol') ) + +.. See ##REF## for more examples of use of this parameterization. diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 78094a40e..1d180f579 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -12,7 +12,7 @@ Contents Compiliation Instructions - defining-phases + cti/index python/index C++ Introduction