rowan

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

概述

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

当你希望以编程方式运行药物化学或分子设计工作流，而无需维护本地 HPC 基础设施、GPU 配置或一堆彼此分离的建模工具时，可以使用 Rowan。该服务负责托管计算和结果；可用的工作流取决于账户。

何时使用 Rowan

Rowan 适合以下场景：

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

Rowan 不适合以下场景：

• 简单的分子 I/O（直接使用 RDKit）
• 所选引擎文档支持范围之外的方法或元素/电荷范围

快速开始

uv pip install "rowan-python==3.2.0"

import rowan
# Reads ROWAN_API_KEY from the environment.

# 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"])       # exact/monoisotopic mass
print(result.descriptors["SLogP"])
print(result.descriptors["TopoPSA"])  # topological PSA

这会提交一次托管计算并消耗额度。示例针对 rowan-python 3.2.0，于 2026-09-30 对照已发布的 SDK 和官方参考进行了审查。 本地 schema/序列化冒烟测试使用了 stjames 0.0.279。托管示例仅作说明用途：本次更新未运行任何需要身份验证的工作流。请锁定两个包的版本，以获得可复现的任务。

安装

uv pip install "rowan-python==3.2.0"
# Lock dependencies in your own environment; do not install the unrelated "rowan" package.

身份验证和账户访问

身份验证

通过环境变量设置 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()}")
print(user.enabled_workflows)  # Account-specific backend workflow slugs

分子输入格式

基于拓扑的方法使用 SMILES，基于几何的方法使用真实的 3D 结构。SMARTS 是一种子结构查询语言，不是通用的工作流分子输入；请先用化学工具包转换 InChI，再传入受支持的输入。记录立体化学、电荷、质子化状态和原始标识符。仅靠规范化无法解决这些科学选择。

SMILES 字符串与分子对象

• pKa：starling 和 chemprop_nevolianis2025 需要 SMILES 字符串； gxtb_wagen2026（默认）和 aimnet2_wagen2024 需要坐标。
• 构象搜索：SMILES 可用于 OpenConf（默认）或 ETKDG；CREST/MCMM 需要 3D 分子。
• 膜渗透性：gnn-mtl 需要 SMILES；pypermm 需要 3D 分子。
• ADMET、LogP、macropKa 和溶解度基于 SMILES；构象分析 MD 需要 配体 SMILES 以及包含其结合构象的蛋白质复合物。
• 描述符、互变异构体、对接、类似物对接、BDE、NMR 和 Fukui 需要 rowan.Molecule、stjames.Molecule 或带构象的 RDKit 分子。 仅使用 Chem.MolFromSmiles() 没有坐标。请使用 rowan.Molecule.from_smiles() 显式生成坐标，或导入现有几何结构。对于类似物 对接，请在受体的坐标系中保留参考构象。

提示： 提交前使用 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 — named functions build and validate workflow-specific payloads
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"]) # 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()	进程可以阻塞等待完成
stream_result()	任务运行期间轮询快照有用

stream_result() 采用轮询；它不是服务器推送的事件流。部分类型化 属性可能不可用，因此请检查 .data 直到 .complete 为 true。 result(wait=False) 可能返回部分数据，或在尚无数据时抛出 WorkflowError。done() 包含失败和停止的运行，而不仅是成功的运行。

处理结果

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

项目、文件夹与组织

对于较为复杂的任务，使用项目和文件夹来保持工作有序。

项目

Rowan 3.2.0 有一个未解决的 Folder.created_at 类型注解问题；在进行文件夹操作之前，先按如下方式初始化模型（参见故障排除）。

import rowan
from datetime import datetime
rowan.Folder.model_rebuild(_types_namespace={"datetime": datetime})

# Create a project
project = rowan.create_project(name="CDK2 lead optimization")
rowan.project_uuid = project.uuid
folder = rowan.create_folder(name="descriptors", parent_uuid=project.root_folder_uuid)

# Pass the destination folder explicitly on submissions
wf = rowan.submit_descriptors_workflow(
    rowan.Molecule.from_smiles("CCO"), name="test compound", folder=folder
)

# parent_uuid is a folder UUID, not a project UUID.
project = rowan.retrieve_project(project.uuid)
workflows = rowan.list_workflows(parent_uuid=project.root_folder_uuid, page=0, size=50)
# This lists only workflows directly in the root folder. List folder.uuid for the above job.

文件夹

示例说明：protein、pocket 和 3D ligand 必须先准备好。 请先运行上面的 Folder.model_rebuild 初始化。get_folder() 会创建 缺失的路径段；create_folder() 创建一个文件夹。

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

wf = rowan.submit_docking_workflow(
    protein=protein, pocket=pocket, initial_molecule=ligand,
    folder=folder,
    name="compound_001",
)

# List workflows in a folder
results = rowan.list_workflows(parent_uuid=folder.uuid, page=0, size=50)

列表辅助函数只返回一页。递增从零开始的 page，直到出现空 页；size 是页大小，并不承诺返回所有匹配项。文件夹列表 不是递归的：清点任务时请单独遍历子文件夹。

工作流决策树

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

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

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

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

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

• 互变异构平衡不确定（例如杂环、酮–烯醇体系）
• 你需要同分子式的质子转移异构体；另行枚举电荷/质子化状态
• 下游计算（对接、pKa）取决于互变异构形式

组合工作流：

# Step 1: Find best tautomer
taut_wf = rowan.submit_tautomer_search_workflow(
    initial_molecule=rowan.Molecule.from_smiles("O=c1cccc[nH]1"),
    name="2-pyridone tautomers",
)
best_taut = taut_wf.result().best_tautomer  # Molecule or None, not SMILES
if best_taut is None:
    raise RuntimeError("No weighted tautomer structure was returned")

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

对接与类似物对接与共折叠

工作流	适用场景	输入	输出
对接	单一配体、已知口袋	蛋白质 + 3D 配体 + 口袋坐标	姿态和评分记录
类似物对接	共享骨架的相关化合物	蛋白质 + SMILES 列表 + 结合参考姿态	按 SMILES 索引的姿态和评分
蛋白质-配体共折叠	序列 + 配体，无晶体结构	蛋白质序列 + SMILES	ML 预测的结合复合物

蛋白质工具

上传蛋白质

以下示例性 API 调用需要已认证的账户以及所指定的本地文件；在本次文档修正中，它们未针对该服务重新运行。在构建对接项目之前，请核实每个 PDB 登录号与其靶标是否一致：1M17 是结合 erlotinib 的 EGFR。

# 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="EGFR (1M17)",
    code="1M17",
)

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

# List the first page of proteins
my_proteins = rowan.list_proteins(page=0, size=20)

蛋白质准备指南

• 文件格式：upload_protein 对 .cif/.mmcif 选择 mmCIF，否则选择 PDB。
• 准备：上传/导入仅存储结构；它并不建立对接就绪状态。 针对所选工作流，检查链选择、可变位置、缺失原子/残基、质子化、 水、金属、辅因子以及保留的配体。
• 多链结构：在适当时显式选择预期的链。
• 准备工作流：submit_protein_preparation_workflow 暴露 pH、缺失原子 补全和非聚合物保留；在使用其默认值之前检查这些设置。
• 口袋：从准备好的受体或其结合配体导出坐标。任意的 示例坐标不能在不同结构之间通用。通过重新对接已知配体 并检查几何构型来验证对接；分数并非实测结合自由能。

工作流目录

九个常见工作流类别——描述符、微观 pKa、MacropKa、构象 搜索、互变异构体搜索、对接、类似物对接、MSA 生成和蛋白质-配体 共折叠——每个都附有提交代码和结果形态，另有一个 工作流函数目录（核心建模、基于结构的设计、高级计算 化学、反应化学、高级性质、结合自由能，以及序列与 结构生物学），详见 references/workflow_catalog.md。

批量提交、webhook 和异步工作

批量提交/轮询/获取、非阻塞的触发并检查模式、webhook 设置、 密钥创建与轮换、签名验证（含一个 FastAPI 处理器），以及已发布 payload 合约的限制，详见 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 结构预测）
• 使用 webhook处理长时间运行的项目（>50 个工作流）或异步流水线
• 使用流式传输以对大型构象/对接搜索获得交互式反馈

概述

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

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