rowan-python 3.2.2__tar.gz → 3.2.4__tar.gz

{rowan_python-3.2.2 → rowan_python-3.2.4}/PKG-INFO

@@ -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.4/examples/mixmd_pocket_detection.py

@@ -0,0 +1,41 @@
+"""Detect protein binding pockets with mixed-solvent molecular dynamics."""
+
+import rowan
+
+# Set your API key or use the ROWAN_API_KEY environment variable
+# rowan.api_key = "rowan-sk..."
+folder = rowan.get_folder("examples")
+
+protein = rowan.create_protein_from_pdb_id("1OTP", name="thymidine phosphorylase")
+preparation_workflow = rowan.submit_protein_preparation_workflow(
+    protein=protein.uuid,
+    name="Prepare thymidine phosphorylase",
+    folder=folder,
+)
+prepared_protein_uuid = preparation_workflow.result().prepared_protein_uuid
+if prepared_protein_uuid is None:
+    raise ValueError("Protein preparation returned no prepared protein")
+
+# Runs three independent replicas, each with 5 ns equilibration and 15 ns production.
+workflow = rowan.submit_pocket_detection_workflow(
+    protein=prepared_protein_uuid,
+    settings=rowan.MixMDSettings(probe=rowan.Solvent.ACETONITRILE),
+    name="MixMD pocket detection on thymidine phosphorylase",
+    folder=folder,
+)
+print(f"View workflow privately at: https://labs.rowansci.com/pocket-detection/{workflow.uuid}")
+result = workflow.result()
+
+for message in result.messages:
+    print(message)
+
+print(f"Detected {len(result.pockets)} pocket(s):")
+for i, pocket in enumerate(result.pockets):
+    print(f"  Pocket {i}: score={pocket.score}, enriched-region volume={pocket.volume} ų")
+    print(f"    center={pocket.pocket_center}, sides={pocket.pocket_sides}")
+    print(f"    residues={pocket.residue_numbers}")
+
+# Pocket coordinates refer to this reference structure.
+reference_protein = result.get_reference_protein()
+if reference_protein is not None:
+    print(f"Reference protein: {reference_protein.uuid}")

{rowan_python-3.2.2 → rowan_python-3.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rowan-python"
-version = "3.2.2"
+version = "3.2.4"
 description = "Rowan Python Library"
 readme = "README.md"
 license = "MIT"
@@ -12,7 +12,7 @@ authors = [
 ]
 dependencies = [
     "httpx",
-    "stjames>=0.0.281",
+    "stjames>=0.0.293",
     "setuptools",
     "rdkit",
     "nest-asyncio",

{rowan_python-3.2.2 → rowan_python-3.2.4}/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_python-3.2.4/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_python-3.2.2 → rowan_python-3.2.4}/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_python-3.2.2 → rowan_python-3.2.4}/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_python-3.2.2 → rowan_python-3.2.4}/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_python-3.2.2 → rowan_python-3.2.4}/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_python-3.2.2 → rowan_python-3.2.4}/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")