Rowan：雲端原生分子建模與藥物設計工作流程
概觀
Rowan 是一個雲端原生工作流程平台，用於分子模擬、藥物化學和結構設計。其 Python API 提供了一個統一的介面，用於小分子建模、性質預測、對接、分子動力學和 AI 結構工作流程。
當你想要以程式化方式執行藥物化學或分子設計工作流程，而無需維護本地 HPC 基礎架構、GPU 配置或一系列獨立的建模工具時，請使用 Rowan。Rowan 會處理所有基礎架構、結果管理和計算規模調整。
何時使用 Rowan
Rowan 適用於：
- 量子化學、半經驗方法或神經網路勢能
- 批量性質預測（pKa、描述符、滲透性、溶解度）
- 構象異構體和互變異構體集合生成
- 對接工作流程（單一配體、類似物系列、姿態最佳化）
- 蛋白質-配體共折疊和 MSA 生成
- 多步化學工作管線（例如，互變異構體搜尋 → 對接 → 姿態分析）
- 需要一致、可擴展基礎架構的批量藥物化學活動
Rowan 不適用於：
- 簡單的分子 I/O（直接使用 RDKit）
- 後-HF 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: {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 任務遵循相同的三步驟模式：
- 提交 工作流程
- 等待 完成（可選串流）
- 擷取 帶有便捷屬性的類型化結果
import rowan
# 1. 提交 — 使用特定的工作流程函數（而非通用的 submit_workflow）
workflow = rowan.submit_descriptors_workflow(
rowan.Molecule.from_smiles("CC(=O)Oc1ccccc1C(=O)O"),
name="aspirin descriptors",
)
# 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"Complete: {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="ethanol",
).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 lead optimization")
rowan.set_project("CDK2 lead optimization")
# 後續的所有工作流程都歸入此專案
wf = rowan.submit_descriptors_workflow(
rowan.Molecule.from_smiles("CCO"), name="test compound"
)
# 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
跨 GI 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="imidazole tautomers",
)
best_taut = taut_wf.result().best_tautomer
# 步驟 2：從最佳互變異構體生成構象
conf_wf = rowan.submit_conformer_search_workflow(
initial_molecule=best_taut,
name="imidazole conformers",
)
對接 vs. 類似物對接 vs. 共折疊
| 工作流程 | 使用時機 | 輸入 | 輸出 |
|---|---|---|---|
| 對接 | 單一配體，已知結合口袋 | 蛋白質 + 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。
批量提交、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 是一個分子設計工作流程平台，而不只是一個遠端化學引擎。它處理基礎架構擴展、結果持久化和多步工作管線編排，讓你可以專注於科學研究。