Add alias field to species definition in YAML input files

[bryanwweber]

Abstract

Recent work has allowed the idea of species aliases, names by which species can be referenced in user code without having to change the species name. This concept is extremely useful, and it would be useful add a field in the YAML specification of a species to define this in the input file.

Motivation

Although it is possible to currently define an alias programmatically, these definitions are not persistent. Persisting the definition of an alias would save work for the user.

Possible Solutions

Current species definition syntax:

- name: CH4
  thermo: NASA7
  ...

Proposed definition (both should be allowed):

- name: CH4
  alias: methane
  thermo: NASA7
  ...
- name: C3H8
  alias: ["propane", "natural gas"]
  thermo: NASA7
  ...

The alias key is singular on purpose, although it is possible for multiple aliases to be defined. I think the more common case will be to have a single alias, therefore I prefer that name, but this could be iterated on,

References

Original implementation of aliases: Cantera/cantera#714

[ischoegl]

@bryanwweber ... Certainly looks like a reasonable extension. As a friendly amendment, I believe the alias fields could be added from ck2yaml and/or another command line utility?

Another idea @speth mentioned in a different PR are smiles.

PS: once the YAML emitters are done (see #11), writing/saving alias fields will become very intuitive.

[bryanwweber]

Another idea @speth mentioned in a different PR are smiles.

Indeed, this was why I envisioned multiple possible aliases.

I believe the alias fields could be added from ck2yaml and/or another command line utility?

How did you envision this would work?

[ischoegl]

A file could serve as a dictionary specifying mappings, e.g. alias.yaml

CH4: methane
C3H8: [propane, CCC]

which could be passed as an argument, e.g.

ck2yaml [...] --alias=alias.yaml

As mentioned, once the YAML emitters are done, things would get more intuitive. Until then, my main point is that manually editing may be too cumbersome for most.

[speth]

In the case of identifiers like SMILES or InChI, I feel like it would be preferable to be able to store them in fields with those names, rather than a generic alias field. To accommodate this, we could have a field in the phase definition (say, species-aliases) which specifies the names of fields in each species entry to use for setting aliases, with the default being to use the alias field.

[sin-ha]

Hey, @bryanwweber I am new here and have been working on this issue. So do we need to overload the add_species_alias method in the C++ version which currently supports 1 alias.... or do we need to create a new method in the ck2yaml file in python as said by @ischoegl. I think the later will be a bit cleaner.

[ischoegl]

If I recall correctly, you can add as many aliases as you want in the C++ code, so there’s no need to change anything there. What would be of interest here is to add those aliases in a programmatic/automated way, e.g. using some form of YAML.

[bryanwweber]

@sin-ha I think the answer is that the C++ code will need to be modified, so that the field defined in the YAML file will be read and assigned to the right place. I think an example YAML file could look like:

phases:
- name: gas
  species-aliases: [SMILES, InChI, alias]
  ...
species:
- name: H2O
  SMILES: O
  InChI: 1/H2O/...
  alias: [water, dihydrogen monoxide]
  ...
- name: H2
  alias: hydrogen

In the phases entry, you have an optional mapping called species-aliases which lists all the fields in the species entry that should be added to the alias entries. If species-aliases is not specified, the default is alias. Within a species entry, the key alias maps to a sequence of possible aliases for that species. alias can also be a single string, as shown in the entry for H2. If fields specified in species-aliases are not present for a species, they can be ignored.

As far as adding these to a YAML input file, I think the --extra option that was added recently will be fine.

[ischoegl]

Correct, the C++ YAML parser will require modifications.