CTI File Syntax¶
CTI is the human-readable input format for Cantera, and we describe it’s syntax here
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 Dimensional Values.
Entries have fields that can be assigned values. A species entry is shown below that has fields name and atoms:
Most entries have some fields that are required; these must be assigned values, or else processing of the file will abort and an error message will be printed. Other fields may be optional, and take default values if not assigned.
An entry may be either a top-level entry or an embedded entry. Top-level entries specify a phase, an interface, an element, a species, or a reaction, and begin in the first (leftmost) column. Embedded entries specify a model, or a group of parameters for a top-level entry, and are usually embedded in a field of another entry.
The fields of an entry are specified in the form <field_name>=<value>, and may be listed on one line, or extend across several. For example, two entries for graphite are shown below. The first is compact:
and the second is formatted to be easier to read:
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
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.
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:
The multi-line form is useful when specifying a phase containing a large number of species:
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 in many cases either can be used:
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:
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:
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
validate() function. For example, to disable validation of reactions, add
the following to the CTI file:
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
units() directive described in
Setting the 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:
- Units in the denominator follow /.
- Units in the numerator follow -, except for the first one.
- 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)
Setting the Default Units¶
The default unit system may be set with the
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
units() for the declaration of the units directive.
Cantera recognizes the following units in various contexts:
|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'|