rdtools.resonance.pathfinder

This module includes an RDKit-based rewrite of the RMG resonance pathfinder.

class rdtools.resonance.pathfinder.AdjacentLonePairRadicalPathFinder

Bases: PathFinder

Find Adjacent Lone Pair Radical Path.

Find all the delocalization paths of lone electron pairs next to the radical center. Used to generate resonance isomers in adjacent N/O/S atoms.

The radical site (atom1) could be either:

• N u1 p0, eg O=[N.+][:::O-]

• N u1 p1, eg R[:NH][:NH.]

• O u1 p1, eg [:O.+]=[::N-]; not allowed when adjacent to another O atom

• O u1 p2, eg O=N[::O.]; not allowed when adjacent to another O atom

• S u1 p0, eg O[S.+]([O-])=O

• S u1 p1, eg O[:S.+][O-]

• S u1 p2, eg O=N[::S.]

• any of the above with more than 1 radical where possible

The non-radical site (atom2) could respectively be:

• N u0 p1

• N u0 p2

• O u0 p2

• O u0 p3

• S u0 p1

• S u0 p2

• S u0 p3

(where ‘:’ denotes a lone pair, ‘.’ denotes a radical, ‘-’ not in [] denotes a single bond, ‘-‘/’+’ denote charge) The bond between the sites does not have to be single, e.g.: [:O.+]=[::N-] <=> [::O]=[:N.]

reverse: str = 'AdjacentLonePairRadicalPathFinder'

reverse_abbr: str = 'adj_lone_pair_radical'

template: Mol = <rdkit.Chem.rdchem.Mol object>

static transform(mol: Mol, path: tuple[int, ...], *args: Any, **kwargs: Any) → Mol | None

Wrapper function to handle resonance structure generation.

Parameters:

• mol (Chem.Mol) – The molecule to be processed.

• path (tuple[int, ...]) – The path of the resonance structure.

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Returns:

Optional[Chem.Mol] – The transformed molecule if successful, otherwise None.

static verify(mol: Mol, path: tuple[int, ...]) → bool

Verify that the adjacent lone pair radical delocalization path is valid.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• path (tuple[int, ...]) – The adjacent lone pair radical delocalization path to verify.

Returns:

bool – True if the adjacent lone pair radical delocalization path is valid, False otherwise.

class rdtools.resonance.pathfinder.AllylRadicalPathFinder

Bases: PathFinder

A finder to find all the delocalization paths allyl to the radical center.

reverse: str = 'AllylRadicalPathFinder'

reverse_abbr: str = 'allyl_radical'

template: Mol = <rdkit.Chem.rdchem.Mol object>

static transform(mol: Mol, path: tuple[int, ...], *args: Any, **kwargs: Any) → Mol | None

Wrapper function to handle resonance structure generation.

Parameters:

• mol (Chem.Mol) – The molecule to be processed.

• path (tuple[int, ...]) – The path of the resonance structure.

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Returns:

Optional[Chem.Mol] – The transformed molecule if successful, otherwise None.

static verify(mol: Mol, path: tuple[int, ...]) → bool

Verify that the allyl delocalization path is valid.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• path (tuple[int, ...]) – The allyl delocalization path to verify.

Returns:

bool – True if the allyl delocalization path is valid, False otherwise.

class rdtools.resonance.pathfinder.ForwardAdjacentLonePairMultipleBondPathFinder

Bases: PathFinder

Find Forward Adjacent Lone Pair Multiple Bond Path.

Find all the delocalization paths of atom1 that has a lonePair and is bonded by a single/double bond e.g., [::NH-]-[CH2+] <=> [:NH]=[CH2].

template

The SMARTS pattern for the path finder.

Type:

Chem.Mol

reverse

The name of the reverse path finder.

Type:

str

reverse_abbr

The abbreviation of the reverse path finder.

Type:

str

reverse: str = 'ReverseAdjacentLonePairMultipleBondPathFinder'

reverse_abbr: str = 'reverse_adj_lone_pair_multiple_bond'

template: Mol = <rdkit.Chem.rdchem.Mol object>

static transform(mol: Mol, path: tuple[int, ...], *args: Any, **kwargs: Any) → Mol | None

Wrapper function to handle resonance structure generation.

Parameters:

• mol (Chem.Mol) – The molecule to be processed.

• path (tuple[int, ...]) – The path of the resonance structure.

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Returns:

Optional[Chem.Mol] – The transformed molecule if successful, otherwise None.

static verify(mol: Mol, path: tuple[int, ...]) → bool

Verify that the path is valid.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• path (tuple[int, ...]) – The adjacent lone pair multiple bond delocalization path to verify.

Returns:

bool – True if the adjacent lone pair multiple bond delocalization path is valid, False otherwise.

class rdtools.resonance.pathfinder.ForwardAdjacentLonePairRadicalMultipleBondPathFinder

Bases: PathFinder

Find Forward Adjacent Lone Pair Radical Multiple Bond Path.

Find all the delocalization paths of atom1 which has a lonePair and is bonded by a single/double bond to a radical atom.

For example: [::N]-[.CH2] <=> [:N.]=[CH2]

template

The SMARTS pattern for the path finder.

Type:

Chem.Mol

reverse

The name of the reverse path finder.

Type:

str

reverse_abbr

The abbreviation of the reverse path finder.

Type:

str

reverse: str = 'ReverseAdjacentLonePairRadicalMultipleBondPathFinder'

reverse_abbr: str = 'reverse_adj_lone_pair_radical_multiple_bond'

template: Mol = <rdkit.Chem.rdchem.Mol object>

static transform(mol: Mol, path: tuple[int, ...], *args: Any, **kwargs: Any) → Mol | None

Wrapper function to handle resonance structure generation.

Parameters:

• mol (Chem.Mol) – The molecule to be processed.

• path (tuple[int, ...]) – The path of the resonance structure.

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Returns:

Optional[Chem.Mol] – The transformed molecule if successful, otherwise None.

static verify(mol: Mol, path: tuple[int, ...]) → bool

Verify that the path is valid.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• path (tuple[int, ...]) – The ÷÷÷÷≥≥adjacent lone pair multiple bond delocalization path to verify.

Returns:

bool – True if the adjacent lone pair multiple bond delocalization path is valid, False otherwise.

class rdtools.resonance.pathfinder.LonePairMultipleBondPathFinder

Bases: PathFinder

Find all the delocalization paths of lone pair and multiple bond.

A finder to find all the delocalization paths between lone electron pair and multiple bond in a 3-atom system.

Examples: - N2O (N#[N+][O-] <-> [N-]=[N+]=O) - Azide (N#[N+][NH-] <-> [N-]=[N+]=N <-> [N-2][N+]#[NH+]) - N#N group on sulfur (O[S-](O)[N+]#N <-> OS(O)=[N+]=[N-] <-> O[S+](O)#[N+][N-2]) - N[N+]([O-])=O <=> N[N+](=O)[O-], these structures are isomorphic but not identical, this transition is

important for correct degeneracy calculations

template

The SMARTS pattern for the path finder.

Type:

Chem.Mol

reverse

The name of the reverse path finder.

Type:

str

reverse_abbr

The abbreviation of the reverse path finder.

Type:

str

reverse: str = 'LonePairMultipleBondPathFinder'

reverse_abbr: str = 'lone_pair_multiple_bond'

template: Mol = <rdkit.Chem.rdchem.Mol object>

static transform(mol: Mol, path: tuple[int, ...], *args: Any, **kwargs: Any) → Mol | None

Wrapper function to handle resonance structure generation.

Parameters:

• mol (Chem.Mol) – The molecule to be processed.

• path (tuple[int, ...]) – The path of the resonance structure.

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Returns:

Optional[Chem.Mol] – The transformed molecule if successful, otherwise None.

static verify(mol: Mol, path: tuple[int, ...]) → bool

Verify that the lone pair multiple bond path is valid.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• path (tuple[int, ...]) – The lone pair multiple bond path to verify.

Returns:

bool – True if the lone pair multiple bond path is valid, False otherwise.

class rdtools.resonance.pathfinder.PathFinder

Bases: ABC

Base class for path finders.

This class provides a template for finding and transforming resonance structures in molecules. Subclasses should implement the verify and transform methods to define specific resonance structures.

template

The SMARTS pattern for the path finder.

Type:

Chem.Mol

reverse

The name of the reverse path finder.

Type:

str

reverse_abbr

The abbreviation of the reverse path finder.

Type:

str

classmethod find(mol: Mol, max_matches: int = 1000) → Set[Tuple[int, ...]]

Find the paths for according to the template of class.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• max_matches (int) – The maximum number of matches to return. Defaults to 1000.

Returns:

Set[Tuple[int, …]] – A set of tuples containing the atom indices of the paths.

reverse: str

reverse_abbr: str

template: Mol

abstract static transform(mol: Mol, path: tuple[int, ...]) → Mol

Abstract method that transoforms the resonance structures.

This needs to be implemented by subclasses.

abstract static verify(mol: Mol, path: tuple[int, ...]) → bool

Abstract method that should return True if the path is valid.

This needs to be implemented by subclasses.

class rdtools.resonance.pathfinder.PathFinderRegistry

Bases: object

Registry for path finders.

classmethod get(name: str) → PathFinder

Get a path finder class by name.

Parameters:

name (str) – The name of the path finder.

Returns:

PathFinder – The path finder class, or None if not found.

classmethod register(name: str) → Callable[[...], PathFinder]

Decorator to register a path finder class.

Parameters:

name (str) – The name of the path finder.

Returns:

Callable[…, PathFinder] – A decorator that registers the class.

class rdtools.resonance.pathfinder.ReverseAdjacentLonePairMultipleBondPathFinder

Bases: PathFinder

Find Reversed Adjacent Lone Pair Multiple Bond Path.

Find all the delocalization paths of atom1 which either can obtain a lonePair and is bonded by a double/triple bond (e.g., [:NH]=[CH2], [:N]#[CH]).

For example, [:NH]=[CH2] <=> [::NH-]-[CH2+]

template

The SMARTS pattern for the path finder.

Type:

Chem.Mol

reverse

The name of the reverse path finder.

Type:

str

reverse_abbr

The abbreviation of the reverse path finder.

Type:

str

reverse: str = 'ForwardAdjacentLonePairMultipleBondPathFinder'

reverse_abbr: str = 'forward_adj_lone_pair_multiple_bond'

template: Mol = <rdkit.Chem.rdchem.Mol object>

static transform(mol: Mol, path: tuple[int, ...], *args: Any, **kwargs: Any) → Mol | None

Wrapper function to handle resonance structure generation.

Parameters:

• mol (Chem.Mol) – The molecule to be processed.

• path (tuple[int, ...]) – The path of the resonance structure.

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Returns:

Optional[Chem.Mol] – The transformed molecule if successful, otherwise None.

static verify(mol: Mol, path: tuple[int, ...]) → bool

Verify the path is valid.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• path (tuple[int, ...]) – The adjacent lone pair multiple bond delocalization path to verify.

Returns:

bool – True if the adjacent lone pair multiple bond delocalization path is valid, False otherwise.

class rdtools.resonance.pathfinder.ReverseAdjacentLonePairRadicalMultipleBondPathFinder

Bases: PathFinder

Find Reversed Adjacent Lone Pair Radical Multiple Bond Path.

This is the reverse of the ForwardAdjacentLonePairRadicalMultipleBondPathFinder class. It is used to find the delocalization paths of atom1 which either can obtain a lonePair, has a radical, and is bonded by a double/triple bond.

For example, [:N.]=[CH2] <=> [::N]-[.CH2]

template

The SMARTS pattern for the path finder.

Type:

Chem.Mol

reverse

The name of the reverse path finder.

Type:

str

reverse_abbr

The abbreviation of the reverse path finder.

Type:

str

reverse: str = 'ForwardAdjacentLonePairRadicalMultipleBondPathFinder'

reverse_abbr: str = 'forward_adj_lone_pair_radical_multiple_bond'

template: Mol = <rdkit.Chem.rdchem.Mol object>

static transform(mol: Mol, path: tuple[int, ...], *args: Any, **kwargs: Any) → Mol | None

Wrapper function to handle resonance structure generation.

Parameters:

• mol (Chem.Mol) – The molecule to be processed.

• path (tuple[int, ...]) – The path of the resonance structure.

• *args (Any) – Additional arguments.

• **kwargs (Any) – Additional keyword arguments.

Returns:

Optional[Chem.Mol] – The transformed molecule if successful, otherwise None.

static verify(mol: Mol, path: tuple[int, ...]) → bool

Verify that the delocalization path is valid.

Parameters:

• mol (Chem.Mol) – The molecule to search.

• path (tuple[int, ...]) – The adjacent lone pair multiple bond delocalization path to verify.

Returns:

bool – True if the adjacent lone pair multiple bond delocalization path is valid, False otherwise.

rdtools.resonance.pathfinder.transform_pre_and_post_process(fun: Callable[[...], Any]) → Callable[[...], Any]

A decorator for resonance structure generation functions that require a radical.

This decorator handles the pre- and post-processing of the input molecule.

Parameters:

fun (Callable[..., Any]) – The function to be decorated.

Returns:

Callable[…, Any] – The decorated function.