alterlab-rowan

Rowan：基于云的量子化学平台

概述

Rowan 是一个基于云的计算化学平台，可通过 Python API 以编程方式访问量子化学工作流。它能够自动执行复杂的分子模拟，无需本地计算资源，也不必精通多个量子化学软件包。

主要功能：

• 分子性质预测（pKa、氧化还原电位、溶解度、ADMET-Tox）
• 几何优化和构象搜索
• 使用 AutoDock Vina 进行蛋白质-配体对接
• 使用 Chai-1 和 Boltz 模型进行 AI 蛋白质协同折叠
• 使用 DFT、半经验和神经网络势方法
• 云端计算并自动分配资源

选择 Rowan 的理由：

• 无需本地计算集群
• 通过统一 API 使用数十种计算方法
• 可在 labs.rowansci.com 的 Web 界面中查看结果
• 自动扩展资源

何时使用此技能

在用户希望执行以下操作时使用此技能：

• 无需本地 QM 软件即可预测 pKa / 宏观 pKa、氧化还原电位、溶解度或其他性质
• 在云端使用 NNP（AIMNet2、Egret）、xTB 或 DFT 运行几何优化、构象搜索或单点计算
• 通过托管云端作业进行配体对接（Vina/GNINA）或蛋白质-配体复合物协同折叠（Boltz、Chai-1、OpenFold3）
• 从 Python（rowan-python）编写脚本并批量运行这些作业，并在文件夹中整理作业、设置额度上限

不适用的场景

场景	请改用
运行并分析本地 OpenMM MD 轨迹（RMSD/RMSF、接触）	alterlab-molecular-dynamics
使用 DiffDock 进行开源、本地扩散对接（无需云端账户）	alterlab-diffdock
在自己的 GPU 上本地运行 Boltz-2 或 Chai-1	alterlab-boltz 或 alterlab-chai
本地构象、描述符或 RDKit 力场最小化	alterlab-rdkit

安装与身份验证

安装

需要 Python >= 3.12。此技能面向 rowan-python 3.x（截至 2026-09 的当前版本为 3.2.0；v2 的结果 API 不同）。

uv pip install "rowan-python>=3.2"

安装 rowan-python 时也会安装 stjames（分子/结果模型）和 rdkit。

身份验证

在 labs.rowansci.com/account/api-keys 生成 API 密钥。

选项 1：直接赋值

import rowan
rowan.api_key = "your_api_key_here"

选项 2：环境变量（推荐）

export ROWAN_API_KEY="your_api_key_here"

模块导入时会自动从 ROWAN_API_KEY 读取 API 密钥。

验证设置

import rowan

# Check authentication
user = rowan.whoami()
print(f"Logged in as: {user.username}")
print(f"Credits available: {user.credits}")

结果模式（请先阅读）

每个 submit_*_workflow 都会返回一个 Workflow。不要手动读取 workflow.data[...]，也不要调用已弃用的 wait_for_result()。v3 的惯用写法只需一次调用：

mol = rowan.Molecule.from_smiles("c1ccccc1O")   # 3D structure for the default 3D method
workflow = rowan.submit_pka_workflow(mol, name="phenol pKa")
result = workflow.result()        # blocks until done, returns a typed WorkflowResult
print(result.strongest_acid)      # typed attribute access, not a dict key

要点：

• workflow.result(wait=True, poll_interval=5) 会阻塞等待、获取结果；如果工作流失败或已停止，则会抛出 rowan.WorkflowError。使用 wait=False 可在不阻塞的情况下获取当前已就绪的内容。
• workflow.status 是 stjames.Status 的整数枚举（QUEUED=0, RUNNING=1, COMPLETED_OK=2, FAILED=3, STOPPED=4, AWAITING_QUEUE=5, DRAFT=6, PREEMPTED=7），不是字符串。请使用 workflow.done() / workflow.is_finished()，不要与 "completed" 进行比较。
• 基于几何结构的工作流现在不接受不带坐标的 SMILES 字符串。 从 rowan-python 3.x 起，submit_basic_calculation_workflow、submit_docking_workflow 以及任何 3D pKa/构象方法调用都会执行 require_coordinates；如果 SMILES 没有坐标，就会引发 ValueError。请先构建 3D 分子：mol = rowan.Molecule.from_smiles("CCO")（或 stjames.Molecule.from_smiles(...)，它会自动生成坐标），然后传入 mol。基于 SMILES 的方法仍接受 SMILES 字符串（submit_macropka_workflow，以及 method="starling"/"chemprop_nevolianis2025" 时的 pKa）。Molecule.from_smiles(smiles) 只接受 SMILES（不接受 charge=/multiplicity= 关键字参数）。

核心工作流

1. pKa 预测

预测微观 pKa／酸解离常数：

import rowan

# The default pKa method is now a 3D method, so build a molecule (bare SMILES is rejected).
workflow = rowan.submit_pka_workflow(
    rowan.Molecule.from_smiles("c1ccccc1O"),   # Phenol
    name="phenol pKa calculation",
    pka_range=(2, 12),                  # default
    method="gxtb_wagen2026",            # default (g-xTB); "aimnet2_wagen2024" also 3D.
                                        # "starling" / "chemprop_nevolianis2025" take a SMILES string.
)

result = workflow.result()
print(f"Strongest acid pKa: {result.strongest_acid}")
print(f"Strongest base pKa: {result.strongest_base}")

如需计算宏观 pKa、微观状态随 pH 变化的分布、等电点，以及 logD／溶解度随 pH 的变化，请使用 rowan.submit_macropka_workflow(...)，并读取 result.pka_values、result.microstates 和 result.isoelectric_point。

2. 构象搜索

生成并排序构象集合：

import rowan

workflow = rowan.submit_conformer_search_workflow(
    "CCCC",  # Butane
    name="butane conformer search",
    final_method="aimnet2_wb97md3",     # NNP; default
)

result = workflow.result()
print(f"Found {result.num_conformers} conformers")
for energy in result.get_energies():   # relative energies, kcal/mol
    print(f"  ΔE = {energy:.2f} kcal/mol")
lowest = result.get_conformer(0)       # stjames.Molecule of the lowest-energy conformer

3. 几何优化

submit_basic_calculation_workflow 由任务驱动：传入 tasks（例如 ["optimize"]、["energy"]、["optimize", "frequencies"]），而不是 workflow_type 字符串。

import rowan

workflow = rowan.submit_basic_calculation_workflow(
    rowan.Molecule.from_smiles("CC(=O)O"),  # Acetic acid (needs 3D coords; SMILES is rejected)
    tasks=["optimize"],
    preset="organic_nnp",     # quick NNP preset; or set method=/basis_set= explicitly
    name="acetic acid optimization",
)

result = workflow.result()
print(f"Final energy: {result.energy} Hartree")
optimized_mol = result.molecule   # stjames.Molecule with optimized coordinates

4. 蛋白质-配体对接

将小分子对接到蛋白质靶点。口袋的格式为以埃为单位的 [[center_x, center_y, center_z], [size_x, size_y, size_z]] —— 一个包含两个 3 维向量的列表，而不是字典。

import rowan

# Create protein from a PDB ID (fetched from RCSB)
protein = rowan.create_protein_from_pdb_id(name="EGFR kinase", code="1M17")
protein.sanitize()   # strip waters/ions, fix residues

pocket = [[10.0, 20.0, 30.0],    # center (Å)
          [20.0, 20.0, 20.0]]    # box size (Å)

workflow = rowan.submit_docking_workflow(
    protein=protein,             # Protein object or its .uuid
    pocket=pocket,
    # 3D input required — a bare SMILES string raises ValueError
    initial_molecule=rowan.Molecule.from_smiles("Cc1ccc(NC(=O)c2ccc(CN3CCN(C)CC3)cc2)cc1"),
    # engine options go in docking_settings; the loose scoring_function=/exhaustiveness=
    # kwargs are deprecated (rowan.GninaSettings selects GNINA instead of Vina)
    docking_settings=rowan.VinaSettings(scoring_function="vinardo"),  # or "vina"
    name="EGFR docking",
)

result = workflow.result()
best = result.scores[0]          # DockingScore, sorted best-first
print(f"Best docking score: {best.score} kcal/mol")
best_pose = result.best_pose     # stjames.Molecule of the top pose

5. 蛋白质协同折叠（AI 结构预测）

使用 AI 模型预测蛋白质-配体复合物结构：

import rowan

protein_seq = "MENFQKVEKIGEGTYGVVYKARNKLTGEVVALKKIRLDTETEGVPSTAIREISLLKELNHPNIVKLLDVIHTENKLYLVFEFLHQDLKKFMDASALTGIPLPLIKSYLFQLLQGLAFCHSHRVLHRDLKPQNLLINTEGAIKLADFGLARAFGVPVRTYTHEVVTLWYRAPEILLGCKYYSTAVDIWSLGCIFAEMVTRRALFPGDSEIDQLFRIFRTLGTPDEVVWPGVTSMPDYKPSFPKWARQDFSKVVPPLDEDGRSLLSQMLHYDPNKRISAKAALAHPFFQDVTKPVPHLRL"
ligand = "CCC(C)CN=C1NCC2(CCCOC2)CN1"

workflow = rowan.submit_protein_cofolding_workflow(
    initial_protein_sequences=[protein_seq],
    initial_smiles_list=[ligand],
    name="kinase-ligand cofolding",
    model="chai_1r",   # default is "boltz_2"; see note below for the full list
)

result = workflow.result()
top = result.predictions[0]            # first CofoldingResult sample
print(f"pTM: {top.scores.ptm}")        # predicted TM score (0-1)
print(f"interface pTM: {top.scores.iptm}")

注意：在 rowan-python 3.2 中，协同折叠模型字符串为 chai_1r、boltz_1、boltz_2（默认值）、boltz_2_1、openfold_3 和 decaf_boltz（不存在 boltz_1x）。置信度位于 result.scores／每个预测的 .scores 中，属性为 .ptm 和 .iptm。

工作流管理

列出和查询工作流

# List recent workflows (page is 0-indexed; default size=10)
workflows = rowan.list_workflows(size=10)
for wf in workflows:
    print(f"{wf.name}: {wf.status.name}")   # status is an int enum

# Filter by type / name substring / folder
pka_runs = rowan.list_workflows(workflow_type="pka", name_contains="phenol")
folder_runs = rowan.list_workflows(parent_uuid=folder.uuid)

# Retrieve specific workflow
workflow = rowan.retrieve_workflow("workflow-uuid")

批量操作

# Submit many workflows of one type at once. This is a thin loop over the generic
# submit_workflow: it skips the per-type input checks the submit_*_workflow helpers do,
# so pass workflow_data= for non-default settings.
workflows = rowan.batch_submit_workflow(
    workflow_type="pka",
    initial_smileses=["CCO", "CC(=O)O", "c1ccccc1O"],
)

# Non-blocking status poll: returns {uuid: status_int} (stjames.Status values)
statuses = rowan.batch_poll_status([wf.uuid for wf in workflows])

文件夹整理

# Create folder for project
folder = rowan.create_folder(name="Drug Discovery Project")

# Submit workflow to folder
workflow = rowan.submit_pka_workflow(
    rowan.Molecule.from_smiles("CCO"),
    name="compound pKa",
    folder=folder,          # or folder_uuid=folder.uuid (not both)
)

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

计算方法

Rowan 支持多个理论层级：

神经网络势：

• AIMNet2 (ωB97M-D3) - 快速且准确
• Egret - Rowan 的专有模型

半经验方法：

• GFN1-xTB、GFN2-xTB - 适用于大型分子，速度快

DFT：

• B3LYP、PBE、ωB97X 变体
• 提供多种基组

系统会根据工作流类型自动选择方法，也可在工作流参数中显式指定。

参考文档

如需详细的 API 文档，请参阅以下参考文件：

• references/api_reference.md：Workflow 类、提交函数、检索方法和结果模式
• references/workflow_types.md：完整的工作流类型及其参数——pKa、对接、协同折叠等
• references/molecule_handling.md：stjames.Molecule 类——从 SMILES、XYZ、RDKit 创建分子
• references/proteins_and_organization.md：蛋白质上传、文件夹管理、项目整理
• references/results_interpretation.md：理解工作流输出、置信度分数和验证

常见模式

模式 1：性质预测流程

先提交所有任务，再收集结果——提交操作不会阻塞，result() 会阻塞等待。

import rowan

smiles_list = ["CCO", "c1ccccc1O", "CC(=O)O"]

# Submit all pKa calculations (default 3D method -> build molecules from the SMILES)
workflows = [
    rowan.submit_pka_workflow(rowan.Molecule.from_smiles(smi), name=f"pKa: {smi}")
    for smi in smiles_list
]

# Collect results
for wf in workflows:
    result = wf.result()
    print(f"{wf.name}: pKa = {result.strongest_acid}")

模式 2：虚拟筛选

针对一个靶点筛选分子库时，优先使用专用的批量对接工作流，而不是使用 Python 循环。

import rowan

protein = rowan.upload_protein(name="Drug Target", file_path="target.pdb")
protein.sanitize()

pocket = [[x, y, z], [20.0, 20.0, 20.0]]   # center, size (Å)

workflow = rowan.submit_batch_docking_workflow(
    smiles_list=compound_library,
    protein=protein,
    pocket=pocket,
    name="library screen",
)
result = workflow.result()

模式 3：基于构象的分析

import rowan

conf_wf = rowan.submit_conformer_search_workflow(
    "C1CCCCC1",  # any SMILES
    name="conformer search",
)
result = conf_wf.result()

energies = result.get_energies()   # relative energies, kcal/mol, ascending
print(f"Found {result.num_conformers} conformers")
print(f"Energy range: {energies[0]:.2f} to {energies[-1]:.2f} kcal/mol")

最佳实践

1. 通过环境变量设置 API 密钥，更安全、更方便
2. 使用文件夹整理相关工作流
3. 使用 workflow.result()——它会等待、获取结果，并在一次调用中处理失败情况
4. 对大量相似任务使用批量函数（batch_submit_workflow、submit_batch_docking_workflow）
5. 通过任意提交函数中的 max_credits= 限制开销，并检查 rowan.whoami().credits

错误处理

如果工作流失败或已停止，workflow.result() 会引发 rowan.WorkflowError，因此请使用以下方式进行处理：

import rowan

workflow = rowan.submit_pka_workflow(
    rowan.Molecule.from_smiles("c1ccccc1O"), name="calculation", max_credits=10
)   # input problems (e.g. a bare SMILES for a 3D method) raise ValueError at submit time

try:
    result = workflow.result()       # blocks until done; raises on failure
    print(result.strongest_acid)
except rowan.WorkflowError as e:
    # workflow failed/stopped — inspect workflow.logfile for details
    print(f"Workflow failed: {e}")
    print(workflow.logfile)

workflow.status 是 int 枚举 stjames.Status；可使用 workflow.done() 进行非阻塞的完成状态检查。

更多资源

• 网页界面：https://labs.rowansci.com
• 文档：https://docs.rowansci.com
• 教程：https://docs.rowansci.com/tutorials

属于 AlterLab Academic Skills 套件。