diff --git a/.readthedocs.yml b/.readthedocs.yml index c85124e7..2999f19c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -18,4 +18,7 @@ formats: all # Optionally set the version of Python and requirements required to build your docs conda: - environment: environment.yml \ No newline at end of file + environment: environment.yml + +build: + image: stable \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 79d365e0..ca03f223 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -35,7 +35,6 @@ 'sphinx.ext.napoleon', # support for NumPy and Google style docstrings 'sphinx.ext.todo', # include to do 'sphinx.ext.coverage', - 'sphinx_automodapi.automodapi' ] # Add any paths that contain templates here, relative to this directory. diff --git a/rdmc/forcefield.py b/rdmc/forcefield.py index b50ae017..c0451c42 100644 --- a/rdmc/forcefield.py +++ b/rdmc/forcefield.py @@ -23,15 +23,36 @@ class RDKitFF(object): """ A wrapper to deal with Force field in RDKit. """ - def __init__(self, force_field:str = 'mmff94s'): + def __init__(self, force_field: str = 'mmff94s'): + """ + Initiate the ``RDKitFF`` by given the name of the force field. + + Args: + force_field: The name of the force field. Supporting: + - MMFF94s (default) + - MMFF94 + - UFF + """ self.ForceField = force_field @property def ForceField(self): + """ + Return the force field backend. + """ return self._ff @ForceField.setter def ForceField(self, force_field): + """ + Reset the force field backend. + + Args: + force_field: The name of the force field. Supporting: + - MMFF94s (default) + - MMFF94 + - UFF + """ force_field = force_field.lower() if not force_field in ['mmff94s', 'mmff94', 'uff']: raise ValueError(f'RDKit does not support {force_field}') @@ -58,13 +79,14 @@ def MakeOptimizable(self, mol: 'RDKitMol', inplace: bool = False): """ - Make the molecule able to be optimized by the force field. - 1. it is known that RO[O] is not optimizable by MMFF. By changing -O[O] to -OF, + Make the molecule able to be optimized by the force field. Known problematic molecules: + + 1. RO[O] is not optimizable by MMFF. By changing -O[O] to -OF, it allows the geometry to be optimized yielding reasonable results. Args: mol ('Mol'): Molecule to be changed. - inplace (bool, optional): Whether to make the change inplace. Defaults to False. + inplace (bool, optional): Whether to make the change inplace. Defaults to ``False``. Returns: ('Mol', dict): A modified molecule and approaches to modify this molecule. @@ -110,7 +132,7 @@ def RecoverMol(self, Args: mol ('Mol'): Molecule to be changed. edits (dict): A dict of approach to modify this molecule - inplace (bool, optional): Whether to make the change inplace. Defaults to True. + inplace (bool, optional): Whether to make the change inplace. Defaults to ``True``. Returns: 'Mol' A recovered molecule. @@ -143,8 +165,8 @@ def _OptimizeConfs(self, Args: mol ('Mol'): A molecule to be optimized. - maxIters (int, optional): max iterations. Defaults to 200. - numThreads (int, optional): number of threads to use. Defaults to 0 for all. + maxIters (int, optional): max iterations. Defaults to ``200``. + numThreads (int, optional): number of threads to use. Defaults to ``0`` for all. Returns: - int: 0 for optimization done; 1 for not optimized; -1 for not optimizable. @@ -175,10 +197,10 @@ def OptimizeConfs(self, Args: mol ('Mol'): A molecule to be optimized. - maxIters (int, optional): max iterations. Defaults to 200. - numThreads (int, optional): number of threads to use. Defaults to 0 for all. + maxIters (int, optional): max iterations. Defaults to ``200``. + numThreads (int, optional): number of threads to use. Defaults to ``0`` for all. maxCycles (int, optional): number of outer cycle. Check convergence after maxIters. - Defaults to 20. + Defaults to ``20``. Returns: - int: 0 for optimization done; 1 for not optimized; -1 for not optimizable. diff --git a/rdmc/mol.py b/rdmc/mol.py index 8539dc7c..ed485a96 100644 --- a/rdmc/mol.py +++ b/rdmc/mol.py @@ -43,10 +43,10 @@ class RDKitMol(object): def __init__(self, mol: Union[Mol, RWMol]): """ - Generate an RDKitMol Molecule instance from a RDKit Chem.rdchem.Mol or RWMol molecule. + Generate an RDKitMol Molecule instance from a RDKit ``Chem.rdchem.Mol`` or ``RWMol`` molecule. Args: - mol (Union[Mol, RWMol]): The RDKit Chem.rdchem.Mol / RWmol molecule to be converted. + mol (Union[Mol, RWMol]): The RDKit ``Chem.rdchem.Mol`` / ``RWmol`` molecule to be converted. """ # keep the link to original molecule so we can easily recover it if needed. if isinstance(mol, Mol): @@ -84,14 +84,14 @@ def AlignMol(self, Args: refMol (Mol): RDKit molecule as a reference. - confid (int, optional): The conformer id to be aligned. Defaults to 0. - refCid (int, optional): The id of reference conformer. Defaults to 0. + confid (int, optional): The conformer id to be aligned. Defaults to ``0``. + refCid (int, optional): The id of reference conformer. Defaults to ``0``. reflect (bool, optional): Whether to reflect the conformation of the probe molecule. - Defaults to False. - atomMap (list, optional): a vector of pairs of atom IDs (probe AtomId, ref AtomId) + Defaults to ``False``. + atomMap (list, optional): a vector of pairs of atom IDs ``(probe AtomId, ref AtomId)`` used to compute the alignments. If this mapping is not specified an attempt is made to generate on by substructure matching. - maxIters (int, optional): maximum number of iterations used in mimizing the RMSD. Defaults to 1000. + maxIters (int, optional): maximum number of iterations used in mimizing the RMSD. Defaults to ``1000``. """ try: return Chem.rdMolAlign.AlignMol(prbMol=self._mol, @@ -121,16 +121,16 @@ def Copy(self) -> 'RDKitMol': def EmbedConformer(self): """ - Embed a conformer to the RDKitMol. This will overwrite current conformers. + Embed a conformer to the ``RDKitMol``. This will overwrite current conformers. """ AllChem.EmbedMolecule(self._mol) def EmbedMultipleConfs(self, n: int = 1): """ - Embed conformers to the RDKitMol. This will overwrite current conformers. + Embed conformers to the ``RDKitMol``. This will overwrite current conformers. Args: - n (int): The number of conformers to be embedded. The default is 1. + n (int): The number of conformers to be embedded. The default is ``1``. """ AllChem.EmbedMultipleConfs(self._mol, numConfs=n) @@ -142,13 +142,13 @@ def FromOBMol(cls, embed: bool = True, ) -> 'RDKitMol': """ - Convert a OpenBabel molecular structure to an RDKit RDMol object. + Convert a OpenBabel Mol to an RDKitMol object. Args: ob_mol (Molecule): An OpenBabel Molecule object for the conversion. - remove_h (bool, optional): Whether to remove hydrogen atoms from the molecule, Defaults to False. - sanitize (bool, optional): Whether to sanitize the RDKit molecule. Defaults to True. - embed (bool, optional): Whether to embeb 3D conformer from OBMol. Defaults to True. + remove_h (bool, optional): Whether to remove hydrogen atoms from the molecule, Defaults to ``False``. + sanitize (bool, optional): Whether to sanitize the RDKit molecule. Defaults to ``True``. + embed (bool, optional): Whether to embeb 3D conformer from OBMol. Defaults to ``True``. Returns: RDKitMol: An RDKit molecule object corresponding to the input OpenBabel Molecule object. @@ -161,10 +161,10 @@ def FromMol(cls, mol: Union[Mol, RWMol], ) -> 'RDKitMol': """ - Convert a RDKit Chem.rdchem.Mol molecule to RDKitMol Molecule. + Convert a RDKit ``Chem.rdchem.Mol`` molecule to ``RDKitMol`` Molecule. Args: - rdmol (Union[Mol, RWMol]): The RDKit Chem.rdchem.Mol / RWMol molecule to be converted. + rdmol (Union[Mol, RWMol]): The RDKit ``Chem.rdchem.Mol`` / ``RWMol`` molecule to be converted. Returns: RDKitMol: An RDKitMol molecule. @@ -178,7 +178,7 @@ def FromSmiles(cls, sanitize: bool = True, ) -> 'RDKitMol': """ - Convert a smiles to an RDkit Mol object. + Convert a SMILES to an ``RDkitMol`` object. Args: smiles (str): A SMILES representation of the molecule. @@ -202,10 +202,10 @@ def FromRMGMol(cls, sanitize: bool = True, ) -> 'RDKitMol': """ - Convert an RMG Molecule to an RDkit Mol object. + Convert an RMG ``Molecule`` to an ``RDkitMol`` object. Args: - smiles (str): An RMG Molecule instance. + smiles (str): An RMG ``Molecule`` instance. remove_h (bool, optional): Whether to remove hydrogen atoms from the molecule, ``True`` to remove. sanitize (bool, optional): Whether to sanitize the RDKit molecule, ``True`` to sanitize. @@ -227,16 +227,17 @@ def FromXYZ(cls, Args: xyz (str): A XYZ String. - backend (str): The backend used to perceive molecule. Defaults to "pybel". - Currently, we only support "pybel" and "jensen". + backend (str): The backend used to perceive molecule. Defaults to ``pybel``. + Currently, we only support ``pybel`` and ``jensen``. header (bool, optional): If lines of the number of atoms and title are included. - Defaults to True. + Defaults to ``True.`` supported kwargs: - jensen: - charge: The charge of the species. Defaults to 0. - - allow_charged_fragments: ``True`` for charged fragment, ``False`` for radical. Defaults to False. - - use_graph: ``True`` to use networkx module for accelerate. Defaults to True. - - use_huckel: ``True`` to use extended Huckel bond orders to locate bonds. Defaults to False. - - embed_chiral: ``True`` to embed chiral information. Defaults to True. + jensen: + - charge: The charge of the species. Defaults to ``0``. + - allow_charged_fragments: ``True`` for charged fragment, ``False`` for radical. Defaults to False. + - use_graph: ``True`` to use networkx module for accelerate. Defaults to True. + - use_huckel: ``True`` to use extended Huckel bond orders to locate bonds. Defaults to False. + - embed_chiral: ``True`` to embed chiral information. Defaults to True. Returns: RDKitMol: An RDKit molecule object corresponding to the xyz. @@ -292,15 +293,10 @@ def GetElementSymbols(self): def GetConformer(self, id: int = 0) -> 'RDKitConf': """ - Get the embedded conformer according to ID. The relationship: - mol - RDKitMol ======== RWMol - owing || || owing - mol || || mol - RDKitConf ====== Conformer - conformer + Get the embedded conformer according to ID. + Args: - id (int): The ID of the conformer to be obtained. The default is 0. + id (int): The ID of the conformer to be obtained. The default is ``0``. Raises: ValueError: Bad id assigned. @@ -324,7 +320,7 @@ def GetConformers(self, Args: ids (Union[list, tuple]): The ids of the conformer to be obtained. - The default is [0]. + The default is ``[0]``. Raises: ValueError: Bad id assigned. @@ -363,9 +359,9 @@ def GetSubstructMatch(self, Returns the indices of the molecule's atoms that match a substructure query. Args: - query (Mol): a Molecule. - useChirality (bool, optional): enables the use of stereochemistry in the matching. Defaults to False. - useQueryQueryMatches (bool, optional): use query-query matching logic. Defaults to False. + query (Mol): a RDkit Molecule. + useChirality (bool, optional): enables the use of stereochemistry in the matching. Defaults to ``False``. + useQueryQueryMatches (bool, optional): use query-query matching logic. Defaults to ``False``. Returns: tuple: A tuple of matched indices. @@ -409,7 +405,7 @@ def GetTorsionalModes(self, Get all of the torsional modes (rotors) from the molecule. Args: - exclude_methyl (bool): Whether exclude the torsions with methyl groups. + exclude_methyl (bool): Whether exclude the torsions with methyl groups. Defaults to ``False``. Returns: list: A list of four-atom-indice to indicating the torsional modes. @@ -426,15 +422,17 @@ def PrepareOutputMol(self, Args: remove_h (bool, optional): Remove less useful explicity H atoms. E.g., When output SMILES, H atoms, - if explicitly added, will be included and reduce the readablity. Note, following Hs are not removed: - 1. H which aren’t connected to a heavy atom. E.g.,[H][H]. - 2. Labelled H. E.g., atoms with atomic number=1, but isotope > 1. - 3. Two coordinate Hs. E.g., central H in C[H-]C. - 4. Hs connected to dummy atoms - 5. Hs that are part of the definition of double bond Stereochemistry. - 6. Hs that are not connected to anything else. - Defaults to False: - sanitize (bool, optional): whether to sanitize the molecule. Defaults to True. + if explicitly added, will be included and reduce the readablity. Defaults to ``False``. + Note, following Hs are not removed: + + 1. H which aren’t connected to a heavy atom. E.g.,[H][H]. + 2. Labelled H. E.g., atoms with atomic number=1, but isotope > 1. + 3. Two coordinate Hs. E.g., central H in C[H-]C. + 4. Hs connected to dummy atoms + 5. Hs that are part of the definition of double bond Stereochemistry. + 6. Hs that are not connected to anything else. + + sanitize (bool, optional): whether to sanitize the molecule. Defaults to ``True``. Returns: Mol: A Mol instance used for output purpose. @@ -453,8 +451,8 @@ def RenumberAtoms(self, Args: newOrder (list): the new ordering the atoms (should be numAtoms long). E.g, - if newOrder is [3,2,0,1], then atom 3 in the original molecule - will be atom 0 in the new one. + if newOrder is [3,2,0,1], then atom 3 in the original molecule + will be atom 0 in the new one. Returns: RDKitMol: Molecule with reordered atoms. @@ -512,11 +510,11 @@ def ToSmiles(self, Convert RDKitMol to a SMILES string. Args: - stereo (bool, optional): Whether keep stereochemistry information. Defaults to True. - kekule (bool, optional): Whether use Kekule form. Defaults to False. - canonical (bool, optional): Whether generate a canonical SMILES. Defaults to True. - mapid (bool, optional): Whether to keep map id information in the SMILES. Defaults to False. - remove_h (bool, optional): Whether to remove H atoms to make obtained SMILES clean. Defaults to True. + stereo (bool, optional): Whether keep stereochemistry information. Defaults to ``True``. + kekule (bool, optional): Whether use Kekule form. Defaults to ``False``. + canonical (bool, optional): Whether generate a canonical SMILES. Defaults to ``True``. + mapid (bool, optional): Whether to keep map id information in the SMILES. Defaults to ``False``. + remove_h (bool, optional): Whether to remove H atoms to make obtained SMILES clean. Defaults to ``True``. Returns: str: The smiles string of the molecule. @@ -543,9 +541,9 @@ def ToXYZ(self, Args: conf_id (int): The conformer ID to be exported. header (bool, optional): Whether to include header (first two lines). - Defaults to True. + Defaults to ``True``. - Returns + Returns: str: The xyz of the molecule. """ xyz = Chem.MolToXYZBlock(self._mol, conf_id) @@ -575,7 +573,7 @@ def EmbedMultipleConfs(self, n: int = 1): All coordinates will be initialized to zeros. Args: - n (int): The number of conformers to be embedded. Defaults to 1. + n (int): The number of conformers to be embedded. Defaults to ``1``. """ self._mol.RemoveAllConformers() num_atoms = self._mol.GetNumAtoms()