rowan-python 3.0.12__py3-none-any.whl → 3.1.0__py3-none-any.whl

rowan/__init__.py

@@ -4,11 +4,14 @@ from stjames import (
     Atom,
     Constraint,
     ConstraintType,
+    ConformerClusteringSettings,
     ConformerGenSettingsUnion,
     Correction,
     Engine,
     ETKDGSettings,
+    GreedyClusteringSettings,
     iMTDSettings,
+    KMeansClusteringSettings,
     Method,
     Mode,
     MultiStageOptSettings,
@@ -17,10 +20,19 @@ from stjames import (
     PBCDFTSettings,
     PeriodicCell,
     Settings,
+    Solvent,
     SolventSettings,
     Task,
 )
+from stjames.excited_state_settings import TDDFTSettings
 from stjames.pbc_dft_settings import PBCDFTSmearing
+from stjames.engine_compatibility import (
+    ENGINE_METHODS,
+    ENGINE_SOLVENT_MODELS,
+    ENGINE_SUPPORTS_BASIS_SET,
+    METHOD_ENGINES,
+    get_supported_corrections,
+)
 from stjames.optimization.freezing_string_method import (
     FSMInterpolation,
     FSMOptimizationCoordinates,
@@ -34,7 +46,7 @@ from .api_keys import *
 from .calculation import *
 from .folder import *
 from .molecule import *
-from .types import RdkitMol, StJamesMolecule
+from .types import RdkitMol, StJamesMolecule, StructureInput
 from .workflows import *
 from .project import *
 from .protein import *

rowan/config.py

@@ -373,7 +373,7 @@ class ConformerGeneratorSettings:
     solvent_warning: bool = False
 
 
-# Main group elements for ETKDG/Lyrebird
+# Main group elements for ETKDG
 _MAIN_GROUP = {1, 5, 6, 7, 8, 9, 14, 15, 16, 17, 35, 53}
 
 CONFORMER_GENERATOR_SETTINGS: dict[str, ConformerGeneratorSettings] = {
@@ -395,12 +395,6 @@ CONFORMER_GENERATOR_SETTINGS: dict[str, ConformerGeneratorSettings] = {
         disable_ts=True,
         allowed_engines=["aimnet2", "xtb"],  # MCMM only supports these for energy
     ),
-    "lyrebird": ConformerGeneratorSettings(
-        disable_constraints=True,
-        disable_open_shell=True,
-        disable_ts=True,
-        atoms_supported=_MAIN_GROUP,
-    ),
 }
 
 

rowan/folder.py

@@ -11,13 +11,13 @@ class Folder(BaseModel):
     """
     A class representing a folder in the Rowan API.
 
-    :ivar uuid: The UUID of the folder.
-    :ivar name: The name of the folder.
-    :ivar parent_uuid: The UUID of the parent folder.
+    :ivar uuid: UUID of the folder.
+    :ivar name: Name of the folder.
+    :ivar parent_uuid: UUID of the parent folder.
     :ivar notes: Folder notes.
     :ivar starred: Whether the folder is starred.
     :ivar public: Whether the folder is public.
-    :ivar created_at: The date and time the folder was created.
+    :ivar created_at: Date and time the folder was created.
     """
 
     uuid: str
@@ -225,7 +225,7 @@ def get_folder(path: str, create: bool = True) -> Folder:
     :param path: Folder name or ``/``-separated path, e.g. ``"project/subdir/run1"``.
     :param create: If True (default), create missing folders. If False, raise ValueError if any
         segment is not found.
-    :returns: The deepest :class:`Folder` in the path.
+    :returns: Deepest :class:`Folder` in the path.
     :raises ValueError: If the path is empty, or ``create=False`` and a folder is not found.
     """
     segments = [s for s in path.split("/") if s]

rowan/molecule.py

@@ -14,12 +14,6 @@ class Molecule(BaseModel):
 
     Can be created from SMILES, XYZ, or directly from atoms. Wraps stjames.Molecule
     internally but provides a cleaner interface.
-
-    :param charge: Molecular charge.
-    :param multiplicity: Spin multiplicity.
-    :param atoms: List of atoms with positions.
-    :param energy: Electronic energy (Hartree).
-    :param smiles: SMILES string representation.
     """
 
     _stjames: stjames.Molecule = PrivateAttr()
@@ -85,6 +79,19 @@ class Molecule(BaseModel):
         """
         return cls.from_xyz(Path(path).read_text(), charge=charge, multiplicity=multiplicity)
 
+    @classmethod
+    def molecules_from_sdf(cls, path: str | Path) -> list[Self]:
+        """
+        Read all records from an SDF file as a list of molecules.
+
+        Each record becomes one Molecule, in file order, with atom ordering preserved
+        across records -- so a multi-conformer SDF reads as a consistent ensemble.
+
+        :param path: path to the SDF file
+        :returns: one Molecule per record
+        """
+        return [cls.from_stjames(mol) for mol in stjames.Molecule.molecules_from_sdf(path)]
+
     @classmethod
     def from_stjames(cls, stj: stjames.Molecule) -> Self:
         """

rowan/project.py

@@ -12,9 +12,9 @@ class Project(BaseModel):
     """
     A class representing a project in the Rowan API.
 
-    :ivar uuid: The UUID of the project.
-    :ivar name: The name of the project.
-    :ivar created_at: The date and time the project was created.
+    :ivar uuid: UUID of the project.
+    :ivar name: Name of the project.
+    :ivar created_at: Date and time the project was created.
     """
 
     uuid: str
@@ -139,7 +139,7 @@ def set_project(name: str) -> Project:
         folder = rowan.get_folder("docking/batch_1")
 
     :param name: Exact name of the project to activate.
-    :returns: The matched Project.
+    :returns: Matched project.
     :raises ValueError: If no project with that name is found.
     """
     matches = list_projects(name_contains=name, size=100)

rowan/protein.py

@@ -16,13 +16,13 @@ class Protein(BaseModel):
     Data is not loaded by default to avoid unnecessary downloads that could impact performance.
     Call `load_data()` to fetch and attach the protein data to this `Protein` object.
 
-    :ivar uuid: The UUID of the protein
-    :ivar created_at: The creation date of the protein
+    :ivar uuid: UUID of the protein
+    :ivar created_at: Creation date of the protein
     :ivar used_in_workflow: Whether the protein is used in a workflow
-    :ivar ancestor_uuid: The UUID of the ancestor protein
+    :ivar ancestor_uuid: UUID of the ancestor protein
     :ivar sanitized: Whether the protein is sanitized
-    :ivar name: The name of the protein
-    :ivar data: The data of the protein
+    :ivar name: Name of the protein
+    :ivar data: Data of the protein
     :ivar public: Whether the protein is public
     """
 
@@ -36,7 +36,7 @@ class Protein(BaseModel):
     public: bool | None = None
     pocket: list[list[float]] | None = None
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Protein name='{self.name}' created_at='{self.created_at}' uuid='{self.uuid}'>"
 
     def refresh(self, in_place: bool = True) -> Self:
@@ -67,7 +67,6 @@ class Protein(BaseModel):
         public: bool | None = None,
         pocket: list[list[float]] | None = None,
     ) -> Self:
-        # Use current values unless new ones are passed in
         """
         Updates protein data
 
@@ -77,6 +76,7 @@ class Protein(BaseModel):
         :param pocket: New pocket of the protein
         :returns: Updated protein object
         """
+        # Use current values unless new ones are passed in
         updated_payload = {
             "name": name if name is not None else self.name,
             "data": data if data is not None else self.data,
@@ -312,6 +312,7 @@ def upload_protein(
 
     :param name: Name of the protein to create
     :param file_path: Path to the PDB file to upload
+    :param project_uuid: UUID of the project to create the protein in
     :returns: Protein object representing the uploaded protein
     :raises requests.HTTPError: if the request to the API fails
     """

rowan/types.py

@@ -1,6 +1,6 @@
 """Shared type aliases for the Rowan package."""
 
-from typing import Any, TypeAlias
+from typing import TypeAlias
 
 import stjames
 from rdkit import Chem
@@ -9,7 +9,9 @@ from .molecule import Molecule as RowanMolecule
 
 RdkitMol: TypeAlias = Chem.rdchem.Mol | Chem.rdchem.RWMol
 StJamesMolecule: TypeAlias = stjames.Molecule
-MoleculeInput: TypeAlias = dict[str, Any] | RowanMolecule | StJamesMolecule | RdkitMol | str
+# 3D-structure input: molecule objects carrying coordinates. Excludes bare SMILES strings
+# (no geometry) and dicts (internal serialization only).
+StructureInput: TypeAlias = RowanMolecule | StJamesMolecule | RdkitMol
 SolventInput: TypeAlias = stjames.Solvent | str | None
 SMILES: TypeAlias = str
 UUID: TypeAlias = str

rowan/user.py

@@ -11,9 +11,9 @@ class Organization(BaseModel):
     """
     A Rowan organization
 
-    :ivar name: The name of the organization.
-    :ivar weekly_credits: The weekly credits of the organization.
-    :ivar credits: The credits of the organization.
+    :ivar name: Name of the organization.
+    :ivar weekly_credits: Weekly credits of the organization.
+    :ivar credits: Credits of the organization.
     """
 
     name: str
@@ -25,7 +25,7 @@ class OrganizationRole(BaseModel):
     """
     A Rowan organization role
 
-    :ivar name: The name of the organization role.
+    :ivar name: Name of the organization role.
     """
 
     name: str
@@ -35,7 +35,7 @@ class SubscriptionPlan(BaseModel):
     """
     A Rowan subscription plan
 
-    :ivar name: The name of the subscription plan.
+    :ivar name: Name of the subscription plan.
     """
 
     name: str
@@ -45,7 +45,7 @@ class IndividualSubscription(BaseModel):
     """
     A Rowan individual subscription
 
-    :ivar subscription_plan: The subscription plan of the individual subscription.
+    :ivar subscription_plan: Subscription plan of the individual subscription.
     """
 
     subscription_plan: SubscriptionPlan
@@ -55,19 +55,23 @@ class User(BaseModel):
     """
     A Rowan user
 
-    :ivar uuid: The UUID of the user.
-    :ivar username: The username of the user.
-    :ivar email: The email of the user.
-    :ivar firstname: The first name of the user.
-    :ivar lastname: The last name of the user.
-    :ivar weekly_credits: The weekly credits of the user.
-    :ivar credits: The credits of the user.
-    :ivar billing_name: The billing name of the user.
-    :ivar billing_address: The billing address of the user.
-    :ivar credit_balance_warning: The credit balance warning of the user.
-    :ivar organization: The organization of the user.
-    :ivar organization_role: The organization role of the user.
-    :ivar individual_subscription: The individual subscription of the user.
+    :ivar uuid: UUID of the user.
+    :ivar username: Username of the user.
+    :ivar email: Email of the user.
+    :ivar firstname: First name of the user.
+    :ivar lastname: Last name of the user.
+    :ivar weekly_credits: Weekly credits of the user.
+    :ivar credits: Credits of the user.
+    :ivar billing_name: Billing name of the user.
+    :ivar billing_address: Billing address of the user.
+    :ivar credit_balance_warning: Credit balance warning of the user.
+    :ivar organization: Organization of the user.
+    :ivar organization_role: Organization role of the user.
+    :ivar individual_subscription: Individual subscription of the user.
+    :ivar enabled_workflows: Workflow types this account may submit, as backend slugs that
+        mostly match the ``submit_<slug>_workflow`` names (note ``molecular_dynamics`` is
+        protein MD).
+    :ivar feature_list: Feature flags enabled for this account.
     """
 
     uuid: str
@@ -83,6 +87,8 @@ class User(BaseModel):
     organization: Organization | None = None
     organization_role: OrganizationRole | None = None
     individual_subscription: IndividualSubscription | None = None
+    enabled_workflows: list[str] = []
+    feature_list: list[str] = []
 
     @property
     def name(self) -> str:
@@ -173,7 +179,7 @@ def verify_webhook_secret(
 ) -> bool:
     """Verify an incoming webhook request from Rowan.
 
-    :param raw_body: The raw (unparsed) request body bytes.
+    :param raw_body: Raw (unparsed) request body bytes.
     :param signature_header: Value of the X-Rowan-Signature header.
     :param secret: Your webhook secret (from :func:`create_webhook_secret` or
         :func:`rotate_webhook_secret`).

rowan/workflows/__init__.py

@@ -9,7 +9,6 @@ Basic pattern:
 
 from stjames import (
     ETKDGSettings,
-    LyrebirdSettings,
     MonteCarloMultipleMinimumSettings,
     SolventModel,
     iMTDGCSettings,
@@ -40,7 +39,14 @@ from .base import (
 )
 from .basic_calculation import BasicCalculationResult, submit_basic_calculation_workflow
 from .batch_docking import BatchDockingResult, submit_batch_docking_workflow
-from .bde import BDEEntry, BDEResult, submit_bde_workflow
+from .bde import (
+    BDEEntry,
+    BDEResult,
+    find_bonds,
+    find_ch_bonds,
+    find_cx_bonds,
+    submit_bde_workflow,
+)
 from .conformer_search import ConformerSearchResult, submit_conformer_search_workflow
 from .descriptors import DescriptorsResult, submit_descriptors_workflow
 from .docking import DockingResult, DockingScore, submit_docking_workflow
@@ -94,6 +100,7 @@ from .protein_binder_design import (
 from .protein_cofolding import (
     CofoldingModel,
     CofoldingResult,
+    CofoldingTemplate,
     ConstraintTarget,
     ContactConstraint,
     PocketConstraint,

rowan/workflows/admet.py

@@ -3,9 +3,8 @@
 import stjames
 
 from ..folder import Folder
-from ..types import MoleculeInput
 from ..utils import api_client
-from .base import Workflow, WorkflowResult, extract_smiles, register_result
+from .base import SMILES, Workflow, WorkflowResult, extract_smiles, register_result
 
 
 @register_result("admet")
@@ -26,7 +25,7 @@ class ADMETResult(WorkflowResult):
 
 
 def submit_admet_workflow(
-    initial_smiles: str | MoleculeInput,
+    initial_smiles: SMILES,
     name: str = "ADMET Workflow",
     folder_uuid: str | None = None,
     folder: Folder | None = None,

rowan/workflows/analogue_docking.py

@@ -1,14 +1,22 @@
 """Analogue docking workflow - dock analogues using a template ligand."""
 
+from typing import Literal
+
 import stjames
 
 from ..calculation import Calculation, retrieve_calculation
 from ..folder import Folder
 from ..molecule import Molecule
 from ..protein import Protein, retrieve_protein
-from ..types import MoleculeInput
 from ..utils import api_client
-from .base import Workflow, WorkflowResult, molecule_to_dict, register_result
+from .base import (
+    StructureInput,
+    Workflow,
+    WorkflowResult,
+    molecule_to_dict,
+    register_result,
+    require_coordinates,
+)
 from .docking import DockingScore
 
 
@@ -32,6 +40,13 @@ class AnalogueDockingResult(WorkflowResult):
                     best_smiles = smiles
         return f"<AnalogueDockingResult analogues={n} best=({best_score:.2f}, {best_smiles!r})>"
 
+    def __post_init__(self) -> None:
+        """Default `complex_pdb` to None on each analogue's scores, then parse."""
+        for scores in (self.workflow_data.get("analogue_scores") or {}).values():
+            for score in scores:
+                score.setdefault("complex_pdb", None)
+        super().__post_init__()
+
     @property
     def analogue_scores(self) -> dict[str, list[DockingScore]]:
         """Docking scores for each analogue SMILES."""
@@ -157,11 +172,11 @@ class AnalogueDockingResult(WorkflowResult):
 
 def submit_analogue_docking_workflow(
     analogues: list[str],
-    initial_molecule: MoleculeInput,
+    initial_molecule: StructureInput,
     protein: str | Protein,
-    executable: str = "vina",
-    scoring_function: str = "vinardo",
-    exhaustiveness: float = 8,
+    scoring_function: Literal["vina", "vinardo"] = "vinardo",
+    exhaustiveness: int = 8,
+    max_poses: int = 4,
     num_conformers_per_analogue: int = 100,
     require_posebusters: bool = False,
     run_local_optimization: bool = False,
@@ -178,9 +193,9 @@ def submit_analogue_docking_workflow(
     :param analogues: SMILES strings to dock.
     :param initial_molecule: Template to which to align molecules to.
     :param protein: Protein to dock. Can be input as a uuid or a Protein object.
-    :param executable: Which docking implementation to use.
-    :param scoring_function: Which docking scoring function to use.
-    :param exhaustiveness: Which exhaustiveness to employ.
+    :param scoring_function: Docking scoring function: "vina" or "vinardo".
+    :param exhaustiveness: How many times Vina attempts to find a pose for each conformer.
+    :param max_poses: Maximum number of poses generated per input conformer.
     :param num_conformers_per_analogue: Maximum number of conformers to generate per analogue.
     :param require_posebusters: Filter conformers based on PoseBusters validity before docking.
     :param run_local_optimization: Whether to run a local opt in docking pocket or just score.
@@ -193,24 +208,26 @@ def submit_analogue_docking_workflow(
     :returns: Workflow object representing the submitted analogue-docking workflow.
     :raises requests.HTTPError: if the request to the API fails.
     """
+    require_coordinates(initial_molecule)
     if folder and folder_uuid:
         raise ValueError("Provide either `folder` or `folder_uuid`, not both.")
     if folder:
         folder_uuid = folder.uuid
     docking_settings = {
-        "executable": executable,
-        "exhaustiveness": exhaustiveness,
+        "executable": "vina",
         "scoring_function": scoring_function,
+        "exhaustiveness": exhaustiveness,
+        "max_poses": max_poses,
     }
 
-    initial_molecule = molecule_to_dict(initial_molecule)
+    mol_dict = molecule_to_dict(initial_molecule)
 
     if isinstance(protein, Protein):
         protein = protein.uuid
 
     workflow = stjames.AnalogueDockingWorkflow(
         analogues=analogues,
-        initial_molecule=initial_molecule,
+        initial_molecule=mol_dict,
         protein=protein,
         docking_settings=docking_settings,
         num_conformers_per_analogue=num_conformers_per_analogue,
@@ -219,7 +236,7 @@ def submit_analogue_docking_workflow(
     )
 
     data = {
-        "initial_molecule": initial_molecule,
+        "initial_molecule": mol_dict,
         "workflow_type": "analogue_docking",
         "workflow_data": workflow.model_dump(serialize_as_any=True, mode="json"),
         "name": name,

rowan/workflows/base.py

@@ -15,7 +15,7 @@ from rdkit import Chem
 
 from ..folder import Folder
 from ..molecule import Molecule as RowanMolecule
-from ..types import SMILES, MoleculeInput
+from ..types import SMILES, StructureInput
 from ..utils import api_client
 
 logger = logging.getLogger(__name__)
@@ -30,7 +30,9 @@ Task = stjames.Task
 Settings = stjames.Settings
 MultiStageOptSettings = stjames.MultiStageOptSettings
 ETKDGSettings = stjames.ETKDGSettings
+OpenConfSettings = stjames.OpenConfSettings
 ConformerGenSettings = stjames.conformers.ConformerGenSettings
+ConformerClusteringSettings = stjames.ConformerClusteringSettings
 
 
 @dataclass(frozen=True, slots=True)
@@ -106,8 +108,21 @@ class WorkflowResult:
             try:
                 obj = self._stjames_class.model_validate(self.workflow_data)  # type: ignore[attr-defined]
                 object.__setattr__(self, "_workflow", obj)
-            except ValidationError:
-                pass  # incomplete or invalid data; _workflow stays None
+            except ValidationError as e:
+                if not self.complete:
+                    # Still-running workflow: partial data is expected; leave `_workflow`
+                    # None and fall back to `.data` until the workflow finishes.
+                    return
+                # A completed workflow whose data won't validate is a real mismatch between
+                # the installed stjames model and the server response. Fail clearly here
+                # rather than as a downstream AttributeError on a None `_workflow`.
+                raise ValueError(
+                    f"""\
+Could not parse the completed '{self.workflow_type}' workflow into \
+{self._stjames_class.__name__}. The installed stjames version is likely out of sync with \
+the server (a field is missing, extra, or the wrong type). Underlying validation error:
+{e}"""
+                ) from e
 
     @property
     def data(self) -> dict[str, Any]:
@@ -546,7 +561,7 @@ Workflow:  {self.name}
             f.write(response.content)
 
 
-def extract_smiles(mol: SMILES | MoleculeInput) -> SMILES:
+def extract_smiles(mol: SMILES | StructureInput | dict[str, Any]) -> SMILES:
     """
     Extract a SMILES string from a molecule input or return the string directly.
 
@@ -575,7 +590,7 @@ def extract_smiles(mol: SMILES | MoleculeInput) -> SMILES:
     return smiles
 
 
-def molecule_to_stjames(mol: MoleculeInput) -> stjames.Molecule:
+def molecule_to_stjames(mol: StructureInput | dict[str, Any]) -> stjames.Molecule:
     """Convert any molecule input type to a stjames.Molecule."""
     match mol:
         case RowanMolecule():
@@ -590,16 +605,37 @@ def molecule_to_stjames(mol: MoleculeInput) -> stjames.Molecule:
             raise TypeError(f"Cannot convert {type(mol)} to stjames.Molecule")
 
 
-def molecule_to_dict(mol: MoleculeInput) -> dict[str, Any]:
+def require_coordinates(mol: StructureInput) -> None:
     """
-    Convert any molecule input type to a dict for API submission.
+    Validate that a molecule input carries real 3D coordinates.
+
+    Geometry-based workflows operate on 3D structure, so reject inputs that have no
+    geometry rather than silently embedding an arbitrary conformer: a SMILES string
+    (no coordinates) or an RDKit molecule with no conformer.
+
+    :param mol: molecule input to check
+    :raises ValueError: if the input has no 3D coordinates
+    """
+    if isinstance(mol, str):
+        raise ValueError(
+            "This workflow requires a 3D structure, not a SMILES string. Build one "
+            'explicitly, e.g. rowan.Molecule.from_smiles("CCO") or rowan.Molecule.from_xyz(...).'
+        )
+    if isinstance(mol, Chem.Mol) and mol.GetNumConformers() == 0:
+        raise ValueError(
+            "RDKit molecule has no 3D conformer. Embed one first (e.g. "
+            "rdkit.Chem.AllChem.EmbedMolecule) or use rowan.Molecule.from_smiles(...)."
+        )
+
+
+def molecule_to_dict(mol: StructureInput | dict[str, Any]) -> dict[str, Any]:
+    """
+    Convert a 3D molecule input to a dict for API submission.
 
     :param mol: Molecule as Molecule, stjames.Molecule, RDKit Mol, or dict.
     :returns: Dict representation suitable for API submission.
     """
     match mol:
-        case str():
-            return RowanMolecule.from_smiles(mol).to_stjames().model_dump(mode="json")
         case RowanMolecule():
             return mol.to_stjames().model_dump(mode="json")
         case stjames.Molecule():
@@ -615,8 +651,8 @@ def molecule_to_dict(mol: MoleculeInput) -> dict[str, Any]:
 def submit_workflow(
     workflow_type: stjames.WORKFLOW_NAME,
     workflow_data: dict[str, Any] | None = None,
-    initial_molecule: MoleculeInput | None = None,
-    initial_smiles: str | None = None,
+    initial_molecule: StructureInput | dict[str, Any] | None = None,
+    initial_smiles: SMILES | None = None,
     name: str | None = None,
     folder_uuid: str | Folder | None = None,
     max_credits: int | None = None,
@@ -785,8 +821,8 @@ def list_workflows(
 def batch_submit_workflow(
     workflow_type: stjames.WORKFLOW_NAME,
     workflow_data: dict[str, Any] | None = None,
-    initial_molecules: list[MoleculeInput] | None = None,
-    initial_smileses: list[str] | None = None,
+    initial_molecules: list[StructureInput | dict[str, Any]] | None = None,
+    initial_smileses: list[SMILES] | None = None,
     names: list[str] | None = None,
     folder_uuid: str | Folder | None = None,
     max_credits: int | None = None,