GreenGroup/RMG-database — pull request #38 by rwest (2014-05-20 23:35:08+00:00)
Title: New style adjacency list

This is a copy of @bbuesser's pull request #37, but pulling from a GreenGroup branch (`GreenGroup/new-style-adjacency-list`), so that we can all add commits (and indeed pull requests) to this pull request before merging, without Beat needing to merge them all. It should stay in sync with (and will only work with) `GreenGroup/new-style-adjacency-list` branch on the RMG-Py project. The rest of this comment is from Beat's original pull request:

## Do not merge yet ##

This is the first version of the RMG database with the new adjacency list format and multiplicity as a species/molecule property. Kinetics libraries store the multiplicity as part of the adjacency list where everywhere else it is a separate argument. I think multiplicity should not be part of the adjacency list because it does not depend on its details, e.g. there can be many adjacency list for the same species (resonance isomers) all having necessarily the same multiplicity. As soon as we continue with our efforts of having a separate structure library for kinetics rules, this difference of storing multiplicity in the adjacency list for kinetics will fall away.

The new adjacency list format is (e.g. nitromethane, CH3NO2):

```
1 C U0 L0 E0 {2,S} {3,S} {4,S} {5,S}
2 N U0 L0 E+1 {1,S} {6,D} {7,S}
3 H U0 L0 E0 {1,S}
4 H U0 L0 E0 {1,S}
5 H U0 L0 E0 {1,S}
6 O U0 L2 E0 {2,D}
7 O U0 L3 E-1 {2,S}
```

where

U: the flag for unpaired electrons (formerly radicals). There are two reasons to abandon the R for radicals. First we are using R to represent unspecified groups in the elements column. Second it would be confusing in a future publication to use "radical" at the same time for the species with unpaired electrons and the unpaired electron itself.

L: the flag for the number of lone electron pairs. The reason against P as flag was the possible future introduction of phosphorus that would bring P as an element.

E: the flag for formal charges. The sum of all E is equal to the total charge of the species. Currently only neutral species are reactive in RMG, therefore sum(E)=0 is required for reactivity. E has been chosen as the capital letter of e representing an electronic charge. E+1 means one electron less, E-2 means two additional electrons on that atom. C was not used as flag for formal charge because it is used to represent carbon

There are no more 2T and 2S or any other combination accepted by RMG to represent multiplicity.

Adjacency list in kinetics libraries or rules look like the following:

```
HCO
multiplicity 2
1 C U1 L0 E0 {2,D} {3,S}
2 O U0 L2 E0 {1,D}
3 H U0 L0 E0 {1,S}
```

It can contain in its first line as always a label. The second line contains the label "multiplicity" followed by a space and a number representing the multiplicity of that species.

For groups the multiplicity label is always a separate argument (thermo and kinetics) and is defined as a list containing all accepted multiplicities where that group will be applicable.

Groups only require the U flag for unpaired electrons, L is optional and will be compared if defined while E is not read at the moment.