rmgpy.molecule.resonance

This module contains methods for generation of resonance structures of molecules.

The main function to generate all relevant resonance structures for a given Molecule object is generate_resonance_structures. It calls the necessary functions for generating each type of resonance structure.

Currently supported resonance types:

  • All species:

    • generate_allyl_delocalization_resonance_structures: single radical shift with double or triple bond

    • generate_lone_pair_multiple_bond_resonance_structures: lone pair shift with double or triple bond in a 3-atom system (between nonadjacent atoms)

    • generate_adj_lone_pair_radical_resonance_structures: single radical shift with lone pair between adjacent atoms

    • generate_adj_lone_pair_multiple_bond_resonance_structures: multiple bond shift with lone pair between adjacent atoms

    • generate_adj_lone_pair_radical_multiple_bond_resonance_structures: multiple bond and radical shift with lone pair and radical between adjacent atoms

    • generate_N5dc_radical_resonance_structures: shift between radical and lone pair mediated by an N5dc atom

    • generate_aryne_resonance_structures: shift between cumulene and alkyne forms of arynes, which are not considered aromatic in RMG

  • Aromatic species only:

    • generate_optimal_aromatic_resonance_structures: fully delocalized structure, where all aromatic rings have benzene bonds

    • generate_kekule_structure: generate a single Kekule structure for an aromatic compound (single/double bond form)

    • generate_opposite_kekule_structure: for monocyclic aromatic species, rotate the double bond assignment

    • generate_clar_structures: generate all structures with the maximum number of pi-sextet assignments

  • Multidentate adsorbates only

    • generate_adsorbate_shift_down_resonance_structures: shift 2 electrons from a C=/#C bond to the X-C bond

    • generate_adsorbate_shift_up_resonance_structures: shift 2 electrons from a X=/#C bond to a C-C bond

    • generate_adsorbate_conjugate_resonance_structures: shift 2 electrons in a conjugate pi system for bridged X-C-C-C-X adsorbates

rmgpy.molecule.resonance.analyze_molecule(mol, save_order)

Identify key features of molecule important for resonance structure generation. save_order is used to maintain the atom order, when analyzing the molecule, defaults to False.

Returns a dictionary of features.

rmgpy.molecule.resonance.generate_N5dc_radical_resonance_structures(mol)

Generate all of the resonance structures formed by radical and lone pair shifts mediated by an N5dc atom.

rmgpy.molecule.resonance.generate_adj_lone_pair_multiple_bond_resonance_structures(mol)

Generate all of the resonance structures formed by lone electron pair - multiple bond shifts between adjacent atoms. Example: [:NH]=[CH2] <=> [::NH-]-[CH2+] (where ‘:’ denotes a lone pair, ‘.’ denotes a radical, ‘-’ not in [] denotes a single bond, ‘-‘/’+’ denote charge) Here atom1 refers to the N/S/O atom, atom 2 refers to the any R!H (atom2’s lone_pairs aren’t affected) (In direction 1 atom1 <losses> a lone pair, in direction 2 atom1 <gains> a lone pair)

rmgpy.molecule.resonance.generate_adj_lone_pair_radical_multiple_bond_resonance_structures(mol)

Generate all of the resonance structures formed by lone electron pair - radical - multiple bond shifts between adjacent atoms. Example: [:N.]=[CH2] <=> [::N]-[.CH2] (where ‘:’ denotes a lone pair, ‘.’ denotes a radical, ‘-’ not in [] denotes a single bond, ‘-‘/’+’ denote charge) Here atom1 refers to the N/S/O atom, atom 2 refers to the any R!H (atom2’s lone_pairs aren’t affected) This function is similar to generate_adj_lone_pair_multiple_bond_resonance_structures() except for dealing with the radical transformations. (In direction 1 atom1 <losses> a lone pair, gains a radical, and atom2 looses a radical. In direction 2 atom1 <gains> a lone pair, looses a radical, and atom2 gains a radical)

rmgpy.molecule.resonance.generate_adj_lone_pair_radical_resonance_structures(mol)

Generate all of the resonance structures formed by lone electron pair - radical shifts between adjacent atoms. These resonance transformations do not involve changing bond orders. NO2 example: O=[:N]-[::O.] <=> O=[N.+]-[:::O-] (where ‘:’ denotes a lone pair, ‘.’ denotes a radical, ‘-’ not in [] denotes a single bond, ‘-‘/’+’ denote charge)

rmgpy.molecule.resonance.generate_adsorbate_conjugate_resonance_structures(mol)

Generate all of the resonance structures formed by the shift of two electrons in a conjugated pi bond system of a bidentate adsorbate with a bridging atom in between.

Example XCHCHXC: [X]#CC=C[X] <=> [X]=C=CC=[X] (where ‘#’ denotes a triple bond, ‘=’ denotes a double bond)

rmgpy.molecule.resonance.generate_adsorbate_shift_down_resonance_structures(mol)

Generate all of the resonance structures formed by the shift a pi bond between two C-C atoms to both X-C bonds. Example XCHXCH: [X]C=C[X] <=> [X]=CC=[X] (where ‘=’ denotes a double bond)

rmgpy.molecule.resonance.generate_adsorbate_shift_up_resonance_structures(mol)

Generate all of the resonance structures formed by the shift of two electrons from X-C bonds to increase the bond order between two C-C atoms by 1. Example XCHXCH: [X]=CC=[X] <=> [X]C=C[X] (where ‘=’ denotes a double bond, ‘#’ denotes a triple bond)

rmgpy.molecule.resonance.generate_allyl_delocalization_resonance_structures(mol)

Generate all of the resonance structures formed by one allyl radical shift.

Biradicals on a single atom are not supported.

rmgpy.molecule.resonance.generate_aromatic_resonance_structure(mol, aromatic_bonds, copy, save_order)

Generate the aromatic form of the molecule in place without considering other resonance.

Parameters:

  • mol – Molecule object to modify

  • aromatic_bonds (optional) – list of previously identified aromatic bonds

  • copy (optional) – copy the molecule if True, otherwise modify in place

Returns:

List of one molecule if successful, empty list otherwise

rmgpy.molecule.resonance.generate_aryne_resonance_structures(mol)

Generate aryne resonance structures, including the cumulene and alkyne forms.

For all 6-membered rings, check for the following bond patterns:

  • DDDSDS

  • STSDSD

This does NOT cover all possible aryne resonance forms, only the simplest ones. Especially for polycyclic arynes, enumeration of all resonance forms is related to enumeration of all Kekule structures, which is very difficult.

rmgpy.molecule.resonance.generate_clar_structures(mol, save_order)

Generate Clar structures for a given molecule.

Returns a list of Molecule objects corresponding to the Clar structures.

rmgpy.molecule.resonance.generate_isomorphic_resonance_structures(mol, saturate_h)

Select the resonance isomer that is isomorphic to the parameter isomer, with the lowest unpaired electrons descriptor.

We generate over all resonance isomers (non-isomorphic as well as isomorphic) and retain isomorphic isomers.

If saturate_h is True, then saturate mol with hydrogens before generating the resonance structures, and remove the hydrogens before returning isomorphic_isomers. This is useful when resonance structures are generated for molecules in which all hydrogens were intentionally removed as in generating augInChI. Otherwise, RMG will probably get many of the lone_pairs and partial charges in a molecule wrong.

WIP: do not generate aromatic resonance isomers.

rmgpy.molecule.resonance.generate_kekule_structure(mol)

Generate a kekulized (single-double bond) form of the molecule. The specific arrangement of double bonds is non-deterministic, and depends on RDKit.

Returns a single Kekule structure as an element of a list of length 1. If there’s an error (eg. in RDKit) then it just returns an empty list.

rmgpy.molecule.resonance.generate_lone_pair_multiple_bond_resonance_structures(mol)

Generate all of the resonance structures formed by lone electron pair - multiple bond shifts in 3-atom systems. Examples: aniline (Nc1ccccc1), azide, [:NH2]C=[::O] <=> [NH2+]=C[:::O-] (where ‘:’ denotes a lone pair, ‘.’ denotes a radical, ‘-’ not in [] denotes a single bond, ‘-‘/’+’ denote charge)

rmgpy.molecule.resonance.generate_optimal_aromatic_resonance_structures(mol, features, save_order)

Generate the aromatic form of the molecule. For radicals, generates the form with the most aromatic rings.

Returns result as a list. In most cases, only one structure will be returned. In certain cases where multiple forms have the same number of aromatic rings, multiple structures will be returned. If there’s an error (eg. in RDKit) it just returns an empty list.

rmgpy.molecule.resonance.generate_resonance_structures(mol, clar_structures, keep_isomorphic, filter_structures, save_order)

Generate and return all of the resonance structures for the input molecule.

Most of the complexity of this method goes into handling aromatic species, particularly to generate an accurate set of resonance structures that is consistent regardless of the input structure. The following considerations are made:

  1. False positives from RDKit aromaticity detection can occur if a molecule has exocyclic double bonds

  2. False negatives from RDKit aromaticity detection can occur if a radical is delocalized into an aromatic ring

  3. sp2 hybridized radicals in the plane of an aromatic ring do not participate in hyperconjugation

  4. Non-aromatic resonance structures of PAHs are not important resonance contributors (assumption)

Aromatic species are broken into the following categories for resonance treatment:

  • Radical polycyclic aromatic species: Kekule structures are generated in order to generate adjacent resonance structures. The resulting structures are then used for Clar structure generation. After all three steps, any non-aromatic structures are removed, under the assumption that they are not important resonance contributors.

  • Radical monocyclic aromatic species: Kekule structures are generated along with adjacent resonance structures. All are kept regardless of aromaticity because the radical is more likely to delocalize into the ring.

  • Stable polycyclic aromatic species: Clar structures are generated

  • Stable monocyclic aromatic species: Kekule structures are generated

rmgpy.molecule.resonance.populate_resonance_algorithms(features)

Generate list of resonance structure algorithms relevant to the current molecule.

Takes a dictionary of features generated by analyze_molecule(). Returns a list of resonance algorithms.