ResonanceEnumerator

class openff.nagl.utils.resonance.ResonanceEnumerator(molecule: Molecule)[source]

Bases: object

A convenience class for enumerating resonance forms of a molecule according to the algorithm proposed by Gilson et al [1].

Enumeration proceeds by:

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

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

  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:
    1. The networkx graph is converted to a FragmentEnumerator

    2. The original v-charge algorithm is applied to yield the resonance structures of that subgraph, using FragmentEnumerator.enumerate_resonance_forms()

Methods

enumerate_resonance_forms

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].

to_fragment

Convert to a FragmentEnumerator

enumerate_resonance_forms(lowest_energy_only: bool = True, max_path_length: int | None = None, include_all_transfer_pathways: bool = False, as_dicts: bool = False) List[Molecule | Dict[str, Dict[str, Any]]][source]

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:
    1. The original v-charge algorithm is applied to yield the resonance structures of that subgraph.

Parameters:
  • 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 as dictionaries. If False, all combinatorial resonance forms will be returned as molecule objects. This may be significantly slow if the molecule is very heavily conjugated and has many donor / acceptor pairs. If True then the resonance states in each sub-graph are returned. This avoids the need to combinatorially combining resonance information from each sub-graph.

  • 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.

to_fragment() FragmentEnumerator[source]

Convert to a FragmentEnumerator