Merge pull request #218 from GreenGroup/new-style-adjacency-list

New style adjacency list

Author: connie

.travis.yml

@@ -9,6 +9,7 @@ before_install:
 #  - sudo apt-get install python-rdkit librdkit-dev librdkit1 rdkit-data
   - sudo apt-get install -qq python-numpy python-scipy python-matplotlib
   - cd ..
+
   - git clone https://github.com/GreenGroup/RMG-database.git
   - git clone https://github.com/GreenGroup/PyDAS.git
   - git clone https://github.com/GreenGroup/PyDQED.git

documentation/source/reference/molecule/adjlist.rst

@@ -7,6 +7,15 @@ Adjacency Lists
 
 .. module:: rmgpy.molecule.adjlist
 
+
+.. note::
+    The adjacency list syntax changed in July 2014.
+    The minimal requirement for most translations is to prefix the number
+    of unpaired electrons with the letter `u`.
+    The new syntax, however, allows much
+    greater flexibility, including definition of lone pairs, partial charges, 
+    wildcards, and molecule multiplicities.
+
 .. note::
     To quickly visualize any adjacency list, or to generate an adjacency list from
     other types of molecular representations such as SMILES, InChI, or even common
@@ -21,49 +30,100 @@ RMG -- but extended to allow for specification of extra semantic information.
 The first line of most adjacency lists is a unique identifier for the molecule
 or pattern the adjacency list represents. This is not strictly required, but
 is recommended in most cases. Generally the identifier should only use
-alphanumeric characters and the underscore, as if an identifer in many popular
+alphanumeric characters and the underscore, as if an identifier in many popular
 programming languages. However, strictly speaking any non-space ASCII character
 is allowed.
 
-After the identifier line, each subsequent line describes a single atom and its
+The subsequent lines may contain keyword-value pairs. Currently there is only
+one keyword, ``multiplicity``.
+
+For species or molecule declarations, the value after ``multiplicity`` defines 
+the spin multiplicity of the molecule. E.g. ``multiplicity 1`` for most ground state 
+closed shell species, ``multiplicity 2`` for most radical species, 
+and ``multiplicity 3`` for a triplet biradical.
+If the ``multiplicity`` line is not present then a value of 
+(1 + number of unpaired electrons) is assumed. 
+Thus, it can usually be omitted, but if present can be used to distinguish,
+for example, singlet CH2 from triplet CH2.
+
+If defining a Functional :class:`~rmgpy.molecule.Group`, then the value must be a list,
+which defines the multiplicities that will be matched by the group, eg. 
+``multiplicity [1,2,3,4,5]`` or, for a single value, ``multiplicity [1]``. 
+If the multiplicity line is omitted, then ``multiplicity [1,2,3,4,5]`` is assumed.
+
+After the identifier line and keyword-value lines,
+each subsequent line describes a single atom and its
 local bond structure. The format of these lines is a whitespace-delimited list
 with tokens ::
 
-    <number> [<label>] <element> <radicals> <bondlist>
+    <number> [<label>] <element> u<unpaired> [p<pairs>] [c<charge>] <bondlist>
 
 The first item is the number used to identify that atom. Any number may be used,
 though it is recommended to number the atoms sequentially starting from one.
 Next is an optional label used to tag that atom; this should be an
-asterisk followed by a unique number for the label, e.g. ``*1``. After that is
-the atom's element, indicated by its atomic symbol, followed by the number of
-radical electrons on the atom. The last set of tokens is the list of bonds.
+asterisk followed by a unique number for the label, e.g. ``*1``.
+In some cases (e.g. thermodynamics groups) there is only one labeled atom, and the label 
+is just an asterisk with no number: ``*``.
+
+After that is
+the atom's element or atom type, indicated by its atomic symbol, followed by 
+a sequence of tokens describing the electronic state of the atom:
+
+* ``u0`` number of **unpaired** electrons (eg. radicals)
+* ``p0`` number of lone **pairs** of electrons, common on oxygen and nitrogen.
+* ``c0`` formal **charge** on the atom, e.g. ``c-1`` (negatively charged),
+  ``c0``, ``c+1`` (positively charged)
+
+For :class:`~rmgpy.molecule.Molecule` definitions:
+The value must be a single integer (and for charge must have a + or - sign if not equal to 0)
+The number of unpaired electrons (i.e. radical electrons) is required, even if zero.
+The number of lone pairs and the formal charge are assumed to be zero if omitted.
+
+For :class:`~rmgpy.molecule.Group` definitions:
+The value can be an integer or a list of integers (with signs, for charges),
+ eg. ``u[0,1,2]`` or ``c[0,+1,+2,+3,+4]``, or may be a wildcard ``x`` 
+ which matches any valid value, 
+eg. ``px`` is the same as ``p[0,1,2,3,4]`` and ``cx`` is the same as
+``c[-4,-3,-2,-1,0,+1,+2,+3,+4]``. Lists must be enclosed is square brackets,
+and separated by commas, without spaces.
+If lone pairs or formal charges are omitted from a group definition,
+the wildcard is assumed.
+
+
+The last set of tokens is the list of bonds.
 To indicate a bond, place the number of the atom at the other end of the bond
 and the bond type within curly braces and separated by a comma, e.g. ``{2,S}``.
-Multiple bonds to the same atom should be separated by whitespace.
+Multiple bonds from the same atom should be separated by whitespace.
 
 .. note::
     You must take care to make sure each bond is listed on the lines of *both*
     atoms in the bond, and that these entries have the same bond type. RMG will
     raise an exception if it encounters such an invalid adjacency list.
 
+
 When writing a molecular substructure pattern, you may specify multiple 
-elements, radical counts, and bond types as a comma-separated list inside curly
-braces. For example, to specify any carbon or oxygen atom, use the syntax 
-``{C,O}``. Atom types may also be used as a shorthand. (Atom types can also be
+elements, radical counts, and bond types as a comma-separated list inside square
+brackets. For example, to specify any carbon or oxygen atom, use the syntax 
+``[C,O]``. For a single or double bond to atom 2, write ``{2,[S,D]}``.
+
+Atom types such as ``R!H`` or ``Cdd`` may also be used as a shorthand. (Atom types 
+like ``Cdd`` can also be
 used in full molecules, but this use is discouraged, as RMG can compute them
 automatically for full molecules.)
 
 Below is an example adjacency list, for 1,3-hexadiene, with the weakest bond in
 the molecule labeled with ``*1`` and ``*2``. Note that hydrogen atoms
-can be omitted if desired, as their presence is inferred::
+can be omitted if desired, as their presence is inferred, provided that unpaired
+electrons, lone pairs, and charges are all correctly defined::
 
     HXD13
-    1    C 0       {2,D}
-    2    C 0 {1,D} {3,S}
-    3    C 0 {2,S} {4,D}
-    4    C 0 {3,D} {5,S}
-    5 *1 C 0 {4,S} {6,S}
-    6 *2 C 0 {5,S}
+    multiplicity 1
+    1    C u0       {2,D}
+    2    C u0 {1,D} {3,S}
+    3    C u0 {2,S} {4,D}
+    4    C u0 {3,D} {5,S}
+    5 *1 C u0 {4,S} {6,S}
+    6 *2 C u0 {5,S}
     
 The allowed element types, radicals, and bonds are listed in the following table:
 
@@ -77,10 +137,10 @@ The allowed element types, radicals, and bonds are listed in the following table
  |                      | H        | Hydrogen atom       |
  |                      +----------+---------------------+
  |                      | S        | Sulfur atom         |
- +----------------------+----------+---------------------+
- | Nonreactive Elements | N        | Nitrogen atom       |
  |                      +----------+---------------------+
- |                      | Si       | Silicon atom        |
+ |                      | N        | Nitrogen atom       |
+ +----------------------+----------+---------------------+
+ | Nonreactive Elements | Si       | Silicon atom        |
  |                      +----------+---------------------+
  |                      | Cl       | Chlorine atom       |
  |                      +----------+---------------------+
@@ -89,18 +149,6 @@ The allowed element types, radicals, and bonds are listed in the following table
  |                      | Ar       | Argon atom          |
  |                      +----------+---------------------+
  +----------------------+----------+---------------------+
- | Free Electrons       | 0        | Non-radical         |
- |                      +----------+---------------------+
- |                      | 1        | Mono-radical        |
- |                      +----------+---------------------+
- |                      | 2        | Bi-radical          |
- |                      +----------+---------------------+
- |                      | 2T       | Triplet             |
- |                      +----------+---------------------+
- |                      | 2S       | Singlet             |
- |                      +----------+---------------------+
- |                      | 3        | Tri-radical         |
- +----------------------+----------+---------------------+
  | Chemical Bond        | S        | Single Bond         |
  |                      +----------+---------------------+
  |                      | D        | Double Bond         |

documentation/source/users/rmg/faq.rst

@@ -3,3 +3,37 @@
 **************************
 Frequently Asked Questions
 **************************
+
+
+Why can't my adjacency lists be read any more?
+==============================================
+
+The adjacency list syntax changed in July 2014.
+The minimal requirement for most translations is to prefix the number
+of unpaired electrons with the letter `u`.
+
+Example old syntax::
+
+    HXD13
+    1    C 0       {2,D}
+    2    C 0 {1,D} {3,S}
+    3    C 0 {2,S} {4,D}
+    4    C 0 {3,D} {5,S}
+    5 *1 C 0 {4,S} {6,S}
+    6 *2 C 0 {5,S}
+
+Example new syntax::
+
+    HXD13
+    1    C u0       {2,D}
+    2    C u0 {1,D} {3,S}
+    3    C u0 {2,S} {4,D}
+    4    C u0 {3,D} {5,S}
+    5 *1 C u0 {4,S} {6,S}
+    6 *2 C u0 {5,S}
+    
+The new syntax, however, allows much
+greater flexibility, including definition of lone pairs, partial charges, 
+wildcards, and molecule multiplicities, and was necessary to allow us to 
+add Nitrogen chemistry.
+See :ref:`rmgpy.molecule.adjlist` for details of the new syntax.

examples/rmg/1,3-hexadiene/input.py

@@ -8,6 +8,11 @@
     kineticsEstimator = 'rate rules',
 )
 
+# Constraints on generated species
+generatedSpeciesConstraints(
+    maximumRadicalElectrons = 2,
+)
+
 # List of species
 species(
     label='HXD13',
@@ -24,8 +29,8 @@
     reactive=True,
     structure=adjacencyList(
         """
-        1 H 0 {2,S}
-        2 H 0 {1,S}
+        1 H u0 p0 {2,S}
+        2 H u0 p0 {1,S}
         """),
 )
 species(

examples/rmg/c3h4/input.py

@@ -8,6 +8,10 @@
 	kineticsEstimator = 'rate rules',
 )
 
+generatedSpeciesConstraints(
+    maximumRadicalElectrons = 4,
+)
+
 # List of species
 species(
 	label='CH2',

examples/rmg/ch3no2/input.py

@@ -26,13 +26,13 @@
     reactive=True,
         structure=adjacencyList(
         """
-        1 C 0 0 {2,S} {3,S} {4,S} {5,S}
-        2 H 0 0 {1,S}
-        3 H 0 0 {1,S}
-        4 H 0 0 {1,S}
-        5 N 0 0 {1,S} {6,D} {7,S}
-        6 O 0 2 {5,D}
-        7 O 0 3 {5,S}
+        1 C u0 p0 {2,S} {3,S} {4,S} {5,S}
+        2 H u0 p0 {1,S}
+        3 H u0 p0 {1,S}
+        4 H u0 p0 {1,S}
+        5 N u0 p0 {1,S} {6,D} {7,S}
+        6 O u0 p2 {5,D}
+        7 O u0 p3 {5,S}
         """),
 )
 
@@ -41,8 +41,8 @@
     reactive=True,
         structure=adjacencyList(
         """
-        1 O 1 2 {2,S}
-        2 O 1 2 {1,S}
+        1 O u1 p2 {2,S}
+        2 O u1 p2 {1,S}
         """),
 )
 
@@ -51,8 +51,8 @@
     reactive=True,
         structure=adjacencyList(
         """
-        1 N 1 1 {2,T}
-        2 N 1 1 {1,T}
+        1 N u0 p1 {2,T}
+        2 N u0 p1 {1,T}
         """),
 )
 

examples/rmg/diesel/input.py

@@ -47,7 +47,7 @@
 species(
     label='O2',
     reactive=True,
-    structure=SMILES("O=O"),
+    structure=SMILES("[O][O]"),
 )
 
 # Reaction systems

examples/rmg/e85/input.py

@@ -8,11 +8,16 @@
     kineticsEstimator = 'rate rules',
 )
 
+# Constraints on generated species
+generatedSpeciesConstraints(
+    maximumRadicalElectrons = 2,
+)
+
 # List of species
 species(
     label='O2',     # oxygen
     reactive=True,
-    structure=SMILES("O=O"),
+    structure=SMILES("[O][O]"),
 )
 species(
     label='C8H18i', # isooctane

examples/rmg/liquid_phase/input.py

@@ -8,6 +8,11 @@
     kineticsEstimator = 'rate rules',
 )
 
+# Constraints on generated species
+generatedSpeciesConstraints(
+    maximumRadicalElectrons = 3,
+)
+
 # List of species
 species(
     label='octane',

examples/rmg/methylformate/input.py

@@ -29,8 +29,8 @@
     reactive=True,
     structure=adjacencyList(
         """
-        1     C     3 {2,S}
-        2     H     0 {1,S}
+        1 C u3 p0 {2,S}
+        2 H u0 p0 {1,S}
         """),
 )
 species(
@@ -46,7 +46,7 @@
 species(
     label='CO',
     reactive=True,
-    structure=SMILES("[C]=O"),
+    structure=SMILES("[C+]#[O-]"),
 )
 species(
     label='CO2',
@@ -157,4 +157,5 @@
     drawMolecules=False,
     generatePlots=False,
     saveConcentrationProfiles=False,
+    saveEdgeSpecies=True,
 )