rdtools.mol#

Molecule manipulation functions.

rdtools.mol.combine_mols(mol1: Mol, mol2: Mol, offset: ndarray[tuple[int, ...], dtype[float64]] | None = None, c_product: bool = False) → Mol#

Combine two molecules (mol1 and mol2).

A new object instance will be created and changes are not made to the current molecule.

Parameters:

  • mol1 (Chem.Mol) – The current molecule.

  • mol2 (Chem.Mol) – The molecule to be combined.

  • offset (Optional[npt.NDArray[np.float64]], optional) – The offset to be added to the coordinates of mol2. It should be a length-3 array. This is not used when any of the molecules has 0 conformer. Defaults to None.

  • c_product (bool, optional) –

    If True, generate conformers for every possible combination between the current molecule and the molFrag. E.g., (1,1), (1,2), … (1,n), (2,1), …(m,1), … (m,n). \(N(conformer) = m \\times n.\)

    Defaults to False, meaning only generate conformers according to (1,1), (2,2), … When c_product is set to False, if the current molecule has 0 conformer, conformers will be embedded to the current molecule first. The number of conformers of the combined molecule will be equal to the number of conformers of molFrag. Otherwise, the number of conformers of the combined molecule will be equal to the number of conformers of the current molecule. Some coordinates may be filled by 0s, if the current molecule and molFrag have different numbers of conformers.

Returns:

Chem.Mol – The combined molecule.

rdtools.mol.fast_sanitize(mol: RWMol) → None#

Only update the molecule’s property and ring perception.

rdtools.mol.force_no_implicit(mol: Mol) → None#

Set no implicit hydrogen for atoms without implicit/explicit hydrogens.

When manipulating molecules by changing number of radical electrons / charges and then updating the cached properties, additional hydrogens may be added to the molecule. This function helps avoid this problem.

rdtools.mol.get_atom_masses(mol: Mol) → List[float]#

Get atomic masses of a molecule.

Parameters:

mol (Chem.Mol) – The molecule to get atomic masses.

Returns:

List[float] – List of atomic masses (e.g. [1.008, 12.01, 15.999, ] etc.)

rdtools.mol.get_atomic_nums(mol: Mol) → List[int]#

Get atomic numbers of a molecule.

Parameters:

mol (Chem.Mol) – The molecule to get atomic numbers.

Returns:

List[int] – List of atomic numbers (e.g. [1, 6, 8, ] etc.)

rdtools.mol.get_closed_shell_explicit(mol: RWMol, sanitize: bool = True, max_num_hs: int = 12) → RWMol#

Get the closed shell molecule by explicitly adding H atoms to the molecule.

Parameters:

  • mol (Chem.RWMol) – The radical molecule.

  • sanitize (bool, optional) – Whether to sanitize the molecule. Defaults to True.

  • max_num_hs (int, optional) – The max number of Hs to add on a single atom. This option allows partial saturation for a bi- or tri-radical site. E.g., [CH] => [CH3]. Defaults to 12, which is equivalent to add as many Hs as possible to the radical site.

Returns:

Chem.RWMol – The closed shell molecule.

rdtools.mol.get_closed_shell_implicit(mol: Mol, sanitize: bool = True, max_num_hs: int = 12) → Mol#

Get the closed shell molecule of a radical molecule.

This only adds Hs implicitly and no new atom is actually added to the molecule. This is suggested for the molecule objects with (most) H atoms are not explicitly defined.

Parameters:

  • mol (Chem.Mol) – The radical molecule.

  • sanitize (bool, optional) – Whether to sanitize the molecule. Defaults to True.

  • max_num_hs (int, optional) – The max number of Hs to add on a single atom. This option allows partial saturation for a bi- or tri-radical site. E.g., [CH] => [CH3]. Defaults to 12, which is equivalent to add as many Hs as possible to the radical site.

Returns:

Chem.Mol – The closed shell molecule.

rdtools.mol.get_closed_shell_mol(mol: RWMol, sanitize: bool = True, explicit: bool = True, max_num_hs: int = 12) → RWMol#

Get a closed shell molecule.

The modification is done by removing all radical electrons and adding H atoms to these radical sites. This method currently only work for radicals and will not work properly for singlet radicals (number of radical electrons = 0).

Parameters:

  • mol (Chem.RWMol) – The radical molecule

  • sanitize (bool) – Whether to sanitize the molecule. Defaults to True.

  • explicit (bool) – Whether to use add H atoms explicitly. Defaults to True, which is best used with radical molecules with hydrogen atoms explicitly defined. Setting it to False, if the hydrogen atoms are implicitly defined.

  • max_num_hs (int, optional) – The max number of Hs to add on a single atom. This option allows partial saturation for a bi- or tri-radical site. E.g., [CH] => [CH3]. Defaults to 12, which is equivalent to add as many Hs as possible to the radical site.

Returns:

Chem.RWMol – A closed shell molecule.

rdtools.mol.get_dehydrogenated_mol(mol: Mol, kind: str = 'radical', once_per_heavy: bool = True, only_on_atoms: list[int] | None = None) → list[Mol]#

Get the dehydrogenated molecules.

Generate the molecules that have one less hydrogen atom compared to the reference molecule. This function only supports molecules that have H atoms explicitly defined. Note, this function doesn’t filter out equivalent structures.

Parameters:

  • mol (Chem.Mol) – The reference molecule

  • kind (str, optional) – The kind of generated molecules. The available options are “radical”, “cation”, and “anion”.

  • once_per_heavy (bool, optional) – There can be multiple Hs on a single heavy atom. By setting this argument to True, the function will only remove H atom once per heavy atoms. Otherwise, the function will comprehensively generate dehydrogenated molecule by remove every single H atoms. Defaults to True.

  • only_on_atoms (Optional[list[int]], optional) – This argument allows only operating on specific atoms. Defaults to None, operating on all atoms.

Returns:

list[Chem.Mol] – a list of dehydrogenated molecules

rdtools.mol.get_element_counts(mol: Mol) → dict[str, int]#

Get element counts of a molecule.

Parameters:

mol (Chem.Mol) – The molecule to get element counts.

Returns:

dict[str, int] – {“element_symbol”: count}

rdtools.mol.get_element_symbols(mol: Mol) → List[str]#

Get element symbols of a molecule.

Parameters:

mol (Chem.Mol) – The molecule to get element symbols.

Returns:

List[str] – List of element symbols (e.g. ["H", "C", "O",] etc.)

rdtools.mol.get_formal_charge(mol: Mol) → int#

Get formal charge of a molecule.

Parameters:

mol (Chem.Mol) – The molecule to get formal charge.

Returns:

int – Formal charge.

rdtools.mol.get_heavy_atoms(mol: Mol) → list[Atom]#

Get heavy atoms of a molecule.

Parameters:

mol (Chem.Mol) – The molecule to get heavy atoms.

Returns:

list[Chem.Atom] – the list of heavy atoms.

rdtools.mol.get_heavy_hydrogen_query() → Mol#

Get the heavy hydrogen query.

This is used to find the heavy atom and hydrogen pair in the molecule.

Returns:

Chem.Mol – The heavy hydrogen query.

rdtools.mol.get_mol_weight(mol: Mol, exact: bool = False, heavy_atoms: bool = False) → float#

Get the molecule weight.

Parameters:

  • mol (Chem.Mol) – The molecule to get the weight.

  • exact (bool, optional) – If True, the exact weight is returned. Otherwise, the average weight is returned. Defaults to False.

  • heavy_atoms (bool, optional) – If True, the weight is calculated using only heavy atoms. Otherwise, the weight is calculated using all atoms. Defaults to False.

Returns:

float – The weight of the molecule.

rdtools.mol.get_spin_multiplicity(mol: Mol) → int#

Get spin multiplicity of a molecule.

The spin multiplicity is calculated using Hund’s rule of maximum multiplicity defined as 2S + 1.

Parameters:

mol (Chem.Mol) – The molecule to get spin multiplicity.

Returns:

int – Spin multiplicity.

rdtools.mol.get_writable_copy(mol: Mol) → RWMol#

Get an writable (editable) copy of the current molecule object.

If it is an RWMol, then return a copy with the same type. Otherwise, return a copy in RWMol type.

Parameters:

mol (Chem.Mol) – molecule to copy from.

Returns:

Chem.RWMol – The writable copy of the molecule

rdtools.mol.reflect(mol: Mol, conf_id: int = 0) → None#

Reflect the coordinates of the conformer of the molecule.

Parameters:

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

  • conf_id (int, optional) – The conformer ID to reflect.

rdtools.mol.set_mol_positions(mol: Mol, coords: str | tuple[tuple[float, float, float], ...] | list[list[float]] | ndarray[tuple[int, ...], dtype[float64]], conf_id: int = 0, header: bool = False) → None#

Set the positions of atoms to one of the conformer.

Parameters:

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

  • coords (Union[str, tuple[tuple[float, float, float], ...], list[list[float]], npt.NDArray[np.float64]]) – A tuple/list/ndarray containing atom positions; or a string with the typical XYZ formating.

  • conf_id (int, optional) – Conformer ID to assign the Positions to. Defaults to 0.

  • header (bool, optional) – Whether the XYZ string has an header, if feeding in XYZ. Defaults to False.

Raises:

ValueError – If the conformer ID is invalid.