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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rowan-python
-Version: 3.2.3
+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.289
+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.3 → rowan_python-3.2.4}/pyproject.toml

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

{rowan_python-3.2.3 → rowan_python-3.2.4}/rowan/__init__.py

@@ -28,7 +28,9 @@ from stjames import (
     iMTDSettings,
     InducedFitSettings,
     KMeansClusteringSettings,
+    MDRestraints,
     Method,
+    MixMDSettings,
     Mode,
     MSAFormat,
     MultiStageOptSettings,
@@ -39,9 +41,11 @@ from stjames import (
     OptimizationSettings,
     PBCDFTSettings,
     PeriodicCell,
+    PocketeerSettings,
     ProteinSequence,
     ProteinForceField,
     ResidueModification,
+    RestraintType,
     RNASequence,
     ScanSettings,
     Settings,
@@ -68,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

{rowan_python-3.2.3 → 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.3 → 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.4/rowan/workflows/pocket_detection.py

@@ -0,0 +1,253 @@
+"""Pocket detection workflow - detect potential binding sites on a protein."""
+
+from dataclasses import dataclass
+
+import stjames
+from stjames import MixMDSettings, PocketeerSettings
+
+from rowan.folder import Folder
+from rowan.protein import Protein, retrieve_protein
+from rowan.types import ProteinUUID
+from rowan.utils import api_client
+
+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: 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], ...]
+    sphere_radii: tuple[float, ...]
+    volume: float
+    score: float
+    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")
+class PocketDetectionResult(WorkflowResult):
+    """Result from a pocket-detection workflow."""
+
+    _stjames_class = stjames.PocketDetectionWorkflow
+
+    def __repr__(self) -> str:
+        return f"<PocketDetectionResult pockets={len(self.pockets)}>"
+
+    @property
+    def pockets(self) -> list[Pocket]:
+        """Detected pockets, in the order returned by the backend."""
+        raw = getattr(self._workflow, "pockets", []) or []
+        return [
+            Pocket(
+                sphere_centers=tuple(tuple(c) for c in p.sphere_centers),
+                sphere_radii=tuple(p.sphere_radii),
+                volume=p.volume,
+                score=p.score,
+                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 | 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,
+    max_credits: int | None = None,
+    webhook_url: str | None = None,
+    is_draft: bool = False,
+) -> Workflow[PocketDetectionResult]:
+    """Submits a pocket-detection workflow to the API.
+
+    Args:
+        protein: protein to analyze. Can be a UUID or a Protein object
+        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
+        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
+
+    Returns:
+        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
+
+    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(serialize_as_any=True, mode="json"),
+        "name": name,
+        "folder_uuid": folder_uuid,
+        "max_credits": max_credits,
+        "webhook_url": webhook_url,
+        "is_draft": is_draft,
+    }
+
+    with api_client() as client:
+        response = client.post("/workflow", json=data)
+        response.raise_for_status()
+        return Workflow[PocketDetectionResult](**response.json())

{rowan_python-3.2.3 → rowan_python-3.2.4}/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_python-3.2.3 → rowan_python-3.2.4}/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_python-3.2.3 → rowan_python-3.2.4}/rowan/workflows/relative_binding_free_energy_perturbation.py

@@ -352,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.
 
@@ -388,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
@@ -410,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?")
 
@@ -446,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.3 → rowan_python-3.2.4}/skills/computational-chemistry-and-biology/SKILL.md

@@ -73,7 +73,7 @@ dedicated reference, in which case trust MCP discovery or the installed SDK for
 - **Pose-analysis MD**: run MD on a docked protein-ligand complex to test pose stability. See [reference/pose_analysis_md.md](reference/pose_analysis_md.md).
 - **Protein binder design**: generate, filter, and rank protein binders for a given protein or small-molecule target. See [reference/protein_binder_design.md](reference/protein_binder_design.md).
 - **Protein co-folding**: predict 3D structures of biomolecules and protein-ligand complexes using AlphaFold 3-style models (Boltz-2, Chai-1r, Boltz-1). See [reference/protein_cofolding.md](reference/protein_cofolding.md).
-- **Protein MD**: run a molecular dynamics simulation on a protein. See [reference/protein_md.md](reference/protein_md.md).
+- **Protein MD**: run a molecular dynamics simulation on a protein, with optional atom or residue restraints. See [reference/protein_md.md](reference/protein_md.md).
 - **Protein preparation**: repair missing protein structure, cap termini, assign protonation states, and retain selected non-polymer residues before docking, MD, or FEP. See [reference/protein_preparation.md](reference/protein_preparation.md).
 - **RBFE graph**: take a list of ligands and generate the graph used by the relative binding free energy perturbation (FEP) workflow. Its edges are the ligand pairs FEP transforms between. See [reference/rbfe_graph.md](reference/rbfe_graph.md).
 - **Redox potential**: predict a molecule's reduction or oxidation potential. See [reference/redox_potential.md](reference/redox_potential.md).

{rowan_python-3.2.3 → rowan_python-3.2.4}/skills/computational-chemistry-and-biology/reference/pocket_detection.md

@@ -9,7 +9,7 @@ A `rowan.Protein` (or its UUID string). Proteins are not SMILES. Load one and pr
 
 Pocket detection accepts any stored `rowan.Protein` or protein UUID. Protein preparation is recommended before submission; when chaining from it, passing `prepared_protein_uuid` avoids an unnecessary structure fetch.
 
-Detects potential binding pockets on the protein structure using Pocketeer.
+Detects potential binding pockets on the protein structure using Pocketeer (default), or with mixed-solvent molecular dynamics (MixMD), which finds regions where small probe molecules accumulate across independent replicas.
 
 ## Example
 
@@ -39,17 +39,22 @@ for i, pocket in enumerate(result.pockets):
 
 ## Settings
 
-- `merge_distance` (default `1.75`): distance in angstrom for merging detected pocket spheres into a single pocket.
+- `merge_distance` (default `1.75`): Pocketeer distance in angstrom for merging detected pocket spheres into a single pocket.
+- `settings`: `rowan.PocketeerSettings(merge_distance=...)` (default) or `rowan.MixMDSettings(...)`. MixMD settings include `probe` (`rowan.Solvent.ACETONITRILE` or `rowan.Solvent.ISOPROPANOL`), `num_trajectories` (default `3`), `equilibration_time_ns` (default `5`), `simulation_time_ns` (default `15`), `enrichment_threshold` (default `5`, probe density relative to bulk), and the same force-field and simulation settings as protein MD. Set `merge_distance` on `PocketeerSettings` when passing `settings`.
+- `validate_forcefield` (default `True`): for MixMD, check that the protein can be parameterized before submitting.
 
 ## Result fields
 
 `result.pockets` is a list of detected pockets, each with:
 
-- `score`: druggability/quality score (larger is better).
-- `volume`: pocket volume in cubic angstrom.
+- `score`: method-specific ranking score (larger is better); scores are not comparable between Pocketeer and MixMD.
+- `volume`: pocket volume in cubic angstrom. For MixMD this is the volume of the enriched probe-density region, not the cavity.
 - `pocket_center`: center of the axis-aligned bounding box, in angstrom.
 - `pocket_sides`: side lengths of the bounding box, in angstrom.
 - `residue_numbers`: residue numbers lining the pocket.
 - `sphere_centers`, `sphere_radii`: centers and radii of the detected spheres, in angstrom.
+- `mixmd`: for MixMD pockets, `density_center`, `peak_enrichment`, and `integrated_excess_density`; otherwise `None`.
+
+For MixMD runs, `result.mixmd` lists each replica (`seed`, `num_frames`, `num_probes`, `largest_probe_cluster_fraction`, and artifact UUIDs), and `result.get_reference_protein()` returns the protein that defines pocket coordinates. Reliability warnings, such as fewer than three replicas or disagreement between replicas, appear in `result.messages`.
 
 To dock into a detected pocket, pass its `pocket_center` and `pocket_sides` as the docking workflow's `pocket`: `pocket=[list(p.pocket_center), list(p.pocket_sides)]`.

{rowan_python-3.2.3 → rowan_python-3.2.4}/skills/computational-chemistry-and-biology/reference/protein_md.md

@@ -59,12 +59,54 @@ result.download_trajectories([0], path=".")  # save DCD trajectory files
 - `num_solvent_to_save` (default `None`): when `save_solvent=True` and a `binder` is set, keep only the N solvent molecules nearest the binder each frame; `None` keeps all solvent. Ignored when `save_solvent=False` or no `binder`.
 - `small_molecules` (default `None`): SMILES keyed by non-polymer residue name or zero-based index. Use this to parameterize one or more small molecules in the protein; a `None` value selects an existing residue template.
 - `binder` (default `None`): a `rowan.Binder` specifying the binder within the complex — protein/peptide chains (`chain_ids`), small molecules (`small_molecule_residues`, identified by residue-name string or 0-based non-polymer residue index), or both. Enables per-frame MM/GBSA and binder RMSD analyses (see result fields).
-- `protein_restraint_cutoff` (default `None`): distance from the binder past which Cα atoms are harmonically restrained, in angstrom; `None` disables restraints. Useful for keeping the binding site mobile while stabilizing the rest of the protein.
+- `restraints` (default `None`): a list of `rowan.MDRestraints` for atoms or whole residues. See [restraints](#restraints).
+- `protein_restraint_cutoff` (default `None`): distance from the binder past which Cα atoms are harmonically restrained, in angstrom; `None` disables these Cα restraints. Useful for keeping the binding site mobile while stabilizing the rest of the protein.
 - `protein_restraint_constant` (default `100`): force constant for the Cα backbone restraints, in kcal/mol/Ų.
 - `analysis_interval_ps` (default `100`): interval at which to compute per-frame SASA and polar SASA, in ps. `None` disables those analyses.
 - `clustering` (default `None`): cluster the trajectory frames. `None` disables it; pass `rowan.KMeansClusteringSettings(num_clusters=10)` or `rowan.GreedyClusteringSettings(cutoff_angstrom=2.0)`.
 - `validate_forcefield` (default `True`): validate the protein forcefield before submitting; raises early if the protein cannot be parameterized or has clashing residues. When a `binder` is set, its small molecules are excluded from validation, whether keyed by residue name or by non-polymer index, since they are parameterized from their SMILES. Cofactors, metals, and glycans outside the binder are still validated — set `False` to skip the pre-check entirely.
 
+## Restraints
+
+Pass a list of `rowan.MDRestraints`; each adds one spring during minimization, equilibration, and production. Leave `protein_restraint_cutoff=None`.
+
+Select an atom with `rowan.ResidueAtomRef` or a whole residue with `rowan.ResidueRef`. Atoms use their positions; residues use their centers of mass, including added hydrogens. Use separate restraints to hold atoms individually.
+
+| `restraint_type` | Selections | `target` |
+| --- | --- | --- |
+| `"position"` | 1 | Omit; uses the position before minimization |
+| `"distance"` | 2 | ≥ 0 Å |
+| `"angle"` | 3 | 0–180°; middle selection is the vertex |
+| `"dihedral"` | 4 | -180–180°; selections in torsion order |
+
+- `force_constant`: positive, in kcal/mol/Ų for position/distance or kcal/mol/rad² for angle/dihedral.
+- `flat_bottom_range` (default `0`): ± tolerance in Å or degrees; for position, allowed displacement from the starting point. `target=8, flat_bottom_range=1` permits 7–9 Å. Dihedrals wrap: 179° and -179° differ by 2°.
+- Use IDs and atom names from the submitted protein. For non-polymer residues, use e.g. `rowan.ResidueRef("non_polymer", "B.101")`.
+
+```python
+residue_10 = rowan.ResidueRef("polymer", "A", "A.10")
+residue_25 = rowan.ResidueRef("polymer", "A", "A.25")
+ca_10 = rowan.ResidueAtomRef(residue_10, "CA")
+
+restraints = [
+    rowan.MDRestraints(restraint_type="position", selections=[ca_10], force_constant=5),
+    rowan.MDRestraints(
+        restraint_type="distance",
+        selections=[residue_10, residue_25],
+        force_constant=5,
+        target=8,
+        flat_bottom_range=1,
+    ),
+]
+wf = rowan.submit_protein_md_workflow(
+    protein=prepared_protein_uuid,
+    restraints=restraints,
+    num_trajectories=1,
+    simulation_time_ns=1,
+    folder=folder,
+)
+```
+
 ## Result fields
 
 - `trajectory_uuids`: UUIDs of the trajectory calculations, one per replicate.

{rowan_python-3.2.3 → rowan_python-3.2.4}/skills/computational-chemistry-and-biology/reference/protein_preparation.md

@@ -53,6 +53,7 @@ print(prepared_protein_uuid)
 - `protonation_method` (default `"openmm"`): use `"openmm"`, `"protonate_utils"`, or `"propka_3"` to add hydrogens.
 - `pH` (default `7.4`): pH used to assign protonation states.
 - `retain_protonation` (default `True`): retain existing protonation states where possible.
+- `retain_noncanonical_residues` (default `False`): preserve modified polymer residues such as phosphorylated SEP/TPO/PTR. When `False`, replace them with their unmodified parent residues. Use OpenMM or PROPKA 3 protonation when retaining phosphorylated residues.
 - `retain_non_polymer` (default `{"NA": None, "CL": None, "MG": None}`): non-polymer residues to preserve, keyed by residue name or 0-based residue index. Map ligands and other non-ion residues to their SMILES for parameterization. Known ions and waters may map to `None`. Pass `None` to remove all non-polymer residues.
 
 Example retaining a ligand and a structural water:

{rowan_python-3.2.3 → rowan_python-3.2.4}/skills/computational-chemistry-and-biology/reference/relative_binding_free_energy_perturbation.md

@@ -6,6 +6,7 @@ A completed RBFE graph and a prepared protein.
 
 - `graph_result`: a `RelativeBindingFreeEnergyGraphResult` from the RBFE graph workflow, which turns a congeneric ligand series into the graph of ligand pairs FEP transforms between.
 - `protein`: any stored `rowan.Protein` or protein UUID. Upload your own PDB with `rowan.upload_protein(name, path)`, or get one from the PDB with `rowan.create_protein_from_pdb_id(pdb_code, name=..., project_uuid=...)`. Protein preparation is recommended before RBFE; when chaining from it, passing `prepared_protein_uuid` avoids fetching structure data solely for submission.
+- `small_molecules` (default `None`): fixed cofactors present in the prepared protein, mapped from residue names or zero-based indices among all residues ordered by lowest atom ID to SMILES, for example `{"EDO": "OCCO"}`. Known ions and waters may map to `None` to use existing residue templates. These molecules are included in complex simulations rather than treated as candidate ligands.
 
 This workflow runs FEP simulations along the graph edges to predict relative binding free energies across the ligand series.
 
@@ -71,7 +72,7 @@ The `tmd_settings` profile is the intended interface: it sets sensible defaults
 - `legs` (default all): which thermodynamic-cycle legs to run, a subset of `vacuum`, `solvent`, `complex`.
 - `save_trajectories` (default `False`): save DCD trajectories.
 - `trajectory_save_interval` (default `1000`): when saving trajectories, save a frame every N production frames.
-- `validate_forcefield` (default `True`): validate protein forcefield compatibility before submitting.
+- `validate_forcefield` (default `True`): validate protein forcefield compatibility before submitting, excluding cofactors supplied with SMILES. Template-backed ions and waters are still checked.
 
 ### Advanced sampling parameters