CTML to YAML conversion#

Module-level documentation#

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() and format_float_scientific() if they are is available, requires numpy >= 1.14. In that case, values with magnitude between 0.01 and 10000 are formatted using format_float_positional () and other values are formatted using format_float_scientific(). If those NumPy functions are not available, returns the repr 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: 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: 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 parseCompString().

cantera.ctml2yaml.clean_node_text(node: 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: Element) → Dict[str, List[Species]]#

Generate lists of Species instances mapped to the speciesData id string.

Parameters:: ctml_tree – The root XML node of the CTML document.

The CTML document is searched for speciesData nodes that contain species child nodes. Each speciesData node must have an id attribute, which is used as the key of the returned dictionary. The values in the dictionary are lists of Species instances representing the species nodes in that speciesData node. The id attribute is also used as the top-level key in the YAML document for that set of species, with the exception that species_data is changed to just species.

If speciesData nodes with the same id attribute are found, only the first section with that id is put into the YAML output file.

cantera.ctml2yaml.create_reactions_from_data_node(ctml_tree: Element) → Dict[str, List[Reaction]]#

Generate lists of Reaction instances mapped to the reactionData id string.

Parameters:: ctml_tree – The root XML node of the CTML document.

The CTML document is searched for reactionData nodes that contain reaction child nodes. Each reactionData node must have an id attribute, which is used as the key of the returned dictionary. The values in the dictionary are lists of Reaction instances representing the reaction nodes in that reactionData node. The id attribute is also used as the top-level key in the YAML document for that set of reactions, with the exception that reaction_data is changed to just reactions.

If reactionData nodes with the same id attribute are found, only the first section with that id is put into the YAML output file.

cantera.ctml2yaml.create_phases_from_data_node(ctml_tree: Element, species_data: Dict[str, List[Species]], reaction_data: Dict[str, List[Reaction]]) → List[Phase]#

Generate a list of Phase instances from XML phase nodes.

Parameters:

ctml_tree – The root XML node of the CTML document.
species_data – Mapping of speciesData id strings to lists of Species instances.
reaction_data – Mapping of reactionData id strings to lists of Reaction instances.

The CTML document is searched for phase nodes, which are processed into Phase instances. For any Lattice-type phases, the child phase nodes are un-nested from their parent node.

cantera.ctml2yaml.convert(inpfile: str | Path = None, outfile: str | Path = None, text: 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.

cantera.ctml2yaml.main()#: Parse command line arguments and pass them to convert.

Conversion classes#

class cantera.ctml2yaml.Phase(phase: Element, species_data: Dict[str, List[Species]], reaction_data: Dict[str, List[Reaction]])#

Bases: object

Represent an XML phase node.

Parameters:

phase – XML node containing a phase definition.
species_data – Mapping of species data sources to lists of Species instances.
reaction_data – Mapping of reaction data sources to lists of Reaction instances.

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 the to_yaml class method.

check_elements(this_phase_species: List[Dict[str, Iterable[str]]], species_data: Dict[str, List[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 instance attribs 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 on speciesData nodes) to lists of Species 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: Element, species_data: Dict[str, List[Species]]) → Dict[str, 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 instance attribs 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 on speciesData nodes) to lists of Species instances.

filter_reaction_list(datasrc: str, filter_text: str, reaction_data: Dict[str, List[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 on reactionData nodes) to lists of Reaction 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: Element, reaction_data: Dict[str, List[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 source id is reaction_data, reformat to just reaction for the YAML file. Otherwise, retain the id as-is.

get_species_array(speciesArray_node: 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 source id is species_data, reformat to just species for the YAML file. Otherwise, retain the id as-is.

get_tabulated_thermo(tab_thermo_node: 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: 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 the A_debye node, as well as any interaction parameters between species.

ideal_molal_solution(activity_coeffs: Element) → Dict[str, str | QUANTITY]#

Process the cutoff data in an IdealMolalSolution phase-thermo type.

Parameters:: activity_coeffs – XML activityCoefficients node. For the IdealMolalSolution 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 the activityCoefficients node.

margules(activity_coeffs: Element) → List[Dict[str, List[str | QUANTITY]]]#

Process activity coefficients for a Margules phase-thermo type.

Parameters:: activity_coeffs – XML activityCoefficients node. For the Margules 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 the binaryNeutralSpeciesParameters 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: Element, species_data: Dict[str, List[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 instance attribs 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 on speciesData nodes) to lists of Species instances.

The YAML format moves the specification of Redlich-Kwong binary interaction parameters from the Phase node into the Species nodes. This modifies the Species objects in-place in the species_data list.

move_density_to_species(this_phase_species: List[Dict[str, Iterable[str]]], phase_thermo: Element, species_data: Dict[str, List[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 instance attribs 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 on speciesData nodes) to lists of Species instances.

The YAML format moves the specification of density for StoichSubstance phase-thermo types from the Phase node into the Species nodes. This modifies the Species objects in-place in the species_data list.

redlich_kister(activity_coeffs: Element) → List[Dict[str, List[str | QUANTITY]]]#

Process activity coefficients for a Redlich-Kister phase-thermo type.

Parameters:: activity_coeffs – XML activityCoefficients node. For the RedlichKister 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 a binaryNeutralSpeciesParameters 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 the represent_dict method of the representer.

class cantera.ctml2yaml.Species(species_node: 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 the to_yaml class method.

hkft(species_node: 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 the standardState node.

process_standard_state_node(species_node: 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 or HKFT, this function doesn’t do anything to the Species object. Otherwise, the model data is put into the YAML equation-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 the represent_dict method of the representer.

class cantera.ctml2yaml.SpeciesThermo(thermo: 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 tag NASA, NASA9, const_cp, Shomate, or Mu0.

This class will process the Species-level thermodynamic information for the polynomial thermo types. The pressure-dependent standard state types are processed directly in the Species instance.

Mu0(thermo: Element) → Dict[str, 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 tag Mu0.

NASA(thermo: Element) → Dict[str, 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 tag NASA.

NASA9(thermo: Element) → Dict[str, 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 tag NASA9.

Shomate(thermo: Element) → Dict[str, 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 tag Shomate.

const_cp(thermo: Element) → Dict[str, 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 tag const_cp.

process_polynomial(thermo: 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 tag NASA, NASA9, or Shomate.
poly_type – A string determining the type of polynomial. One of NASA, NASA9, or Shomate.

This method converts the polynomial data for the NASA, NASA9, and Shomate 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 the represent_dict method of the representer.

class cantera.ctml2yaml.SpeciesTransport(transport: 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 the represent_dict method of the representer.

class cantera.ctml2yaml.Reaction(reaction: 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 the reactionData node that contains this reaction node has the motz_wise attribute set to True. Otherwise, False. This argument is used to adjust each reaction instead of setting the Phase-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: 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: Element) → CHEBYSHEV_TYPE#

Process a Chebyshev reaction.

Parameters:: rate_coeff – The XML node with rate coefficient information for this reaction.

chemact(rate_coeff: 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: 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: Element) → LINDEMANN_TYPE#

Process a Lindemann falloff reaction.

Parameters:: rate_coeff – The XML node with rate coefficient information for this reaction.

plog(rate_coeff: 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: Element | None) → ARRHENIUS_PARAMS#

Process the parameters from an Arrhenius child of a rateCoeff node.

Parameters:: arr_node – The XML node with the Arrhenius parameters. Must have three child nodes with tags A, b, and E.

process_efficiencies(eff_node: 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: Element) → SRI_TYPE#

Process an SRI reaction.

Parameters:: rate_coeff – The XML node with rate coefficient information for this reaction.

threebody(rate_coeff: 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 the represent_dict method of the representer.

troe(rate_coeff: 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: Element | None = 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: Element | None = 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: Element | None = 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.