rowan

Rowan：云原生分子建模与药物设计工作流

概述

Rowan 是一个用于分子模拟、药物化学和基于结构的设计的云原生工作流平台。其 Python API 提供统一接口，用于小分子建模、性质预测、对接、分子动力学和 AI 结构工作流。

如果你想以编程方式运行药物化学或分子设计工作流，同时又不想维护本地 HPC 基础设施、配置 GPU 或管理一系列独立的建模工具，就可以使用 Rowan。Rowan 会处理所有基础设施、结果管理和计算扩展。

何时使用 Rowan

适合使用 Rowan 的场景：

• 量子化学、半经验方法或神经网络势
• 批量性质预测（pKa、描述符、渗透性、溶解度）
• 构象异构体和互变异构体集合生成
• 对接工作流（单个配体、类似物系列、姿势精修）
• 蛋白质-配体共折叠和 MSA 生成
• 多步化学流程（例如：互变异构体搜索 → 对接 → 姿势分析）
• 需要一致、可扩展基础设施的批量药物化学项目

不适合使用 Rowan 的场景：

• 简单的分子 I/O（直接使用 RDKit）
• 后 HF 从头算 量子化学或相对论计算

快速开始

uv pip install rowan-python

import rowan
rowan.api_key = "your_api_key_here"  # or set ROWAN_API_KEY env var

# Descriptors require a 3D Molecule, not a bare SMILES string.
mol = rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O")
wf = rowan.submit_descriptors_workflow(mol, name="aspirin")
result = wf.result()

print(result.descriptors["MW"])       # 180.042 — exact mass
print(result.descriptors["SLogP"])    # 1.31
print(result.descriptors["TopoPSA"])  # 63.6 — topological PSA

如果运行后没有报错，就说明设置正确。这些值和示例已针对 rowan-python 3.1.13 验证。

安装

uv pip install rowan-python
# or: uv pip install rowan-python

用户和 webhook 管理

身份验证

通过环境变量设置 API 密钥（推荐）：

export ROWAN_API_KEY="your_api_key_here"

或者直接在 Python 中设置：

import rowan
rowan.api_key = "your_api_key_here"

验证身份验证：

import rowan
user = rowan.whoami()  # Returns user info if authenticated
print(f"User: {user.email}")
print(f"Credits available: {user.credits_available_string()}")

分子输入格式

Rowan 接受以下格式的分子：

• SMILES（首选）："CCO"、"c1ccccc1O"
• SMARTS 模式（适用于部分工作流）：用于子结构匹配的 SMARTS 子集
• InChI（如果你的 API 版本支持）："InChI=1S/C2H6O/c1-2-3/h3H,2H2,1H3"

API 会验证分子输入。对于无法解析的 SMILES 或与工作流不兼容的输入类型，会抛出 ValueError。为确保结果可复现，请始终使用规范化的 SMILES。

SMILES 字符串与分子对象

在 rowan-python 3.1.13 中，不同工作流接受的输入类型各不相同。只有以下常见工作流接受普通字符串：pKa、构象搜索、膜渗透性、ADMET、LogP、macropKa、溶解度和姿势分析 MD。大多数其他工作流——包括描述符、互变异构体搜索、对接、类似物对接、BDE、NMR 和 Fukui——都需要 rowan.Molecule.from_smiles(smiles) 或 RDKit Mol/RWMol。类型错误会在提交前抛出 ValueError。

提示： 提交前使用 RDKit 验证 SMILES：

from rdkit import Chem
smiles = "CCO"
mol = Chem.MolFromSmiles(smiles)
if mol is None:
    raise ValueError(f"Invalid SMILES: {smiles}")

核心用法模式

大多数 Rowan 任务都遵循相同的三步模式：

1. 提交 工作流
2. 等待 完成（可选择启用流式传输）
3. 获取 类型化结果，并使用便捷属性

import rowan

# 1. Submit — use the specific workflow function (not the generic submit_workflow)
workflow = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O"),
    name="aspirin descriptors",
)

# 2. & 3. Wait and retrieve
result = workflow.result()  # Blocks until done (default: wait=True, poll_interval=5)
print(result.data)              # Raw dict
print(result.descriptors["MW"]) # 180.042 exact mass; no result.molecular_weight property

对于运行时间较长的工作流，请使用流式传输：

for partial in workflow.stream_result(poll_interval=5):
    print(f"Complete: {partial.complete}")  # bool, not a percentage
    print(partial.data)

result() 与 stream_result()

模式	使用场景	持续时间
result()	可以等待完整结果时	通常 <5 min
stream_result()	需要查看进度或提前获取部分结果时	>5 min，或交互式使用

建议： 对描述符和 pKa 使用 result()。对构象搜索、对接和共折叠使用 stream_result()。

处理结果

Rowan 的 API 包含带便捷属性的类型化工作流结果对象。

使用类型化属性和 .data

结果有两种访问方式：

1. 便捷属性（建议优先使用）：result.descriptors、result.best_pose、result.scores。不同结果类的访问方式有所不同：构象搜索使用 get_energies() 和 get_conformers() 方法。
2. 原始数据回退方式：result.data — API 返回的原始字典

示例：

result = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CCO"),
    name="ethanol",
).result()

# Convenience property (returns all descriptors):
print(result.descriptors["MW"])       # exact/monoisotopic mass
print(result.descriptors["SLogP"])
print(result.descriptors["TopoPSA"])  # usual topological PSA

# Raw data fallback:
print(result.data["descriptors"])

注意：DescriptorsResult 没有 molecular_weight 属性。 MW 是精确质量／单同位素质量，而不是平均分子量。TPSA 是 3D 带电表面描述符；药物相似性规则中常用的拓扑极性表面积应使用 TopoPSA。

缓存失效

某些结果属性采用延迟加载（例如构象几何结构、蛋白质结构）。如需刷新：

result.clear_cache()
new_structures = result.get_conformers()  # Refetched for ConformerSearchResult

项目、文件夹和组织方式

对于较复杂的研究项目，请使用项目和文件夹来整理工作。

项目

import rowan

# Create a project
project = rowan.create_project(name="CDK2 lead optimization")
rowan.set_project("CDK2 lead optimization")

# All subsequent workflows go into this project
wf = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CCO"), name="test compound"
)

# retrieve_project takes a UUID; list_workflows scopes with parent_uuid.
project = rowan.retrieve_project(project.uuid)
workflows = rowan.list_workflows(parent_uuid=project.uuid, size=50)

文件夹

# Create a hierarchical folder structure
folder = rowan.create_folder(name="docking/batch_1/screening")

wf = rowan.submit_docking_workflow(
    # ... docking params ...
    folder=folder,
    name="compound_001",
)

# List workflows in a folder
results = rowan.list_workflows(parent_uuid=folder.uuid)

工作流决策树

pKa 与 MacropKa

在以下情况下使用微观 pKa：

• 需要单个可电离基团的 pKa
• 关注酸碱转变和质子化热力学
• 分子有一个或两个可电离位点
• 速度至关重要（更快、消耗的额度更少）

在以下情况下使用 macropKa：

• 需要了解生理相关范围（例如 0–14）内随 pH 变化的行为
• 希望获得不同 pH 下的汇总电荷和质子化状态分布
• 分子有多个相互耦合质子化的可电离基团
• 需要不同 pH 下的水溶性等下游性质

决策示例：

Phenol (pKa ~10): Use microscopic pKa
Amine (pKa ~9–10): Use microscopic pKa
Multi-ionizable drug (N, O, acidic group): Use macropKa
ADME assessment across GI pH: Use macropKa

构象搜索与互变异构体搜索

在以下情况下使用构象搜索：

• 已知单一互变异构体形式
• 需要多样化的 3D 构象集合，用于对接、MD 或 SAR 分析
• 可旋转键主导化学空间

在以下情况下使用互变异构体搜索：

• 互变异构平衡不确定（例如杂环、酮–烯醇体系）
• 需要对所有相关质子化异构体进行建模
• 下游计算（对接、pKa）取决于互变异构体形式

组合工作流：

# Step 1: Find best tautomer
taut_wf = rowan.submit_tautomer_search_workflow(
    initial_molecule=rowan.Molecule.from_smiles("O=c1[nH]ccnc1"),
    name="imidazole tautomers",
)
best_taut = taut_wf.result().best_tautomer

# Step 2: Generate conformers from best tautomer
conf_wf = rowan.submit_conformer_search_workflow(
    initial_molecule=best_taut,
    name="imidazole conformers",
)

对接与类似物对接及蛋白质–配体协同折叠

工作流	适用情况	输入	输出
对接	单个配体，口袋已知	蛋白质 + SMILES + 口袋坐标	构象、评分、dG
类似物对接	5–100+ 种相关化合物	蛋白质 + SMILES 列表 + 参考配体	所有构象，与参考结构对齐
蛋白质–配体协同折叠	有序列和配体，无晶体结构	蛋白质序列 + SMILES	ML 预测的结合复合物

蛋白质工具

上传蛋白质

# From local PDB file
protein = rowan.upload_protein(
    name="egfr_kinase_domain",
    file_path="egfr_kinase.pdb",
)

# From PDB database
protein_from_pdb = rowan.create_protein_from_pdb_id(
    name="CDK2 (1M17)",
    code="1M17",
)

# Retrieve previously uploaded protein
protein = rowan.retrieve_protein("protein-uuid")

# List all proteins
my_proteins = rowan.list_proteins()

蛋白质准备指南

• 文件格式：PDB、mmCIF（Rowan 会自动检测）
• 水分子：Rowan 通常会保留相关水分子；如有需要，可提前移除大量水分子
• 杂原子：辅因子、离子和结合配体通常会保留；上传前请移除不需要的杂原子
• 多链蛋白质：完全支持
• 分辨率：适用于 NMR 结构、同源建模和冷冻电镜结构；结构质量会影响下游预测
• 验证：Rowan 会验证 PDB 语法；严重格式错误的文件可能会被拒绝

工作流目录

九种常见工作流类别——描述符、微观 pKa、MacropKa、构象搜索、互变异构体搜索、对接、类似物对接、MSA 生成和蛋白质–配体协同折叠——各自的提交代码和结果格式，以及所有受支持工作流类型的完整列表（核心建模、基于结构的设计、高级计算化学、反应化学、高级性质、结合自由能，以及序列和结构生物学），请参阅 references/workflow_catalog.md。

批量提交、Webhook 和异步任务

有关批量提交、轮询和检索、非阻塞的提交后查询模式、Webhook 设置、密钥创建与轮换、负载和签名验证（含 FastAPI 处理程序），以及 Webhook 最佳实践，请参阅 references/batch_and_webhooks.md。

访问权限、定价和额度

有关免费层级限制、每个工作流的额度消耗，以及典型成本估算，请参阅 references/access_and_pricing.md。

完整示例和故障排除

有关完整的潜在客户优化活动——项目设置、互变异构体、类似物系列的 pKa、结果收集和后续对接——请参阅 references/end_to_end_example.md。

有关常见错误及其修复方法，以及调试技巧，请参阅 references/troubleshooting.md。

推荐使用模式

• 优先使用 Rowan 原生工作流，而非低级组装（如果有）
• 对任何非简单活动（>5 个工作流）使用项目和文件夹
• 使用 result() 阻塞等待完成（默认：wait=True, poll_interval=5）
• 优先使用类型化结果属性，未映射的字段则使用 .data
• 对化合物库或类似物系列使用批量提交
• 对多步骤化学活动使用工作流链：
  • pKa → macropKa → permeability（ADME 评估）
  • tautomer search → docking → pose-analysis MD（姿势优化）
  • MSA generation → protein-ligand cofolding（AI 结构预测）
• 对长时间运行的活动（>50 个工作流）或异步管道使用 Webhook
• 对大型构象搜索或对接使用流式传输，以获取交互式反馈

总结

当工作流需要在云端执行分子设计任务时，请使用 Rowan，尤其是当你希望通过统一的 API，在小分子建模、蛋白质、对接、ADME 预测和 ML 结构生成之间一致地处理结果时。

Rowan 是一个分子设计工作流平台，而不只是远程化学引擎。它负责基础设施扩展、结果持久化和多步骤管道编排，让你专注于科学研究。

相关技能

• diffdock：DiffDock 和 DiffDock-L 分子对接。
• tamarind：通过 REST API 或 MCP 服务访问 Tamarind Bio 平台上的开源分子设计和结构生物学工具集合……
• molecular-dynamics：使用 OpenMM 和 MDAnalysis 运行并分析分子动力学模拟。