Converters

Module with converters from other formats.

exception pyked.converters.KeywordError(*keywords)[source]

Raised for errors in keyword parsing.

exception pyked.converters.MissingAttributeError(*keywords)[source]

Raised for missing required attribute.

exception pyked.converters.MissingElementError(*keywords)[source]

Raised for missing required elements.

exception pyked.converters.ParseError[source]

Base class for errors.

pyked.converters.ReSpecTh_to_ChemKED(filename_xml, file_author='', file_author_orcid='', *, validate=False, apparatus_kind=None)[source]

Convert ReSpecTh XML file to ChemKED-compliant dictionary.

Parameters:

  • filename_xml (str) – Name of ReSpecTh XML file to be converted.

  • file_author (str, optional) – Name to override original file author

  • file_author_orcid (str, optional) – ORCID of file author

  • validate (bool, optional, keyword-only) – Set to True to validate the resulting property dictionary with ChemKED. Set to False if the file is being loaded and will be validated at some other point before use.

  • apparatus_kind (str, optional, keyword-only) – ChemKED apparatus kind to use instead of the one derived from the file. ReSpecTh often records only the generic flame apparatus, in which case the specific burner is known from the article rather than from the file.

pyked.converters.apparatus_kinds = {'bunsen burner': 'bunsen burner', 'burner stabilized flame': 'burner stabilized flame', 'counterflow twin flame': 'counterflow twin flame', 'flame cone method': 'bunsen burner', 'flow reactor': 'flow reactor', 'heat flux burner': 'heat flux burner', 'jet stirred reactor': 'jet stirred reactor', 'outwardly propagating spherical flame': 'outwardly propagating spherical flame', 'rapid compression machine': 'rapid compression machine', 'shock tube': 'shock tube'}

ReSpecTh apparatus/kind mapped to ChemKED apparatus.kind

Only names that identify the apparatus on their own. The vessel material that ReSpecTh appends in parentheses, as in flow reactor (quartz), is stripped before lookup because ChemKED has no field for it.

Type:

dict

pyked.converters.apparatus_kinds_by_experiment = {('stirred reactor', 'jet stirred reactor measurement'): 'jet stirred reactor'}

(ReSpecTh apparatus/kind, experimentType) mapped to ChemKED apparatus.kind

For kinds that name how a reactor is operated rather than which apparatus it is, and so can only be mapped when the experiment type corroborates them.

Type:

dict

pyked.converters.attach_value_metadata(properties, metadata)[source]

Attach uncertainty metadata to the quantities it describes.

ReSpecTh states uncertainties as standalone properties that point at another quantity, so each one is attached to that quantity wherever it ended up: on every datapoint, on the shared common property, or on a species profile.

Parameters:

  • properties (dict) – Partially built ChemKED dictionary, with datapoints

  • metadata (list) – Descriptors from get_value_metadata

pyked.converters.auxiliary_axes = {'distance': 'distance', 'residence-time': 'time', 'time': 'time'}

Speciation axis name mapped to the axis name of an auxiliary profile against it

auxiliary-profiles.independent.name is a coordinate along the reactor or flame rather than the full set of names independent-variables allows, and a residence time is a time coordinate.

Type:

dict

pyked.converters.auxiliary_profile_types = ['temperature', 'pressure', 'volume', 'velocity']

Quantities that a speciation datapoint can carry as an auxiliary profile

Type:

list

pyked.converters.check_units(name, field, unit_str)[source]

Ensure ReSpecTh units are dimensionally consistent with the ChemKED field.

Parameters:

  • name (str) – ReSpecTh property name, used in the error message

  • field (str) – ChemKED field name, used to look up the expected units

  • unit_str (str) – Units as written in the ReSpecTh file

Raises:

KeywordError – If the units cannot be parsed or are incompatible with the field

pyked.converters.ck2respth(argv=None)[source]

Command-line entry point for converting a ChemKED YAML file to a ReSpecTh XML file.

pyked.converters.common_property_fields = {'environment temperature': 'environment-temperature', 'equivalence ratio': 'equivalence-ratio', 'exchange area': 'exchange-area', 'flow rate': 'flow-rate', 'global heat exchange coefficient': 'global-heat-exchange-coefficient', 'ignition delay': 'ignition-delay', 'laminar burning velocity': 'laminar-burning-velocity', 'pressure': 'pressure', 'pressure in reference state': 'pressure-in-reference-state', 'pressure rise': 'pressure-rise', 'reactor diameter': 'reactor-diameter', 'reactor length': 'reactor-length', 'residence time': 'residence-time', 'temperature': 'temperature', 'temperature in reference state': 'temperature-in-reference-state', 'volume': 'reactor-volume', 'volumetric flow rate in reference state': 'volumetric-flow-in-reference-state'}

ReSpecTh commonProperties property name mapped to ChemKED field name

Type:

dict

pyked.converters.composition_unit_typos = ['mole faction']

Misspelled composition units in the ReSpecTh corpus, accepted with a warning

Kept out of the error message, since they are tolerated rather than recommended.

Type:

list

pyked.converters.composition_units = {'mass fraction': ('mass fraction', 1.0, None), 'mol/L': ('mol/L', 1.0, None), 'mol/cm3': ('mol/cm3', 1.0, None), 'mol/dm3': ('mol/dm3', 1.0, None), 'mol/m3': ('mol/m3', 1.0, None), 'mole faction': ('mole fraction', 1.0, 'Assuming misspelled composition units "mole faction" mean mole fraction'), 'mole fraction': ('mole fraction', 1.0, None), 'mole percent': ('mole percent', 1.0, None), 'percent': ('mole percent', 1.0, 'Assuming percent in composition means mole percent'), 'ppb': ('mole fraction', 1e-09, 'Assuming molar ppb in composition and converting to mole fraction'), 'ppm': ('mole fraction', 1e-06, 'Assuming molar ppm in composition and converting to mole fraction')}

ReSpecTh composition units mapped to (ChemKED kind, scale factor, warning)

Type:

dict

pyked.converters.datagroup_properties = ['temperature', 'pressure', 'ignition delay', 'pressure rise']

Valid properties for a ReSpecTh dataGroup

Type:

list

pyked.converters.dimensionless_units = ['unitless', '[-]', 'dimensionless', '-', '']

Ways ReSpecTh spells a dimensionless quantity

Type:

list

pyked.converters.experiment_types = {'burner stabilized flame speciation measurement': 'speciation measurement', 'concentration time profile measurement': 'speciation measurement', 'ignition delay measurement': 'ignition delay', 'jet stirred reactor measurement': 'speciation measurement', 'laminar burning velocity measurement': 'laminar burning velocity measurement', 'laminar flame speed measurement': 'laminar burning velocity measurement', 'outlet concentration measurement': 'speciation measurement'}

ReSpecTh experimentType mapped to ChemKED experiment-type

Type:

dict

pyked.converters.flame_modes = {'burner stabilized': 'burner stabilized flame', 'burner-stabilized': 'burner stabilized flame', 'constant volume combustion chamber': 'outwardly propagating spherical flame', 'counterflow': 'counterflow twin flame', 'ctf': 'counterflow twin flame', 'fcm': 'bunsen burner', 'flame cone method': 'bunsen burner', 'heat flux burner': 'heat flux burner', 'hfm': 'heat flux burner', 'opf': 'outwardly propagating spherical flame', 'spherical': 'outwardly propagating spherical flame', 'twin flat': 'counterflow twin flame'}

ReSpecTh apparatus/mode mapped to ChemKED apparatus.kind

Only consulted when apparatus/kind is the generic flame. Modes that only describe the mixture or flow, such as premixed and laminar, are absent on purpose: they do not identify a burner, so a file carrying nothing else cannot be converted without curation.

Type:

dict

pyked.converters.format_value_metadata(item, factor=None, numeric=False)[source]

Turn one ReSpecTh uncertainty descriptor into ChemKED metadata keys.

Parameters:

  • item (dict) – Descriptor from get_value_metadata or a dataGroup metadata column

  • factor (float, optional) – Scale factor to apply, used when the described quantity is a composition whose units were converted, e.g. ppm to mole fraction

  • numeric (bool, optional) – Store the value as a number rather than as the text of the file. Composition amounts and profile values are plain numbers with the units stated elsewhere, so an uncertainty about one of them is a number too.

Returns:

ChemKED uncertainty or evaluated standard deviation metadata

Return type:

dict

Raises:

KeywordError – If the kind attribute is neither absolute nor relative

pyked.converters.get_apparatus_kind(root, experiment_type=None)[source]

Map the ReSpecTh apparatus onto a ChemKED apparatus kind.

ReSpecTh often gives the generic kind flame and leaves the configuration to one or more mode elements, so both are consulted. Modes that ReSpecTh flags as uncertain with a trailing question mark are ignored.

Parameters:

  • root (Element) – Root of ReSpecTh XML file

  • experiment_type (str, optional) – The ReSpecTh experimentType, which names the apparatus a second time for kinds that do not identify it on their own

Returns:

The ChemKED apparatus.kind

Return type:

str

Raises:
pyked.converters.get_common_properties(root)[source]

Read common properties from root of ReSpecTh XML file.

Uncertainty and evaluated standard deviation properties are skipped here because they are metadata about another quantity rather than quantities in their own right; get_value_metadata collects them so they can be attached to whatever they describe.

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

Dictionary with common properties

Return type:

properties (dict)

pyked.converters.get_composition(elem, capitalize=False)[source]

Read a ReSpecTh initial composition property into a ChemKED composition.

Parameters:

  • elem (Element) – The initial composition property element

  • capitalize (bool, optional) – Capitalize the units error message

Returns:

ChemKED composition with species and kind

Return type:

dict

Raises:

KeywordError – If the composition units are unsupported or inconsistent

pyked.converters.get_composition_amount(units, value, capitalize=False)[source]

Convert a ReSpecTh composition amount to a ChemKED amount and kind.

Parameters:

  • units (str) – Composition units as written in the ReSpecTh file

  • value (str) – Amount as written in the ReSpecTh file

  • capitalize (bool, optional) – Capitalize the units error message, matching the wording used for common properties

Returns:

The amount as a float and the ChemKED composition kind

Return type:

tuple

Raises:

KeywordError – If the composition units are not supported

pyked.converters.get_datagroup_columns(dataGroup, root=None)[source]

Describe the columns of a ReSpecTh dataGroup.

Parameters:

  • dataGroup (Element) – A dataGroup element

  • root (Element, optional) – Root of the file, used to resolve an uncertainty that points at a column by its label or id

Returns:

One dict per column, in file order, with the ReSpecTh name, units, id, the species it refers to if any, and the uncertainty attributes if it is a metadata column

Return type:

list

Raises:
pyked.converters.get_datagroup_rows(dataGroup, columns)[source]

Read the dataPoint rows of a ReSpecTh dataGroup.

Parameters:
Returns:

One dict per dataPoint, mapping column id to the text of the value

Return type:

list

Raises:
pyked.converters.get_datapoints(root)[source]

Parse datapoints with ignition delay from file.

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

Dictionary with ignition delay data

Return type:

properties (dict)

pyked.converters.get_experiment_kind(root, apparatus_kind=None)[source]

Read the experiment type and apparatus from the root of a ReSpecTh XML file.

Parameters:

  • root (Element) – Root of ReSpecTh XML file

  • apparatus_kind (str, optional) – ChemKED apparatus kind to use instead of the one derived from the file, for files whose apparatus is only known from the article

Returns:

Dictionary with experiment type and apparatus information.

Return type:

properties (dict)

pyked.converters.get_file_metadata(root)[source]

Read and parse ReSpecTh XML file metadata (file author, version, etc.)

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

Dictionary with file metadata

Return type:

properties (dict)

pyked.converters.get_ignition_type(root)[source]

Gets ignition type and target.

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

Dictionary with ignition type/target information

Return type:

properties (dict)

pyked.converters.get_lbv_datapoints(root)[source]

Parse laminar burning velocity datapoints from a ReSpecTh file.

Every dataPoint in the first dataGroup becomes one ChemKED datapoint, with the composition columns gathered into that datapoint’s composition.

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

ChemKED datapoints

Return type:

list

Raises:

KeyError – If a column is not a valid property for this experiment type

pyked.converters.get_reference(root)[source]

Read reference info from root of ReSpecTh XML file.

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

Dictionary with reference information

Return type:

properties (dict)

pyked.converters.get_reference_details(elem)[source]

Read bibliographic details written directly in a ReSpecTh 2.x bibliographyLink.

ReSpecTh 2.x records the reference in child elements rather than the doi and preferredKey attributes used by 1.x, so the citation can be built without a DOI lookup.

Parameters:

elem (Element) – The bibliographyLink element

Returns:

Reference information, empty if the element carries no usable details

Return type:

dict

pyked.converters.get_speciation_datapoints(root)[source]

Parse speciation datapoints from a ReSpecTh file.

Each dataGroup becomes one ChemKED datapoint: the first column that is not a species is the swept axis, the species columns become concentration profiles, and any remaining measured quantity becomes an auxiliary profile.

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

ChemKED datapoints

Return type:

list

Raises:

  • KeyError – If a column is not a valid property for this experiment type

  • NotImplementedError – If the file cannot be represented by the ChemKED speciation schema

pyked.converters.get_value_metadata(root)[source]

Read uncertainty and evaluated standard deviation common properties.

ReSpecTh states these as properties in their own right, tied by the reference attribute (and a speciesLink when the reference is a composition) to the quantity they describe. ChemKED instead stores them alongside that quantity, so they are collected separately here and attached by attach_value_metadata.

Parameters:

root (Element) – Root of ReSpecTh XML file

Returns:

One dict per uncertainty or evaluated standard deviation property

Return type:

list

Raises:

KeywordError – If a property is missing the reference or kind attribute

pyked.converters.ignition_target_values = ['temperature', 'pressure', 'OH', 'OH*', 'CH', 'CH*', 'NH3', 'CO2', 'N2O', 'CH4', 'CO', 'H2O', 'C2', 'O', 'CH3OH', 'CH3', 'O2', 'soot']

Ignition targets the ChemKED schema allows

Kept in step with ignition-type.target in ignition_delay_schema.yaml.

Type:

list

pyked.converters.ignition_targets = {'CHEX': 'CH*', 'OHEX': 'OH*', 'P': 'pressure', 'T': 'temperature'}

ReSpecTh ignitionType target abbreviations mapped to ChemKED target names

Type:

dict

pyked.converters.ignition_type_values = ['d/dt max', 'max', '1/2 max', 'min', 'd/dt max extrapolated', 'd/dt min extrapolated', 'relative concentration', 'd/dt second max', 'concentration', 'relative increase']

Ignition types the ChemKED schema allows

Kept in step with ignition-type.type in ignition_delay_schema.yaml.

Type:

list

pyked.converters.ignition_types = {'baseline max intercept from d/dt': 'd/dt max extrapolated', 'baseline min intercept from d/dt': 'd/dt min extrapolated'}

ReSpecTh ignitionType type names mapped to ChemKED type names

Type:

dict

pyked.converters.independent_variables = {'distance': 'distance', 'equivalence ratio': 'equivalence-ratio', 'initial composition': 'initial-composition', 'pressure': 'pressure', 'residence time': 'residence-time', 'temperature': 'temperature', 'time': 'time'}

ReSpecTh dataGroup property name mapped to a speciation independent-variable name

Type:

dict

pyked.converters.main(argv=None)[source]

General function for converting between ReSpecTh and ChemKED files based on extension.

pyked.converters.merge_value_metadata(value, metadata)[source]

Add uncertainty metadata to a ChemKED value list, in place.

Parameters:
pyked.converters.normalize_units(unit_str)[source]

Convert a ReSpecTh unit string into one Pint can parse.

Parameters:

unit_str (str) – Unit string as written in the ReSpecTh file

Returns:

Equivalent unit string in Pint syntax

Return type:

str

pyked.converters.reconcile_composition_kind(species, kinds)[source]

Settle on one composition kind for a set of species amounts.

ReSpecTh files sometimes state one species in mole percent and another in mole fraction. That pair converts exactly, so the amounts are put on a mole fraction basis; any other mixture is an error because ChemKED stores a single kind per composition.

Parameters:

  • species (list) – ChemKED species dictionaries, modified in place

  • kinds (list) – The composition kind read for each species, in the same order

Returns:

The single ChemKED composition kind

Return type:

str

Raises:

KeywordError – If the kinds cannot be reconciled

pyked.converters.resolve_reference(root, reference)[source]

Work out which quantity a ReSpecTh uncertainty refers to.

The reference attribute usually names a property, but part of the corpus points at a column by its label or its id instead, as in reference="Sl" for the column labelled Sl or reference="x1" for the first column.

Parameters:

  • root (Element) – Root of ReSpecTh XML file

  • reference (str) – The reference attribute as written

Returns:

The property name referred to, and the species it belongs to if the referenced property names one, otherwise None

Return type:

tuple

pyked.converters.respth2ck(argv=None)[source]

Command-line entry point for converting a ReSpecTh XML file to a ChemKED YAML file.

pyked.converters.unit_aliases = {'Torr': 'torr'}

ReSpecTh unit strings that Pint spells differently

Type:

dict

pyked.converters.value_with_units(value, unit_str)[source]

Build a ChemKED value-with-units string from ReSpecTh text.

Parameters:

  • value (str) – Value as written in the ReSpecTh file

  • unit_str (str) – Units as written in the ReSpecTh file

Returns:

Value and units joined in a form the ChemKED schema accepts

Return type:

str