nuri.algo

Ring detection

nuri.algo.find_all_rings(*args, **kwargs)

Overloaded function.

1. find_all_rings(mol: nuri.core._core.Molecule, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find all rings (a.k.a. elementary circuits) in a molecule.

Parameters:

• mol – The molecule to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

Raises:

ValueError – If the molecule has too many rings to find. Currently, this will fail if and only if any atom is a member of more than 100 rings.

2. find_all_rings(sub: nuri.core._core.Substructure, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find all rings (a.k.a. elementary circuits) in a substructure.

Parameters:

• sub – The substructure to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

Raises:

ValueError – If the substructure has too many rings to find. Currently, this will fail if and only if any atom is a member of more than 100 rings.

3. find_all_rings(sub: nuri.core._core.ProxySubstructure, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find all rings (a.k.a. elementary circuits) in a substructure.

Parameters:

• sub – The substructure to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

Raises:

ValueError – If the substructure has too many rings to find. Currently, this will fail if and only if any atom is a member of more than 100 rings.

This is based on the algorithm by Hanser et al. [HJK96].

Note

The time complexity of this function is inherently exponential, but it is expected to run in a reasonable time for most molecules in practice. See the reference for more details.

SSSR-related routines

Formally, SSSR (smallest set of smallest rings) is a minimum cycle basis of the molecular graph. As discussed in many literatures, there is no unique SSSR for a given molecular graph (even for simple molecules such as 2-oxabicyclo[2.2.2]octane), and the SSSR is often counter-intuitive. For example, the SSSR of cubane (although unique, due to symmetry reasons) contains only five rings, which is not most chemists would expect.

On the other hand, union of all SSSRs, sometimes called the relevant rings in the literatures, is unique for a given molecule. Chemically speaking, it is the “all smallest rings” of the molecule and more appropriate for most applications than SSSR.

Here, we provide two functions to find the relevant rings and SSSR, respectively. The finding algorithms are based on the algorithm by Vismara [Vis97].

Note

The time complexity of the functions when max size is not specified is theoretically \(\mathcal{O}(\nu E^3)\) where \(\nu = \mathcal{O}(E)\) is size of SSSR and \(E\) is the number of bonds. For most molecules, this is in practice \(\mathcal{O}(V^3)\), where \(V\) is the number of atoms. See the reference for more details.

nuri.algo.find_relevant_rings(*args, **kwargs)

Overloaded function.

1. find_relevant_rings(mol: nuri.core._core.Molecule, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find union of all SSSR (smallest set of smallest rings) in a molecule.

Parameters:

• mol – The molecule to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

2. find_relevant_rings(sub: nuri.core._core.Substructure, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find union of all SSSR (smallest set of smallest rings) in a substructure.

Parameters:

• sub – The substructure to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

3. find_relevant_rings(sub: nuri.core._core.ProxySubstructure, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find union of all SSSR (smallest set of smallest rings) in a substructure.

Parameters:

• sub – The substructure to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

nuri.algo.find_sssr(*args, **kwargs)

Overloaded function.

1. find_sssr(mol: nuri.core._core.Molecule, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find a SSSR (smallest set of smallest rings) in a molecule.

Parameters:

• mol – The molecule to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

2. find_sssr(sub: nuri.core._core.Substructure, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find a SSSR (smallest set of smallest rings) in a substructure.

Parameters:

• sub – The substructure to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

3. find_sssr(sub: nuri.core._core.ProxySubstructure, max_size: Optional[int] = None) -> list[nuri.core._core.Substructure]

Find a SSSR (smallest set of smallest rings) in a substructure.

Parameters:

• sub – The substructure to find rings in.

• max_size – The maximum size of rings to find. If not specified, all rings are found.

Returns:

A list of substructures, each representing a ring.

Return type:

list[Substructure]

Note

This function does not guarantee that the returned set is unique, nor that the result is reproducible even for the same molecule.

Other routines

nuri.algo.generate_coords(mol: Molecule, method: str = 'DG', max_trial: int = 10, seed: int = 0) → None

Generate 3D coordinates of a molecule. The generated coordinates are stored in the last conformer of the molecule if the generation is successful.

Parameters:

• mol – The molecule to generate coordinates.

• method – The method to use for coordinate generation (case insensitive). Currently, only DG (distance geometry) is supported.

• max_trial – The maximum number of trials to generate trial distances.

• seed – The seed for the random number generator. Might not be used depending on the method used or if the algorithm succeeds before random initialization.

Raises:

ValueError – If the generation fails. On exception, the molecule is left unmodified.

nuri.algo.guess_all_types(mol: Molecule, conf: int = 0) → None

Guess types of atoms and bonds, and number of hydrogens of a molecule.

Parameters:

• mol – The molecule to be guessed.

• conf – The index of the conformation used for guessing.

Raises:

• IndexError – If the conformer index is out of range.

• ValueError – If the guessing fails. The state of molecule is not guaranteed to be preserved in this case. If you want to preserve the state, copy the molecule before calling this function using copy().

Tip

If want to find extra bonds that are not in the input molecule, consider using guess_everything().

nuri.algo.guess_connectivity(mutator: Mutator, conf: int = 0, threshold: float = 0.5) → None

Guess connectivity information of a molecule.

Parameters:

• mutator – The mutator of the molecule to be guessed.

• conf – The index of the conformation used for guessing.

• threshold – The threshold for guessing connectivity. Will be added to the sum of two covalent radii of the atoms to determine the maximum distance between two atoms to be considered as bonded.

Raises:

IndexError – If the conformer index is out of range. This function never fails otherwise.

This function find extra bonds that are not in the input molecule. Unlike guess_everything(), this function does not touch other information present in the molecule.

Tip

If want to guess types of atoms and bonds as well, consider using guess_everything().

nuri.algo.guess_everything(mutator: Mutator, conf: int = 0, threshold: float = 0.5) → None

Guess connectivity information of a molecule, then guess types of atoms and bonds, and number of hydrogens of a molecule.

Parameters:

• mutator – The mutator of the molecule to be guessed.

• conf – The index of the conformation used for guessing.

• threshold – The threshold for guessing connectivity. Will be added to the sum of two covalent radii of the atoms to determine the maximum distance between two atoms to be considered as bonded.

Raises:

• IndexError – If the conformer index is out of range.

• ValueError – If the guessing fails. The state of molecule is not guaranteed to be preserved in this case. If you want to preserve the state, copy the molecule before calling this function using copy().

This function is functionally equivalent to calling guess_connectivity() and guess_all_types() in sequence, except that it is (slightly) more efficient.

Tip

If connectivity information is already present and is correct, consider using guess_all_types().

Warning

The information present in the molecule is overwritten by this function.