rowan-python 3.1.3__tar.gz → 3.1.4__tar.gz

{rowan_python-3.1.3 → rowan_python-3.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rowan-python
-Version: 3.1.3
+Version: 3.1.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

{rowan_python-3.1.3 → rowan_python-3.1.4}/docs/index.md

@@ -23,6 +23,16 @@
         - batch_submit_workflow
         - batch_poll_status
 
+::: rowan.calculation
+    handler: python
+    options:
+      show_source: false
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      group_by_category: true
+      filters: ["!^_"]
+
 ## ADMET
 ::: rowan.workflows.admet
     handler: python
@@ -254,6 +264,17 @@
       group_by_category: true
       filters: ["!^__"]
 
+## Pocket Detection
+::: rowan.workflows.pocket_detection
+    handler: python
+    options:
+      show_source: false
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      group_by_category: true
+      filters: ["!^__"]
+
 ## Pose Analysis MD
 ::: rowan.workflows.pose_analysis_md
     handler: python
@@ -397,6 +418,17 @@
       group_by_category: true
       filters: ["!^__"]
 
+## API Keys
+::: rowan.api_keys
+    handler: python
+    options:
+      show_source: false
+      show_root_heading: false
+      show_root_toc_entry: false
+      members_order: source
+      group_by_category: true
+      filters: ["!^__"]
+
 ## Folder Class and Functions
 ::: rowan.folder
     handler: python

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/batch_docking.py

@@ -13,7 +13,7 @@ ligands = [
 ]
 
 protein = rowan.create_protein_from_pdb_id(
-    "CDK2", "1HCK", project_uuid=rowan.default_project().uuid
+    "1HCK", name="CDK2", project_uuid=rowan.default_project().uuid
 )
 
 protein.prepare()

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/boltz_paired_msa.py

@@ -14,7 +14,7 @@ msa_workflow = rowan.submit_msa_workflow(
         "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR",
         "VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH",
     ],
-    output_formats=["boltz"],
+    output_formats=[rowan.MSAFormat.BOLTZ],
     name="Boltz Paired MSA Example",
     folder=folder,
 )
@@ -23,7 +23,7 @@ print(f"View workflow privately at: https://labs.rowansci.com/msa/{msa_workflow.
 
 msa_result = msa_workflow.result()
 
-msa_result.download_files("boltz", path=msa_directory)
+msa_result.download_files(rowan.MSAFormat.BOLTZ, path=msa_directory)
 
 tar_path = next(msa_directory.glob("*.tar.gz"))
 with tarfile.open(tar_path, "r") as tar_ref:

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/boltz_single_msa.py

@@ -13,7 +13,7 @@ msa_workflow = rowan.submit_msa_workflow(
     initial_protein_sequences=[
         "HPETLVKVKDAEDQLGARVGYIELDLNSGKILESFRPEERFPMMSTFKVLLCGAVLSRIDAGQEQLGRRIHYSQNDLVEYSPVTEKHLTDGMTVRELCSAAITMSDNTAANLLLTTIGGPKELTAFLHNMGDHVTRLDRWEPELNEAIPNDERDTTMPVAMATTLRKLLTGELLTLASRQQLIDWMEADKVAGPLLRSALPAGWFIADKSGAGERGSRGIIAALGPDGKPSRIVVIYTTGSQATMDERNRQIAEIGASLIKHW"
     ],
-    output_formats=["boltz"],
+    output_formats=[rowan.MSAFormat.BOLTZ],
     name="Boltz MSA Example",
     folder=folder,
 )
@@ -22,7 +22,7 @@ print(f"View workflow privately at: https://labs.rowansci.com/msa/{msa_workflow.
 
 msa_result = msa_workflow.result()
 
-msa_result.download_files("boltz", path=msa_directory)
+msa_result.download_files(rowan.MSAFormat.BOLTZ, path=msa_directory)
 
 tar_path = next(msa_directory.glob("*.tar.gz"))
 with tarfile.open(tar_path, "r") as tar_ref:

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/chai_paired_msa.py

@@ -25,7 +25,7 @@ msa_workflow = rowan.submit_msa_workflow(
         "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR",
         "VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH",
     ],
-    output_formats=["chai"],
+    output_formats=[rowan.MSAFormat.CHAI],
     name="CHAI Paired MSA Example",
     folder=folder,
 )
@@ -34,7 +34,7 @@ print(f"View workflow privately at: https://labs.rowansci.com/msa/{msa_workflow.
 
 msa_result = msa_workflow.result()
 
-msa_result.download_files("chai", path=msa_directory)
+msa_result.download_files(rowan.MSAFormat.CHAI, path=msa_directory)
 
 tar_path = next(msa_directory.glob("*.tar.gz"))
 with tarfile.open(tar_path, "r") as tar_ref:

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/chai_single_msa.py

@@ -22,7 +22,7 @@ msa_workflow = rowan.submit_msa_workflow(
     initial_protein_sequences=[
         "HPETLVKVKDAEDQLGARVGYIELDLNSGKILESFRPEERFPMMSTFKVLLCGAVLSRIDAGQEQLGRRIHYSQNDLVEYSPVTEKHLTDGMTVRELCSAAITMSDNTAANLLLTTIGGPKELTAFLHNMGDHVTRLDRWEPELNEAIPNDERDTTMPVAMATTLRKLLTGELLTLASRQQLIDWMEADKVAGPLLRSALPAGWFIADKSGAGERGSRGIIAALGPDGKPSRIVVIYTTGSQATMDERNRQIAEIGASLIKHW"
     ],
-    output_formats=["chai"],
+    output_formats=[rowan.MSAFormat.CHAI],
     name="CHAI MSA Example",
     folder=folder,
 )
@@ -31,7 +31,7 @@ print(f"View workflow privately at: https://labs.rowansci.com/msa/{msa_workflow.
 
 msa_result = msa_workflow.result()
 
-msa_result.download_files("chai", path=msa_directory)
+msa_result.download_files(rowan.MSAFormat.CHAI, path=msa_directory)
 
 tar_path = next(msa_directory.glob("*.tar.gz"))
 with tarfile.open(tar_path, "r") as tar_ref:

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/colabfold_paired_msa.py

@@ -14,7 +14,7 @@ msa_workflow = rowan.submit_msa_workflow(
         "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR",
         "VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH",
     ],
-    output_formats=["colabfold"],
+    output_formats=[rowan.MSAFormat.COLABFOLD],
     name="Colabfold Paired MSA Example",
     folder=folder,
 )
@@ -23,7 +23,7 @@ print(f"View workflow privately at: https://labs.rowansci.com/msa/{msa_workflow.
 
 msa_result = msa_workflow.result()
 
-msa_result.download_files("colabfold", path=msa_directory)
+msa_result.download_files(rowan.MSAFormat.COLABFOLD, path=msa_directory)
 
 tar_path = next(msa_directory.glob("*.tar.gz"))
 with tarfile.open(tar_path, "r") as tar_ref:

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/colabfold_single_msa.py

@@ -13,7 +13,7 @@ msa_workflow = rowan.submit_msa_workflow(
     initial_protein_sequences=[
         "HPETLVKVKDAEDQLGARVGYIELDLNSGKILESFRPEERFPMMSTFKVLLCGAVLSRIDAGQEQLGRRIHYSQNDLVEYSPVTEKHLTDGMTVRELCSAAITMSDNTAANLLLTTIGGPKELTAFLHNMGDHVTRLDRWEPELNEAIPNDERDTTMPVAMATTLRKLLTGELLTLASRQQLIDWMEADKVAGPLLRSALPAGWFIADKSGAGERGSRGIIAALGPDGKPSRIVVIYTTGSQATMDERNRQIAEIGASLIKHW"
     ],
-    output_formats=["colabfold"],
+    output_formats=[rowan.MSAFormat.COLABFOLD],
     name="Colabfold MSA Example",
     folder=folder,
 )
@@ -22,7 +22,7 @@ print(f"View workflow privately at: https://labs.rowansci.com/msa/{msa_workflow.
 
 msa_result = msa_workflow.result()
 
-msa_result.download_files("colabfold", path=msa_directory)
+msa_result.download_files(rowan.MSAFormat.COLABFOLD, path=msa_directory)
 
 tar_path = next(msa_directory.glob("*.tar.gz"))
 with tarfile.open(tar_path, "r") as tar_ref:

rowan_python-3.1.4/examples/docking.py

@@ -0,0 +1,39 @@
+import rowan
+
+# Set your API key or use the ROWAN_API_KEY environment variable
+# rowan.api_key = "rowan-sk..."
+folder = rowan.get_folder("examples")
+
+# Dasatinib — redocked into its own ABL1 co-crystal structure (PDB: 2GQG)
+dasatinib = rowan.Molecule.from_smiles("Cc1nc(Nc2ncc(C(=O)Nc3c(C)cccc3Cl)s2)cc(N2CCN(CCO)CC2)n1")
+
+protein = rowan.create_protein_from_pdb_id("2GQG")
+if len(protein.chains) > 1:
+    protein = protein.select_chains([protein.chains[0]])
+protein.prepare()
+
+# Pocket is [[center_x, center_y, center_z], [size_x, size_y, size_z]] in Å.
+# For a co-crystal structure, extract these from the bound ligand's position.
+# Use rowan.submit_pocket_detection_workflow() when the binding site is unknown.
+center = [44.59, 79.75, 39.59]
+size = [24.15, 21.33, 19.88]
+workflow = rowan.submit_docking_workflow(
+    protein,
+    pocket=[center, size],
+    initial_molecule=dasatinib,
+    name="dasatinib docking (2GQG redock)",
+    folder=folder,
+)
+
+print(f"View workflow privately at: https://labs.rowansci.com/docking/{workflow.uuid}")
+
+result = workflow.result()
+print(result)
+
+for i, score in enumerate(result.scores):
+    print(f"  Pose {i}: score={score.score:.3f}  posebusters_valid={score.posebusters_valid}")
+
+# Download the top-scoring protein–ligand complex as a PDB
+complex_protein = result.get_complex(0)
+complex_protein.download_pdb_file("dasatinib_2GQG_complex.pdb")
+print("Saved dasatinib_2GQG_complex.pdb")

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/docking_screen.py

@@ -19,7 +19,7 @@ workflows = []
 results = {}
 
 protein = rowan.create_protein_from_pdb_id(
-    "CDK2", "1HCK", project_uuid=rowan.default_project().uuid
+    "1HCK", name="CDK2", project_uuid=rowan.default_project().uuid
 )
 
 protein.prepare()
@@ -43,11 +43,14 @@ lowest_conformer_energy = 0
 for workflow, result in workflow_results:
     for conformer_uuid in result.conformers:
         energy = rowan.retrieve_calculation_molecules(conformer_uuid)[0]["energy"]
-        lowest_conformer_energy = min(lowest_conformer_energy, energy)
+        if energy is not None:
+            lowest_conformer_energy = min(lowest_conformer_energy, energy)
 
     sorted_scores = sorted(result.scores, key=lambda s: s.score)
     for score in sorted_scores:
         pose_energy = rowan.retrieve_calculation_molecules(score.pose)[0]["energy"]
+        if pose_energy is None:
+            continue
         strain = (pose_energy - lowest_conformer_energy) * HARTREE_TO_KCALMOL
         if score.posebusters_valid and strain < 4:
             results[workflow.name] = score

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/pocket_detection.py

@@ -5,7 +5,7 @@ import rowan
 folder = rowan.get_folder("examples")
 
 protein = rowan.create_protein_from_pdb_id(
-    "thymidine phosphorylase", "1OTP", project_uuid=rowan.default_project().uuid
+    "1OTP", name="thymidine phosphorylase", project_uuid=rowan.default_project().uuid
 )
 
 protein.prepare()

rowan_python-3.1.4/examples/resubmit_with_perturbations.py

@@ -0,0 +1,39 @@
+"""
+Resubmit a completed workflow with a perturbed structure.
+
+Two strategies: random noise to break symmetry, or displacement along a
+vibrational mode to follow a reaction coordinate or escape a stuck geometry.
+"""
+
+import rowan
+
+# Set your API key or use the ROWAN_API_KEY environment variable
+# rowan.api_key = "rowan-sk..."
+folder = rowan.get_folder("examples")
+
+# --- Option 1: random noise ---
+wf = rowan.retrieve_workflow("your-workflow-uuid")
+mol = wf.result().molecule
+
+perturbed_mol = mol.perturb()
+resubmit = rowan.submit_multistage_optimization_workflow(
+    initial_molecule=perturbed_mol,
+    name="cyclobutane opt - perturbed resubmit",
+    folder=folder,
+)
+print(f"https://labs.rowansci.com/multistage-opt/{resubmit.uuid}")
+
+# --- Option 2: displace along a vibrational mode ---
+# Requires a prior frequency calculation. Imaginary modes have negative frequency.
+ts_wf = rowan.retrieve_workflow("your-ts-freq-workflow-uuid")
+ts_mol = ts_wf.result().molecule
+
+imaginary_mode = next(m for m in ts_mol.vibrational_modes if m.frequency < 0)
+
+displaced_mol = ts_mol.displace_along_mode(mode=imaginary_mode, displacement=0.3)
+resubmit = rowan.submit_multistage_optimization_workflow(
+    initial_molecule=displaced_mol,
+    name="TS resubmit - displaced along imaginary mode",
+    folder=folder,
+)
+print(f"https://labs.rowansci.com/multistage-opt/{resubmit.uuid}")

{rowan_python-3.1.3 → rowan_python-3.1.4}/examples/scan.py

@@ -13,13 +13,13 @@ folder = rowan.get_folder("examples")
 workflow = rowan.submit_scan_workflow(
     initial_molecule=rowan.Molecule.from_smiles("O"),
     name="Water Angle scan",
-    scan_settings={
-        "type": "angle",
-        "atoms": [2, 1, 3],  # 1-indexed
-        "start": 100,
-        "stop": 110,
-        "num": 5,
-    },
+    scan_settings=rowan.ScanSettings(
+        type="angle",
+        atoms=[2, 1, 3],  # 1-indexed
+        start=100,
+        stop=110,
+        num=5,
+    ),
     calculation_method="GFN2-xTB",
     calculation_engine="xtb",
     folder=folder,

{rowan_python-3.1.3 → rowan_python-3.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rowan-python"
-version = "3.1.3"
+version = "3.1.4"
 description = "Rowan Python Library"
 readme = "README.md"
 requires-python = ">=3.12"

{rowan_python-3.1.3 → rowan_python-3.1.4}/rowan/__init__.py

@@ -2,6 +2,8 @@
 from . import constants
 from stjames import (
     Atom,
+    BindingPoseContact,
+    ConformerGenSettings,
     Constraint,
     ConstraintType,
     ConformerClusteringSettings,
@@ -14,15 +16,19 @@ from stjames import (
     KMeansClusteringSettings,
     Method,
     Mode,
+    MSAFormat,
     MultiStageOptSettings,
     OpenConfSettings,
     OptimizationSettings,
     PBCDFTSettings,
     PeriodicCell,
+    ProteinSequence,
+    ScanSettings,
     Settings,
     Solvent,
     SolventSettings,
     Task,
+    VibrationalMode,
 )
 from stjames.workflows.relative_binding_free_energy_perturbation import RBFEGraph, RBFEGraphEdge
 from stjames.excited_state_settings import TDDFTSettings

{rowan_python-3.1.3 → rowan_python-3.1.4}/rowan/calculation.py

@@ -2,6 +2,7 @@
 
 from typing import Self
 
+import httpx
 import stjames
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -62,10 +63,13 @@ class Calculation(BaseModel):
         :param in_place: If True, update this instance in-place. If False, return new instance.
         :returns: Updated Calculation object.
         """
-        with api_client() as client:
-            response = client.get(f"/calculation/{self.uuid}/stjames")
-            response.raise_for_status()
-            data = response.json()
+        try:
+            with api_client() as client:
+                response = client.get(f"/calculation/{self.uuid}/stjames")
+                response.raise_for_status()
+                data = response.json()
+        except httpx.TimeoutException as e:
+            raise TimeoutError(f"Timed out fetching calculation {self.uuid}.") from e
 
         molecules = _parse_molecules(data.get("molecules", []))
 
@@ -94,11 +98,15 @@ def retrieve_calculation(uuid: str) -> Calculation:
     :param uuid: UUID of the calculation to retrieve.
     :returns: Calculation object with the fetched data.
     :raises requests.HTTPError: If the API request fails.
+    :raises TimeoutError: If the response times out.
     """
-    with api_client() as client:
-        response = client.get(f"/calculation/{uuid}/stjames")
-        response.raise_for_status()
-        data = response.json()
+    try:
+        with api_client() as client:
+            response = client.get(f"/calculation/{uuid}/stjames")
+            response.raise_for_status()
+            data = response.json()
+    except httpx.TimeoutException as e:
+        raise TimeoutError(f"Timed out fetching calculation {uuid}.") from e
 
     molecules = _parse_molecules(data.get("molecules", []))
 

{rowan_python-3.1.3 → rowan_python-3.1.4}/rowan/folder.py

@@ -1,11 +1,16 @@
+from __future__ import annotations
+
 from datetime import datetime
-from typing import Any, Self
+from typing import TYPE_CHECKING, Any, Self
 
 from pydantic import BaseModel
 
 from .project import default_project, retrieve_project
 from .utils import api_client, get_project_uuid
 
+if TYPE_CHECKING:
+    from .workflows.base import Workflow
+
 
 class Folder(BaseModel):
     """
@@ -121,6 +126,77 @@ class Folder(BaseModel):
         """
         print_folder_tree(self.uuid, max_depth, show_uuids)
 
+    def children(self, size: int = 100) -> list[Folder]:
+        """
+        List all child folders directly inside this folder.
+
+        :param size: Maximum number of child folders to return.
+        :returns: List of child Folder objects.
+        :raises HTTPError: If the API request fails.
+        """
+        return list_folders(parent_uuid=self.uuid, size=size)
+
+    def workflows(self, size: int = 100) -> list[Workflow]:
+        """
+        List all workflows directly inside this folder.
+
+        :param size: Maximum number of workflows to return.
+        :returns: List of Workflow objects.
+        :raises HTTPError: If the API request fails.
+        """
+        from .workflows.base import list_workflows
+
+        return list_workflows(parent_uuid=self.uuid, size=size)
+
+    def contents(self, size: int = 100) -> list[Folder | Workflow]:
+        """
+        List everything directly inside this folder, both child folders and workflows.
+
+        Folders come first, followed by workflows. For a single type, use :func:`children`
+        or :func:`workflows`.
+
+        :param size: Maximum number of items of each type to return.
+        :returns: List of Folder and Workflow objects.
+        :raises HTTPError: If the API request fails.
+        """
+        return [*self.children(size=size), *self.workflows(size=size)]
+
+    def parent(self) -> Folder | None:
+        """
+        Retrieve the parent folder, or None if this is a root folder.
+
+        :returns: Parent Folder, or None if there is no parent.
+        :raises HTTPError: If the API request fails.
+        """
+        if self.parent_uuid is None:
+            return None
+        return retrieve_folder(self.parent_uuid)
+
+    def __truediv__(self, name: str) -> Folder:
+        """
+        Traverse into a child folder by name using the ``/`` operator.
+
+        Example::
+
+            root = rowan.root_folder()
+            subfolder = root / "CDK2" / "docking"
+
+        :param name: Exact name of the child folder to navigate into.
+        :returns: Child Folder with the given name.
+        :raises ValueError: If no child with that name exists, or if multiple children share
+            the same name (use :func:`children` and select by UUID to disambiguate).
+        """
+        matches = [f for f in self.children(size=200) if f.name == name]
+        if not matches:
+            raise ValueError(f"No child folder named {name!r} in {self.name!r} ({self.uuid})")
+        if len(matches) > 1:
+            uuids = ", ".join(f.uuid for f in matches)
+            raise ValueError(
+                f"Multiple child folders named {name!r} in {self.name!r} ({self.uuid}). "
+                f"Use retrieve_folder() with one of these UUIDs to disambiguate: {uuids}"
+            )
+        return matches[0]
+
 
 def retrieve_folder(uuid: str) -> Folder:
     """
@@ -147,6 +223,9 @@ def list_folders(
     """
     Retrieve a list of folders based on the specified criteria.
 
+    If no ``parent_uuid`` is given and a project is active (via :func:`set_project` or
+    ``rowan.project_uuid``), lists folders rooted at that project's root folder.
+
     :param parent_uuid: UUID of the parent folder to filter by.
     :param name_contains: Substring to search for in folder names.
     :param public: Filter folders by their public status.
@@ -156,6 +235,11 @@ def list_folders(
     :returns: List of Folder objects that match the search criteria.
     :raises requests.HTTPError: if the request to the API fails.
     """
+    if parent_uuid is None:
+        if project_uuid := get_project_uuid():
+            parent_uuid = retrieve_project(project_uuid).root_folder_uuid
+        else:
+            parent_uuid = default_project().root_folder_uuid
 
     params: dict[str, Any] = {
         "page": page,
@@ -189,6 +273,9 @@ def create_folder(
     """
     Create a new folder.
 
+    If no ``parent_uuid`` is given and a project is active (via :func:`set_project` or
+    ``rowan.project_uuid``), the folder is created inside that project's root folder.
+
     :param name: Name of the folder.
     :param parent_uuid: UUID of the parent folder.
     :param notes: Description of the folder.
@@ -196,6 +283,12 @@ def create_folder(
     :param public: Whether the folder is public.
     :returns: Newly created folder.
     """
+    if parent_uuid is None:
+        if project_uuid := get_project_uuid():
+            parent_uuid = retrieve_project(project_uuid).root_folder_uuid
+        else:
+            parent_uuid = default_project().root_folder_uuid
+
     data = {
         "name": name,
         "parent_uuid": parent_uuid,
@@ -210,6 +303,32 @@ def create_folder(
     return Folder(**folder_data)
 
 
+def root_folder() -> Folder:
+    """
+    Get the root folder of the active project.
+
+    The root folder is the top of the folder tree you navigate and store workflows in. Use the
+    active project set via :func:`set_project` (or ``rowan.project_uuid``), falling back to the
+    default project.
+
+    Example::
+
+        root = rowan.root_folder()
+        for child in root.children():
+            print(child.name)
+        batch = root / "CDK2" / "docking"
+
+    :returns: Root Folder of the active or default project.
+    :raises HTTPError: If the API request fails.
+    """
+    if project_uuid := get_project_uuid():
+        root_uuid = retrieve_project(project_uuid).root_folder_uuid
+    else:
+        root_uuid = default_project().root_folder_uuid
+    assert root_uuid is not None
+    return retrieve_folder(root_uuid)
+
+
 def get_folder(path: str, create: bool = True) -> Folder:
     """
     Get a folder by name or nested path within the default project.

{rowan_python-3.1.3 → rowan_python-3.1.4}/rowan/molecule.py

@@ -1,5 +1,7 @@
 """Molecule class for representing molecular structures and computed properties."""
 
+import math
+import random
 from pathlib import Path
 from typing import Any, Self
 
@@ -272,6 +274,77 @@ class Molecule(BaseModel):
         """
         return self._stjames.dihedral(i, j, k, l, degrees=degrees)
 
+    def perturb(self, stddev: float = 0.005) -> "Molecule":
+        """
+        Return a copy with random Gaussian noise added to each atom position.
+
+        Useful for breaking symmetry before resubmitting an optimization (e.g. when
+        a calculation is stuck in a saddle point or converges to an unwanted geometry).
+
+        :param stddev: standard deviation of the Gaussian displacement (Angstroms)
+        :returns: new Molecule with perturbed coordinates
+        """
+
+        def _gauss() -> float:
+            u1 = random.random()
+            u2 = random.random()
+            return math.sqrt(-2.0 * math.log(u1)) * math.cos(2.0 * math.pi * u2) * stddev
+
+        new_atoms = [
+            stjames.Atom(
+                atomic_number=atom.atomic_number,
+                position=(
+                    atom.position[0] + _gauss(),
+                    atom.position[1] + _gauss(),
+                    atom.position[2] + _gauss(),
+                ),
+                mass=atom.mass,
+            )
+            for atom in self._stjames.atoms
+        ]
+        new_mol = self._stjames.model_copy(update={"atoms": new_atoms})
+        return Molecule(_stjames=new_mol)
+
+    def displace_along_mode(self, mode: stjames.VibrationalMode, displacement: float) -> "Molecule":
+        """
+        Return a copy with atom positions displaced along a vibrational normal mode.
+
+        Requires a prior frequency calculation. For a transition state, the imaginary
+        mode has a negative frequency and points toward the reactant or product.
+
+        :param mode: vibrational mode to displace along, from ``vibrational_modes``
+        :param displacement: displacement distance along the normalized mode (Angstroms)
+        :returns: new Molecule with displaced coordinates
+        :raises ValueError: if the mode has no displacements or zero-norm displacements
+        """
+        raw = mode.displacements
+        if not raw:
+            raise ValueError(
+                "Vibrational mode has no displacements. "
+                "Rerun the calculation with frequencies=True to displace along a mode."
+            )
+        norm = math.sqrt(sum(x**2 + y**2 + z**2 for x, y, z in raw))
+        if norm == 0:
+            raise ValueError(
+                "Vibrational mode has zero-norm displacements. "
+                "This indicates malformed frequency output, try displacing along a different mode."
+            )
+
+        new_atoms = [
+            stjames.Atom(
+                atomic_number=atom.atomic_number,
+                position=(
+                    atom.position[0] + (dx / norm) * displacement,
+                    atom.position[1] + (dy / norm) * displacement,
+                    atom.position[2] + (dz / norm) * displacement,
+                ),
+                mass=atom.mass,
+            )
+            for atom, (dx, dy, dz) in zip(self._stjames.atoms, raw, strict=True)
+        ]
+        new_mol = self._stjames.model_copy(update={"atoms": new_atoms})
+        return Molecule(_stjames=new_mol)
+
 
 def load_named_ligands(path: Path | str) -> dict[str, Molecule]:
     """