rdworks 0.25.7__py3-none-any.whl → 0.35.1__py3-none-any.whl

rdworks/__init__.py

@@ -1,35 +1,34 @@
-__version__ = '0.25.7'
+__version__ = '0.35.1'
+
+from rdworks.conf    import Conf
+from rdworks.mol     import Mol
+from rdworks.mollibr import MolLibr
 
-from rdworks.xml import list_predefined_xml, get_predefined_xml, parse_xml
-from rdworks.units import ev2kcalpermol, hartree2ev, hartree2kcalpermol, periodictable
-from rdworks.readin import read_csv, merge_csv, read_dataframe, read_smi, read_sdf, read_mae 
-from rdworks.std import desalt_smiles, standardize_smiles, standardize
-from rdworks.tautomers import complete_tautomers
 from rdworks.stereoisomers import complete_stereoisomers
+from rdworks.tautomers import complete_tautomers
 from rdworks.ionized import IonizedStates
+
+from rdworks.readin import read_csv, merge_csv, read_dataframe, read_smi, read_sdf, read_mae 
+from rdworks.std import desalt_smiles, standardize_smiles, standardize
+
 from rdworks.rgroup import expand_rgroup, most_common, most_common_in_NP
 from rdworks.scaffold import scaffold_network, scaffold_tree, BRICS_fragmented, BRICS_fragment_indices
 from rdworks.matchedseries import MatchedSeries
-from rdworks.descriptor import rd_descriptor, rd_descriptor_f
-from rdworks.utils import fix_decimal_places_in_list, fix_decimal_places_in_dict, mae_to_dict, mae_rd_index
-from rdworks.display import svg
-from rdworks.conf import Conf
-from rdworks.mol import Mol
-from rdworks.mollibr import MolLibr
 
-from rdkit import rdBase, RDLogger
-rdkit_logger = RDLogger.logger().setLevel(RDLogger.CRITICAL)
+from rdworks.descriptor import rd_descriptor, rd_descriptor_f
+from rdworks.xml import list_predefined_xml, get_predefined_xml, parse_xml
 
+import rdkit
 import logging
 
+__rdkit_version__ = rdkit.rdBase.rdkitVersion
+
+rdkit_logger = rdkit.RDLogger.logger().setLevel(rdkit.RDLogger.CRITICAL)
+
 main_logger = logging.getLogger()
 main_logger.setLevel(logging.INFO) # level: DEBUG < INFO < WARNING < ERROR < CRITICAL
-logger_formatter = logging.Formatter(
-    fmt='%(asctime)s %(levelname)s %(message)s',
-    datefmt='%Y-%m-%d %H:%M:%S')
+logger_formatter = logging.Formatter(fmt='%(asctime)s %(levelname)s %(message)s', 
+                                     datefmt='%Y-%m-%d %H:%M:%S')
 logger_ch = logging.StreamHandler()
 logger_ch.setFormatter(logger_formatter)
 main_logger.addHandler(logger_ch)
-
-
-__rdkit_version__ = rdBase.rdkitVersion

rdworks/conf.py

@@ -1,46 +1,69 @@
 import io
 import copy
 import json
-import types
 import numpy as np
-
 import ase
-from ase.optimize import FIRE
 
 from collections.abc import Callable
+from typing import Self
+
+from mendeleev import element
+from ase.optimize import FIRE
 
 from rdkit import Chem
 from rdkit.Chem import rdMolTransforms, AllChem, rdMolAlign
 from rdkit.Chem.Draw import rdMolDraw2D
+from PIL import Image
 
-from typing import List, Optional, Union, Self
+from rdworks.units import ev2kcalpermol, pm2angstrom
+from rdworks.utils import recursive_round
+from rdworks.xtb.wrapper import GFN2xTB
+from rdworks.display import render_png, render_svg
 
-from .units import ev2kcalpermol
-from .element import radii
 
 class Conf:
-    """Container for 3D conformers.
-    """
+    """Container for 3D conformers."""
     
-    def __init__(self, molecular_input:Chem.Mol, name:str='') -> None:
-        """Create 3D conformers.
+    def __init__(self, molecule: str | Chem.Mol | None = None, name: str='') -> None:
+        """Initialize.
 
         Args:
-            molecular_input (Chem.Mol): Molecule for conformer generation.
-            name (str, optional): Name prefix of the generated conformers. Defaults to ''.
+            molecule (Chem.Mol | MolBlock string): Molecule for 3D conformer.
+            name (str): Name prefix of the generated conformers. Defaults to ''.
 
         Raises:
-            ValueError: if `molecular_input` is not rdkit.Chem.Mol object.
+            ValueError: if `molecule` is not rdkit.Chem.Mol object.
         """
-        self.rdmol = None # has only one rdkit conformer
+        assert isinstance(molecule, str | Chem.Mol) or molecule is None
+
+        self.rdmol = None # must contain one and only one rdkit conformer
         self.name = name
+        self.natoms = 0
         self.props = {}
-        if isinstance(molecular_input, Chem.Mol):
-            self.rdmol = molecular_input
-            self.natoms = self.rdmol.GetNumAtoms()
-            self.props.update({'atoms': self.natoms})
-        else:
-            raise ValueError(f'rdworks.Conf() takes Chem.Mol object')
+
+        if molecule is None:
+            return
+
+        if isinstance(molecule, str): # 3-D MolBLock string
+            try:
+                self.rdmol = Chem.MolFromMolBlock(molecule)
+            except:
+                ValueError(f'Conf() Error: invalid MolBlock string')
+
+        elif isinstance(molecule, Chem.Mol): # 3-D
+            try:
+                self.rdmol = molecule
+            except:
+                ValueError(f'Conf() Error: invalid Chem.Mol object')
+
+        num_atoms = self.rdmol.GetNumAtoms()
+        tot_atoms = self.rdmol.GetNumAtoms(onlyExplicit=False)
+        assert num_atoms == tot_atoms, "Conf() Error: missing hydrogens"
+        self.natoms = num_atoms
+        self.props.update({'atoms': num_atoms})
+     
+        assert self.rdmol.GetConformer().Is3D(), "Conf() Error: not 3D"
+
         
 
     def __str__(self) -> str:
@@ -50,12 +73,7 @@ class Conf:
             str: string representation.
         """
         return f"<rdworks.Conf({self.rdmol} name={self.name} atoms={self.natoms})>"
-    
-
-    ##################################################
-    ### Cascading methods
-    ##################################################
-
+       
 
     def copy(self) -> Self:
         """Returns a copy of self.
@@ -85,7 +103,7 @@ class Conf:
         return self
     
 
-    def sync(self, coord:Union[np.ndarray, list]) -> Self:
+    def sync(self, coord: np.ndarray | list) -> Self:
         """Synchronize the conformer coordinates with the provided `coord`.
 
         Args:
@@ -107,56 +125,31 @@ class Conf:
         return self
 
 
-    def get_potential_energy(self, calculator: str | Callable = 'MMFF94') -> float:
-        """Get potential energy in kcal/mol.
+    def set_torsion(self, i:int, j:int, k:int, l:int, degree:float) -> Self:
+        """Set dihedral angle (i-j-k-l) in degrees.
 
         Args:
-            calculator (str | Callable): MMFF94 (= MMFF), MMFF94s, UFF, or ASE calculator.
-                `MMFF94` or `MMFF` - Intended for general use, including organic molecules and proteins, 
-                    and primarily relies on data from quantum mechanical calculations. 
-                    It's often used in molecular dynamics simulations.
-                `MMFF94s` - A "static" variant of MMFF94, with adjusted parameters for out-of-plane 
-                    bending and dihedral torsions to favor planar geometries for specific nitrogen atoms. 
-                    This makes it better suited for geometry optimization studies where a static, 
-                    time-averaged structure is desired. The "s" stands for "static".
-                `UFF` - UFF refers to the "Universal Force Field," a force field model used for 
-                    molecular mechanics calculations. It's a tool for geometry optimization, 
-                    energy minimization, and exploring molecular conformations in 3D space. 
-                    UFF is often used to refine conformers generated by other methods, 
-                    such as random conformer generation, to produce more physically plausible 
-                    and stable structures.
+            i (int): atom index
+            j (int): atom index
+            k (int): atom index
+            l (int): atom index
+            degree (float): dihedral angle in degrees
 
         Returns:
-            float: potential energy in kcal/mol.
+            Self: modified Conf object
         """
-        PE = None
-        if isinstance(calculator, str):
-            if calculator == 'MMFF94' or calculator == 'MMFF':
-                mp = AllChem.MMFFGetMoleculeProperties(self.rdmol, mmffVariant='MMFF94')
-                ff = AllChem.MMFFGetMoleculeForceField(self.rdmol, mp)
-            elif calculator == 'MMFF94s':
-                mp = AllChem.MMFFGetMoleculeProperties(self.rdmol, mmffVariant='MMFF94s')
-                ff = AllChem.MMFFGetMoleculeForceField(self.rdmol, mp)
-            elif calculator == 'UFF':
-                ff = AllChem.UFFGetMoleculeForceField(self.rdmol)
-            else:
-                raise ValueError("Unsupported calculator")
-            PE = ff.CalcEnergy()
-            self.props.update({'E_tot(kcal/mol)': PE})
-        else:
-            try:
-                ase_atoms = ase.Atoms(symbols=self.symbols(), positions=self.positions())
-                ase_atoms.calc = calculator
-                PE = ase_atoms.get_potential_energy() # np.array
-                PE = ev2kcalpermol * float(PE[0]) # np.float64 to float
-                self.props.update({'E_tot(kcal/mol)': PE})
-            except:
-                raise RuntimeError("ASE calculator error")
-        return PE
+        rdMolTransforms.SetDihedralDeg(self.rdmol.GetConformer(), i, j, k, l, degree)
+
+        return self
     
 
-    def optimize(self, calculator: str | Callable = 'MMFF94', fmax:float=0.05) -> Self:
-        """Optimize conformation using a callable.
+    
+    def optimize(self, 
+                 calculator: str | Callable = 'MMFF94',
+                 fmax:float=0.05, 
+                 max_iter:int=1000,
+                 **kwargs) -> Self:
+        """Optimize 3D geometry.
 
         Args:
             calculator (str | Callable): MMFF94 (= MMFF), MMFF94s, UFF, or ASE calculator.
@@ -173,31 +166,52 @@ class Conf:
                     UFF is often used to refine conformers generated by other methods, 
                     such as random conformer generation, to produce more physically plausible 
                     and stable structures.
-            fmax (float, optional): fmax for the calculator. Defaults to 0.05.
+            fmax (float, optional): fmax for the calculator convergence. Defaults to 0.05.
+            max_iter (int, optional): max iterations for the calculator. Defaults to 1000.
+            
+        Args for xTB:
+            water (str, optional): water solvation model (choose 'gbsa' or 'alpb')
+                alpb: ALPB solvation model (Analytical Linearized Poisson-Boltzmann).
+                gbsa: generalized Born (GB) model with Surface Area contributions.
 
         Returns:
             Self: self
         """
         if isinstance(calculator, str) :
-            init = self.get_potential_energy(calculator)
-            if calculator == 'MMFF94' or calculator == 'MMFF':
-                retcode = AllChem.MMFFOptimizeMolecule(self.rdmol, mmffVariant='MMFF94')
+            
+            PE_start = self.potential_energy(calculator)
+            
+            if calculator.lower() == 'xTB'.lower():
+                water = kwargs.get('water', None)
+                PE_final, self.rdmol = GFN2xTB(self.rdmol).optimize(water=water)
+
+            elif calculator.lower() == 'MMFF94'.lower() or calculator.lower() == 'MMFF'.lower():
+                retcode = Chem.rdForceFieldHelpers.MMFFOptimizeMolecule(self.rdmol, 
+                                                                        mmffVariant='MMFF94',
+                                                                        maxIters=max_iter)
                 # returns 0 if the optimization converged
-            elif calculator == 'MMFF94s':
-                retcode = AllChem.MMFFOptimizeMolecule(self.rdmol, mmffVariant='MMFF94s')
+            elif calculator.lower() == 'MMFF94s'.lower():
+                retcode = Chem.rdForceFieldHelpers.MMFFOptimizeMolecule(self.rdmol, 
+                                                                        mmffVariant='MMFF94s',
+                                                                        maxIters=max_iter)
                 # returns 0 if the optimization converged
-            elif calculator == 'UFF':
-                retcode = AllChem.UFFOptimizeMolecule(self.rdmol)
+            elif calculator.lower() == 'UFF'.lower():
+                retcode = Chem.rdForceFieldHelpers.UFFOptimizeMolecule(self.rdmol,
+                                                                       maxIters=max_iter)
                 # returns 0 if the optimization converged
-            final = self.get_potential_energy(calculator)
+
+            PE_final = self.potential_energy(calculator)
+            
             self.props.update({
-                'E_tot_init(kcal/mol)': init , # energy before optimization
-                'E_tot(kcal/mol)': final, # energy after optimization
+                'E_tot_init(kcal/mol)': PE_start , # energy before optimization
+                'E_tot(kcal/mol)': PE_final, # energy after optimization
                 'Converged' : retcode == 0, # True or False
             })
+            
             return self
 
         else:
+            # assuming ASE calculator
             with io.StringIO() as logfile:
                 ase_atoms = ase.Atoms(symbols=self.symbols(), positions=self.positions())
                 ase_atoms.calc = calculator
@@ -209,9 +223,11 @@ class Conf:
                     'E_tot(kcal/mol)': data[-1][0] * ev2kcalpermol, # energy after optimization
                     'Converged' : data[-1][1] < fmax, # True or False
                 })
+                
                 # update atomic coordinates
                 return self.sync(ase_atoms.get_positions())
  
+    
 
     ##################################################
     ### Endpoint methods
@@ -233,13 +249,13 @@ class Conf:
             idx2 = bond.GetEndAtomIdx()
             nuc1 = self.rdmol.GetAtomWithIdx(idx1).GetAtomicNum()
             nuc2 = self.rdmol.GetAtomWithIdx(idx2).GetAtomicNum()
-            sum_radii = (radii[nuc1] + radii[nuc2])
+            sum_radii = (element(nuc1).vdw_radius + element(nuc2).vdw_radius) * pm2angstrom
             bond_length = rdMolTransforms.GetBondLength(self.rdmol.GetConformer(), idx1, idx2)
             if abs(bond_length - sum_radii) > tolerance:
                 return False
             
         return True
-
+    
 
     def positions(self) -> np.array:
         """Returns the coordinates.
@@ -298,14 +314,94 @@ class Conf:
         return np.sqrt(np.mean(b))
 
 
-    def serialize(self, key:str='') -> dict:
+    def potential_energy(self, calculator: str | Callable = 'MMFF94', **kwargs) -> float:
+        """Get potential energy and set `E_tot(kcal/mol)` in the self.props.
+
+        Args:
+            calculator (str | Callable): MMFF94 (= MMFF), MMFF94s, UFF, or ASE calculator.
+                `MMFF94` or `MMFF` - Intended for general use, including organic molecules and proteins, 
+                    and primarily relies on data from quantum mechanical calculations. 
+                    It's often used in molecular dynamics simulations.
+                `MMFF94s` - A "static" variant of MMFF94, with adjusted parameters for out-of-plane 
+                    bending and dihedral torsions to favor planar geometries for specific nitrogen atoms. 
+                    This makes it better suited for geometry optimization studies where a static, 
+                    time-averaged structure is desired. The "s" stands for "static".
+                `UFF` - UFF refers to the "Universal Force Field," a force field model used for 
+                    molecular mechanics calculations. It's a tool for geometry optimization, 
+                    energy minimization, and exploring molecular conformations in 3D space. 
+                    UFF is often used to refine conformers generated by other methods, 
+                    such as random conformer generation, to produce more physically plausible 
+                    and stable structures.
+
+        Returns:
+            float | None: potential energy in kcal/mol or None.
+        """
+
+        if isinstance(calculator, str):
+            if calculator.lower() == 'xTB'.lower():
+                water = kwargs.get('water', None)
+                PE = GFN2xTB(self.rdmol).singlepoint(water=water)
+            
+            elif calculator.lower() == 'MMFF94'.lower() or calculator.lower() == 'MMFF'.lower():
+                mp = Chem.rdForceFieldHelpers.MMFFGetMoleculeProperties(self.rdmol, mmffVariant='MMFF94')
+                ff = Chem.rdForceFieldHelpers.MMFFGetMoleculeForceField(self.rdmol, mp)
+                PE = ff.CalcEnergy()
+            
+            elif calculator.lower() == 'MMFF94s'.lower():
+                mp = Chem.rdForceFieldHelpers.MMFFGetMoleculeProperties(self.rdmol, mmffVariant='MMFF94s')
+                ff = Chem.rdForceFieldHelpers.MMFFGetMoleculeForceField(self.rdmol, mp)
+                PE = ff.CalcEnergy()
+            
+            elif calculator.lower() == 'UFF'.lower():
+                ff = Chem.rdForceFieldHelpers.UFFGetMoleculeForceField(self.rdmol)
+                PE = ff.CalcEnergy()
+            
+            else:
+                raise ValueError("Unsupported calculator")                
+            
+            self.props.update({'E_tot(kcal/mol)': PE})
+
+            return PE
+        
+        else:
+            try:
+                ase_atoms = ase.Atoms(symbols=self.symbols(), positions=self.positions())
+                ase_atoms.calc = calculator
+                PE = ase_atoms.get_potential_energy() # np.array
+                PE = ev2kcalpermol * float(PE[0]) # np.float64 to float
+                self.props.update({'E_tot(kcal/mol)': PE})
+            
+                return PE
+            
+            except:
+                raise RuntimeError("ASE calculator error")
+
+
+    def torsion_angle(self, i:int, j:int, k:int, l:int) -> float:
+        """Get dihedral angle (i-j-k-l) in degrees.
+
+        Args:
+            i (int): atom index
+            j (int): atom index
+            k (int): atom index
+            l (int): atom index
+
+        Returns:
+            float: dihedral angle in degrees.
+        """
+        degree = rdMolTransforms.GetDihedralDeg(self.rdmol.GetConformer(), i, j, k, l)
+
+        return degree
+
+
+    def dumps(self, key:str='') -> str:
         """Returns JSON dumps of the `props`.
 
         Args:
             key (str): a key for the `props` dictionary. Defaults to '' (all).
 
         Returns:
-            dict: JSON dumps.
+            str: JSON dumps.
         """
         if key:
             return json.dumps({key:self.props[key]})
@@ -313,6 +409,59 @@ class Conf:
             return json.dumps(self.props)
     
 
+    def serialize(self, decimals:int=3) -> str:
+        """Serialize information necessary to rebuild.
+
+        Returns:
+            str: serialized string for json.loads()
+        """
+        serialized = json.dumps({
+            'name' : self.name, 
+            'natoms': self.natoms, 
+            'props' : recursive_round(self.props, decimals),
+            'molblock' : self.to_molblock(),
+            })
+
+        return serialized
+
+
+    def deserialize(self, serialized:str) -> Self:
+        """De-serialize information and rebuild.
+
+        Args:
+            serialized (str): _description_
+
+        Returns:
+            Self: _description_
+        """
+        data = json.loads(serialized)
+
+        self.name = data['name']
+        self.natoms = data['natoms']
+        self.props = data['props']
+        self.rdmol = Chem.MolFromMolBlock(data['molblock'], sanitize=False, removeHs=False)
+
+        return self
+
+
+    def to_molblock(self) -> str:
+        """Returns MolBlock"""
+        return Chem.MolToMolBlock(self.rdmol)
+
+
+    def to_xyz(self) -> str:
+        """Returns XYZ formatted strings.
+
+        Returns:
+            str: XYZ formatted strings.
+        """
+        lines = [f'{self.natoms}', ' ']
+        for e, (x, y, z) in zip(self.symbols(), self.positions()):
+            lines.append(f'{e:5} {x:23.14f} {y:23.14f} {z:23.14f}')
+        
+        return '\n'.join(lines)
+
+
     def to_sdf(self, props:bool=True) -> str:
         """Returns the SDF-formatted strings.
 
@@ -332,43 +481,85 @@ class Conf:
             f.write(rdmol)
         return in_memory.getvalue()
     
+
+    def to_png(self,
+               width: int = 300, 
+               height: int = 300,
+               legend: str = '', 
+               atom_index: bool = False, 
+               highlight_atoms: list[int] | None = None,
+               highlight_bonds: list[int] | None = None,
+               redraw: bool = False,
+               coordgen: bool = False,
+               trim: bool = True) -> Image.Image:
+        """Draw 2D molecule in PNG format.
+
+        Args:
+            width (int, optional): width. Defaults to 300.
+            height (int, optional): height. Defaults to 300.
+            legend (str, optional): legend. Defaults to ''.
+            atom_index (bool, optional): whether to show atom index. Defaults to False.
+            highlight_atoms (list[int] | None, optional): atom(s) to highlight. Defaults to None.
+            highlight_bonds (list[int] | None, optional): bond(s) to highlight. Defaults to None.
+            redraw (bool, optional): whether to redraw. Defaults to False.
+            coordgen (bool, optional): whether to use coordgen. Defaults to False.
+            trim (bool, optional): whether to trim white margins. Default to True.
+        
+        Returns:
+            Image.Image: output PIL Image object.
+        """
+        
+        return render_png(self.rdmol,
+                          width = width, 
+                          height = height, 
+                          legend = legend, 
+                          atom_index = atom_index, 
+                          highlight_atoms = highlight_atoms,
+                          highlight_bonds = highlight_bonds,
+                          redraw = redraw, 
+                          coordgen = coordgen, 
+                          trim = trim)
+    
     
-    def to_svg(self, 
-               width:int=400, 
-               height:int=400,
-               legend:Optional[str]=None, 
-               atom_index:bool=False, 
-               highlight:Optional[List[int]]=None) -> str:
-        """Returns 2D SVG depiction of the molecule.
+    def to_svg(self,
+               width: int = 300,
+               height: int = 300,
+               legend: str = '', 
+               atom_index: bool = False, 
+               highlight_atoms: list[int] | None = None,
+               highlight_bonds: list[int] | None = None,
+               redraw: bool = False,
+               coordgen: bool = False,
+               optimize: bool = True) -> str:
+        """Draw 2D molecule in SVG format.
 
         Examples:
+            For Jupyternotebook, wrap the output with SVG:
+
             >>> from IPython.display import SVG
-            >>> SVG(libr[0].confs[0].to_svg(atom_index=True))
+            >>> SVG(libr[0].to_svg())
 
         Args:
-            width (int): width (default:400)
-            height (int): height (default:400)
-            legend (str, optional): title or Mol.name if not given
-            atom_index (bool): True/False whether to display atom index
-            highlight (list): list of atom indices to highlight
-            
+            width (int, optional): width. Defaults to 300.
+            height (int, optional): height. Defaults to 300.
+            legend (str, optional): legend. Defaults to ''.
+            atom_index (bool, optional): whether to show atom index. Defaults to False.
+            highlight_atoms (list[int] | None, optional): atom(s) to highlight. Defaults to None.
+            highlight_bonds (list[int] | None, optional): bond(s) to highlight. Defaults to None.
+            redraw (bool, optional): whether to redraw. Defaults to False.
+            coordgen (bool, optional): whether to use coordgen. Defaults to False.
+            optimize (bool, optional): whether to optimize SVG string. Defaults to True.
+
         Returns:
-            str: SVG text
+            str: SVG string
         """
-        rdmol_3d = Chem.Mol(self.rdmol) # a copy of self.rdmol (3D, with hydrogens)
-        AllChem.Compute2DCoords(rdmol_3d) # 2D depiction
-        for atom in rdmol_3d.GetAtoms():
-            for key in atom.GetPropsAsDict():
-                atom.ClearProp(key)
-        drawer = rdMolDraw2D.MolDraw2DSVG(width, height)
-        if not legend:
-            legend = self.name
-        if atom_index:
-            for atom in rdmol_3d.GetAtoms():
-                atom.SetProp("atomLabel", str(atom.GetIdx()))
-        if highlight:
-            drawer.DrawMolecule(rdmol_3d, legend=legend, highlightAtoms=highlight)
-        else:
-            drawer.DrawMolecule(rdmol_3d, legend=legend)
-        drawer.FinishDrawing()
-        return drawer.GetDrawingText()
+        return render_svg(self.rdmol, 
+                          width = width, 
+                          height = height, 
+                          legend = legend, 
+                          atom_index = atom_index, 
+                          highlight_atoms = highlight_atoms,
+                          highlight_bonds = highlight_bonds,
+                          redraw = redraw, 
+                          coordgen = coordgen, 
+                          optimize = optimize)