ChemKED

Main ChemKED module

class pyked.chemked.Apparatus(kind: str | None, institution: str | None, facility: str | None)[source]

Information about the experimental apparatus used to generate the data

facility: str | None

(str) The particular experimental facility at the location

institution: str | None

(str) The institution where the experiment is located

kind: str | None

(str) The kind of experimental apparatus

class pyked.chemked.ChemKED(yaml_file=None, dict_input=None, *, skip_validation=False)[source]

Main ChemKED class.

The ChemKED class stores information about the contents of a ChemKED database file. It stores each datapoint associated with the database and provides access the the reference information, versions, and file author.

Parameters:

  • yaml_file (str, optional) – The filename of the YAML database in ChemKED format.

  • dict_input (dict, optional) – A dictionary with the parsed ouput of YAML file in ChemKED format.

  • skip_validation (bool, optional) – Whether validation of the ChemKED should be done. Must be supplied as a keyword-argument.

datapoints

List of DataPoint objects storing each datapoint in the database.

Type:

list

reference

Attributes include volume, journal, doi, authors, detail, year, and pages describing the reference from which the datapoints are derived.

Type:

namedtuple

apparatus

Attributes include kind of experimental apparatus, and the institution and facility where the experimental apparatus is located.

Type:

namedtuple

chemked_version

Version of the ChemKED database schema used in this file.

Type:

str

experiment_type

Type of exeperimental data contained in this database.

Type:

str

file_author

Information about the author of the ChemKED database file.

Type:

dict

file_version

Version of the ChemKED database file.

Type:

str

_properties

Original dictionary read from ChemKED database file, meant for internal use.

Type:

dict

convert_to_ReSpecTh(filename)[source]

Convert ChemKED record to ReSpecTh XML file.

This converter uses common information in a ChemKED file to generate a ReSpecTh XML file. Note that some information may be lost, as ChemKED stores some additional attributes.

Parameters:

filename (str) – Filename for output ReSpecTh XML file.

Example

>>> dataset = ChemKED(yaml_file)
>>> dataset.convert_to_ReSpecTh(xml_file)
classmethod from_respecth(filename_xml, file_author='', file_author_orcid='')[source]

Construct a ChemKED instance directly from a ReSpecTh file.

Parameters:

  • filename_xml (str) – Filename of the ReSpecTh-formatted XML file to be imported

  • file_author (str, optional) – File author to be added to the list generated from the XML file

  • file_author_orcid (str, optional) – ORCID for the file author being added to the list of file authors

Returns:

Instance of the ChemKED class containing the data in filename_xml.

Return type:

ChemKED

Examples

>>> ck = ChemKED.from_respecth('respecth_file.xml')
>>> ck = ChemKED.from_respecth('respecth_file.xml', file_author='Bryan W. Weber')
>>> ck = ChemKED.from_respecth('respecth_file.xml', file_author='Bryan W. Weber',
                               file_author_orcid='0000-0000-0000-0000')
get_dataframe(output_columns=None)[source]

Get a Pandas DataFrame of the datapoints in this instance.

Parameters:

output_columns (list, optional) –

List of strings specifying the columns to include in the output DataFrame. The default is None, which outputs all of the columns. Options include (not case sensitive):

  • Temperature

  • Pressure

  • Ignition Delay

  • Composition

  • Equivalence Ratio

  • Reference

  • Apparatus

  • Experiment Type

  • File Author

  • File Version

  • ChemKED Version

In addition, specific fields from the Reference and Apparatus attributes can be included by specifying the name after a colon. These options are:

  • Reference:Volume

  • Reference:Journal

  • Reference:DOI

  • Reference:Authors

  • Reference:Detail

  • Reference:Year

  • Reference:Pages

  • Apparatus:Kind

  • Apparatus:Facility

  • Apparatus:Institution

Only the first author is printed when Reference or Reference:Authors is selected because the whole author list may be quite long.

Note

If the Composition is selected as an output type, the composition specified in the DataPoint is used. No attempt is made to convert to a consistent basis; mole fractions will remain mole fractions, mass fractions will remain mass fractions, and mole percent will remain mole percent. Therefore, it is possible to end up with more than one type of composition specification in a given column. However, if the composition is included in the resulting dataframe, the type of each composition will be specified by the “Kind” field in each row.

Examples

>>> df = ChemKED(yaml_file).get_dataframe()
>>> df = ChemKED(yaml_file).get_dataframe(['Temperature', 'Ignition Delay'])
Returns:

Contains the information regarding each point in the datapoints

attribute

Return type:

DataFrame

validate_yaml(properties)[source]

Validate the parsed YAML file for adherance to the ChemKED format.

Parameters:

properties (dict) – Dictionary created from the parsed YAML file

Raises:

ValueError – If the YAML file cannot be validated, a ValueError is raised whose string contains the errors that are present.

write_file(filename, *, overwrite=False)[source]

Write new ChemKED YAML file based on object.

Parameters:

  • filename (str) – Filename for target YAML file

  • overwrite (bool, optional) – Whether to overwrite file with given name if present. Must be supplied as a keyword-argument.

Raises:

NameError – If filename is already present, and overwrite is not True.

Example

>>> dataset = ChemKED(yaml_file)
>>> dataset.write_file(new_yaml_file)
class pyked.chemked.Composition(species_name: str, InChI: str | None, SMILES: str | None, atomic_composition: dict | None, amount: Quantity)[source]

Detail of the initial composition of the mixture for the experiment

InChI: str | None

(str) The InChI identifier for the species

SMILES: str | None

(str) The SMILES identifier for the species

amount: Quantity

(Quantity) The amount of this species

atomic_composition: dict | None

(dict) The atomic composition of the species

species_name: str

(str) The name of the species

class pyked.chemked.DataPoint(properties)[source]

Class for a single datapoint.

The DataPoint class stores the information associated with a single data point in the dataset parsed from the ChemKED YAML input.

Parameters:

properties (dict) – Dictionary adhering to the ChemKED format for datapoints

composition

List of dictionaries representing the species and their quantities

Type:

list

ignition_delay

The ignition delay of the experiment

Type:

pint.Quantity

temperature

The temperature of the experiment

Type:

pint.Quantity

pressure

The pressure of the experiment

Type:

pint.Quantity

pressure_rise

The amount of pressure rise during the induction period of a shock tube experiment.

Type:

pint.Quantity, optional

compression_time

The compression time for an RCM experiment.

Type:

pint.Quantity, optional

compressed_pressure

The pressure at the end of compression for an RCM experiment.

Type:

pint.Quantity, optional

compressed_temperature

The temperature at the end of compression for an RCM experiment.

Type:

pint.Quantity, optional

first_stage_ignition_delay

The first stage ignition delay of the experiment.

Type:

pint.Quantity, optional

ignition_type

Dictionary with the ignition target and type.

Type:

dict

volume_history

The volume history of the reactor during an RCM experiment.

Type:

namedtuple, optional

pressure_history

The pressure history of the reactor during an experiment.

Type:

namedtuple, optional

temperature_history

The temperature history of the reactor during an experiment.

Type:

namedtuple, optional

piston_position_history

The piston position history of the reactor during an RCM experiment.

Type:

namedtuple, optional

light_emission_history

The light emission history of the reactor during an experiment.

Type:

namedtuple, optional

OH_emission_history

The OH emission history of the reactor during an experiment.

Type:

namedtuple, optional

absorption_history

The absorption history of the reactor during an experiment.

Type:

namedtuple, optional

get_cantera_composition_string(species_conversion=None)[source]

Get the composition in a string format suitable for input to Cantera.

Returns a formatted string no matter the type of composition. As such, this method is not recommended for end users; instead, prefer the get_cantera_mole_fraction or get_cantera_mass_fraction methods.

Parameters:

species_conversion (dict, optional) – Mapping of species identifier to a species name. This argument should be supplied when the name of the species in the ChemKED YAML file does not match the name of the same species in a chemical kinetic mechanism. The species identifier (the key of the mapping) can be the name, InChI, or SMILES provided in the ChemKED file, while the value associated with a key should be the desired name in the Cantera format output string.

Returns:

String in the SPEC:AMT, SPEC:AMT format

Return type:

str

Raises:

ValueError – If the composition type of the DataPoint is not one of 'mass fraction', 'mole fraction', or 'mole percent'

get_cantera_mass_fraction(species_conversion=None)[source]

Get the mass fractions in a string format suitable for input to Cantera.

Parameters:

species_conversion (dict, optional) – Mapping of species identifier to a species name. This argument should be supplied when the name of the species in the ChemKED YAML file does not match the name of the same species in a chemical kinetic mechanism. The species identifier (the key of the mapping) can be the name, InChI, or SMILES provided in the ChemKED file, while the value associated with a key should be the desired name in the Cantera format output string.

Returns:

String of mass fractions in the SPEC:AMT, SPEC:AMT format

Return type:

str

Raises:

ValueError – If the composition type is 'mole fraction' or 'mole percent', the conversion cannot be done because no molecular weight information is known

Examples

>>> dp = DataPoint(properties)
>>> dp.get_cantera_mass_fraction()
'H2:2.2525e-04, O2:4.4775e-03, Ar:9.9530e-01'
>>> species_conversion = {'H2': 'h2', 'O2': 'o2'}
>>> dp.get_cantera_mass_fraction(species_conversion)
'h2:2.2525e-04, o2:4.4775e-03, Ar:9.9530e-01'
>>> species_conversion = {'1S/H2/h1H': 'h2', '1S/O2/c1-2': 'o2'}
>>> dp.get_cantera_mass_fraction(species_conversion)
'h2:2.2525e-04, o2:4.4775e-03, Ar:9.9530e-01'
get_cantera_mole_fraction(species_conversion=None)[source]

Get the mole fractions in a string format suitable for input to Cantera.

Parameters:

species_conversion (dict, optional) – Mapping of species identifier to a species name. This argument should be supplied when the name of the species in the ChemKED YAML file does not match the name of the same species in a chemical kinetic mechanism. The species identifier (the key of the mapping) can be the name, InChI, or SMILES provided in the ChemKED file, while the value associated with a key should be the desired name in the Cantera format output string.

Returns:

String of mole fractions in the SPEC:AMT, SPEC:AMT format

Return type:

str

Raises:

ValueError – If the composition type is 'mass fraction', the conversion cannot be done because no molecular weight information is known

Examples

>>> dp = DataPoint(properties)
>>> dp.get_cantera_mole_fraction()
'H2:4.4400e-03, O2:5.5600e-03, Ar:9.9000e-01'
>>> species_conversion = {'H2': 'h2', 'O2': 'o2'}
>>> dp.get_cantera_mole_fraction(species_conversion)
'h2:4.4400e-03, o2:5.5600e-03, Ar:9.9000e-01'
>>> species_conversion = {'1S/H2/h1H': 'h2', '1S/O2/c1-2': 'o2'}
>>> dp.get_cantera_mole_fraction(species_conversion)
'h2:4.4400e-03, o2:5.5600e-03, Ar:9.9000e-01'
process_quantity(properties)[source]

Process the uncertainty information from a given quantity and return it

class pyked.chemked.RCMData(compressed_pressure: Quantity | None, compressed_temperature: Quantity | None, compression_time: Quantity | None, stroke: Quantity | None, clearance: Quantity | None, compression_ratio: Quantity | None)[source]

Data fields specific to rapid compression machine experiments

clearance: Quantity | None

(Quantity) The clearance between piston face and end wall at the end of compression

compressed_pressure: Quantity | None

(Quantity) The pressure at the end of compression

compressed_temperature: Quantity | None

(Quantity) The temperature at the end of compression

compression_ratio: Quantity | None

(Quantity) The volumetric compression ratio

compression_time: Quantity | None

(Quantity) The duration of the compression stroke

stroke: Quantity | None

(Quantity) The length of the stroke

class pyked.chemked.Reference(volume: str | None, journal: str | None, doi: str | None, authors: list | None, detail: str | None, year: int | None, pages: str | None)[source]

Information about the article or report where the data can be found

authors: list | None

(list) The list of authors of the article

detail: str | None

(str) Detail about where the data can be found in the article

doi: str | None

(str) The Digital Object Identifier of the article

journal: str | None

(str) The name of the journal

pages: str | None

(str) The pages in the journal where the article was published

volume: str | None

(str) The journal volume

year: int | None

(int) The year the article was published

class pyked.chemked.TimeHistory(time: Quantity, quantity: Quantity, type: str)[source]

Time history of the quantity in an RCM experiment

quantity: Quantity

the quantity of interest during the experiment

Type:

(Quantity)

time: Quantity

the time during the experiment

Type:

(Quantity)

type: str

the type of time history represented. Possible options are:

  • volume

  • temperature

  • pressure

  • piston position

  • light emission

  • OH emission

  • absorption

Type:

(str)

class pyked.chemked.VolumeHistory(time: Quantity, volume: Quantity)[source]

Time history of the volume in an RCM experiment. Deprecated, to be removed after PyKED 0.4

time: Quantity

the time during the experiment

Type:

(Quantity)

volume: Quantity

the volume during the experiment

Type:

(Quantity)