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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rowan-python
-Version: 3.2.1
+Version: 3.2.3
 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.275
+Requires-Dist: stjames>=0.0.289
 Description-Content-Type: text/markdown
 
 # Rowan Python Library

{rowan_python-3.2.1 → rowan_python-3.2.3}/pyproject.toml

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

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

@@ -15,6 +15,7 @@ from stjames import (
     Constraint,
     ConstraintType,
     ConformerClusteringSettings,
+    ConformerProperties,
     ConformerGenSettingsUnion,
     Correction,
     DNASequence,
@@ -67,6 +68,7 @@ from stjames.engine_compatibility import (
     METHOD_ENGINES,
     get_supported_corrections,
 )
+from stjames.pdb import ResidueRef
 from stjames.optimization.band_method import NEBSettings
 from stjames.optimization.interpolation import Interpolation
 from stjames.optimization.string_method import FSMSettings, StringMethodSettings
@@ -82,5 +84,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.1 → rowan_python-3.2.3}/rowan/project.py

@@ -197,8 +197,15 @@ def default_project() -> Project:
 
     Raises:
         httpx.HTTPStatusError: API request fails
+        ValueError: user has no default project in the API key's organization
     """
     with api_client() as client:
         response = client.get("/user/me/default_project")
         response.raise_for_status()
-        return Project(**response.json())
+        project = response.json()
+    if project is None:
+        raise ValueError(
+            "You have no default project in this organization. "
+            "Set a default project, or pass a folder or project."
+        )
+    return Project(**project)

rowan_python-3.2.3/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.1 → rowan_python-3.2.3}/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.1 → rowan_python-3.2.3}/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.1 → rowan_python-3.2.3}/rowan/workflows/binding_affinity.py

@@ -153,9 +153,15 @@ def submit_binding_affinity_workflow(
         binding_affinity_settings=binding_affinity_settings or SinglePointEnergySettings(),
     )
 
+    workflow_data = workflow.model_dump(serialize_as_any=True, mode="json")
+    if isinstance(workflow.binding_affinity_settings, SinglePointEnergySettings):
+        workflow_data["binding_affinity_settings"]["truncation_radius"] = (
+            workflow.binding_affinity_settings.truncation_radius
+        )
+
     data = {
         "workflow_type": "binding_affinity",
-        "workflow_data": workflow.model_dump(serialize_as_any=True, mode="json"),
+        "workflow_data": workflow_data,
         "name": name,
         "folder_uuid": folder_uuid,
         "max_credits": max_credits,

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

@@ -149,7 +149,7 @@ def submit_protein_md_workflow(
     binder: Binder | None = None,
     protein_restraint_cutoff: float | None = None,
     protein_restraint_constant: float = 100,
-    analysis_interval_ps: float | None = None,
+    analysis_interval_ps: float | None = 100,
     clustering: KMeansClusteringSettings | GreedyClusteringSettings | None = None,
     validate_forcefield: bool = True,
     name: str = "Protein MD Workflow",
@@ -194,8 +194,8 @@ def submit_protein_md_workflow(
         protein_restraint_cutoff: cutoff distance from the binder past which Cα atoms are
             harmonically restrained, in Å; None disables 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, in ps.
-            None disables those analyses
+        analysis_interval_ps: interval at which to compute per-frame SASA and polar SASA
+            (default 100), in ps. None disables those analyses
         clustering: how to cluster trajectory frames. None disables clustering; pass a
             KMeansClusteringSettings (num_clusters) or GreedyClusteringSettings (cutoff_angstrom)
         validate_forcefield: validate the protein forcefield

{rowan_python-3.2.1 → rowan_python-3.2.3}/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."""

{rowan_python-3.2.1 → rowan_python-3.2.3}/skills/computational-chemistry-and-biology/reference/binding_affinity.md

@@ -57,9 +57,19 @@ for name, score in zip(ligands.keys(), result.scores):
 
 - `rowan.SinglePointEnergySettings` (default):
   - `multistage_opt_settings` (default PM6-D3H4X/COSMO optimization + PM6-D3H4X/COSMO2 single-point in water): a `rowan.MultiStageOptSettings` controlling ligand geometry optimization and energy evaluation.
-  - `truncation_radius` (default `6.0` Å): protein residues beyond this distance from the ligand are excluded from the calculation.
+  - `truncation_radius` (default `6.0` Å): selects whole protein residues with any atom within this distance of any submitted ligand atom.
+  - `truncation_residues`: nonempty list of `rowan.ResidueRef` objects identifying polymer residues by chain and residue keys in the submitted protein. Requires `truncation_radius=None`; a radius and explicit residues cannot be supplied together.
 - `rowan.GninaAffinitySettings`, `rowan.AEVPLIGAffinitySettings`, `rowan.NessoAffinitySettings`: no tunable parameters.
 
+For an explicit pocket, pass settings like these, using keys from your protein:
+
+```python
+rowan.SinglePointEnergySettings(
+    truncation_radius=None,
+    truncation_residues=[rowan.ResidueRef("polymer", "A", "A.182")],
+)
+```
+
 ```python
 # Replace the path, residue name, and SMILES with those of your holo complex.
 holo_protein = rowan.upload_protein("Holo complex", "PATH_TO_HOLO_PDB")

{rowan_python-3.2.1 → rowan_python-3.2.3}/skills/computational-chemistry-and-biology/reference/conformer_search.md

@@ -27,10 +27,29 @@ best = result.get_conformers(1)[0]  # lowest-energy conformer, a rowan.Molecule
 
 `get_conformers(n)` returns the `n` lowest-energy conformers as `rowan.Molecule` objects (omit `n` for all), and `get_energies(relative=True)` gives their relative energies in kcal/mol. Both are energy-ordered, so the lowest-energy conformer is index 0, ready to feed into a downstream 3D workflow. `get_conformers` makes one API call per conformer, so request only as many as you need.
 
+## Ensemble properties
+
+`sasa`, `polar_sasa`, `radii_of_gyration`, and `dipoles` give per-conformer values in energy order (`None` where a value could not be computed); `dipoles` are magnitudes about the center of mass, in Debye. `boltzmann_weights` are the conformer populations at `weighting_temperature`, from free energies when every conformer has frequencies and from ground-state energies otherwise.
+
+`ensemble_properties` is a `rowan.ConformerProperties` weighted by those populations over the conformers that have each value: SASA, polar SASA, Rg, the root-mean-square dipole, 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⁻¹) with `ir_intensities` (km/mol).
+
+```python
+import rowan
+
+props = result.ensemble_properties
+energies_ev = [e * rowan.HARTREE_TO_EV for e in props.excitation_energies]
+grid = [2 + 0.01 * i for i in range(600)]  # eV
+uv_vis = rowan.broaden_spectrum(energies_ev, props.oscillator_strengths, grid, fwhm=0.3)
+```
+
+Spectra need the matching calculations: set `frequencies=True` for IR, and give `multistage_opt_settings` a TDDFT `singlepoint_settings` (with `excited_state_settings=rowan.TDDFTSettings(...)`) for UV-vis and ECD. ECD is omitted when the conformers differ in stereochemistry, so give a SMILES with every stereocenter assigned. A TDDFT single point does not report dipoles or charges. The populations are fixed when the workflow runs; resubmit with another `weighting_temperature` for a different temperature.
+
 ## Settings
 
 - `final_method` (default `aimnet2_wb97md3`): method used to rank the final conformers.
 - `solvent` (default gas phase): implicit solvent; introspect `rowan.Solvent` for the available solvents.
+- `frequencies` (default `False`): compute vibrational frequencies of each conformer at the optimization level, for the ensemble IR spectrum and free-energy populations.
+- `weighting_temperature` (default 298.15 K): temperature for the conformer populations and their free-energy corrections.
 - `transition_state` (default `False`): optimize each conformer toward a transition state rather than a minimum. Start from a fully optimized transition state, not a guess and not a SMILES. Conformer generation will otherwise relax the transition state to a local minimum, so pass constraints in `conf_gen_settings` to hold the reacting atoms in place during generation; the post-generation TS optimizations then run without constraints.
 - `conf_gen_settings` (default none, currently resolves to OpenConf): override conformer generation. Pick and tune a generator by passing its settings object: `rowan.OpenConfSettings`, `rowan.ETKDGSettings`, `rowan.MonteCarloMultipleMinimumSettings` (MCMM), or `rowan.iMTDGCSettings` (iMTDGC). OpenConf (the default) is Rowan's conformer generator; ETKDG is a fast RDKit knowledge-based generator; iMTDGC runs CREST metadynamics for more thorough sampling of flexible molecules, at higher cost. Each has its own tuning fields; run `help()` on the one you want. `max_confs` is common to every generator and caps how many conformers are kept after generation.
 - `multistage_opt_settings` (default none): override the full optimization-and-ranking stack as a `MultiStageOptSettings`. When supplied, it takes precedence over `final_method`, `solvent`, and `transition_state`, so those are ignored. Omit it and set `final_method`/`solvent`/`transition_state` instead unless you need a stack they cannot express.

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

@@ -61,7 +61,7 @@ result.download_trajectories([0], path=".")  # save DCD trajectory files
 - `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.
 - `protein_restraint_constant` (default `100`): force constant for the Cα backbone restraints, in kcal/mol/Ų.
-- `analysis_interval_ps` (default `None`): interval at which to compute per-frame SASA and polar SASA, in ps. `None` (the default) disables those analyses.
+- `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.