rdtools.conf#

A module contains functions to manipulate conformers in a molecule.

rdtools.conf.add_conformer(mol: RWMol, conf: Conformer | None = None, coords: ndarray[tuple[int, ...], dtype[float64]] | None = None, conf_id: int | None = None) → int#

Add a conformer to the current RDKitMol.

Parameters:

  • mol (Chem.RWMol) – The molecule to be set.

  • conf (Optional[Chem.Conformer], optional) – A user may provide a predefined conformer and add it to the mol. Defaults to None, but either conf or coords must be provided.

  • coords (Optional[npt.NDArray[np.float64]], optional) – Instead of feeding a conformer, a user may provide the coordinates of the conformer to be added. Defaults to None, but either conf or coords must be provided.

  • conf_id (Optional[int], optional) – Which ID to set for the conformer (will be added as the last conformer by default). Defaults to None.

Returns:

int – The conformer ID added.

Raises:

ValueError – If both conf and coords are None.

rdtools.conf.add_null_conformer(mol: RWMol, conf_id: int | None = None, random: bool = True) → int#

Embed a conformer with null atom coordinates.

The coordinates are either set to random numbers or all zero coordinates.

Parameters:

  • mol (Chem.RWMol) – The molecule to be set.

  • conf_id (Optional[int], optional) – Which ID to set for the conformer (will be added as the last conformer by default).

  • random (bool, optional) – Whether set coordinates to random numbers. Otherwise, set to all-zero coordinates. Defaults to True.

Returns:

int – The conformer ID added.

rdtools.conf.create_conformer(coords: ndarray[tuple[int, ...], dtype[float64]], conf_id: int | None = None) → Conformer#

Create a conformer with the given coordinates.

Parameters:

  • coords (npt.NDArray[np.float64]) – The coordinates to be set.

  • conf_id (Optional[int], optional) – Which ID to set for the conformer. Defaults to 0.

Returns:

Chem.Conformer – The conformer created.

rdtools.conf.edit_conf_by_add_bonds(conf: Conformer, function_name: str, atoms: tuple[int, ...], value: int | float) → None#

Add bonds to the conformer and modify the internal coordinates.

This is a workaround for RDKit forbidding modifying internal coordinates with non-bonding atoms. The function will add the bonds, modify the internal coordinates, and then remove the bonds. The conformer will be modified in place. Note, the function will not work for ring systems.

Parameters:

  • conf (Chem.Conformer) – The conformer to be modified.

  • function_name (str) – The function name of the edit, should be a method provided in rdMolTransforms.

  • atoms (tuple[int, ...]) – A list of atoms representing the internal coordinates.

  • value (Union[int, float]) – Value to be set.

rdtools.conf.embed_conformer(mol: Mol, allow_null: bool = True, **kwargs: Any) → None#

Embed a conformer to the molecule object.

This will overwrite current conformers. By default, it will first try embedding a 3D conformer; if fails, it then try to compute 2D coordinates and use that for the conformer structure; if both approaches fail, and embedding a null conformer is allowed, a conformer with all random coordinates will be embedded. The last one is helpful for the case where you can use SetPositions to set their positions afterward, or if you want to optimize the geometry using force fields.

Parameters:

  • mol (Chem.Mol) – The molecule object to embed.

  • allow_null (bool, optional) – If embedding 3D and 2D coordinates fails, whether to embed a conformer with all null coordinates, (0, 0, 0), for each atom. Defaults to True.

  • **kwargs (Any) – The keyword arguments to pass to the embedding function.

Raises:

RuntimeError – If embedding fails and allow_null is False.

rdtools.conf.embed_multiple_confs(mol: Mol, n: int = 10, allow_null: bool = True, **kwargs: Any) → None#

Embed multiple conformers to the RDKitMol.

This will overwrite current conformers. By default, it will first try embedding a 3D conformer; if fails, it then try to compute 2D coordinates and use that for the conformer structure; if both approaches fail, and embedding a null conformer is allowed, a conformer with all random coordinates will be embedded. The last one is helpful for the case where you can use SetPositions to set their positions afterward, or if you want to optimize the geometry using force fields.

Parameters:

  • mol (Chem.Mol) – The molecule object to embed.

  • n (int, optional) – The number of conformers to be embedded. The default is 1.

  • allow_null (bool, optional) – If embedding fails, whether to embed null conformers. Defaults to True.

  • **kwargs (Any) – The keyword arguments to pass to the embedding function.

Raises:

RuntimeError – If embedding fails and allow_null is False.

rdtools.conf.embed_multiple_null_confs(mol: Mol, n: int = 10, random: bool = False) → None#

Embed conformers with null or random atom coordinates.

This helps the cases where a conformer can not be successfully embedded. You can choose to generate all zero coordinates or random coordinates. You can set to all-zero coordinates, if you will set coordinates later; You should set to random coordinates, if you want to optimize this molecule by force fields (RDKit force field cannot optimize all-zero coordinates).

Parameters:

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

  • n (int, optional) – The number of conformers to be embedded. Defaults to 10.

  • random (bool, optional) – Whether set coordinates to random numbers. Otherwise, set to all-zero coordinates. Defaults to True.

rdtools.conf.get_angle_deg(conf: Conformer, atom_ids: tuple[int, int, int]) → float#

Get the angle between three atoms in degrees.

Parameters:

  • conf (Chem.Conformer) – The conformer to be set.

  • atom_ids (tuple[int, int, int]) – The atom IDs to be set.

Returns:

float – The angle between three atoms in degrees.

rdtools.conf.get_bond_length(conf: Conformer, atom_ids: tuple[int, int]) → float#

Get the distance between two atoms.

Note, the two atoms can be non-bonded.

Parameters:

  • conf (Chem. Conformer) – The conformer to be set.

  • atom_ids (tuple[int, int]) – The atom IDs to be set.

Returns:

float – The bond length between two atoms.

rdtools.conf.get_torsion_deg(conf: Conformer, atom_ids: tuple[int, int, int, int]) → float#

Get the torsion angle between four atoms in degrees.

Parameters:

  • conf (Chem.Conformer) – The conformer to be set.

  • atom_ids (tuple[int, int, int, int]) – The atom IDs to be set.

Returns:

float – The torsion angle between four atoms in degrees.

rdtools.conf.reflect(conf: Conformer) → None#

Reflect the coordinates of the conformer.

Parameters:

conf (Chem.Conformer) – The conformer to be set.

rdtools.conf.set_angle_deg(conf: Conformer, atom_ids: tuple[int, int, int], value: int | float) → None#

Set the angle between three atoms in degrees.

If the three atoms are not bonded, the function will give it a try by forming the bonds, adjusting the angle, and then removing the bonds. This is a workaround for RDKit forbidding modifying internal coordinates with non-bonding atoms.

Parameters:

  • conf (Chem.Conformer) – The conformer to be set.

  • atom_ids (tuple[int, int, int]) – The atom IDs to be set.

  • value (Union[int, float]) – The value to be set.

Raises:

NotImplementedError – If the approach for modifying the angle is not available.

rdtools.conf.set_bond_length(conf: Conformer, atom_ids: tuple[int, int], value: int | float) → None#

Set the distance between two atoms.

If the two atoms are not bonded, the function will give it a try by forming the bonds, adjusting the bond length, and then removing the bonds. This is a workaround for RDKit forbidding modifying internal coordinates with non-bonding atoms.

Parameters:

  • conf (Chem.Conformer) – The conformer to be set.

  • atom_ids (tuple[int, int]) – The atom IDs to be set.

  • value (Union[int, float]) – The value to be set.

Raises:

NotImplementedError – If the approach for modifying the bond length is not available.

rdtools.conf.set_conformer_coordinates(conf: Conformer, coords: tuple[tuple[float, float, float], ...] | list[list[float]] | ndarray[tuple[int, ...], dtype[float64]]) → None#

Set the Positions of atoms of the conformer.

Parameters:

  • conf (Chem.Conformer) – The conformer to be set.

  • coords (Union[tuple[tuple[float, float, float], ...], list[list[float]], npt.NDArray[np.float64]]) – The coordinates to be set.

rdtools.conf.set_torsion_deg(conf: Conformer, atom_ids: tuple[int, int, int, int], value: int | float) → None#

Set the torsion angle between four atoms in degrees.

If the four atoms are not bonded, the function will give it a try by forming the bonds, adjusting the torsion, and then removing the bonds. This is a workaround for RDKit forbidding modifying internal coordinates with non-bonding atoms.

Parameters:

  • conf (Chem.Conformer) – The conformer to be set.

  • atom_ids (tuple[int, int, int, int]) – The atom IDs to be set.

  • value (Union[int, float]) – The value to be set.

Raises:

NotImplementedError – If the approach for modifying the torsion is not available.