enumerate_resonance_forms

openff.nagl.utils.resonance.enumerate_resonance_forms(molecule: Molecule, lowest_energy_only: bool = True, max_path_length: int | None = None, include_all_transfer_pathways: bool = False, as_dicts: bool = False, as_fragments: bool = False) → List[Molecule | Dict[str, Dict[str, Any]]][source]

Find all resonance structures of molecule according to Gilson et al [1].

Recursively attempts to find all resonance structures of an input molecule according to a modified version of the algorithm proposed by Gilson et al [1]. Enumeration proceeds by:

  1. The molecule is turned into a networkx graph object.

  2. All hydrogen’s and uncharged sp3 carbons are removed from the graph as these will not be involved in electron transfer.

  3. Disjoint sub-graphs are detected and separated out.

  4. Sub-graphs that don’t contain at least 1 donor and 1 acceptor are discarded

  5. For each disjoint subgraph:

    a) The original v-charge algorithm is applied to yield the resonance structures of that subgraph.

This will lead to M_i resonance structures for each of the N sub-graphs.

If as_dicts=True then the resonance states in each sub-graph are returned. This avoids the need to combinatorially combining resonance information from each sub-graph. When as_dicts=False, all M_0 x M_1 x ... x M_N forms are fully enumerated and return as molecule objects matching the input molecule type.

Note

  • This method will strip all stereochemistry and aromaticity information from the input molecule.

  • The method only attempts to enumerate resonance forms that occur when a pair of electrons can be transferred along a conjugated path from a donor to an acceptor. Other types of resonance, e.g. different Kekule structures, are not enumerated.

Parameters:

  • molecule (openff.toolkit.topology.Molecule) – The molecule to enumerate resonance forms for.

  • lowest_energy_only (bool, optional) – Whether to only return the resonance forms with the lowest ‘energy’ as defined in [1].

  • max_path_length (int, optional) – The maximum number of bonds between a donor and acceptor to consider. If None, all paths are considered.

  • as_dicts (bool, optional) – Whether to return the resonance forms in a form that is more compatible with producing feature vectors. If false, all combinatorial resonance forms will be returned which may be significantly slow if the molecule is very heavily conjugated and has many donor / acceptor pairs.

  • include_all_transfer_pathways (bool, optional) – Whether to include resonance forms that have the same formal charges but have different arrangements of bond orders. Such cases occur when there exists multiple electron transfer pathways between electron donor-acceptor pairs e.g. in cyclic systems.

References

[1] Gilson, Michael K., Hillary SR Gilson, and Michael J. Potter. “Fast assignment of accurate partial atomic charges: an electronegativity equalization method that accounts for alternate resonance forms.” Journal of chemical information and computer sciences 43.6 (2003): 1982-1997.

Returns:

resonance_forms – A list of all resonance forms including the original molecule.