Schema Documentation¶

This document contains the complete specification for the ChemKED schema. The schema is broken into several files for ease of maintenance. These files are combined with the custom !include directive that has been added for this purpose. Note that !include should only be used in the main schema file (chemked_schema.yaml) and must appear at the top of the file. The !include directive is not supported in any actual ChemKED files.

Examples of constructing a ChemKED format file, as well as examples of files themselves, are located in Creating ChemKED files. The sections laid out in this file roughly correspond to the sections discussed in the tutorial.

Meta Keys ¶

The keys in this section encode the “meta” information about the ChemKED file. All of the keys in this section are required in every ChemKED file.

chemked-version: string, required
A string with the version of the ChemKED schema that this file targets. Must be one of the versions listed under chemked-version in chemked_schema.yaml. Files written by the converters carry the version of the PyKED release that produced them.

datapoints: sequence, required
A sequence of mappings representing the data encoded in the file. Each element of the sequence must conform to the schema described in Ignition Delay Keys (for now).

file-version: integer, required
An integer that represents the version of the file. Should be incremented every time a change is committed to a file in the database.

file-authors: sequence, required
The author(s) of the ChemKED file, which may be different from the authors of the referenced work. Elements of the sequence must be mappings that conform to the author schema.

comments: sequence, optional
Free-text notes about the file as a whole, one string per element. Converting a ReSpecTh file brings across each of its comment elements, which typically record how a quantity was derived or what the file author was unsure of.

method: string, optional
Free text describing how the data were obtained or processed, when that does not belong to any single datapoint.

Reference Keys ¶

The keys in this section are related to the reference for the experiment, the article where the data is published, and the apparatus used to conduct the experiment. All the top-level keys in this section are required, although some of the sub-keys are optional.

apparatus: mapping, required
This mapping provides information about the apparatus used to conduct the experiments. Fields:
- kind: string, required
  Must be one of shock tube, rapid compression machine, jet stirred reactor, flow reactor, burner stabilized flame, counterflow twin flame, heat flux burner, bunsen burner, or outwardly propagating spherical flame. Values are case-sensitive.
- institution: string, optional
  The institution where the experimental apparatus is located
- facility: string, optional
  A unique name or identifier for the apparatus, if the institution has several that are similar

experiment-type: string, required
The type of experiment encoded in this file. Must be one of the following case-sensitive values:
ignition delay

laminar burning velocity measurement

speciation measurement
The type is cross-checked against the rest of the file, because the datapoint schemas alone cannot tell one kind of datapoint from another. Every datapoint must carry the quantity its experiment type measures (ignition-delay, laminar-burning-velocity, or concentration-profiles), and the apparatus kind must be one the measurement can be made on:
ignition delay: shock tube, rapid compression machine

laminar burning velocity measurement: counterflow twin flame, heat flux burner, bunsen burner, outwardly propagating spherical flame

speciation measurement: jet stirred reactor, flow reactor, burner stabilized flame, shock tube

reference: mapping, required
The reference contains the information about the article where the data in the file are published. Fields:
- journal: string, optional
  The journal where the data are published
- year: integer, required
  The year of publication. Must be greater than 1600.
- authors: sequence, required
  A sequence of all the authors of the article, where the elements of the sequence are mappings that must conform to the author type.
- volume: integer, optional
  The volume of the publication. Must be greater than 0.
- doi: string, optional
  A DOI, if available.
- detail: string, optional
  A description of where in the article the data in this file are from, for instance, a figure or table number.
- pages: string, optional
  The pages in the journal where the article is published (not the pages where the data are located, that would go in the detail field.)

Common Property Keys ¶

The keys in this section can be specified as sub-keys of the the common-properties top-level key, and reused in many different data points within a single ChemKED file. All of the keys in the common-properties section are optional, although some of their values may be required in a particular experiment type.

Sharing common values across datapoints is done with YAML anchors and aliases: define the value once in common-properties with an anchor and reference it from each datapoint. Uncertainty and evaluated-standard-deviation metadata for a measured property must be attached to that property’s value in each datapoint; metadata without the corresponding property value is not allowed in common-properties.

pressure-rise: sequence, optional
Has the same format as pressure-rise

pressure: sequence, optional
The pressure of the experiment, with dimensions of mass per length per time squared. Must conform to value-unit-optional

temperature: sequence, optional
The temperature of the experiment, with dimensions of temperature. Must conform to value-unit-optional

ignition-type: mapping, optional
Has the same schema as ignition-type

ignition-delay: sequence, optional
The ignition delay measurement, with dimensions of time. Must conform to value-unit-optional

equivalence-ratio: sequence, optional
The equivalence ratio of the experiment, dimensionless. Must conform to value-unit-optional

laminar-burning-velocity: sequence, optional
The laminar burning velocity measurement, with dimensions of length per time. Must conform to value-unit-optional

residence-time: sequence, optional
The residence time in a flow or jet-stirred reactor experiment, with dimensions of time. Must conform to value-unit-optional

reactor-volume: sequence, optional
The volume of the reactor, with dimensions of length cubed. Must conform to value-unit-optional

reactor-length: sequence, optional
The length of the reactor, with dimensions of length. Must conform to value-unit-optional

reactor-diameter: sequence, optional
The diameter of the reactor, with dimensions of length. Must conform to value-unit-optional

flow-rate: sequence, optional
The flow rate through the reactor. Must conform to value-unit-optional

environment-temperature: sequence, optional
The temperature of the environment surrounding the reactor, with dimensions of temperature. Must conform to value-unit-optional

global-heat-exchange-coefficient: sequence, optional
The global heat exchange coefficient between the reactor and its environment. Must conform to value-unit-optional

exchange-area: sequence, optional
The heat exchange area between the reactor and its environment, with dimensions of length squared. Must conform to value-unit-optional

pressure-in-reference-state: sequence, optional
The pressure used to define the reference state for reported quantities, with dimensions of mass per length per time squared. Must conform to value-unit-optional

temperature-in-reference-state: sequence, optional
The temperature used to define the reference state for reported quantities, with dimensions of temperature. Must conform to value-unit-optional

composition: mapping, optional
This mapping provides the specification of the initial composition of the mixture. Fields:
- kind: string, required
  The kind can be mole fraction, mass fraction, mole percent, mol/cm3, mol/m3, mol/L, or mol/dm3. Fraction kinds must be nonnegative, no greater than 1, and sum to 1. mole percent values must be nonnegative, no greater than 100, and sum to 100. Concentration-style kinds must be nonnegative and are not required to sum to a fixed total.
  
  The sum is checked to a relative tolerance of 1e-3, so a composition reported to a few digits, summing to 0.9999 for instance, is accepted.
- species: sequence, required
  The elements of this sequence specify the species and their amounts in the mixture. Each element of the sequence is a mapping with the following keys:
  
  species-name: string, required
  The name of the species
  
  InChI: string, required, excludes SMILES, atomic-composition
  The InChI string for the species
  
  SMILES: string, required, excludes InChI, atomic-composition
  The SMILES string for the species
  
  atomic-composition: sequence, required, excludes InChI, SMILES
  A sequence of mappings representing the atoms that make up the species. Useful for species without SMILES or InChI representations, such as real hydrocarbon fuels. Each element of the sequence is a mapping with the following keys:
  
  element: string, required
  The name of the element
  
  amount: float, required, must be greater than 0.0
  The amount of the element
  
  amount: sequence, required
  A sequence conforming to either value-with-uncertainty or value-without-uncertainty, where the first element is a float representing the species amount (interpreted according to the parent kind, e.g., mole fraction, mass fraction, or concentration units). The optional metadata mapping may additionally include the evaluated-standard-deviation fields. Because species amounts are unitless numbers, all uncertainty and evaluated-standard-deviation values must be plain floats (not strings with units).

Ignition Delay Keys ¶

This section details the schema for an autoignition delay measurement. This is one of the options for the datapoints schema.

temperature: sequence, required
The temperature of the experiment, with dimensions of temperature. Must conform to value-unit-required

composition: mapping, required
The composition of the experiment. Must conform to composition

pressure: sequence, required
The pressure of the experiment, with dimensions of mass per length per time squared. Must conform to value-unit-required

ignition-type: mapping, required
A mapping describing how the ignition delay is defined in the experiments. Fields:
- target: string, required
  Describes the target measurement (species or physical quantity) used to define ignition. Must be one of: temperature, pressure, OH, OH*, CH, CH*, NH3, CO2, N2O, CH4, CO, H2O, C2, O, CH3OH, CH3, O2, soot.
- type: string, required
  Describes the type of ignition delay measurement. Can be one of:
  
  d/dt max: maximum of the time derivative of the target
  
  d/dt min extrapolated: minimum slope of the target extrapolated to the baseline
  
  d/dt max extrapolated: maximum slope of the target extrapolated to the baseline
  
  d/dt second max: second maximum of the time derivative of the target
  
  max: maximum of the target
  
  1/2 max: half-maximum of the target
  
  min: minimum of the target
  
  concentration: the target reaches a specified concentration
  
  relative concentration: the target reaches a specified fraction of a reference concentration
  
  relative increase: the target increases by a specified amount relative to its initial value
- amount: float, optional
  A numeric threshold associated with the ignition type (for example, the concentration or relative-increase value used when type is concentration, relative concentration, or relative increase).

ignition-delay: sequence, required
The ignition delay measurement, with dimensions of time. Must conform to value-unit-required

first-stage-ignition-delay: sequence, optional
If two stages of ignition are present, this is the value of the first stage of ignition, with dimensions of time. Must conform to value-unit-optional

pressure-rise: sequence, optional
The pressure rise after the passage of the reflected shock, with dimensions of inverse time. Must conform to value-unit-optional

equivalence-ratio: sequence, optional
The equivalence ratio of the experiment, dimensionless. Must conform to value-unit-optional.

rcm-data: mapping, optional
Data related to rapid compression machine (RCM) experiments. The keys of the mapping are detailed in the Rapid Compression Machine Data Keys section.

time-histories: sequence, optional
A sequence of mappings conforming to the time-history schema. Used to specify a time-varying history of one or more quantities during an experiment.

volume-history: mapping, optional
A legacy key for specifying a volume time-history for RCM experiments. New files should use time-histories with type: volume instead. Fields:
- volume: mapping, required
  Describes the volume column in the values array. Must contain units (string with dimensions of length cubed) and column (integer, 0 or 1).
- time: mapping, required
  Describes the time column in the values array. Must contain units (string with dimensions of time) and column (integer, 0 or 1).
- values: sequence, required
  A sequence of [time, volume] pairs of floats.

Rapid Compression Machine Data Keys ¶

This section details the keys specific to rapid compression machine (RCM) experiments, which are subkeys of the rcm-data key.

compression-time: sequence, optional
The time taken during the compression stroke of a rapid compression machine experiment, with dimensions of time. Must conform to value-unit-optional

compressed-pressure: sequence, optional
The pressure at the end of the compression stroke for a rapid compression machine experiment, with dimensions of mass per length per time squared. Must conform to value-unit-optional

compressed-temperature: sequence, optional
The temperature at the end of the compression stroke for a rapid compression machine experiment, with dimensions of temperature. Must conform to value-unit-optional

compression-ratio: sequence, optional
The dimensionless volumetric compression ratio for a rapid compression machine experiment. Must conform to value-unit-optional

stroke: sequence, optional
The length of the stroke in a rapid compression machine experiment, with dimensions of length. Must conform to value-unit-optional

clearance: sequence, optional
The clearance from the piston face to the end wall of the reaction chamber at the end of compression, with dimensions of length. Must conform to value-unit-optional

Laminar Burning Velocity Measurement Keys ¶

This section details the schema for a laminar burning velocity measurement datapoint, selected when experiment-type is laminar burning velocity measurement.

temperature: sequence, required
Unburnt-mixture temperature, with dimensions of temperature. Must conform to value-unit-required.
pressure: sequence, required
Unburnt-mixture pressure, with dimensions of mass per length per time squared. Must conform to value-unit-required.
laminar-burning-velocity: sequence, required
The measured laminar burning velocity, with dimensions of length per time. Must conform to value-unit-required.
composition: mapping, required
The composition of the unburnt mixture. Must conform to composition.
pressure-rise: sequence, optional
Rate of pressure rise during the measurement, with dimensions of inverse time. Must conform to value-unit-optional.
equivalence-ratio: sequence, optional
The equivalence ratio of the experiment, dimensionless. Must conform to value-unit-optional.

Speciation Measurement Keys ¶

This section details the schema for a speciation measurement datapoint, selected when experiment-type is speciation measurement.

pressure: sequence, required
The pressure of the experiment, with dimensions of mass per length per time squared. Must conform to value-unit-required.
temperature: sequence, optional
The inlet, initial, or local temperature, with dimensions of temperature. Must conform to value-unit-optional.
composition: mapping, optional
The inlet or initial composition. Must conform to composition.
equivalence-ratio: sequence, optional
The equivalence ratio of the experiment, dimensionless. Must conform to value-unit-optional.
environment-temperature: sequence, optional
Temperature of the environment surrounding the reactor or burner. Must conform to value-unit-optional.
residence-time: sequence, optional
Residence time in the reactor, with dimensions of time. Must conform to value-unit-optional.
reactor-volume: sequence, optional
Reactor volume, with dimensions of length cubed. Must conform to value-unit-optional.
reactor-length: sequence, optional
Reactor length, with dimensions of length. Must conform to value-unit-optional.
reactor-diameter: sequence, optional
Reactor diameter, with dimensions of length. Must conform to value-unit-optional.
flow-rate: sequence, optional
Flow rate through the reactor or burner. Must conform to value-unit-optional.
volumetric-flow-in-reference-state: sequence, optional
Volumetric flow rate expressed in a defined reference state, with dimensions of length cubed per time. Must conform to value-unit-optional.
pressure-in-reference-state: sequence, optional
Reference-state pressure for a volumetric flow measurement. Must conform to value-unit-optional.
temperature-in-reference-state: sequence, optional
Reference-state temperature for a volumetric flow measurement. Must conform to value-unit-optional.
global-heat-exchange-coefficient: sequence, optional
Global heat exchange coefficient, with dimensions of heat flux per temperature. Must conform to value-unit-optional.
exchange-area: sequence, optional
Heat exchange area, with dimensions of area. Must conform to value-unit-optional.
independent-variables: sequence, required
A sequence of mappings describing the independent variable columns. Each element has the following fields:
- name: string, required
  Must be one of temperature, residence-time, distance, time, equivalence-ratio, initial-composition, or pressure.
- units: string, required
  Units for the independent variable values.
- primary: boolean, optional
  Indicates the primary swept variable.
- species-name: string, optional
  Identifies the swept inlet species when name is initial-composition.
- InChI: string, optional
  The InChI string for the swept inlet species.
- SMILES: string, optional
  The SMILES string for the swept inlet species.
concentration-profiles: sequence, required
A sequence of mappings, each describing measured values for a single species. Each element has the following fields:
- species-name: string, required
  The name of the measured species.
- InChI: string, optional
  The InChI string for the species.
- SMILES: string, optional
  The SMILES string for the species.
- quantity: mapping, required
  A mapping with a required units string describing the measured quantity.
- values: sequence, required
  A sequence of at least two rows. Each row contains one value for each independent-variables entry, followed by the measured amount, and optionally an uncertainty value.
- uncertainty: sequence, optional
  Profile-level uncertainty or evaluated-standard-deviation information. The measured species values are stored separately in values. The sequence contains one mapping with the uncertainty and/or evaluated-standard-deviation fields described under value-with-uncertainty.
auxiliary-profiles: sequence, optional
A sequence of auxiliary measured profiles, such as temperature, pressure, volume, or velocity. Each profile includes an independent mapping, a quantity mapping, and values rows.

Schema-Only Keys ¶

The schema files contain several keys that are used purely as references within the schema and should not be used in actual ChemKED files. These keys are documented in this section.

author: mapping
Information about a single author, used in several contexts. Fields:
- name: string, required
  The author’s full name
- ORCID: string, optional
  The author’s ORCID identifier. Validated to be a valid ORCID and that the name matches

value-with-uncertainty: sequence
A combination of a value and unit with an associated uncertainty and/or evaluated standard deviation. Sequence elements:
- 0: string or float, required
  The first element of the sequence is the value and its associated units (as a single string, e.g., "1000.0 K") or a bare float. The units are validated to have appropriate dimensions for the particular quantity under consideration.
- 1: mapping, optional
  The second element of the sequence is a mapping containing uncertainty and/or evaluated-standard-deviation metadata. Metadata labels such as uncertainty-type, uncertainty-sourcetype, evaluated-standard-deviation-type, evaluated-standard-deviation-sourcetype, and evaluated-standard-deviation-method must be accompanied by an actual uncertainty, upper-uncertainty/lower-uncertainty, or evaluated-standard-deviation value.
  
  Uncertainty fields:
  
  uncertainty-type: string
  The type of uncertainty. Must be absolute or relative. Required when uncertainty, upper-uncertainty, or lower-uncertainty is specified.
  
  uncertainty: string or float, excludes upper-uncertainty and lower-uncertainty, requires uncertainty-type
  The symmetric uncertainty of the value. If uncertainty-type is absolute and a string is given, it must include units whose dimensions match the units of the value in the first element of the sequence.
  
  upper-uncertainty: string or float, excludes uncertainty, requires lower-uncertainty and uncertainty-type
  The upper value of an asymmetrical uncertainty. Due to limitations in the Python library, asymmetrical uncertainties aren’t supported in PyKED, so the larger of upper-uncertainty and lower-uncertainty is used.
  
  lower-uncertainty: string or float, excludes uncertainty, requires upper-uncertainty and uncertainty-type
  The lower value of an asymmetrical uncertainty. Due to limitations in the Python library, asymmetrical uncertainties aren’t supported in PyKED, so the larger of upper-uncertainty and lower-uncertainty is used.
  
  uncertainty-sourcetype: string, optional
  A label describing how the uncertainty value was obtained. Typical values include reported, estimated, calculated, and digitized. Must be accompanied by an uncertainty value.
  
  The mapping may also include the evaluated-standard-deviation fields, which may be combined with, or used independently of, the uncertainty fields above.

evaluated-standard-deviation: mapping fields
A group of optional fields describing a statistically evaluated standard deviation for a value (e.g., from a dataset-wide re-evaluation). These fields appear inside the metadata mapping of a value-with-uncertainty entry or a composition amount metadata mapping, and may be used with or without the uncertainty fields:
- evaluated-standard-deviation: string or float, requires evaluated-standard-deviation-type
  The evaluated standard deviation value. If evaluated-standard-deviation-type is absolute for a unitful quantity, the value must include units whose dimensions match the quantity being described. Relative values and dimensionless absolute values may be plain floats.
- evaluated-standard-deviation-type: string, optional
  Must be absolute or relative. Required whenever an evaluated-standard-deviation value is given, and must be accompanied by one.
- evaluated-standard-deviation-sourcetype: string, optional
  A label describing how the evaluated standard deviation was obtained. Typical values include reported, estimated, calculated, and digitized. Must be accompanied by an evaluated-standard-deviation value.
- evaluated-standard-deviation-method: string, optional
  The method used to compute the evaluated standard deviation. Typical values include generic uncertainty, combined from scatter and reported uncertainty, and statistical scatter. Must be accompanied by an evaluated-standard-deviation value.

value-without-uncertainty: sequence
A combination of a value and unit without any uncertainty metadata. Sequence elements:
- 0: string or float, required
  The first element of the sequence is the value and its associated units (as a single string, e.g., "1.0 atm") or a bare float. The units are validated to have appropriate dimensions for the particular quantity under consideration.

value-unit-required: sequence, required
A sequence conforming to either value-with-uncertainty or value-without-uncertainty. Must be included in the ChemKED file.

value-unit-optional: sequence, optional
A sequence conforming to one of value-with-uncertainty or value-without-uncertainty. May or may not be included in the ChemKED file.

time-history: mapping, optional
Specify the time history of a quantity during an experiment. Fields:
- type: string, required
  The kind of quantity being recorded. Must be one of volume, temperature, pressure, piston position, light emission, OH emission, or absorption.
- quantity: mapping, required
  A mapping describing the recorded quantity. Fields:
  
  units: string, required
  The units of the quantity, with dimensions appropriate for type (e.g., length cubed for volume, temperature for temperature).
  
  column: integer, required
  The 0-based index of the column containing the quantity in the values array.
- time: mapping, required
  A mapping describing the time in the history. Fields:
  
  units: string, required
  The units of the time, with dimensions of time
  
  column: integer, required
  The 0-based index of the column containing the time information in the values array.
- uncertainty: mapping, optional
  The uncertainty of the values in the quantity column. Can be specified either globally by a single value in the sequence or by specifying a column that must be present in the values array. Mapping keys:
  
  type: string, required
  Either absolute or relative to indicate the type of uncertainty
  
  value: string, optional
  A global value for the uncertainty applied to all points in the values array, specified as a string with units. Either this key must be present, or the column and units keys must be present
  
  column: integer, optional
  The column in the values array containing the uncertainty of each point. Either this key and the units key must be specified, or the value key must be specified.
  
  units: string, optional
  The units of the uncertainty in the column array. IF the type is relative, this should be dimensionless. Either this key and the column key must be specified, or the value key must be specified.
- values: sequence or mapping, required
  Must be a sequence or mapping. If a mapping, the only key should be filename whose value should be the filename of a comma-separated value file containing the values for the history. If a sequence, should be a sequence of sequences describing the values of the volume at the time points. Can be entered in any supported syntax, including:
  
  - [0.0, 0.0] - [1.0, 1.0] - - 2.0 - 2.0 - - 3.0 - 3.0