Converters¶
Module with converters from other formats.
- exception pyked.converters.MissingAttributeError(*keywords)[source]¶
Raised for missing required attribute.
- exception pyked.converters.MissingElementError(*keywords)[source]¶
Raised for missing required elements.
- 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 authorfile_author_orcid (
str, optional) – ORCID of file authorvalidate (
bool, optional, keyword-only) – Set toTrueto validate the resulting property dictionary withChemKED. Set toFalseif 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 genericflameapparatus, 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/kindmapped to ChemKEDapparatus.kindOnly 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:
- pyked.converters.apparatus_kinds_by_experiment = {('stirred reactor', 'jet stirred reactor measurement'): 'jet stirred reactor'}¶
(ReSpecTh
apparatus/kind,experimentType) mapped to ChemKEDapparatus.kindFor 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:
- 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 datapointsmetadata (
list) – Descriptors fromget_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.nameis a coordinate along the reactor or flame rather than the full set of namesindependent-variablesallows, and a residence time is a time coordinate.- Type:
- pyked.converters.auxiliary_profile_types = ['temperature', 'pressure', 'volume', 'velocity']¶
Quantities that a speciation datapoint can carry as an auxiliary profile
- Type:
- pyked.converters.check_units(name, field, unit_str)[source]¶
Ensure ReSpecTh units are dimensionally consistent with the ChemKED field.
- Parameters:
- 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
commonPropertiesproperty name mapped to ChemKED field name- Type:
- 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:
- 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:
- pyked.converters.datagroup_properties = ['temperature', 'pressure', 'ignition delay', 'pressure rise']¶
Valid properties for a ReSpecTh dataGroup
- Type:
- pyked.converters.dimensionless_units = ['unitless', '[-]', 'dimensionless', '-', '']¶
Ways ReSpecTh spells a dimensionless quantity
- Type:
- 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
experimentTypemapped to ChemKEDexperiment-type- Type:
- 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/modemapped to ChemKEDapparatus.kindOnly consulted when
apparatus/kindis the genericflame. Modes that only describe the mixture or flow, such aspremixedandlaminar, are absent on purpose: they do not identify a burner, so a file carrying nothing else cannot be converted without curation.- Type:
- pyked.converters.format_row_uncertainty(item)[source]¶
Say what the uncertainty at the end of each profile row is, as ChemKED metadata keys.
These are the keys of
format_value_metadatawithout the value, which is in the rows. An absolute, symmetric uncertainty with nothing else stated is what the last value of a row means when no key says otherwise, so it needs none.- Parameters:
item (
dict) – Descriptor of the uncertainty column, fromget_datagroup_columns- Returns:
Uncertainty metadata keys without a value, empty for an absolute uncertainty with no sourcetype
- Return type:
- Raises:
KeywordError – If the
kindattribute is neither absolute nor relativeNotImplementedError – If the column is one bound of an asymmetric uncertainty
- pyked.converters.format_value_metadata(item, factor=None, numeric=False)[source]¶
Turn one ReSpecTh uncertainty descriptor into ChemKED metadata keys.
- Parameters:
item (
dict) – Descriptor fromget_value_metadataor a dataGroup metadata columnfactor (
float, optional) – Scale factor to apply, used when the described quantity is a composition whose units were converted, e.g. ppm to mole fractionnumeric (
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:
- Raises:
KeywordError – If the
kindattribute is neither absolute nor relative
- pyked.converters.fraction_kinds = {'mole fraction': 1.0, 'mole percent': 0.01}¶
Composition kinds that state one quantity on different scales, mapped to the mole fraction that one unit of the kind is
- Type:
- 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
flameand leaves the configuration to one or moremodeelements, so both are consulted. Modes that ReSpecTh flags as uncertain with a trailing question mark are ignored.- Parameters:
- Returns:
The ChemKED
apparatus.kind- Return type:
- Raises:
MissingElementError – If
apparatus/kindis absent or emptyNotImplementedError – If the apparatus cannot be identified from the file alone
- 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_metadatacollects them so they can be attached to whatever they describe.
- pyked.converters.get_composition(elem, capitalize=False)[source]¶
Read a ReSpecTh
initial compositionproperty into a ChemKED composition.- Parameters:
- Returns:
ChemKED composition with
speciesandkind- Return type:
- 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:
- Returns:
The amount as a
floatand the ChemKED composition kind- Return type:
- 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:
- Returns:
One
dictper 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:
- Raises:
MissingElementError – If the dataGroup declares no properties
MissingAttributeError – If a metadata column has no
referenceorkind
- pyked.converters.get_datagroup_rows(dataGroup, columns)[source]¶
Read the dataPoint rows of a ReSpecTh dataGroup.
- Parameters:
dataGroup (
Element) – AdataGroupelementcolumns (
list) – Column descriptors fromget_datagroup_columns
- Returns:
One
dictper dataPoint, mapping column id to the text of the value- Return type:
- Raises:
MissingElementError – If the dataGroup has no dataPoints
KeywordError – If a value refers to a column the dataGroup does not declare
- 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:
- 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.)
- 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.
- 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
doiandpreferredKeyattributes used by 1.x, so the citation can be built without a DOI lookup.
- 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. The file’s time shift is given to every datapoint.
- Parameters:
root (
Element) – Root of ReSpecTh XML file- Returns:
ChemKED datapoints
- Return type:
- 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_time_shift(elem)[source]¶
Read a ReSpecTh
timeshiftelement as a ChemKED time shift.ReSpecTh states once for the file how the zero of its time axis was placed: where the amount of the
targetspecies has fallen to half, for example, or by a relativeamount.- Parameters:
elem (
Element) – Thetimeshiftelement- Returns:
ChemKED
time-shift- Return type:
- Raises:
MissingAttributeError – If the element has no
targetortype
- 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
referenceattribute (and aspeciesLinkwhen 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 byattach_value_metadata.- Parameters:
root (
Element) – Root of ReSpecTh XML file- Returns:
One
dictper uncertainty or evaluated standard deviation property- Return type:
- Raises:
KeywordError – If a property is missing the
referenceorkindattribute
- 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.targetinignition_delay_schema.yaml.- Type:
- pyked.converters.ignition_targets = {'CHEX': 'CH*', 'OHEX': 'OH*', 'P': 'pressure', 'T': 'temperature'}¶
ReSpecTh
ignitionTypetarget abbreviations mapped to ChemKED target names- Type:
- 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.typeinignition_delay_schema.yaml.- Type:
- 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
ignitionTypetype names mapped to ChemKED type names- Type:
- 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:
- pyked.converters.main(argv=None)[source]¶
General function for converting between ReSpecTh and ChemKED files based on extension.
- pyked.converters.merge_profile_metadata(profile, metadata)[source]¶
Add uncertainty metadata to a concentration profile, in place.
One mapping holds both the uncertainty of the whole profile and what the last value of each row is, which is described by keys given without a value (see
row_uncertainty_kinds). So each kind of uncertainty can describe either the rows or the whole profile.- Parameters:
profile (
dict) – ChemKED concentration profilemetadata (
dict) – Metadata keys fromformat_value_metadataorformat_row_uncertainty
- Raises:
NotImplementedError – If one kind of uncertainty would describe both the rows and the whole profile
- pyked.converters.merge_value_metadata(value, metadata)[source]¶
Add uncertainty metadata to a ChemKED value list, in place.
- Parameters:
value (
list) – ChemKED value list, either[value]or[value, metadata]metadata (
dict) – Metadata keys fromformat_value_metadata
- pyked.converters.normalize_doi(doi)[source]¶
Strip a resolver prefix from a DOI as ReSpecTh sometimes writes it.
A DOI is the bare
10.xxxx/...identifier. Some ReSpecTh files give a resolvable URL instead, as indoi.org/10.1016/j.proci.2016.05.048, which no lookup accepts.
- pyked.converters.normalize_units(unit_str)[source]¶
Convert a ReSpecTh unit string into one Pint can parse.
- pyked.converters.normalize_value(value)[source]¶
Normalize a numeric value as written in ReSpecTh for use in ChemKED.
Expands Fortran-style exponents written without the
e, which Pint cannot read, and strips leading zeros, which YAML would otherwise take for octal.The digits the source reported are otherwise left alone. A trailing zero is a significant figure, so reformatting through a float would turn a reported
14.70into14.7and record three significant figures where the authors stated four.
- 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:
- Returns:
The single ChemKED composition kind
- Return type:
- 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
referenceattribute usually names a property, but part of the corpus points at a column by itslabelor itsidinstead, as inreference="Sl"for the column labelledSlorreference="x1"for the first column.
- pyked.converters.respth2ck(argv=None)[source]¶
Command-line entry point for converting a ReSpecTh XML file to a ChemKED YAML file.
- pyked.converters.species_identifier(identifiers)[source]¶
Choose the identifier of a ChemKED species from those ReSpecTh gives.
A ReSpecTh
speciesLinkmay give an InChI, a SMILES, or both. The InChI is kept when it is given, and the SMILES only when it is not, so a species keeps an identifier either way. A ChemKED composition species must be identified by exactly one ofInChI,SMILES, andatomic-composition; profile and swept species follow the same rule, so the converted files are unchanged for every species ReSpecTh gives an InChI.
- pyked.converters.uncertainty_factor(item, profile_units, species)[source]¶
Scale factor that states an uncertainty about a profile in the units of the profile.
ReSpecTh gives an uncertainty units of its own, which need not be those of the composition it describes: a profile in ppm often has an evaluated standard deviation in mole fraction. The profile is converted to its ChemKED kind, so an absolute uncertainty is converted to the same kind. A relative uncertainty is a fraction of the amount, so it is not rescaled.
Some cannot be converted. A mole fraction is stated as a concentration only with the density of the mixture at each point, which the file does not give, so such an uncertainty is dropped with a warning rather than attached in the wrong units.
- Parameters:
- Returns:
The factor to multiply the uncertainty by, or
Noneif it cannot be stated in the units of the profile- Return type:
- pyked.converters.unit_aliases = {'Torr': 'torr'}¶
ReSpecTh unit strings that Pint spells differently
- Type: