CTML to YAML conversion¶
The script ctml2yaml.py
will convert files from the legacy CTML format to YAML input
format. The documentation below describes the classes and functions in the script. Each
function/method is annotated with the Python types that the function accepts.
Most users will access the functionality of this module via the command line with the
ctml2yaml
entry-point script. For programmatic access, the main
and/or convert
functions should be used. main
should be used when command line arguments must be
processed, while convert
takes an input filename or a string containing the CTML file
to be converted, and optionally the name of the output file.
Module-level functions¶
- cantera.ctml2yaml.float2string(data: float) str ¶
Format a float into a string.
- Parameters
data – The floating point data to be formatted.
Uses NumPy’s
format_float_positional()
andformat_float_scientific()
if they are is available, requiresnumpy >= 1.14
. In that case, values with magnitude between 0.01 and 10000 are formatted usingformat_float_positional ()
and other values are formatted usingformat_float_scientific()
. If those NumPy functions are not available, returns therepr
of the input.
- cantera.ctml2yaml.represent_float(self: Any, data: Any) Any ¶
Format floating point numbers for ruamel YAML.
- Parameters
data – The floating point data to be formatted.
Uses
float2string
to format the floating point input to a string, then inserts the resulting string into the YAML tree as a scalar.
- cantera.ctml2yaml.get_float_or_quantity(node: xml.etree.ElementTree.Element) QUANTITY ¶
Process an XML node into a float value or a value with units.
- Parameters
node – The XML node with a value in the text and optionally a units attribute.
Given XML nodes like:
<E units="cal/mol">1000.0</E> <E>1000.0</E>
this function returns, respectively:
1000.0 cal/mol 1000.0
where the first value is a string and the second is a float.
- cantera.ctml2yaml.split_species_value_string(node: xml.etree.ElementTree.Element) Dict[str, float] ¶
Split a string of species:value pairs into a dictionary.
- Parameters
node – An XML node whose text contains the species: value pairs
Returns a dictionary where the keys of the dictionary are species names and the values are the number associated with each species. This is useful for things like elemental composition, mole fraction mappings, coverage mappings, etc.
The algorithm is reimplemented from
compositionMap::parseCompString
inbase/stringUtils.cpp
.
- cantera.ctml2yaml.clean_node_text(node: xml.etree.ElementTree.Element) str ¶
Clean the text of a node.
- Parameters
node – An XML node with a text value.
Raises
MissingNodeText
if the node text is not present. Otherwise, replaces newlines and tab characters with spaces, then strips the resulting string. This turns multi-line text values into a single line that can be split on whitespace.
- cantera.ctml2yaml.create_species_from_data_node(ctml_tree: xml.etree.ElementTree.Element) Dict[str, List[cantera.ctml2yaml.Species]] ¶
Generate lists of
Species
instances mapped to thespeciesData
id string.- Parameters
ctml_tree – The root XML node of the CTML document.
The CTML document is searched for
speciesData
nodes that containspecies
child nodes. EachspeciesData
node must have anid
attribute, which is used as the key of the returned dictionary. The values in the dictionary are lists ofSpecies
instances representing thespecies
nodes in thatspeciesData
node. Theid
attribute is also used as the top-level key in the YAML document for that set of species, with the exception thatspecies_data
is changed to justspecies
.If
speciesData
nodes with the sameid
attribute are found, only the first section with thatid
is put into the YAML output file.
- cantera.ctml2yaml.create_reactions_from_data_node(ctml_tree: xml.etree.ElementTree.Element) Dict[str, List[cantera.ctml2yaml.Reaction]] ¶
Generate lists of
Reaction
instances mapped to thereactionData
id string.- Parameters
ctml_tree – The root XML node of the CTML document.
The CTML document is searched for
reactionData
nodes that containreaction
child nodes. EachreactionData
node must have anid
attribute, which is used as the key of the returned dictionary. The values in the dictionary are lists ofReaction
instances representing thereaction
nodes in thatreactionData
node. Theid
attribute is also used as the top-level key in the YAML document for that set of reactions, with the exception thatreaction_data
is changed to justreactions
.If
reactionData
nodes with the sameid
attribute are found, only the first section with thatid
is put into the YAML output file.
- cantera.ctml2yaml.create_phases_from_data_node(ctml_tree: xml.etree.ElementTree.Element, species_data: Dict[str, List[cantera.ctml2yaml.Species]], reaction_data: Dict[str, List[cantera.ctml2yaml.Reaction]]) List[cantera.ctml2yaml.Phase] ¶
Generate a list of
Phase
instances from XMLphase
nodes.- Parameters
The CTML document is searched for
phase
nodes, which are processed intoPhase
instances. For any Lattice-type phases, the childphase
nodes are un-nested from their parent node.
- cantera.ctml2yaml.convert(inpfile: Optional[Union[str, pathlib.Path]] = None, outfile: Optional[Union[str, pathlib.Path]] = None, text: Optional[str] = None) None ¶
Convert an input legacy CTML file to a YAML file.
- Parameters
inpfile – The input CTML file name. Exclusive with
text
, only one of the two can be specified.outfile – The output YAML file name.
text – Contains a string with the CTML input file content. Exclusive with
inpfile
, only one of the two can be specified.
All files are assumed to be relative to the current working directory of the Python process running this script.
Conversion classes¶
- class cantera.ctml2yaml.Phase(phase: xml.etree.ElementTree.Element, species_data: Dict[str, List[cantera.ctml2yaml.Species]], reaction_data: Dict[str, List[cantera.ctml2yaml.Reaction]])¶
Bases:
object
Represent an XML
phase
node.- Parameters
This class processes the XML node of a phase definition and generates a mapping for the YAML output. The mapping is stored in the
attribs
instance attribute and automatically formatted to YAML by theto_yaml
class method.- check_elements(this_phase_species: List[Dict[str, Iterable[str]]], species_data: Dict[str, List[cantera.ctml2yaml.Species]]) None ¶
Check the species elements for inclusion in the
Phase
-level specification.- Parameters
this_phase_species – A list of mappings of species data sources to the species names in that data source. Passed as an argument instead of using the
species
key in the instanceattribs
dictionary because the attribute could be a mapping or a list of mappings, whereas this argument is always a list of mappings.species_data – Mapping of species data sources (that is,
id
attributes onspeciesData
nodes) to lists ofSpecies
instances.
Some species include a charge node that adds an electron to the species composition. The
Phase`s that include these species don't necessarily include the electron in the `Phase
-level elements list, so we need to update that to include it if necessary.
- debye_huckel(this_phase_species: List[Dict[str, Iterable[str]]], activity_node: xml.etree.ElementTree.Element, species_data: Dict[str, List[Species]]) Dict[str, Union[str, QUANTITY, bool]] ¶
Process the activity coefficients for the
DebyeHuckel
phase-thermo type.- Parameters
this_phase_species – A list of mappings of species data sources to the species names in that data source. Passed as an argument instead of using the
species
key in the instanceattribs
because the attribute could be a mapping or a list of mappings, whereas this argument is always a list of mappings.activity_node – XML
activityCoefficients
node.species_data – Mapping of species data sources (that is,
id
attributes onspeciesData
nodes) to lists ofSpecies
instances.
- filter_reaction_list(datasrc: str, filter_text: str, reaction_data: Dict[str, List[cantera.ctml2yaml.Reaction]]) str ¶
Filter the reaction_data list to only include specified reactions.
- Parameters
datasrc – The XML source of the reaction data that is being filtered.
filter_text – The text specified in the
filter
node telling which reactions are being filtered.reaction_data – Mapping of reaction data sources (that is,
id
attributes onreactionData
nodes) to lists ofReaction
instances.
The YAML format does not support filtering reactions by setting options in the
Phase
node, like the XML format does. Instead, when filters are used in XML, the reactions should be split into separate top-level nodes in the YAML file, which then become the data source in the YAML reactions specification. Returns a string that should be used as the data source in the YAML file.
- get_reaction_array(reactionArray_node: xml.etree.ElementTree.Element, reaction_data: Dict[str, List[cantera.ctml2yaml.Reaction]]) Dict[str, str] ¶
Process reactions from a
reactionArray
node in a phase definition.- Parameters
reactionArray_node – An XML
reactionArray
node.
The
reactionArray
node has the data source plus a list of reaction to derive from that data source. If the data source specifies an XML file, convert the extension to.yaml
. If the data sourceid
isreaction_data
, reformat to justreaction
for the YAML file. Otherwise, retain theid
as-is.
- get_species_array(speciesArray_node: xml.etree.ElementTree.Element) Dict[str, Iterable[str]] ¶
Process a list of species from a
speciesArray
node.- Parameters
speciesArray_node – An XML
speciesArray
node.
The
speciesArray
node has the data source plus a list of species to derive from that data source. If the data source specifies an XML file, convert the extension to.yaml
. If the data sourceid
isspecies_data
, reformat to justspecies
for the YAML file. Otherwise, retain theid
as-is.
- get_tabulated_thermo(tab_thermo_node: xml.etree.ElementTree.Element) Dict[str, str] ¶
Process data from the
tabulatedThermo
node.- Parameters
tab_thermo_node – The XML node with the tabulated thermodynamics data.
- hmw_electrolyte(activity_node: xml.etree.ElementTree.Element) Dict[str, HMW_THERMO_TYPE] ¶
Process the activity coefficients for an
HMW
phase-thermo type.- Parameters
activity_coeffs – XML
activityCoefficients
node.
The
activityCoefficients
must include theA_debye
node, as well as any interaction parameters between species.
- ideal_molal_solution(activity_coeffs: xml.etree.ElementTree.Element) Dict[str, Union[str, QUANTITY]] ¶
Process the cutoff data in an
IdealMolalSolution
phase-thermo type.- Parameters
activity_coeffs – XML
activityCoefficients
node. For theIdealMolalSolution
thermo type, this node contains information about cutoff limits for the thermodynamic properties.
Returns a (possibly empty) dictionary to update the
Phase
attributes. The dictionary will be empty when there are no cutoff nodes in theactivityCoefficients
node.
- margules(activity_coeffs: xml.etree.ElementTree.Element) List[Dict[str, List[Union[str, QUANTITY]]]] ¶
Process activity coefficients for a
Margules
phase-thermo type.- Parameters
activity_coeffs – XML
activityCoefficients
node. For theMargules
phase-thermo type these are interaction parameters between the species in the phase.
Returns a list of interaction data values. Margules does not require the
binaryNeutralSpeciesParameters
node to be present. Almost a superset of the Redlich-Kister parameters, but since thebinaryNeutralSpeciesParameters
are processed in a loop, there’s no advantage to re-use Redlich-Kister processing because this function would have to go through the same nodes again.
- move_RK_coeffs_to_species(this_phase_species: List[Dict[str, Iterable[str]]], activity_coeffs: xml.etree.ElementTree.Element, species_data: Dict[str, List[cantera.ctml2yaml.Species]]) None ¶
Move the Redlich-Kwong activity coefficient data from phase to species.
- Parameters
this_phase_species – A list of mappings of species data sources to the species names in that data source. Passed as an argument instead of using the
species
key in the instanceattribs
because the attribute could be a mapping or a list of mappings, whereas this argument is always a list of mappings.activity_coeffs – XML
activityCoefficients
node.species_data – Mapping of species data sources (that is,
id
attributes onspeciesData
nodes) to lists ofSpecies
instances.
The YAML format moves the specification of Redlich-Kwong binary interaction parameters from the
Phase
node into theSpecies
nodes. This modifies theSpecies
objects in-place in thespecies_data
list.
- move_density_to_species(this_phase_species: List[Dict[str, Iterable[str]]], phase_thermo: xml.etree.ElementTree.Element, species_data: Dict[str, List[cantera.ctml2yaml.Species]]) None ¶
Move the phase density information into each species definition.
- Parameters
this_phase_species – A list of mappings of species data sources to the species names in that data source. Passed as an argument instead of using the
species
key in the instanceattribs
because the attribute could be a mapping or a list of mappings, whereas this argument is always a list of mappings.phase_thermo – XML
thermo
node.species_data – Mapping of species data sources (that is,
id
attributes onspeciesData
nodes) to lists ofSpecies
instances.
The YAML format moves the specification of density for
StoichSubstance
phase-thermo types from thePhase
node into theSpecies
nodes. This modifies theSpecies
objects in-place in thespecies_data
list.
- redlich_kister(activity_coeffs: xml.etree.ElementTree.Element) List[Dict[str, List[Union[str, QUANTITY]]]] ¶
Process activity coefficients for a Redlich-Kister phase-thermo type.
- Parameters
activity_coeffs – XML
activityCoefficients
node. For theRedlichKister
phase-thermo type these are interaction parameters between the species in the phase.
Returns a list of interaction data values. The
activityCoefficients
node must have abinaryNeutralSpeciesParameters
child node.
- classmethod to_yaml(representer, data)¶
Serialize the class instance to YAML format suitable for ruamel.yaml.
- Parameters
representer – An instance of a ruamel.yaml representer type.
data – An instance of this class that will be serialized.
The class instance should have an instance attribute called
attribs
which is a dictionary representing the information about the instance. The dictionary is serialized using therepresent_dict
method of therepresenter
.
- class cantera.ctml2yaml.Species(species_node: xml.etree.ElementTree.Element)¶
Bases:
object
Represent an XML
species
node.- Parameters
species_node – The XML node with the species information.
This class processes the XML node of a species definition and generates a mapping for the YAML output. The mapping is stored in the
attribs
instance attribute and automatically formatted to YAML by theto_yaml
class method.- hkft(species_node: xml.etree.ElementTree.Element) Dict[str, HKFT_THERMO_TYPE] ¶
Process a species with HKFT thermo type.
- Parameters
species_node – The XML node with the species information.
Requires synthesizing data from the
thermo
node and thestandardState
node.
- process_standard_state_node(species_node: xml.etree.ElementTree.Element) None ¶
Process the
standardState
node in a species definition.- Parameters
species_node – The XML node with the species information.
If the model is
IonFromNeutral
orHKFT
, this function doesn’t do anything to theSpecies
object. Otherwise, the model data is put into the YAMLequation-of-state
node.
- classmethod to_yaml(representer, data)¶
Serialize the class instance to YAML format suitable for ruamel.yaml.
- Parameters
representer – An instance of a ruamel.yaml representer type.
data – An instance of this class that will be serialized.
The class instance should have an instance attribute called
attribs
which is a dictionary representing the information about the instance. The dictionary is serialized using therepresent_dict
method of therepresenter
.
- class cantera.ctml2yaml.SpeciesThermo(thermo: xml.etree.ElementTree.Element)¶
Bases:
object
Represent the polynomial-type thermodynamic data for a
Species
.- Parameters
thermo – A
species/thermo
XML node. Must have one or more child nodes with tagNASA
,NASA9
,const_cp
,Shomate
, orMu0
.
This class will process the
Species
-level thermodynamic information for the polynomial thermo types. The pressure-dependent standard state types are processed directly in theSpecies
instance.- Mu0(thermo: xml.etree.ElementTree.Element) Dict[str, Union[str, Dict[float, Iterable]]] ¶
Process a piecewise Gibbs Free Energy thermodynamic polynomial.
- Parameters
thermo – A
species/thermo
XML node. There must be one child node with the tagMu0
.
- NASA(thermo: xml.etree.ElementTree.Element) Dict[str, Union[str, THERMO_POLY_TYPE]] ¶
Process a NASA 7-coefficient thermodynamic polynomial.
- Parameters
thermo – A
species/thermo
XML node. There must be one or more child nodes with the tagNASA
.
- NASA9(thermo: xml.etree.ElementTree.Element) Dict[str, Union[str, THERMO_POLY_TYPE]] ¶
Process a NASA 9-coefficient thermodynamic polynomial.
- Parameters
thermo – A
species/thermo
XML node. There must be one or more child nodes with the tagNASA9
.
- Shomate(thermo: xml.etree.ElementTree.Element) Dict[str, Union[str, THERMO_POLY_TYPE]] ¶
Process a Shomate
Species
thermodynamic polynomial.- Parameters
thermo – A
species/thermo
XML node. There must be one or more child nodes with the tagShomate
.
- const_cp(thermo: xml.etree.ElementTree.Element) Dict[str, Union[str, QUANTITY]] ¶
Process a
Species
thermodynamic type with constant specific heat.- Parameters
thermo – A
species/thermo
XML node. There must be one child node with the tagconst_cp
.
- process_polynomial(thermo: xml.etree.ElementTree.Element, poly_type: str) Tuple[List[List[float]], List[float]] ¶
Process the
Species
thermodynamic polynomial for several types.- Parameters
thermo – A
species/thermo
XML node. Must have one or more child nodes with tagNASA
,NASA9
, orShomate
.poly_type – A string determining the type of polynomial. One of
NASA
,NASA9
, orShomate
.
This method converts the polynomial data for the
NASA
,NASA9
, andShomate
thermodynamic types into the appropriate YAML structure.
- classmethod to_yaml(representer, data)¶
Serialize the class instance to YAML format suitable for ruamel.yaml.
- Parameters
representer – An instance of a ruamel.yaml representer type.
data – An instance of this class that will be serialized.
The class instance should have an instance attribute called
attribs
which is a dictionary representing the information about the instance. The dictionary is serialized using therepresent_dict
method of therepresenter
.
- class cantera.ctml2yaml.SpeciesTransport(transport: xml.etree.ElementTree.Element)¶
Bases:
object
Represent the Lennard-Jones transport properties of a species.
- Parameters
transport – A
species/transport
XML node.
This class only supports one type of transport model,
gas_transport
.- classmethod to_yaml(representer, data)¶
Serialize the class instance to YAML format suitable for ruamel.yaml.
- Parameters
representer – An instance of a ruamel.yaml representer type.
data – An instance of this class that will be serialized.
The class instance should have an instance attribute called
attribs
which is a dictionary representing the information about the instance. The dictionary is serialized using therepresent_dict
method of therepresenter
.
- class cantera.ctml2yaml.Reaction(reaction: xml.etree.ElementTree.Element, node_motz_wise: bool)¶
Bases:
object
Represent an XML
reaction
node.- Parameters
reaction – The XML node with the reaction information.
node_motz_wise –
True
if thereactionData
node that contains thisreaction
node has themotz_wise
attribute set toTrue
. Otherwise,False
. This argument is used to adjust each reaction instead of setting thePhase
-level option because the reactions are processed before the phases, so it isn’t known at this point what phase these reactions will apply to.
- arrhenius(rate_coeff: xml.etree.ElementTree.Element) ARRHENIUS_TYPE ¶
Process a standard Arrhenius-type reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
- chebyshev(rate_coeff: xml.etree.ElementTree.Element) CHEBYSHEV_TYPE ¶
Process a Chebyshev reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
- chemact(rate_coeff: xml.etree.ElementTree.Element) CHEMACT_TYPE ¶
Process a chemically activated falloff reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
- interface(rate_coeff: xml.etree.ElementTree.Element) INTERFACE_TYPE ¶
Process an interface reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
This represents both interface and electrochemical reactions.
- lindemann(rate_coeff: xml.etree.ElementTree.Element) LINDEMANN_TYPE ¶
Process a Lindemann falloff reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
- plog(rate_coeff: xml.etree.ElementTree.Element) PLOG_TYPE ¶
Process a PLOG reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
- process_arrhenius_parameters(arr_node: Optional[xml.etree.ElementTree.Element]) ARRHENIUS_PARAMS ¶
Process the parameters from an
Arrhenius
child of arateCoeff
node.- Parameters
arr_node – The XML node with the Arrhenius parameters. Must have three child nodes with tags
A
,b
, andE
.
- process_efficiencies(eff_node: xml.etree.ElementTree.Element) EFFICIENCY_PARAMS ¶
Process the efficiency information about a reaction.
- Parameters
eff_node – The XML efficiency node. The text of the node must be a space-delimited string of
species:value
pairs.
- sri(rate_coeff: xml.etree.ElementTree.Element) SRI_TYPE ¶
Process an SRI reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
- threebody(rate_coeff: xml.etree.ElementTree.Element) THREEBODY_TYPE ¶
Process a three-body reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
- classmethod to_yaml(representer, data)¶
Serialize the class instance to YAML format suitable for ruamel.yaml.
- Parameters
representer – An instance of a ruamel.yaml representer type.
data – An instance of this class that will be serialized.
The class instance should have an instance attribute called
attribs
which is a dictionary representing the information about the instance. The dictionary is serialized using therepresent_dict
method of therepresenter
.
- troe(rate_coeff: xml.etree.ElementTree.Element) TROE_TYPE ¶
Process a Troe falloff reaction.
- Parameters
rate_coeff – The XML node with rate coefficient information for this reaction.
Exceptions¶
- exception cantera.ctml2yaml.MissingXMLNode(message: str = '', node: Optional[xml.etree.ElementTree.Element] = None)¶
Bases:
LookupError
Error raised when a required node is missing in the XML tree.
- Parameters
message – The error message to be displayed to the user.
node – The XML node from which the requested node is missing.
- exception cantera.ctml2yaml.MissingXMLAttribute(message: str = '', node: Optional[xml.etree.ElementTree.Element] = None)¶
Bases:
LookupError
Error raised when a required attribute is missing in the XML node.
- Parameters
message – The error message to be displayed to the user.
node – The XML node from which the requested attribute is missing.
- exception cantera.ctml2yaml.MissingNodeText(message: str = '', node: Optional[xml.etree.ElementTree.Element] = None)¶
Bases:
LookupError
Error raised when the text of an XML node is missing.
- Parameters
message – The error message to be displayed to the user.
node – The XML node from which the text is missing.