rdtools.resonance.rmg_backend#

Functions for generating resonance structures using RMG algorithm.

This is a rewrite of the original resonance_rmg.py module.

rdtools.resonance.rmg_backend.analyze_molecule(mol: Mol) → dict[str, bool]#

Identify key features of molecule important for resonance structure generation.

Parameters:

mol (Chem.Mol) – the input molecule.

Returns:

dict[str, bool] – a dictionary of features. The keys are: - is_radical: whether the molecule is a radical - is_cyclic: whether the molecule is cyclic - is_aromatic: whether the molecule is aromatic - isPolycyclicAromatic: whether the molecule is polycyclic aromatic - is_aryl_radical: whether the molecule is an aryl radical - hasLonePairs: whether the molecule has lone pairs

rdtools.resonance.rmg_backend.generate_aromatic_resonance_structure(mol: RWMol, copy: bool = True) → list[RWMol]#

Generate the aromatic resonance in place without considering other resonance.

This method completely get rid of the implementation in the original rmg algorithm, to perceive aromaticity and use purely RDKit aromaticity perception. So the performance may be different.

Parameters:

  • mol (Chem.RWMol) – molecule to generate aromatic resonance structure for

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

Returns:

list[Chem.RWMol] – List of one molecule if successful, empty list otherwise

rdtools.resonance.rmg_backend.generate_aryne_resonance_structures(mol: RWMol) → list[RWMol]#

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

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

  • TSDSDS (pattern 1)

  • DDDSDS (pattern 2)

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.

Parameters:

mol (Chem.RWMol) – molecule to generate aryne resonance structure for

Returns:

list[Chem.RWMol] – List of resonance structures

rdtools.resonance.rmg_backend.generate_clar_structures(mol: RWMol) → list[RWMol]#

Generate Clar structures for a given molecule.

This method uses the Clar algorithm to generate all possible Clar structures for a given molecule.

Parameters:

mol (Chem.RWMol) – The input molecule.

Returns:

list[Chem.RWMol] – A list of generated Clar structures.

rdtools.resonance.rmg_backend.generate_kekule_structure(mol: RWMol, copy: bool = True) → list[RWMol]#

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.

Parameters:

  • mol (Chem.RWMol) – molecule to generate kekulized structure for

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

Returns:

list[Chem.RWMol] – List of one molecule if successful, empty list otherwise

rdtools.resonance.rmg_backend.generate_optimal_aromatic_resonance_structures(mol: Mol, features: dict[str, bool] | None = None) → list[Mol]#

Generate the aromatic form of the molecule.

For radicals, generates the form with the most aromatic rings.

Parameters:

  • mol (Chem.Mol) – the input molecule.

  • features (Optional[dict[str, bool]], optional) – a dictionary of features from analyze_molecule.

Returns:

list[Chem.Mol] – a list of resonance structures. In certain cases where multiple forms have the same number of aromatic rings, multiple structures will be returned. It just returns an empty list if an error is raised.

rdtools.resonance.rmg_backend.generate_resonance_structures(mol: RWMol, clar_structures: bool = True, keep_isomorphic: bool = False, filter_structures: bool = True, copy: bool = True, **kwargs: Any) → list[Mol]#

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

Note, RDKit atom obeys the octet rule, that is when making an atom electron deficient, it may automatically add implicit hydrogens if possible. This is not desired in resonance structure generation, so the molecule will be processed by setting atoms with no hydrogen (either implicit or explicit) to be “no implicit”.

Parameters:

  • mol (Chem.RWMol) – A charged molecule in RDKit RWMol.

  • clar_structures (bool, optional) – If generate Clar structures. Defaults to True.

  • keep_isomorphic (bool, optional) – If keep isomorphic resonance structures. Defaults to False.

  • filter_structures (bool, optional) – If filter the resonance structures. Defaults to True.

  • copy (bool, optional) – If copy the input molecule. Defaults to True.

  • **kwargs (Any) – Additional arguments for the resonance algorithms.

Returns:

list[Chem.Mol] – A list of resonance structures.

rdtools.resonance.rmg_backend.generate_resonance_structures_with_pathfinder(mol: Mol, pathfinder: PathFinder, prune_paths: set[tuple[int, ...]] = {}) → list[tuple[Mol, tuple[int, ...]]]#

Generate resonance structures using a path finder.

Parameters:

  • mol (Chem.Mol) – the input molecule.

  • pathfinder (PathFinder) – the path finder registered in the registry.

  • prune_paths (set[tuple[int, ...]], optional) – A set of paths to prune. Defaults to an empty set.

Returns:

list[tuple[Chem.Mol, tuple[int, …]]] – a list of tuples, each tuple contains a resonance structure and a path.

rdtools.resonance.rmg_backend.populate_resonance_algorithms(features: dict[str, bool] | None = None) → tuple[list[str], list[Callable[[...], Any]]]#

Generate two list of resonance structure algorithms.

  • The first are aromatic-agnostic approaches

  • The second are aromatic-specific approaches

Parameters:

features (Optional[dict[str, bool]], optional) – a dictionary of features from analyze_molecule.

Returns:

tuple[list[str,], list[Callable[…, Any]]] – a tuple of two lists of resonance structure algorithms

Returns a list of resonance algorithms.