Skip to main content

# 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()` 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 `compositionMap::parseCompString` in `base/stringUtils.cpp`.

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: Optional[Union[str, Path]] = None, outfile: Optional[Union[str, 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.

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, 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 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, Union[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[Union[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[Union[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, 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 tag `Mu0`.

  NASA(thermo: 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 tag `NASA`.

  NASA9(thermo: 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 tag `NASA9`.

  Shomate(thermo: 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 tag `Shomate`.

  const_cp(thermo: 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 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: Optional[Element]) → 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: Optional[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[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[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.