stjames 0.0.61__py3-none-any.whl → 0.0.62__py3-none-any.whl

stjames/atomium_stjames/utilities.py

@@ -2,17 +2,19 @@
 
 import builtins
 import gzip
-from typing import Any
+from pathlib import Path
+from typing import Any, Callable
 
-from requests import get  # type: ignore [import-untyped]
+from requests import get  # type: ignore[import-untyped]
 
 from .mmcif import mmcif_dict_to_data_dict, mmcif_string_to_mmcif_dict
 from .pdb import pdb_dict_to_data_dict, pdb_string_to_pdb_dict
 
 
-def open(path: str, *args, **kwargs) -> Any:  # type: ignore [no-untyped-def]
-    """Opens a file at a given path, works out what filetype it is, and parses
-    it accordingly.
+def open(path: Path | str, file_dict: bool = False, data_dict: bool = False) -> dict[str, Any]:
+    """
+    Opens a file at a given path, works out what filetype it is, and parses it
+    accordingly.
 
     For example:
     open('/path/to/file.pdb', data_dict=True)
@@ -26,26 +28,29 @@ def open(path: str, *args, **kwargs) -> Any:  # type: ignore [no-untyped-def]
     :param bool file_dict: if ``True``, parsing will stop at the file ``dict``.
     :param bool data_dict: if ``True``, parsing will stop at the data ``dict``.
     :rtype: ``File``"""
+    path = Path(path)
 
-    if str(path)[-3:] == ".gz":
+    if path.suffix == ".gz":
         try:
             with gzip.open(path) as f:
                 filestring = f.read().decode()
         except Exception:
             with gzip.open(path, "rt") as f:
                 filestring = f.read()
-        return parse_string(filestring, path[:-3], *args, **kwargs)
-    else:
-        try:
-            with builtins.open(path) as f:
-                filestring = f.read()
-        except Exception:
-            with builtins.open(path, "rb") as f:
-                filestring = f.read()  # type: ignore [assignment]
-        return parse_string(filestring, path, *args, **kwargs)
 
+        return parse_string(filestring, path.suffix, file_dict=file_dict, data_dict=data_dict)
+
+    try:
+        with builtins.open(path) as f:
+            filestring = f.read()
+    except Exception:
+        with builtins.open(path, "rb") as f:
+            filestring = f.read()  # type: ignore [assignment]
 
-def fetch(code: str, *args, **kwargs) -> Any:  # type: ignore [no-untyped-def]
+    return parse_string(filestring, path, file_dict=file_dict, data_dict=data_dict)
+
+
+def fetch(code: str, file_dict: bool = False, data_dict: bool = False) -> dict[str, Any]:
     """Fetches a file from a remote location via HTTP.
 
     If a PDB code is given, the .cif form of that struture will be fetched from
@@ -59,11 +64,11 @@ def fetch(code: str, *args, **kwargs) -> Any:  # type: ignore [no-untyped-def]
     This will get the .mmtf version of structure 1LOL, but only go as far as
     converting it to an atomium file dictionary.
 
-    :param str code: the file to fetch.
-    :param bool file_dict: if ``True``, parsing will stop at the file ``dict``.
-    :param bool data_dict: if ``True``, parsing will stop at the data ``dict``.
-    :raises ValueError: if no file is found.
-    :rtype: ``File``"""
+    :param code: the file to fetch.
+    :param file_dict: if ``True``, parsing will stop at the file ``dict``
+    :param data_dict: if ``True``, parsing will stop at the data ``dict``
+    :raises ValueError: if no file is found
+    """
 
     if code.startswith("http"):
         url = code
@@ -76,50 +81,57 @@ def fetch(code: str, *args, **kwargs) -> Any:  # type: ignore [no-untyped-def]
     response = get(url, stream=True)
     if response.status_code == 200:
         text = response.content if code.endswith(".mmtf") else response.text
-        return parse_string(text, code, *args, **kwargs)
-    raise ValueError("Could not find anything at {}".format(url))
+        return parse_string(text, code, file_dict=file_dict, data_dict=data_dict)
 
+    raise ValueError(f"Could not find anything at {url}")
 
-def parse_string(filestring: str, path: str, file_dict: bool = False, data_dict: bool = False) -> Any:
-    """Takes a filestring and parses it in the appropriate way. You must provide
+
+def parse_string(filestring: Any, path: Path | str, file_dict: bool = False, data_dict: bool = False) -> dict[str, Any]:
+    """
+    Takes a filestring and parses it in the appropriate way. You must provide
     the string to parse itself, and some other string that ends in either .cif,
     .mmtf, or .cif - that will determine how the file is parsed.
 
     (If this cannot be inferred from the path string, atomium will guess based
     on the filestring contents.)
 
-    :param str filestring: the contents of some file.
-    :param str path: the filename of the file of origin.
-    :param bool file_dict: if ``True``, parsing will stop at the file ``dict``.
-    :param bool data_dict: if ``True``, parsing will stop at the data ``dict``.
-    :rtype: ``File``"""
+    :param filestring:  contents of some file
+    :param path: filename of the file of origin
+    :param file_dict: if ``True``, parsing will stop at the file ``dict``
+    :param data_dict: if ``True``, parsing will stop at the data ``dict``
+    :return: File
+    """
 
     file_func, data_func = get_parse_functions(filestring, path)
     parsed = file_func(filestring)
+
     if not file_dict:
         parsed = data_func(parsed)
+
     return parsed
 
 
-def get_parse_functions(filestring: str, path: str) -> Any:
-    """Works out which parsing functions to use for a given filestring and
-    returns them.
+def get_parse_functions(filestring: str, path: Path | str) -> tuple[Callable[[str], dict[str, Any]], Callable[[dict[str, Any]], dict[str, Any]]]:
+    """
+    Determines the parsing functions to use for a given filestring and path.
 
     (If this cannot be inferred from the path string, atomium will guess based
     on the filestring contents.)
 
-    :param str filestring: the filestring to inspect.
-    :param str path: the path to inspect.
-    :rtype: ``tuple``"""
-
-    if "." in path:
-        ending = path.split(".")[-1]
-        if ending in ("mmtf", "cif", "pdb"):
-            return {
-                "cif": (mmcif_string_to_mmcif_dict, mmcif_dict_to_data_dict),
-                "pdb": (pdb_string_to_pdb_dict, pdb_dict_to_data_dict),
-            }[ending]
+    :param filestring: the filestring to inspect
+    :param path: the path to inspect
+    """
+    path = Path(path)
+
+    funcs = {
+        ".mmtf": (mmcif_string_to_mmcif_dict, mmcif_dict_to_data_dict),
+        ".cif": (mmcif_string_to_mmcif_dict, mmcif_dict_to_data_dict),
+        ".pdb": (pdb_string_to_pdb_dict, pdb_dict_to_data_dict),
+    }
+
+    if path.suffix:
+        return funcs.get(path.suffix, (pdb_string_to_pdb_dict, pdb_dict_to_data_dict))
     elif "_atom_sites" in filestring:
         return (mmcif_string_to_mmcif_dict, mmcif_dict_to_data_dict)
-    else:
-        return (pdb_string_to_pdb_dict, pdb_dict_to_data_dict)
+
+    return (pdb_string_to_pdb_dict, pdb_dict_to_data_dict)

stjames/molecule.py

@@ -1,9 +1,11 @@
 import re
 from pathlib import Path
-from typing import Annotated, Iterable, Optional, Self
+from typing import Annotated, Iterable, Optional, Self, TypeAlias
 
 import pydantic
 from pydantic import AfterValidator, NonNegativeInt, PositiveInt, ValidationError
+from rdkit import Chem
+from rdkit.Chem import AllChem
 
 from .atom import Atom
 from .base import Base, round_float, round_optional_float
@@ -20,6 +22,8 @@ from .types import (
     round_vector3d_per_atom,
 )
 
+RdkitMol: TypeAlias = Chem.rdchem.Mol | Chem.rdchem.RWMol
+
 
 class MoleculeReadError(RuntimeError):
     pass
@@ -263,6 +267,47 @@ class Molecule(Base):
         except (ValueError, ValidationError) as e:
             raise MoleculeReadError("Error reading molecule from extxyz") from e
 
+    @classmethod
+    def from_rdkit(cls: type[Self], rdkm: RdkitMol, cid: int = 0) -> Self:
+        if len(rdkm.GetConformers()) == 0:
+            rdkm = _embed_rdkit_mol(rdkm)
+
+        atoms = []
+        atomic_numbers = [atom.GetAtomicNum() for atom in rdkm.GetAtoms()]  # type: ignore [no-untyped-call]
+        geom = rdkm.GetConformers()[cid].GetPositions()
+
+        for i in range(len(atomic_numbers)):
+            atoms.append(Atom(atomic_number=atomic_numbers[i], position=geom[i]))
+
+        charge = Chem.GetFormalCharge(rdkm)
+        multiplicity = 1
+
+        return cls(atoms=atoms, charge=charge, multiplicity=multiplicity)
+
+    @classmethod
+    def from_smiles(cls: type[Self], smiles: str) -> Self:
+        return cls.from_rdkit(Chem.MolFromSmiles(smiles))
+
+
+def _embed_rdkit_mol(rdkm: RdkitMol) -> RdkitMol:
+    try:
+        AllChem.SanitizeMol(rdkm)  # type: ignore [attr-defined]
+    except Exception as e:
+        raise ValueError("Molecule could not be generated -- invalid chemistry!\n") from e
+
+    rdkm = AllChem.AddHs(rdkm)  # type: ignore [attr-defined]
+    try:
+        status1 = AllChem.EmbedMolecule(rdkm, maxAttempts=200)  # type: ignore [attr-defined]
+        assert status1 >= 0
+    except Exception as e:
+        status1 = AllChem.EmbedMolecule(rdkm, maxAttempts=200, useRandomCoords=True)  # type: ignore [attr-defined]
+        if status1 < 0:
+            raise ValueError(f"Cannot embed molecule! Error: {e}")
+
+    AllChem.MMFFOptimizeMolecule(rdkm, maxIters=200)  # type: ignore [attr-defined]
+
+    return rdkm
+
 
 def parse_comment_line(line: str) -> PeriodicCell:
     """

stjames/types.py

@@ -1,4 +1,4 @@
-from typing import Callable, TypeAlias
+from typing import Callable, Iterable, TypeAlias
 
 UUID: TypeAlias = str
 
@@ -10,6 +10,15 @@ FloatPerAtom: TypeAlias = list[float]
 Matrix3x3: TypeAlias = tuple[Vector3D, Vector3D, Vector3D]
 
 
+def round_list(round_to: int = 6) -> Callable[[Iterable[float]], list[float]]:
+    """Create a validator that rounds each float in a list to a given number of decimal places."""
+
+    def rounder(values: Iterable[float]) -> list[float]:
+        return [round(value, round_to) for value in values]
+
+    return rounder
+
+
 def round_vector3d(round_to: int = 6) -> Callable[[Vector3D], Vector3D]:
     """Create a validator that rounds each component of a Vector3D to a given number of decimal places."""
 

stjames/workflows/__init__.py

@@ -18,9 +18,10 @@ from .multistage_opt import *
 from .pka import *
 from .redox_potential import *
 from .scan import *
+from .solubility import *
 from .spin_states import *
 from .tautomer import *
-from .workflow import Workflow
+from .workflow import *
 
 WORKFLOW_NAME = Literal[
     "admet",
@@ -39,11 +40,12 @@ WORKFLOW_NAME = Literal[
     "pka",
     "redox_potential",
     "scan",
+    "solubility",
     "spin_states",
     "tautomers",
 ]
 
-WORKFLOW_MAPPING: dict[str, Workflow] = {
+WORKFLOW_MAPPING: dict[WORKFLOW_NAME, Workflow] = {
     "admet": ADMETWorkflow,  # type: ignore [dict-item]
     "basic_calculation": BasicCalculationWorkflow,  # type: ignore [dict-item]
     "bde": BDEWorkflow,  # type: ignore [dict-item]
@@ -60,6 +62,7 @@ WORKFLOW_MAPPING: dict[str, Workflow] = {
     "pka": pKaWorkflow,  # type: ignore [dict-item]
     "redox_potential": RedoxPotentialWorkflow,  # type: ignore [dict-item]
     "scan": ScanWorkflow,  # type: ignore [dict-item]
+    "solubility": SolubilityWorkflow,  # type: ignore [dict-item]
     "spin_states": SpinStatesWorkflow,  # type: ignore [dict-item]
     "tautomers": TautomerWorkflow,  # type: ignore [dict-item]
 }

stjames/workflows/admet.py

@@ -1,7 +1,18 @@
-from typing import Optional
+"""ADME-Tox property prediction workflow."""
 
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 
-class ADMETWorkflow(Workflow):
-    properties: Optional[dict[str, float | int]] = None
+class ADMETWorkflow(MoleculeWorkflow):
+    """
+    A workflow for predicting ADME-Tox properties.
+
+    Inherited:
+    :param initial_molecule: Molecule of interest
+    :param mode: Mode for workflow (currently unused)
+
+    New:
+    :param properties: predicted properties
+    """
+
+    properties: dict[str, float | int] | None = None

stjames/workflows/basic_calculation.py

@@ -1,9 +1,24 @@
+"""Basic calculation workflow."""
+
 from ..settings import Settings
 from ..types import UUID
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
+
+
+class BasicCalculationWorkflow(MoleculeWorkflow):
+    """
+    Workflow for a basic calculation.
+
+    Inherited:
+    :param initial_molecule: Molecule of interest
+    :param mode: Mode for workflow
 
+    New:
+    :param settings: Settings for running the calculation
+    :param engine: Engine to use
+    :param calculation_uuid: UUID of the calculation
+    """
 
-class BasicCalculationWorkflow(Workflow):
     settings: Settings
     engine: str
     calculation_uuid: UUID | None = None

stjames/workflows/bde.py

@@ -1,4 +1,4 @@
-"""Bond Dissociation Energy (BDE) workflow."""
+"""Bond-dissociation energy (BDE) workflow."""
 
 import itertools
 from typing import Annotated, Any, Iterable, Self, TypeVar
@@ -10,7 +10,7 @@ from ..mode import Mode
 from ..molecule import Molecule
 from ..types import UUID
 from .multistage_opt import MultiStageOptMixin
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 # the id of a mutable object may change, thus using object()
 _sentinel_mso_mode = object()
@@ -19,7 +19,7 @@ _T = TypeVar("_T")
 
 class BDE(BaseModel):
     """
-    Bond Dissociation Energy (BDE) result.
+    Bond-dissociation energy (BDE) result.
 
     energy => (E_{fragment1} + E_{fragment2}) - E_{starting molecule}
 
@@ -49,9 +49,9 @@ class BDE(BaseModel):
         return f"<{type(self).__name__} {self.fragment_idxs} {energy}>"
 
 
-class BDEWorkflow(Workflow, MultiStageOptMixin):
+class BDEWorkflow(MoleculeWorkflow, MultiStageOptMixin):
     """
-    Bond Dissociation Energy (BDE) workflow.
+    Bond-dissociation energy (BDE) workflow.
 
     Uses the modes from MultiStageOptSettings to compute BDEs.
 

stjames/workflows/conformer.py

@@ -1,3 +1,5 @@
+"""Deprecated conformer search workflow, use ConformerSearchWorkflow instead."""
+
 from typing import Annotated, Any, Optional
 
 from pydantic import AfterValidator
@@ -7,7 +9,7 @@ from ..constraint import Constraint
 from ..method import Method
 from ..mode import Mode
 from ..solvent import Solvent
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 
 class ConformerSettings(Base):
@@ -42,7 +44,7 @@ class Conformer(Base):
     uuid: Optional[str] = None
 
 
-class ConformerWorkflow(Workflow):
+class ConformerWorkflow(MoleculeWorkflow):
     mode: Mode = Mode.RAPID
     settings: ConformerSettings = ConformerSettings()
     conformers: list[Conformer] = []

stjames/workflows/conformer_search.py

@@ -1,4 +1,4 @@
-"""Conformer Search Workflow."""
+"""Conformer search workflow."""
 
 from abc import ABC
 from typing import Annotated, Self, Sequence, TypeVar
@@ -11,7 +11,7 @@ from ..method import Method, XTBMethod
 from ..mode import Mode
 from ..types import UUID, FloatPerAtom, round_float_per_atom
 from .multistage_opt import MultiStageOptMixin
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 _sentinel = object()
 
@@ -338,7 +338,7 @@ class ConformerSearchMixin(ConformerGenMixin, MultiStageOptMixin):
         return self
 
 
-class ConformerSearchWorkflow(ConformerSearchMixin, Workflow):
+class ConformerSearchWorkflow(ConformerSearchMixin, MoleculeWorkflow):
     """
     ConformerSearch Workflow.
 

stjames/workflows/descriptors.py

@@ -1,11 +1,24 @@
+"""Molecular descriptors workflow."""
+
 from ..types import UUID
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 Descriptors = dict[str, dict[str, float] | tuple[float | None, ...] | float]
 
 
-class DescriptorsWorkflow(Workflow):
-    # UUID of optimization
+class DescriptorsWorkflow(MoleculeWorkflow):
+    """
+    A workflow for calculating molecular descriptors.
+
+    Inherited:
+    :param initial_molecule: Molecule of interest
+    :param mode: Mode for workflow
+
+    New:
+    :param optimization: UUID of optimization
+    :param descriptors: calculated descriptors
+    """
+
     optimization: UUID | None = None
 
     descriptors: Descriptors | None = None

stjames/workflows/docking.py

@@ -7,7 +7,7 @@ from pydantic import AfterValidator, ConfigDict, field_validator, model_validato
 from ..base import Base, round_float
 from ..pdb import PDB
 from ..types import UUID, Vector3D
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 
 class Score(Base):
@@ -22,7 +22,7 @@ class Score(Base):
     score: Annotated[float, AfterValidator(round_float(3))]
 
 
-class DockingWorkflow(Workflow):
+class DockingWorkflow(MoleculeWorkflow):
     """
     Docking workflow.
 
@@ -84,7 +84,7 @@ class DockingWorkflow(Workflow):
 
     @field_validator("pocket", mode="after")
     def validate_pocket(cls, pocket: tuple[Vector3D, Vector3D]) -> tuple[Vector3D, Vector3D]:
-        center, size = pocket
+        _center, size = pocket
         if any(q <= 0 for q in size):
             raise ValueError(f"Pocket size must be positive, got: {size}")
         return pocket

stjames/workflows/electronic_properties.py

@@ -1,3 +1,5 @@
+"""Electronic properties workflow."""
+
 from typing import Annotated
 
 from pydantic import AfterValidator, NonNegativeFloat, NonNegativeInt
@@ -5,7 +7,7 @@ from pydantic import AfterValidator, NonNegativeFloat, NonNegativeInt
 from ..base import Base, round_float
 from ..settings import Settings
 from ..types import UUID, FloatPerAtom, Matrix3x3, Vector3D, round_optional_float_per_atom, round_optional_matrix3x3, round_optional_vector3d
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 
 class PropertyCubePoint(Base):
@@ -34,12 +36,13 @@ class MolecularOrbitalCube(PropertyCube):
     energy: Annotated[float, AfterValidator(round_float(6))]
 
 
-class ElectronicPropertiesWorkflow(Workflow):
+class ElectronicPropertiesWorkflow(MoleculeWorkflow):
     """
     Workflow for computing electronic properties.
 
     Inherited
     :param initial_molecule: Molecule of interest
+    :param mode: Mode for workflow (currently unused)
 
     Config settings:
     :param settings: settings for the calculation

stjames/workflows/fukui.py

@@ -1,13 +1,30 @@
+"""Fukui index workflow."""
+
 from typing import Annotated
 
 from pydantic import AfterValidator
 
 from ..base import round_optional_float
 from ..types import UUID, FloatPerAtom, round_optional_float_per_atom
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
+
+
+class FukuiIndexWorkflow(MoleculeWorkflow):
+    """
+    Workflow for calculating Fukui indices.
+
+    Inherited:
+    :param initial_molecule: Molecule of interest
+    :param mode: Mode for workflow (currently unused)
 
+    Results:
+    :param optimization: UUID of optimization
+    :param global_electrophilicity_index: global electrophilicity index
+    :param fukui_positive: Fukui index for positive charges
+    :param fukui_negative: Fukui index for negative charges
+    :param fukui_zero: Fukui index for zero charges
+    """
 
-class FukuiIndexWorkflow(Workflow):
     # UUID of optimization
     optimization: UUID | None = None
 

stjames/workflows/hydrogen_bond_basicity.py

@@ -1,21 +1,45 @@
+"""Hydrogen-bond-basicity workflow."""
+
 from ..base import Base
 from ..types import UUID
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 
 class HydrogenBondAcceptorSite(Base):
+    """
+    A hydrogen bond acceptor site.
+
+    :param atom_idx: index of the atom
+    :param pkbhx: Hydrogen bond basicity
+    :param position: position of the atom
+    :param name: name of the atom
+    """
+
     atom_idx: int  # zero-indexed
     pkbhx: float
     position: tuple[float, float, float]
     name: str | None = None
 
 
-class HydrogenBondBasicityWorkflow(Workflow):
+class HydrogenBondBasicityWorkflow(MoleculeWorkflow):
+    """
+    Workflow for calculating hydrogen bond basicity.
+
+    Inherited:
+    :param initial_molecule: Molecule of interest
+    :param mode: Mode for workflow (currently unused)
+
+    New:
+    :param do_csearch: whether to perform a conformational search
+    :param do_optimization: whether to perform an optimization
+
+    Results:
+    :param optimization: UUID of optimization
+    :param hba_sites: hydrogen-bond-acceptor sites
+    """
+
     do_csearch: bool = True
     do_optimization: bool = True
 
-    # UUID of optimization
     optimization: UUID | None = None
-
-    # hydrogen-bond-acceptor sites
     hba_sites: list[HydrogenBondAcceptorSite] = []  # noqa: RUF012

stjames/workflows/irc.py

@@ -1,3 +1,5 @@
+"""Intrinsic reaction coordinate (IRC) workflow."""
+
 from typing import Self
 
 from pydantic import Field, PositiveFloat, field_validator, model_validator
@@ -7,12 +9,12 @@ from ..mode import Mode
 from ..settings import Settings
 from ..solvent import Solvent, SolventModel, SolventSettings
 from ..types import UUID
-from .workflow import Workflow
+from .workflow import MoleculeWorkflow
 
 _sentinel_settings: Settings = object()  # type: ignore [assignment]
 
 
-class IRCWorkflow(Workflow):
+class IRCWorkflow(MoleculeWorkflow):
     """
     Workflow for Intrinsic Reaction Coordinate (IRC) calculations.