Rowan：云原生分子建模与药物设计工作流
概述
Rowan 是一个云原生工作流平台，用于分子模拟、药物化学和基于结构的药物设计。其 Python API 提供了一个统一的接口，用于小分子建模、性质预测、对接、分子动力学和 AI 结构工作流。
当你希望以编程方式运行药物化学或分子设计工作流，而无需维护本地 HPC 基础设施、GPU 配置或一组独立的建模工具时，请使用 Rowan。Rowan 处理所有基础设施、结果管理和计算扩展。
何时使用 Rowan
Rowan 适用于：
- 量子化学、半经验方法或神经网络势
- 批量性质预测（pKa、描述符、渗透性、溶解度）
- 构象和互变异构体集合生成
- 对接工作流（单配体、类似物系列、姿态优化）
- 蛋白质-配体共折叠和 MSA 生成
- 多步化学管线（例如：互变异构体搜索 → 对接 → 姿态分析）
- 批量药物化学项目，需要一致且可扩展的基础设施
Rowan 不适用于：
- 简单的分子 I/O（直接使用 RDKit）
- 后 Hartree-Fock ab initio 量子化学或相对论计算
快速开始
uv pip install rowan-python
import rowan
rowan.api_key = "your_api_key_here" # 或设置 ROWAN_API_KEY 环境变量
# 描述符需要 3D 分子对象，而不是纯 SMILES 字符串。
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 — 精确质量
print(result.descriptors["SLogP"]) # 1.31
print(result.descriptors["TopoPSA"]) # 63.6 — 拓扑极性表面积
如果以上代码无错误打印，说明设置正确。这些值和示例已根据 rowan-python 3.1.13 版验证。
安装
uv pip install rowan-python
# 或：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() # 如果已验证，返回用户信息
print(f"用户：{user.email}")
print(f"可用积分：{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"无效的 SMILES：{smiles}")
核心使用模式
大多数 Rowan 任务遵循相同的三步模式：
- 提交工作流
- 等待完成（可选流式）
- 检索带有便捷属性的类型化结果
import rowan
# 1. 提交 — 使用特定的工作流函数（而非通用的 submit_workflow）
workflow = rowan.submit_descriptors_workflow(
rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O"),
name="阿司匹林描述符",
)
# 2. 和 3. 等待并检索
result = workflow.result() # 阻塞直至完成（默认为 wait=True, poll_interval=5）
print(result.data) # 原始字典
print(result.descriptors["MW"]) # 180.042 精确质量；没有 result.molecular_weight 属性
对于长时间运行的工作流，使用流式：
for partial in workflow.stream_result(poll_interval=5):
print(f"完成：{partial.complete}") # 布尔值，非百分比
print(partial.data)
result() 与 stream_result()
| 模式 | 使用场景 | 持续时间 |
|---|---|---|
result() | 你可以等待完整结果 | 典型 <5 分钟 |
stream_result() | 你需要进度反馈或早期部分结果 | >5 分钟，或交互式使用 |
指南： 描述符、pKa 使用 result()。构象搜索、对接、共折叠使用 stream_result()。
处理结果
Rowan 的 API 包含类型化工作流结果对象及便捷属性。
使用类型化属性和 .data
结果有两种访问模式：
- 便捷属性（首选）：
result.descriptors、result.best_pose、result.scores。不同的结果类有不同的方法：构象搜索使用get_energies()和get_conformers()方法。 - 原始回退：
result.data— 来自 API 的原始字典
示例：
result = rowan.submit_descriptors_workflow(
rowan.Molecule.from_smiles("CCO"),
name="乙醇",
).result()
# 便捷属性（返回所有描述符）：
print(result.descriptors["MW"]) # 精确/单同位素质量
print(result.descriptors["SLogP"])
print(result.descriptors["TopoPSA"]) # 常用拓扑极性表面积
# 原始数据回退：
print(result.data["descriptors"])
注意： DescriptorsResult 没有 molecular_weight 属性。MW 是精确/单同位素质量，而非平均分子量。TPSA 是 3D 带电表面描述符；对于药物相似性规则中常用的拓扑极性表面积，请使用 TopoPSA。
缓存失效
某些结果属性是懒加载的（例如，构象几何、蛋白质结构）。要刷新：
result.clear_cache()
new_structures = result.get_conformers() # 对于 ConformerSearchResult，会重新获取
项目、文件夹和组织
对于重要项目，使用项目和文件夹来保持工作有序。
项目
import rowan
# 创建项目
project = rowan.create_project(name="CDK2 先导优化")
rowan.set_project("CDK2 先导优化")
# 后续所有工作流都会归入此项目
wf = rowan.submit_descriptors_workflow(
rowan.Molecule.from_smiles("CCO"), name="测试化合物"
)
# retrieve_project 接受 UUID；list_workflows 通过 parent_uuid 限定范围。
project = rowan.retrieve_project(project.uuid)
workflows = rowan.list_workflows(parent_uuid=project.uuid, size=50)
文件夹
# 创建层次文件夹结构
folder = rowan.create_folder(name="docking/batch_1/screening")
wf = rowan.submit_docking_workflow(
# ... 对接参数 ...
folder=folder,
name="compound_001",
)
# 列出文件夹中的工作流
results = rowan.list_workflows(parent_uuid=folder.uuid)
工作流决策树
pKa 与 MacropKa
在以下情况下使用微观 pKa：
- 你需要单个可电离基团的 pKa
- 你对酸碱跃迁和质子化热力学感兴趣
- 分子只有一个或两个可电离位点
- 速度至关重要（更快，积分消耗更少）
在以下情况下使用宏观 pKa：
- 你需要跨生理相关范围（例如 0–14）的 pH 依赖行为
- 你需要跨 pH 的聚合电荷和质子化状态群体
- 分子有多个可电离基团且存在耦合质子化
- 你需要下游性质，如不同 pH 下的水溶解度
决策示例：
苯酚 (pKa ~10)：使用微观 pKa
胺 (pKa ~9–10)：使用微观 pKa
多可电离药物 (N, O, 酸性基团)：使用宏观 pKa
跨胃肠道 pH 的 ADME 评估：使用宏观 pKa
构象搜索与互变异构体搜索
在以下情况下使用构象搜索：
- 已知单一互变异构体形式
- 你需要用于对接、MD 或 SAR 分析的多样化 3D 集合
- 可旋转键主导化学空间
在以下情况下使用互变异构体搜索：
- 互变异构平衡不确定（例如，杂环、酮-烯醇系统）
- 你需要建模所有相关的质子化异构体
- 下游计算（对接、pKa）依赖于互变异构体形式
组合工作流：
# 步骤 1：找到最佳互变异构体
taut_wf = rowan.submit_tautomer_search_workflow(
initial_molecule=rowan.Molecule.from_smiles("O=c1[nH]ccnc1"),
name="咪唑互变异构体",
)
best_taut = taut_wf.result().best_tautomer
# 步骤 2：从最佳互变异构体生成构象
conf_wf = rowan.submit_conformer_search_workflow(
initial_molecule=best_taut,
name="咪唑构象",
)
对接、类似物对接与共折叠
| 工作流 | 使用场景 | 输入 | 输出 |
|---|---|---|---|
| 对接 | 单一配体，已知结合口袋 | 蛋白质 + SMILES + 口袋坐标 | 姿态、分数、dG |
| 类似物对接 | 5–100+ 个相关化合物 | 蛋白质 + SMILES 列表 + 参考配体 | 所有姿态，参考对齐 |
| 蛋白质-配体共折叠 | 序列 + 配体，无晶体结构 | 蛋白质序列 + SMILES | ML 预测的结合复合物 |
蛋白质实用工具
上传蛋白质
# 从本地 PDB 文件
protein = rowan.upload_protein(
name="egfr_kinase_domain",
file_path="egfr_kinase.pdb",
)
# 从 PDB 数据库
protein_from_pdb = rowan.create_protein_from_pdb_id(
name="CDK2 (1M17)",
code="1M17",
)
# 检索之前上传的蛋白质
protein = rowan.retrieve_protein("protein-uuid")
# 列出所有蛋白质
my_proteins = rowan.list_proteins()
蛋白质制备指南
- 文件格式：PDB、mmCIF（Rowan 自动检测）
- 水分子：Rowan 通常会保留相关水分子；如果希望移除，请在上传前除去自由水
- 异原子：辅因子、离子和结合配体通常会被保留；在上传前移除不需要的异原子
- 多链蛋白质：完全支持
- 分辨率：适用于 NMR 结构、同源模型和冷冻电镜；质量影响下游预测
- 验证：Rowan 验证 PDB 语法；严重格式错误的文件可能被拒绝
工作流目录
九个常见工作流类别——描述符、微观 pKa、宏观 pKa、构象搜索、互变异构体搜索、对接、类似物对接、MSA 生成和蛋白质-配体共折叠——每个类别都有提交代码和结果形状，以及每个支持工作流类型的完整列表（核心建模、基于结构的设计、高级计算化学、反应化学、高级性质、结合自由能、序列与结构生物学）均位于 references/workflow_catalog.md。
批量提交、Webhooks 和异步工作
批量提交/轮询/检索、非阻塞式 fire-and-check 模式、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 → 渗透性（ADME 评估）互变异构体搜索 → 对接 → 姿态分析 MD（姿态优化）MSA 生成 → 蛋白质-配体共折叠（AI 结构预测）
- 对于长时间运行的项目（>50 个工作流）或异步管线，使用 webhooks
- 对于大型构象/对接搜索的交互式反馈，使用流式
总结
当你的工作流需要针对分子设计任务进行云执行时，尤其是当你希望在整个小分子建模、蛋白质、对接、ADME 预测和 ML 结构生成中拥有统一 API 和一致的结果处理时，请使用 Rowan。
Rowan 是一个分子设计工作流平台，而不仅仅是一个远程化学引擎。它处理基础设施扩展、结果持久化和多步管线编排，让你可以专注于科学。