rowan-python 3.2.2__py3-none-any.whl → 3.2.4__py3-none-any.whl

rowan/__init__.py

@@ -15,6 +15,7 @@ from stjames import (
     Constraint,
     ConstraintType,
     ConformerClusteringSettings,
+    ConformerProperties,
     ConformerGenSettingsUnion,
     Correction,
     DNASequence,
@@ -27,7 +28,9 @@ from stjames import (
     iMTDSettings,
     InducedFitSettings,
     KMeansClusteringSettings,
+    MDRestraints,
     Method,
+    MixMDSettings,
     Mode,
     MSAFormat,
     MultiStageOptSettings,
@@ -38,9 +41,11 @@ from stjames import (
     OptimizationSettings,
     PBCDFTSettings,
     PeriodicCell,
+    PocketeerSettings,
     ProteinSequence,
     ProteinForceField,
     ResidueModification,
+    RestraintType,
     RNASequence,
     ScanSettings,
     Settings,
@@ -67,7 +72,7 @@ from stjames.engine_compatibility import (
     METHOD_ENGINES,
     get_supported_corrections,
 )
-from stjames.pdb import ResidueRef
+from stjames.pdb import ResidueAtomRef, ResidueRef
 from stjames.optimization.band_method import NEBSettings
 from stjames.optimization.interpolation import Interpolation
 from stjames.optimization.string_method import FSMSettings, StringMethodSettings
@@ -83,5 +88,6 @@ from .types import ProteinUUID, RdkitMol, SMILES, StJamesMolecule, StructureInpu
 from .workflows import *
 from .project import *
 from .protein import *
+from .spectra import HARTREE_TO_EV, broaden_spectrum
 from .user import *
 from .utils import *

rowan/spectra.py

@@ -0,0 +1,68 @@
+"""Broaden stick spectra into continuous line shapes."""
+
+import math
+from collections.abc import Sequence
+from typing import Literal
+
+HARTREE_TO_EV = 27.211386245988
+
+_GAUSSIAN_FWHM_TO_SIGMA = 1 / (2 * math.sqrt(2 * math.log(2)))
+
+
+def broaden_spectrum(
+    positions: Sequence[float],
+    intensities: Sequence[float],
+    grid: Sequence[float],
+    fwhm: float,
+    lineshape: Literal["gaussian", "lorentzian"] = "gaussian",
+) -> list[float]:
+    """Sum line shapes centered on each stick, each with area equal to its intensity.
+
+    Use it on the stick spectra of `ConformerSearchResult.ensemble_properties`, for
+    example excitation energies with oscillator or rotatory strengths for UV-vis or ECD,
+    or vibrational frequencies with IR intensities. `grid` and `fwhm` share the units of
+    `positions`; convert excitation energies from Hartree with `HARTREE_TO_EV` first to
+    broaden in eV.
+
+    Args:
+        positions: line positions
+        intensities: line intensities, parallel to `positions`
+        grid: points at which to evaluate the spectrum
+        fwhm: full width at half maximum of each line
+        lineshape: line shape of each stick
+
+    Returns:
+        spectrum at each point of `grid`
+
+    Raises:
+        ValueError: `fwhm` is not positive or `intensities` differs in length from `positions`
+
+    >>> [round(y, 4) for y in broaden_spectrum([0.0], [1.0], [0.0, 0.5], fwhm=1.0)]
+    [0.9394, 0.4697]
+    >>> [round(y, 4) for y in broaden_spectrum([0.0], [2.0], [0.0], 1.0, "lorentzian")]
+    [1.2732]
+    """
+    if fwhm <= 0:
+        raise ValueError(f"fwhm must be positive, got {fwhm}")
+    if len(positions) != len(intensities):
+        raise ValueError(
+            f"positions ({len(positions)}) and intensities ({len(intensities)}) "
+            "must have the same length"
+        )
+
+    if lineshape == "gaussian":
+        sigma = fwhm * _GAUSSIAN_FWHM_TO_SIGMA
+        norm = 1 / (sigma * math.sqrt(2 * math.pi))
+
+        def shape(dx: float) -> float:
+            return norm * math.exp(-0.5 * (dx / sigma) ** 2)
+
+    else:
+        gamma = fwhm / 2
+
+        def shape(dx: float) -> float:
+            return gamma / (math.pi * (dx**2 + gamma**2))
+
+    return [
+        sum(i * shape(x - p) for p, i in zip(positions, intensities, strict=True)) for x in grid
+    ]

rowan/user.py

@@ -60,7 +60,6 @@ class User(BaseModel):
         email: email of the user
         firstname: first name of the user
         lastname: last name of the user
-        weekly_credits: weekly credits of the user
         credits: credits of the user
         billing_name: billing name of the user
         billing_address: billing address of the user
@@ -79,7 +78,6 @@ class User(BaseModel):
     email: str
     firstname: str | None = None
     lastname: str | None = None
-    weekly_credits: float | None = None
     credits: float | None = None
     billing_name: str | None = None
     billing_address: str | dict | None = None
@@ -124,7 +122,7 @@ class User(BaseModel):
         Returns:
             string showing available credits
         """
-        individual_credits = f"Weekly Credits: {self.weekly_credits}\nCredits: {self.credits}"
+        individual_credits = f"Credits: {self.credits}"
         if self.organization is not None:
             return (
                 individual_credits

rowan/utils.py

@@ -4,7 +4,7 @@ from contextvars import ContextVar
 from dataclasses import dataclass
 from pathlib import Path
 from tempfile import NamedTemporaryFile
-from typing import Any, Generator, Literal
+from typing import Any, Callable, ContextManager, Generator, Literal
 
 import httpx
 import stjames
@@ -167,24 +167,14 @@ def api_client() -> Generator[httpx.Client, None, None]:
         yield client
 
 
-def download_file(
-    path: Path,
-    method: Literal["GET", "POST"],
-    url: str,
-    *,
-    params: dict[str, Any] | None = None,
-    json: Any = None,
-) -> Path:
-    """Stream an authenticated API response into one local file atomically."""
+def _stream_to_file(path: Path, stream: Callable[[], ContextManager[httpx.Response]]) -> Path:
+    """Write a streamed response into one local file atomically."""
     path.parent.mkdir(parents=True, exist_ok=True)
     temporary_path: Path | None = None
     try:
         with NamedTemporaryFile(dir=path.parent, prefix=f".{path.name}.", delete=False) as output:
             temporary_path = Path(output.name)
-            with (
-                api_client() as client,
-                client.stream(method, url, params=params, json=json) as response,
-            ):
+            with stream() as response:
                 response.raise_for_status()
                 for chunk in response.iter_bytes():
                     output.write(chunk)
@@ -196,6 +186,65 @@ def download_file(
     return path
 
 
+def download_file(
+    path: Path,
+    method: Literal["GET", "POST"],
+    url: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json: Any = None,
+) -> Path:
+    """Stream an authenticated API response into one local file atomically."""
+
+    @contextmanager
+    def stream() -> Generator[httpx.Response, None, None]:
+        with (
+            api_client() as client,
+            client.stream(method, url, params=params, json=json) as response,
+        ):
+            yield response
+
+    return _stream_to_file(path, stream)
+
+
+def download_presigned_files(
+    directory: Path,
+    url: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json: Any = None,
+) -> list[Path]:
+    """Fetch presigned download links from the API and stream each file into `directory`.
+
+    Links are short-lived, so an expired one is refreshed once before giving up.
+    """
+
+    def fetch_links() -> list[dict[str, str]]:
+        with api_client() as client:
+            return client.post(url, params=params, json=json).json()
+
+    def download(link: dict[str, str]) -> Path:
+        # Plain client: the API key must never be sent to S3.
+        @contextmanager
+        def stream() -> Generator[httpx.Response, None, None]:
+            with httpx.Client(timeout=httpx.Timeout(120, read=None)) as client:
+                with client.stream("GET", link["url"]) as response:
+                    yield response
+
+        return _stream_to_file(directory / Path(link["filename"]).name, stream)
+
+    links = fetch_links()
+    paths = []
+    for i, link in enumerate(links):
+        try:
+            paths.append(download(link))
+        except httpx.HTTPStatusError as error:
+            if error.response.status_code != 403:
+                raise
+            paths.append(download(fetch_links()[i]))
+    return paths
+
+
 ATOMIC_NUMBER_TO_ATOMIC_SYMBOL = {
     "1": "H",
     "2": "He",

rowan/workflows/__init__.py

@@ -102,7 +102,14 @@ from .multistage_optimization import (
 )
 from .nmr import NMRCoupling, NMRPeak, NMRResult, submit_nmr_workflow
 from .pka import pKaMicrostate, pKaResult, submit_pka_workflow
-from .pocket_detection import Pocket, PocketDetectionResult, submit_pocket_detection_workflow
+from .pocket_detection import (
+    MixMDPocketDiagnostics,
+    MixMDReplicaDiagnostics,
+    MixMDResults,
+    Pocket,
+    PocketDetectionResult,
+    submit_pocket_detection_workflow,
+)
 from .pose_analysis_md import PoseAnalysisMDResult, submit_pose_analysis_md_workflow
 from .protein_binder_design import (
     ProteinBinder,

rowan/workflows/_molecular_dynamics.py

@@ -8,7 +8,7 @@ from typing import Literal, Protocol
 from stjames.pdb import PDB
 
 from rowan.protein import Protein, retrieve_protein
-from rowan.utils import api_client, download_file
+from rowan.utils import api_client, download_file, download_presigned_files
 
 from .base import WorkflowResult
 
@@ -222,7 +222,9 @@ class _MolecularDynamicsResult(WorkflowResult):
         name: str | None = None,
         path: Path | str | None = None,
     ) -> Path:
-        """Download DCD trajectory files for selected replicates.
+        """Download DCD trajectory files for selected replicates as one `.tar.gz` archive.
+
+        Long trajectories can time out; use `download_trajectory_files` for those.
 
         Args:
             replicates: zero-based replicate indices
@@ -244,6 +246,29 @@ class _MolecularDynamicsResult(WorkflowResult):
             json=replicates,
         )
 
+    def download_trajectory_files(
+        self,
+        replicates: list[int],
+        path: Path | str | None = None,
+    ) -> list[Path]:
+        """Download each selected replicate's DCD file directly from storage.
+
+        Args:
+            replicates: zero-based replicate indices
+            path: output directory; defaults to the current directory
+
+        Returns:
+            paths to the downloaded `.dcd` files, one per replicate
+
+        Raises:
+            httpx.HTTPStatusError: API or storage request fails
+        """
+        return download_presigned_files(
+            Path(path) if path is not None else Path.cwd(),
+            f"/trajectory/{self.workflow_uuid}/trajectory_dcd_urls",
+            json=replicates,
+        )
+
     def _trajectory(self, replicate: int) -> _MolecularDynamicsTrajectory:
         """Return one trajectory with a consistent bounds error."""
         trajectories = self.trajectories

rowan/workflows/conformer_search.py

@@ -31,6 +31,8 @@ from .base import (
 )
 from .constants import to_relative_kcal
 
+ConformerProperties = stjames.ConformerProperties
+
 
 @register_result("conformer_search")
 class ConformerSearchResult(WorkflowResult):
@@ -72,22 +74,59 @@ class ConformerSearchResult(WorkflowResult):
         return to_relative_kcal(energies) if relative else energies
 
     @property
-    def radii_of_gyration(self) -> list[float]:
-        """Radius of gyration for each conformer (A)."""
+    def radii_of_gyration(self) -> list[float | None]:
+        """Radius of gyration for each conformer (A), None where it failed."""
         return [p.radius_of_gyration for p in self._workflow.conformer_properties]
 
     @property
-    def sasa(self) -> list[float]:
-        """Solvent accessible surface area for each conformer (A^2)."""
+    def sasa(self) -> list[float | None]:
+        """Solvent accessible surface area for each conformer (A^2), None where it failed."""
         return [p.solvent_accessible_surface_area for p in self._workflow.conformer_properties]
 
     @property
-    def polar_sasa(self) -> list[float]:
-        """Polar solvent accessible surface area for each conformer (A^2)."""
+    def polar_sasa(self) -> list[float | None]:
+        """Polar solvent accessible surface area for each conformer (A^2), None where it failed."""
         return [
             p.polar_solvent_accessible_surface_area for p in self._workflow.conformer_properties
         ]
 
+    @property
+    def dipoles(self) -> list[float | None]:
+        """Dipole moment magnitude about the center of mass for each conformer (Debye).
+
+        None where the method reports no dipole.
+        """
+        return [p.dipole for p in self._workflow.conformer_properties]
+
+    @property
+    def ensemble_properties(self) -> ConformerProperties | None:
+        """Ensemble properties weighted by `boltzmann_weights`.
+
+        Each property is averaged over the conformers that have it: SASA, polar SASA, Rg,
+        the root-mean-square dipole (Debye), and per-atom Mulliken charges. When the run
+        computed them, it also holds stick spectra with every conformer's lines, each
+        intensity scaled by its conformer's population: `excitation_energies` (Hartree) with
+        `oscillator_strengths` (UV-vis) and `rotatory_strengths` (ECD), and
+        `vibrational_frequencies` (cm^-1) with `ir_intensities` (km/mol). Pass them to
+        `rowan.broaden_spectrum` for the spectrum. Rotatory strengths are omitted when the
+        conformers differ in stereochemistry, since mixing enantiomers cancels the ECD signal.
+        """
+        return self._workflow.ensemble_properties
+
+    @property
+    def boltzmann_weights(self) -> list[float]:
+        """Population of each conformer at the weighting temperature (sum to 1.0).
+
+        From free energies when every conformer has frequencies, else from ground-state
+        energies. Empty for workflows run before weights were reported.
+        """
+        return list(self._workflow.boltzmann_weights)
+
+    @property
+    def weighting_temperature(self) -> float:
+        """Temperature of `boltzmann_weights` and `ensemble_properties` (K)."""
+        return self._workflow.weighting_temperature
+
     def get_conformers(self, n: int | None = None) -> list[Molecule]:
         """Fetch conformer molecules.
 
@@ -156,6 +195,7 @@ def _mso_for_final_method(
     final_method: Method,
     solvent: SolventInput = None,
     transition_state: bool = False,
+    frequencies: bool = False,
 ) -> MultiStageOptSettings:
     """Build optimization settings for the final method.
 
@@ -163,9 +203,9 @@ def _mso_for_final_method(
     without a named preset.
 
     `solvent` and `transition_state` are merged into each stage's `Settings`
-    when supplied; the named preset itself is independent of them (mirrors how
-    tinbergen's form keeps the preset dropdown separate from the solvent / TS
-    toggles).
+    when supplied, and `frequencies` runs on the optimization stage; the named
+    preset itself is independent of them (mirrors how tinbergen's form keeps the
+    preset dropdown separate from the solvent / TS toggles).
     """
     opt_method, sp_method = _FINAL_METHOD_TO_MSO_RECIPE.get(final_method, (final_method, None))
 
@@ -196,6 +236,7 @@ def _mso_for_final_method(
     return MultiStageOptSettings(
         optimization_settings=[opt_stage],
         singlepoint_settings=sp_stage,
+        frequencies=frequencies,
     )
 
 
@@ -224,6 +265,8 @@ def submit_conformer_search_workflow(
     final_method: Method | str = "aimnet2_wb97md3",
     solvent: SolventInput = None,
     transition_state: bool = False,
+    frequencies: bool = False,
+    weighting_temperature: float = 298.15,
     multistage_opt_settings: MultiStageOptSettings | None = None,
     conformer_clustering_settings: ConformerClusteringSettings | None = None,
     initial_conformers: Sequence[StructureInput] | None = None,
@@ -264,6 +307,11 @@ def submit_conformer_search_workflow(
             `multistage_opt_settings` is provided
         transition_state: whether to optimize the transition state. Ignored
             if `multistage_opt_settings` is provided
+        frequencies: compute vibrational frequencies of each conformer at the optimization
+            level, for the ensemble IR spectrum. Ignored if `multistage_opt_settings` is
+            provided; set its `frequencies` instead
+        weighting_temperature: temperature for the conformer populations, in Kelvin. With
+            frequencies, populations use free energies at this temperature
         multistage_opt_settings: optimization stages and singlepoint settings
             for ranking conformers. When provided, takes precedence over
             `final_method` / `solvent` / `transition_state`. When omitted, an MSO is
@@ -359,7 +407,10 @@ def submit_conformer_search_workflow(
         if isinstance(final_method, str):
             final_method = Method(final_method)
         multistage_opt_settings = _mso_for_final_method(
-            final_method, solvent=solvent, transition_state=transition_state
+            final_method,
+            solvent=solvent,
+            transition_state=transition_state,
+            frequencies=frequencies,
         )
     multistage_opt_settings = _release_ts_optimization_constraints(multistage_opt_settings)
 
@@ -370,6 +421,7 @@ def submit_conformer_search_workflow(
         multistage_opt_settings=multistage_opt_settings,
         conf_gen_settings=conf_gen_settings,
         conformer_clustering_settings=conformer_clustering_settings,
+        weighting_temperature=weighting_temperature,
     )
 
     workflow_data = workflow.model_dump(serialize_as_any=True, mode="json")

rowan/workflows/pocket_detection.py

@@ -3,27 +3,47 @@
 from dataclasses import dataclass
 
 import stjames
+from stjames import MixMDSettings, PocketeerSettings
 
 from rowan.folder import Folder
-from rowan.protein import Protein
+from rowan.protein import Protein, retrieve_protein
 from rowan.types import ProteinUUID
 from rowan.utils import api_client
 
-from .base import Workflow, WorkflowResult, register_result
+from .base import Message, Workflow, WorkflowResult, parse_messages, register_result
+
+
+@dataclass(frozen=True, slots=True)
+class MixMDPocketDiagnostics:
+    """Probe enrichment for a pocket found by mixed-solvent MD.
+
+    Attributes:
+        density_center: density-weighted center of the enriched region, in Å
+        peak_enrichment: maximum probe density relative to bulk solvent
+        integrated_excess_density: probe molecules above bulk, integrated over the region
+    """
+
+    density_center: tuple[float, float, float]
+    peak_enrichment: float
+    integrated_excess_density: float
 
 
 @dataclass(frozen=True, slots=True)
 class Pocket:
     """A detected binding pocket.
 
+    Mixed-solvent MD pockets describe regions of enriched probe density, so their spheres
+    and volume outline that region rather than the cavity.
+
     Attributes:
         sphere_centers: centers of detected spheres, in Å
         sphere_radii: radii of detected spheres, in Å
         volume: pocket volume, in ų
-        score: druggability/quality score; larger is better
+        score: method-specific ranking score; larger is better
         pocket_center: center of axis-aligned bounding box, in Å
         pocket_sides: side lengths of axis-aligned bounding box, in Å
         residue_numbers: residue numbers lining the pocket
+        mixmd: probe-enrichment details for mixed-solvent MD pockets
     """
 
     sphere_centers: tuple[tuple[float, float, float], ...]
@@ -33,6 +53,60 @@ class Pocket:
     pocket_center: tuple[float, float, float]
     pocket_sides: tuple[float, float, float]
     residue_numbers: tuple[int, ...]
+    mixmd: MixMDPocketDiagnostics | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MixMDReplicaDiagnostics:
+    """One mixed-solvent MD replica.
+
+    Attributes:
+        index: zero-based replica index
+        seed: replica random seed
+        num_frames: analyzed frames; zero for a failed replica
+        num_probes: probe molecules in the simulation
+        largest_probe_cluster_fraction: mean fraction of probes in the largest cluster
+        trajectory_uuid: UUID of the stored trajectory
+        topology_uuid: UUID of the trajectory topology protein
+        density_map_uuid: UUID of the stored probe-density map
+    """
+
+    index: int
+    seed: int
+    num_frames: int
+    num_probes: int
+    largest_probe_cluster_fraction: float | None
+    trajectory_uuid: str | None
+    topology_uuid: str | None
+    density_map_uuid: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class MixMDResults:
+    """Mixed-solvent MD replicas and consensus artifacts.
+
+    Attributes:
+        reference_uuid: UUID of the protein defining pocket and map coordinates
+        density_map_uuid: UUID of the consensus probe-density map
+        replicas: per-replica results, including failed replicas
+    """
+
+    reference_uuid: str | None
+    density_map_uuid: str | None
+    replicas: tuple[MixMDReplicaDiagnostics, ...]
+
+
+def _mixmd_diagnostics(
+    raw: stjames.MixMDPocketDiagnostics | None,
+) -> MixMDPocketDiagnostics | None:
+    """Convert stjames probe-enrichment diagnostics, if present."""
+    if raw is None:
+        return None
+    return MixMDPocketDiagnostics(
+        density_center=tuple(raw.density_center),
+        peak_enrichment=raw.peak_enrichment,
+        integrated_excess_density=raw.integrated_excess_density,
+    )
 
 
 @register_result("pocket_detection")
@@ -57,14 +131,59 @@ class PocketDetectionResult(WorkflowResult):
                 pocket_center=tuple(p.pocket_center),
                 pocket_sides=tuple(p.pocket_sides),
                 residue_numbers=tuple(p.residue_numbers),
+                mixmd=_mixmd_diagnostics(p.mixmd),
             )
             for p in raw
         ]
 
+    @property
+    def mixmd(self) -> MixMDResults | None:
+        """Mixed-solvent MD replicas and artifacts, or `None` for Pocketeer runs."""
+        if not (raw := getattr(self._workflow, "mixmd", None)):
+            return None
+        return MixMDResults(
+            reference_uuid=raw.reference_uuid,
+            density_map_uuid=raw.density_map_uuid,
+            replicas=tuple(
+                MixMDReplicaDiagnostics(
+                    index=r.index,
+                    seed=r.seed,
+                    num_frames=r.num_frames,
+                    num_probes=r.num_probes,
+                    largest_probe_cluster_fraction=r.largest_probe_cluster_fraction,
+                    trajectory_uuid=r.trajectory_uuid,
+                    topology_uuid=r.topology_uuid,
+                    density_map_uuid=r.density_map_uuid,
+                )
+                for r in raw.replicas
+            ),
+        )
+
+    @property
+    def messages(self) -> list[Message]:
+        """Any messages or warnings from the workflow, including MixMD reliability warnings."""
+        return parse_messages(getattr(self._workflow, "messages", None))
+
+    def get_reference_protein(self) -> Protein | None:
+        """Fetch and cache the protein defining mixed-solvent MD pocket and map coordinates.
+
+        Returns:
+            protein object, or `None` for Pocketeer runs
+        """
+        if not (mixmd := self.mixmd) or not mixmd.reference_uuid:
+            return None
+        if "reference_protein" not in self._cache:
+            self._cache["reference_protein"] = retrieve_protein(
+                mixmd.reference_uuid, workflow_uuid=self.workflow_uuid
+            )
+        return self._cache["reference_protein"]
+
 
 def submit_pocket_detection_workflow(
     protein: Protein | ProteinUUID,
-    merge_distance: float = 1.75,
+    merge_distance: float | None = None,
+    settings: PocketeerSettings | MixMDSettings | None = None,
+    validate_forcefield: bool = True,
     name: str = "Pocket Detection Workflow",
     folder_uuid: str | None = None,
     folder: Folder | None = None,
@@ -76,7 +195,13 @@ def submit_pocket_detection_workflow(
 
     Args:
         protein: protein to analyze. Can be a UUID or a Protein object
-        merge_distance: distance for merging pocket spheres, in Å
+        merge_distance: Pocketeer distance for merging pocket spheres, in Å; defaults to 1.75.
+            Set it on `PocketeerSettings` instead when passing `settings`
+        settings: method settings; `PocketeerSettings` (default) for geometric detection or
+            `MixMDSettings` for mixed-solvent molecular dynamics
+        validate_forcefield: validate the protein forcefield compatibility before submitting a
+            mixed-solvent MD run. Raises an error early if the protein cannot be parameterized
+            or has clashing residues
         name: name of the workflow
         folder_uuid: UUID of the folder to place the workflow in
         folder: destination folder
@@ -88,23 +213,33 @@ def submit_pocket_detection_workflow(
         workflow object representing the submitted workflow
 
     Raises:
+        ValueError: both `merge_distance` and `settings`, or both `folder` and `folder_uuid`,
+            are given
         httpx.HTTPStatusError: request to the API fails
     """
     if folder and folder_uuid:
         raise ValueError("Provide either `folder` or `folder_uuid`, not both.")
+    if settings is not None and merge_distance is not None:
+        raise ValueError("Set `merge_distance` on `PocketeerSettings` when passing `settings`.")
     if folder:
         folder_uuid = folder.uuid
     if isinstance(protein, Protein):
         protein = protein.uuid
 
-    workflow = stjames.PocketDetectionWorkflow(
-        protein=protein,
-        merge_distance=merge_distance,
-    )
+    if settings is None:
+        settings = (
+            PocketeerSettings()
+            if merge_distance is None
+            else PocketeerSettings(merge_distance=merge_distance)
+        )
+    if validate_forcefield and isinstance(settings, MixMDSettings):
+        Protein(uuid=protein).validate_protein_forcefield()
+
+    workflow = stjames.PocketDetectionWorkflow(protein=protein, settings=settings)
 
     data = {
         "workflow_type": "pocket_detection",
-        "workflow_data": workflow.model_dump(mode="json"),
+        "workflow_data": workflow.model_dump(serialize_as_any=True, mode="json"),
         "name": name,
         "folder_uuid": folder_uuid,
         "max_credits": max_credits,

rowan/workflows/protein_md.py

@@ -8,6 +8,7 @@ from stjames import (
     Binder,
     GreedyClusteringSettings,
     KMeansClusteringSettings,
+    MDRestraints,
     ProteinForceField,
     WaterForceField,
 )
@@ -158,6 +159,7 @@ def submit_protein_md_workflow(
     max_credits: int | None = None,
     webhook_url: str | None = None,
     is_draft: bool = False,
+    restraints: list[MDRestraints] | None = None,
 ) -> Workflow[ProteinMDResult]:
     """Submits a Protein Molecular Dynamics (MD) workflow to the API.
 
@@ -192,7 +194,7 @@ def submit_protein_md_workflow(
             (one small molecule → heavy-atom RMSD; one binder chain → backbone N/CA/C/O RMSD);
             it is empty for multi-molecule, multi-chain, or combined chain+molecule binders
         protein_restraint_cutoff: cutoff distance from the binder past which Cα atoms are
-            harmonically restrained, in Å; None disables restraints
+            harmonically restrained, in Å; None disables these Cα restraints
         protein_restraint_constant: force constant for Cα backbone restraints, in kcal/mol/Ų
         analysis_interval_ps: interval at which to compute per-frame SASA and polar SASA
             (default 100), in ps. None disables those analyses
@@ -210,6 +212,9 @@ def submit_protein_md_workflow(
         max_credits: maximum credits for the workflow
         webhook_url: URL that Rowan will POST to when the workflow completes
         is_draft: save as a draft without starting execution
+        restraints: atom or whole-residue restraints applied during minimization,
+            equilibration, and production. Atoms use their positions; residues use
+            their centers of mass. Cannot be combined with protein_restraint_cutoff
 
     Returns:
         submitted workflow
@@ -256,6 +261,7 @@ def submit_protein_md_workflow(
         binder=binder,
         protein_restraint_cutoff=protein_restraint_cutoff,
         protein_restraint_constant=protein_restraint_constant,
+        restraints=restraints or [],
         analysis_interval_ps=analysis_interval_ps,
         clustering=clustering,
     )

rowan/workflows/protein_preparation.py

@@ -71,6 +71,7 @@ def submit_protein_preparation_workflow(
     max_credits: int | None = None,
     webhook_url: str | None = None,
     is_draft: bool = False,
+    retain_noncanonical_residues: bool = False,
 ) -> Workflow[ProteinPreparationResult]:
     """Submit a protein-preparation workflow to the API.
 
@@ -97,6 +98,8 @@ def submit_protein_preparation_workflow(
         max_credits: maximum credits for the workflow
         webhook_url: URL that Rowan will POST to when the workflow completes
         is_draft: save as a draft without starting execution
+        retain_noncanonical_residues: preserve modified polymer residues such as SEP/TPO/PTR;
+            False replaces them with their unmodified parent residues
 
     Returns:
         workflow object representing the submitted workflow
@@ -119,6 +122,7 @@ def submit_protein_preparation_workflow(
         protonation_method=protonation_method,
         pH=pH,
         retain_protonation=retain_protonation,
+        retain_noncanonical_residues=retain_noncanonical_residues,
         retain_non_polymer=(dict(retain_non_polymer) if retain_non_polymer is not None else None),
     )
 

rowan/workflows/relative_binding_free_energy_perturbation.py

@@ -12,7 +12,7 @@ from rowan.folder import Folder
 from rowan.molecule import Molecule
 from rowan.protein import Protein
 from rowan.types import ProteinUUID
-from rowan.utils import api_client, download_file
+from rowan.utils import api_client, download_file, download_presigned_files
 
 from .base import Workflow, WorkflowResult, molecule_to_dict, register_result
 from .rbfe_graph import RelativeBindingFreeEnergyGraphEdge, RelativeBindingFreeEnergyGraphResult
@@ -143,7 +143,9 @@ class RelativeBindingFreeEnergyPerturbationResult(WorkflowResult):
         *,
         leg: Literal["complex", "solvent"] = "complex",
     ) -> Path:
-        """Download DCD trajectory files for a specific perturbation edge.
+        """Download DCD trajectory files for a specific perturbation edge as one `.tar.gz` archive.
+
+        Long trajectories can time out; use `download_edge_trajectory_files` for those.
 
         Args:
             edge_index: index of the edge (0-based, matching `edges` order)
@@ -183,6 +185,40 @@ class RelativeBindingFreeEnergyPerturbationResult(WorkflowResult):
             json=lambda_vals,
         )
 
+    def download_edge_trajectory_files(
+        self,
+        edge_index: int,
+        lambda_vals: list[float] | None = None,
+        path: Path | str | None = None,
+        *,
+        leg: Literal["complex", "solvent"] = "complex",
+    ) -> list[Path]:
+        """Download each lambda window's DCD file for one edge directly from storage.
+
+        Args:
+            edge_index: index of the edge (0-based, matching `edges` order)
+            lambda_vals: lambda values to download. Defaults to all windows
+            path: directory to save the files to. Defaults to current directory
+            leg: thermodynamic leg whose trajectories should be downloaded
+
+        Returns:
+            paths to the downloaded `.dcd` files, one per lambda window
+
+        Raises:
+            IndexError: edge_index is out of range
+            httpx.HTTPStatusError: API or storage request fails
+        """
+        edges = self.edges
+        if edge_index < 0 or edge_index >= len(edges):
+            raise IndexError(f"Edge index {edge_index} out of range (0-{len(edges) - 1})")
+
+        return download_presigned_files(
+            Path(path) if path is not None else Path.cwd(),
+            f"/trajectory/{self.workflow_uuid}/rbfe_trajectory_dcd_urls",
+            params={"edge_index": edge_index, "leg": leg},
+            json=lambda_vals,
+        )
+
     def download_all_trajectories(
         self,
         path: Path | str | None = None,
@@ -205,6 +241,35 @@ class RelativeBindingFreeEnergyPerturbationResult(WorkflowResult):
             self.download_edge_trajectories(i, path=path, leg=leg) for i in range(len(self.edges))
         ]
 
+    def download_all_trajectory_files(
+        self,
+        path: Path | str | None = None,
+        *,
+        leg: Literal["complex", "solvent"] = "complex",
+    ) -> list[Path]:
+        """Download every edge's DCD files directly from storage.
+
+        Files for each edge go in an `edge_<index>` subdirectory of `path`.
+
+        Args:
+            path: directory to save the files to. Defaults to current directory
+            leg: thermodynamic leg whose trajectories should be downloaded
+
+        Returns:
+            paths to all downloaded `.dcd` files, in edge order
+
+        Raises:
+            httpx.HTTPStatusError: any API or storage request fails
+        """
+        directory = Path(path) if path is not None else Path.cwd()
+        return [
+            file
+            for i in range(len(self.edges))
+            for file in self.download_edge_trajectory_files(
+                i, path=directory / f"edge_{i}", leg=leg
+            )
+        ]
+
     @property
     def ligand_dg_results(self) -> dict[str, RelativeBindingFreeEnergyResult] | None:
         """Per-ligand binding free energy results, or None if not yet computed."""
@@ -287,6 +352,8 @@ def submit_relative_binding_free_energy_perturbation_workflow(
     max_credits: int | None = None,
     webhook_url: str | None = None,
     is_draft: bool = False,
+    *,
+    small_molecules: dict[str | int, str | None] | None = None,
 ) -> Workflow[RelativeBindingFreeEnergyPerturbationResult]:
     """Submits a relative binding free energy perturbation (RBFE) workflow to the API.
 
@@ -323,13 +390,16 @@ def submit_relative_binding_free_energy_perturbation_workflow(
         save_trajectories: whether to save DCD trajectories
         trajectory_save_interval: save every Nth frame when saving trajectories
         validate_forcefield: validate protein forcefield
-            compatibility before submitting
+            compatibility before submitting, excluding cofactors supplied with SMILES
         name: name of the workflow
         folder_uuid: UUID of the folder to place the workflow in
         folder: destination folder
         max_credits: maximum credits for the workflow
         webhook_url: URL that Rowan will POST to when the workflow completes
         is_draft: save as a draft without starting execution
+        small_molecules: fixed cofactors in the prepared protein, keyed by residue name
+            or zero-based index among all residues ordered by lowest atom ID, and mapped
+            to SMILES. Known ions and waters may map to None to use existing residue templates
 
     Returns:
         submitted workflow
@@ -345,9 +415,6 @@ def submit_relative_binding_free_energy_perturbation_workflow(
 
     protein_uuid = protein.uuid if isinstance(protein, Protein) else protein
 
-    if validate_forcefield:
-        Protein(uuid=protein_uuid).validate_protein_forcefield()
-
     if graph_result.graph is None:
         raise ValueError("RBFEGraphResult has no graph - has the workflow completed successfully?")
 
@@ -381,9 +448,20 @@ def submit_relative_binding_free_energy_perturbation_workflow(
         graph=graph_result.graph,
         target=protein_uuid,
         protein=protein_uuid,
+        small_molecules=small_molecules,
         settings=settings,
     )
 
+    if validate_forcefield:
+        exclude_residues = [
+            residue
+            for residue, smiles in (workflow.small_molecules or {}).items()
+            if smiles is not None
+        ]
+        Protein(uuid=protein_uuid).validate_protein_forcefield(
+            exclude_residues=exclude_residues or None
+        )
+
     data = {
         "workflow_type": "relative_binding_free_energy_perturbation",
         "workflow_data": workflow.model_dump(mode="json"),

{rowan_python-3.2.2.dist-info → rowan_python-3.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rowan-python
-Version: 3.2.2
+Version: 3.2.4
 Summary: Rowan Python Library
 Project-URL: Homepage, https://github.com/rowansci/rowan-client
 Project-URL: Bug Tracker, https://github.com/rowansci/rowan-client/issues
@@ -12,7 +12,7 @@ Requires-Dist: httpx
 Requires-Dist: nest-asyncio
 Requires-Dist: rdkit
 Requires-Dist: setuptools
-Requires-Dist: stjames>=0.0.281
+Requires-Dist: stjames>=0.0.293
 Description-Content-Type: text/markdown
 
 # Rowan Python Library

{rowan_python-3.2.2.dist-info → rowan_python-3.2.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-rowan/__init__.py,sha256=NBswhyW8dInEyeCwizI9zZoxhAEBhnP5i00-ETllcG8,2146
+rowan/__init__.py,sha256=QHph9MW2q5LS0nLYJKIn62a5bcnHvfY0pGP8VSNklns,2319
 rowan/api_keys.py,sha256=ms8NAkLreFQcaEUPCf8lSf7T0x2OmrWCAT44N1cgocE,6955
 rowan/calculation.py,sha256=E1dAox4ScE3NHJXiKFZ3Lpmw2h7DKCVzcwRvGZ2H2cQ,3802
 rowan/config.py,sha256=ay6UxKLE9bbTxHFXxDfUXGRVJWJ1T-eS2_L4HF8mb_E,20927
@@ -8,11 +8,12 @@ rowan/molecule.py,sha256=1ueC_M2Yaubkt5eQlONCagShWPnoJfNNXgd0s7sslPM,15826
 rowan/project.py,sha256=R5uwpzg7GOaGQ_ebCvTysYvkUHE_hHxWAhujp7CBqU0,5770
 rowan/protein.py,sha256=AGHarvWfciSwWXfHnVjdUW47FML7vI4Kk4dYTeFfKAQ,19322
 rowan/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rowan/spectra.py,sha256=dNmE5th6wpTVAfvZZNDkg2jlBRAmPtFT6yDtxex8APw,2307
 rowan/types.py,sha256=D0d6MW6MvLMs6UtNgGKlapFGOnPlzqFTk9EAgB9dwks,636
-rowan/user.py,sha256=wGwyp0uzifzJeC88yCC7pgxMhxuZ-LLWHfCcuPXcx44,6199
-rowan/utils.py,sha256=d5s7UzjgJNtZ_NDLjvXSeSVnEBrKOqQiyVy-7C13rm0,8020
-rowan/workflows/__init__.py,sha256=1JBuqs3KlizJEFhidvGCG7KtTdLOQKI2kspn0SK_KHw,5161
-rowan/workflows/_molecular_dynamics.py,sha256=ZkddNEo-aRzwFRopDh6LcPPRDL6Rrx4lwW-_roMW3Kc,9323
+rowan/user.py,sha256=GWPh_d7PMhK7ShQ2NtFKl3YWyHI3hfYX-KPJGUCbGI4,6069
+rowan/utils.py,sha256=n82jhtMrHwIPXjEX4i2JFuQTLsanwixk5HfOfzPpKko,9656
+rowan/workflows/__init__.py,sha256=SmKpoLCsNzkkb6xxoG2DEbGOVGiIBpDcmn6ZQ_F7DT0,5253
+rowan/workflows/_molecular_dynamics.py,sha256=fDQVAZam6Ic_Au1yz41bVWg2_NBfkPX2ZFJNDIbw55U,10204
 rowan/workflows/admet.py,sha256=92jEbZr9OuN0FzJtWmE4EdARzs6r0uiRwq3-kSPV7nE,2531
 rowan/workflows/analogue_docking.py,sha256=NZa-2rNzuyfVE_5WZm4pQspdtWFy8tEhxbqwOrXWGnU,10881
 rowan/workflows/base.py,sha256=DR2k5VFMmv2sa9v4hYU_Fvzf8k2unp5nhPqvOd7NX64,39520
@@ -20,7 +21,7 @@ rowan/workflows/basic_calculation.py,sha256=7o9jxEpDMiong2k3Ke1WCLwaSWZvKY5tqhbi
 rowan/workflows/batch_docking.py,sha256=AtCp2-D_LOVxzSPmQ144zYIz5kft9NeRljELdRDU6vY,4941
 rowan/workflows/bde.py,sha256=4Yw27U2RPsuUDf9tw-7wPbw_4gaUcvDlQP8je7VJktU,7099
 rowan/workflows/binding_affinity.py,sha256=CP5rsWNMhsdLGzLdPBIs89wZDW6sa8YwGEkqep0ls1Q,6821
-rowan/workflows/conformer_search.py,sha256=enx9HbFZVVYgHJP-HUFam63E0qCDq6jjGeXNuBXXlys,16311
+rowan/workflows/conformer_search.py,sha256=PSufIThwh2LoqgP6x5gjFxuNW5DP5ClJ5caBCuJoDKU,18910
 rowan/workflows/constants.py,sha256=iM9-6DyIe0N2ydyq-lRYP7VDufFmMrN5tDjnpUSlxF8,588
 rowan/workflows/covalent_inhibitor_scan.py,sha256=VcZhwW3HRuFuGZNedMPZBWbzuhGvz_B5pNJSIPyi9Kw,6721
 rowan/workflows/descriptors.py,sha256=mLo_VnqVrnEbiMHT1-SrbKhy_Dk5jpIM4btNGrlmNio,3041
@@ -39,22 +40,22 @@ rowan/workflows/msa.py,sha256=oXCbhHjBrodZpu_PjF5JF9z7-6ShpwAwHe1RPt7j_vY,4688
 rowan/workflows/multistage_optimization.py,sha256=27XDEYvvqMPhHscyHRvEM7AWK5CFwP2QoIUXRLhm59s,7316
 rowan/workflows/nmr.py,sha256=6yWhweIkB4tKUmJzMPFczQfDKqPWW5DD0Z7YZrv5XKI,8413
 rowan/workflows/pka.py,sha256=stwjhNcoXYO3Ulh7Wl_3EDED3hRLeX5rNcuGTdVHdHU,8459
-rowan/workflows/pocket_detection.py,sha256=dFeCLB59v5-Izf54blrRzJhwUtBQX2SJyVKT_-_nOUs,3889
+rowan/workflows/pocket_detection.py,sha256=lSzRsmIEGOzvUorpcXeLmWaW0yPP4VfcG8-udaNfkfg,9397
 rowan/workflows/pose_analysis_md.py,sha256=ndfGS8oP8oQ3EXe83Wgbx1H8ZFURlm8IJZN34aDpqeE,10599
 rowan/workflows/protein_binder_design.py,sha256=ee3qYGzTzQsca9otnRz9Qjwj1X66LTCKqtTQ5EOzBHk,9181
 rowan/workflows/protein_cofolding.py,sha256=s4bLxlix4kAO_NzS75tc2wiEYqUxpFofxziUnxI2iUY,17422
-rowan/workflows/protein_md.py,sha256=iDeKW0ONY3ZPKPsjmZVQhbFQbo0vmOp5M8ko2Hfc16U,12277
-rowan/workflows/protein_preparation.py,sha256=8C04rhR4AiGiYJWZ8V06O4kpV443tGihcTk8rnNgscE,5325
+rowan/workflows/protein_md.py,sha256=d7ARvsejEy5ZKFtznlxPZn1auVHdTiyu8GCCLMpz344,12641
+rowan/workflows/protein_preparation.py,sha256=N-IMUveGL7VxFSxWC-uW607PicYjoyYa4tUNuWt30JA,5604
 rowan/workflows/rbfe_graph.py,sha256=DBNxtmgw7BNSwOXFLpHDxJtfpheTpDPs8U3SYB2MXdE,8070
 rowan/workflows/redox_potential.py,sha256=0AV2nKTngEFw7VDDpDQvdeBo5u03Aklc2ak4bDWxUz0,5366
-rowan/workflows/relative_binding_free_energy_perturbation.py,sha256=dBQkM3wtbNVVkiXbB3RBBDUcme2OnWZkWFZdTUR8vlM,15872
+rowan/workflows/relative_binding_free_energy_perturbation.py,sha256=ruNdOW6RWAcvPUWLAV-JpAhf_F1nBVBbWkhzC_5FIC8,18977
 rowan/workflows/scan.py,sha256=MqV0NcjfInwxGlegOyWvAt8pwN0BdpsKvgCgTRkzdzU,7440
 rowan/workflows/solubility.py,sha256=Lws0lk4ifmtj84W_jyeOuaTpt8KM8-fceOggHrEYnmc,11211
 rowan/workflows/solvent_dependent_conformers.py,sha256=1dYf8UBVMRFELdwHzv3MI0pe12qoCAfohkaMiW3ak50,7460
 rowan/workflows/spin_states.py,sha256=C3hJEY4hccE1fCW4UjI4nIqGZLw9l2C2VKWCLiopSlY,9044
 rowan/workflows/strain.py,sha256=hq0dOlxnN72V4Sohr3qNFbOrjGmV01tc5zcF0HrL2-Y,6372
 rowan/workflows/tautomer_search.py,sha256=o5iFXHfcb6DvvWH7itA05hvWIrzxrc3a_9IDikYftiM,6351
-rowan_python-3.2.2.dist-info/METADATA,sha256=xezscvm6Crm8AmqvJ0fXrjTPLcstG5WYq20pkIypqa8,3934
-rowan_python-3.2.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-rowan_python-3.2.2.dist-info/licenses/LICENSE,sha256=i05z7xEhyrg6f8j0lR3XYjShnF-MJGFQ-DnpsZ8yiVI,1084
-rowan_python-3.2.2.dist-info/RECORD,,
+rowan_python-3.2.4.dist-info/METADATA,sha256=EBP6kz8swDog3FXU89-1jiKnxJ7hLFs5f0p9w2cUbrk,3934
+rowan_python-3.2.4.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+rowan_python-3.2.4.dist-info/licenses/LICENSE,sha256=i05z7xEhyrg6f8j0lR3XYjShnF-MJGFQ-DnpsZ8yiVI,1084
+rowan_python-3.2.4.dist-info/RECORD,,

{rowan_python-3.2.2.dist-info → rowan_python-3.2.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.4
+Generator: hatchling 1.33.0
 Root-Is-Purelib: true
 Tag: py3-none-any