生物大分子批量仿真开发教程（3）：MOE 的 SVL 与 moebatch——无界面跑起来，以及 AmberEHT 默认力场的坑
版本声明块
- 工具/软件：MOE 2024.06（Chemical Computing Group，简称 CCG；默认力场自本版起为 AmberEHT）
- 语言/环境：SVL（Scientific Vector Language）、tcsh / bash、Python 3.10 外层驱动
- 本文目标：把 MOE 从"必须有人坐在界面前的软件"变成"可被外层程序投递与回收的执行器"
一句话结论：MOE 的无界面执行只有两个入口——moebatch -script x.svl和moebatch -exec "…"，而moebatch的模型是"加载脚本 + 调用函数"，所以 SVL 文件里必须定义可调用函数（这是 moebatch 报"找不到函数"的头号原因）；数据 I/O 全部围绕数据库对象db_Open('name.mdb')/db_Close，面板级函数请以安装版内 Help 为准，工程上更稳的做法是外层用 Python 生成 SVL、投递moebatch、再回收.mdb结果——但自 MOE 2024.06 起默认力场已改成 AmberEHT，任何脚本都必须显式声明力场，否则新旧结果不可比（铁律 2）。
〇、本篇要解决的认知问题
- SVL 是什么语言？MOE 为什么不用 Python，而 CCG 要自研一门科学向量语言（Scientific Vector Language）？
moebatch -script x.svl与moebatch -exec "…"的语义差别是什么，各适合什么场景？- MOE 的数据库对象
db_Open/db_Close在批量流程里承担什么角色，和 Schrödinger 用.mae文件流有什么本质不同？ - 什么时候该老老实实写 SVL，什么时候该把 MOE 只当"执行器"、逻辑全交给 Python？
- MOE 2024.06 把默认力场改成 AmberEHT，对我已经写好（或打算抄来）的脚本有哪些具体影响？
一、机制解析
1.1 MOE 的扩展模型：一个内核、一门语言、一个数据库中枢
MOE（Molecular Operating Environment）官方把可编程性归在Customization能力族下：Integrated Programming Environment（SVL）、Custom Applications、Web Services / API、HTTP Listener for Remote Control，以及 Laptop–Cluster–Cloud 的部署梯度。也就是说，CCG 给的路是"用 SVL 写逻辑、用 moebatch 无界面执行、用 HTTP Listener 做远程控制"，Python 并不是 MOE 的一等 scripting 语言。
┌──────────────────────────────┐ 交互式（人） ──▶ │ moe（GUI） │ │ ├─ Amber / Alpha / Amber │ │ └─ AMBER 24 / CUDA 12 … │ └──────────────┬───────────────┘ │ 同一套 SVL 内核 ┌──────────────▼───────────────┐ 无界面（脚本）──▶ │ moebatch │ │ -script file.svl │ │ -exec "Func(args)" │ └──────────────┬───────────────┘ │ 读写 ┌──────────────▼───────────────┐ 数据中枢 │ *.mdb 数据库对象 │ │ db_Open(...) / db_Close │ └──────────────────────────────┘为什么这对你重要：理解"数据库是中枢"就不会再拿管理结构文件的习惯去管 MOE 批量任务。Schrödinger 那条路是"文件流 + 项目表"（第 02 篇），MOE 这条路是"一个.mdb装下记录、字段、坐标、计算结果"；因此批量并发的隔离单位应该是每作业一个.mdb，最后再汇总，而不是让多个moebatch抢同一库。
1.2moebatch的执行契约：加载脚本，然后调用函数
| 入口 | 语义 | 典型用法 |
|---|---|---|
moebatch -script x.svl | 加载并执行脚本中的顶层语句；要跑逻辑必须有可调用函数 | 长逻辑、多函数、需要调试的批处理 |
moebatch -exec "…" | 直接执行一条 SVL 语句/函数调用 | 一行式任务、外层程序动态拼接 |
社区协议里最常见的形态就是"tcsh 脚本调用moebatch，SVL 里定义函数，-exec或-script触发"。虚拟筛选协议页给出的读库写法形如db_Open['$vendor…']，收尾用db_Close——这两支函数是 MOE 批处理里少数被一手文献/社区协议明确写出的接口，因此本篇 SVL 部分只以此为准，其余面板级函数一律标注"以安装版内 Help 为准"。
反直觉之处：一个已经正确加载的 SVL 文件，如果里面没有以function/procedure定义的 callable，moebatch依然报"找不到函数"。很多人以为是路径问题，其实是模型理解错了：moebatch不打算顺序执行你的脚本。
为什么这对你重要：这一条决定你第一次跑moebatch是 5 分钟成功还是 5 小时怀疑人生。把"MOE 侧脚本 = 一组函数"当成接口契约来设计，你的批量层才可能有统一的调用形式。
1.3 写 SVL 还是用 Python 驱动 MOE
| 判据 | 选 SVL（在 MOE 内做） | 选 Python 驱动（把 MOE 当执行器） |
|---|---|---|
| 需要 MOE 独有能力 | Protein Patches / Patch 2D Maps、High-Throughput Antibody Modeling、Pro:Pro Dock、Loop/Linker 采样 | — |
| 需要复杂控制流（重试、分支、幂等、断点续跑） | SVL 写起来啰嗦且难以测试 | Python 优势明显 |
| 需要与外部生态拼接（pandas、MDAnalysis、ANARCI、Slurm） | 几乎不可能 | 天然合适 |
| 结果落地 | 必须进.mdb | .mdb→ 导出 CSV/Parquet → 中央结果表 |
| 团队可维护性 | 只有 MOE 专家能改 | 一般后端工程师也能接手 |
工程上的推荐形态是三层：Python 编排层（配置、幂等、重试、失败落库）→SVL 执行层（只做"这一条记录该做的 MOE 操作"，短、无状态）→.mdb数据层（一 job 一库）。这也是本系列第 16、20 篇要固化的骨架。
1.4 铁律 2 的 MOE 侧：AmberEHT 不是"多了个选项"，是数值基准变了
MOE 2024.06 的变更里，对脚本影响最大的四条：
| 变更 | 机制 | 对你脚本的后果 |
|---|---|---|
| 默认力场（force field）改为AmberEHT | 基于 MOE 2024 新 EHT 角度/二面角参数化 + Amber19 CMAP；官方明确 Amber10:EHT 的能量项与 2022.02 及更早可能不同 | 新旧版本的能量、最小化结果不可直接比较；跨版本对照实验会得出"看起来是方法改进、其实是力场换了"的结论 |
| 新增AmberEHTo | 采用 OpenFF 2.1 Sage 二面角 | 同一分子在 AmberEHT / AmberEHTo / AMBER10:EHT 下分数不同，脚本必须把力场名写进元数据 |
| 重训练 pKa 模型 | protomer（质子化异构体）枚举可能与 2022 不同 | 质化步骤的输出残基种类/电荷会变，下游对接与 MD 的拓扑准备随之变化（铁律 4） |
| OpenMOPAC 22.1.1 取代 MOPAC 7 | 半经验引擎换实现 | 老脚本里写死的 MOPAC 方法名/关键字可能失效 |
同期还有两个对批量很有价值的变更：Pro:Pro Dock——含注释的抗体-抗原复合物做 Protein-Protein Docking 时，会自动选抗体为配体、抗原为受体，并支持$CDR_H3自动注释；DBV Compute 菜单新增 Protein Patches 与 Protein Patch 2D Maps；保存格式新增 mmCIF/XYZ/MDB、支持多模型 PDB 写出与 5 字母残基名往返。
为什么这对你重要：$CDR_H3自动注释这条，等于 CCG 亲口告诉你"抗体编号与 CDR 注释是自动化的前置条件"。不先把编号体系固定好（下一篇），你在 MOE 侧就享受不到这批新能力。
二、完整代码与逐行剖析
2.1 SVL 批处理脚本骨架：读库 → 处理 → 回写
先明确本节的运行边界：下表之外的 SVL 函数名与参数请你在安装版 MOE 的 Help 中核实后再替换。
| 本骨架里的内容 | 依据 |
|---|---|
db_Open('….mdb')/db_Close | 社区协议一手写法（Rizzo Lab 虚拟筛选协议） |
必须定义 callable 供moebatch调用 | 社区协议明确的 moebatch 约束 |
function/database类型 /printf等语句级写法 | SVL 通用语法习惯，细节（含打开模式取值、判空写法）以安装版内 Help 为准 |
处理函数MoeStep()内部 | 占位，以 MOE 内 Help 为准 |
/* file: minim_job.svl —— MOE 侧只做一条记录的工作，控制流交给外层 Python */ /* 调用方式： moebatch -exec "RunJob(\"jobs/ab0001.mdb\")" 或 moebatch -script minim_job.svl（再用 -exec 触发 RunJob） */ function RunJob(string mdbpath) { database in, out /* 1) 打开输入库：db_Open 是社区协议里明确核实过的接口。 这里刻意"只读输入 + 另写输出"，绝不在原库上就地改写， 因为批量流水线要保证重跑幂等（铁律 5）。 */ in = db_Open(mdbpath, "r") if (in == null) { /* 打不开就显式退出并留下非零信号： 外层 Python 靠它把这条记录标成 failed，而不是静默跳过（铁律 10） */ printf("DBOPEN_FAIL %s\n", mdbpath) return } /* 2) 数据库遍历 + MOE 计算：读记录、跑最小化/质化、写回字段。 —— 以下每一步涉及的 SVL 面板函数名与参数，本教程不臆造， 请以安装版内 Help（菜单 Window > Help > MOE Help）为准逐行替换。 需要落实的三件事按顺序是： a. 质化 / 互变异构（对应 MOE 的质子化工具，Protonate 3D 语境，铁律 4） b. 力场显式指定：本版本默认已是 AmberEHT； 脚本必须写清用 AmberEHT 还是 AmberEHTo / AMBER10:EHT（铁律 2） c. 结果字段名固定：把能量、ΔG、补丁面积等写进同名数据库字段， 这样汇总阶段才能机械导出 */ MoeStep(in, out) /* 3) 关闭：不 db_Close 的话 .mdb 可能处于未落盘状态， 批量作业里表现为"日志说成功了、结果打不开" */ db_Close(out) db_Close(in) printf("DONE %s\n", mdbpath) } function MoeStep(database in, database out) { /* TODO(Help)：这里放且只放 MOE 侧操作，保持无状态、不读配置、不重试 */ }要点：MoeStep()单独切出来，是为了把"MOE 专有知识"隔离在一个函数里——升级版本时你只需要审计这一处，控制流（重试、跳过、汇总）永远不用改。这是商业软件二次开发里对抗版本漂移最有效的写法。
2.2 tcsh 包装：站点上最常见的一层
#!/bin/tcsh # run_batch.tcsh —— 遍历 job 目录下的 .mdb，逐个丢给 moebatch，退出码落 TSV set DBDIR = $1 # 由外层 Python 传入，避免在 tcsh 里做路径决策 set LEDGER = $2 # 结果账本：铁律 10 要求每条都有行，成功也要写 foreach f ( $DBDIR/*.mdb ) # 一 job 一库，天然避免并发写同一 .mdb set tag = `echo $f:t:r` # 取文件名主干作为记录标识，回填账本用 echo "==== $tag $f" # 便于人眼看日志定位 # -exec 传参注意引号层级：外层双引号给 shell，内层转义双引号给 SVL 字符串 moebatch -exec "RunJob(\"$f\")" >& "log/$tag.log" set rc = $status # tcsh 里退出码是 $status，不是 $? # 账本字段固定：tag、输入库、退出码、日志路径；重跑时按 tag 去重即可 printf "%s\t%s\t%s\t%s\n" "$tag" "$f" "$rc" "log/$tag.log" >> $LEDGER end| shell | 退出码 | 字符串引号 | 说明 |
|---|---|---|---|
| tcsh | $status | "…\"x\"…" | CCG 社区协议里最常见，站点脚本多为 tcsh |
| bash | $? | '…'更省心 | 外层用 bash/Python 时优先单引号包住整条-exec |
2.3 Python 编排层：把 MOE 变成可投递、可回收的执行器
#!/usr/bin/env python3"""moe_driver.py —— 外层只做三件事：幂等目录、投递 moebatch、失败落库（Python 3.10）"""importcsv,hashlib,os,subprocess,sysfrompathlibimportPath# 铁律 2：版本与力场写进代码而不是人脑。MOE 2024.06 起默认力场是 AmberEHT，# 显式声明 = 强制自己在 MoeStep() 里落实它，避免"继承默认值"这种隐式假设MOE_REQUIRED="2024.06"FORCE_FIELD="AmberEHT"defjob_dir(workdir:str,payload:dict)->Path:"""铁律 5：job 目录名 = 输入内容哈希，重跑天然只补缺"""blob=repr(sorted(payload.items())).encode("utf-8")p=Path(workdir)/hashlib.sha1(blob).hexdigest()[:12]p.mkdir(parents=True,exist_ok=True)returnpdefsvl_call(mdb:Path)->str:# 生成交给 moebatch 的一条 SVL 语句：路径里的反斜杠要转义，SVL 字符串按双引号解析return'RunJob("'+str(mdb).replace("\\","/")+'")'defmain(csv_in:str,work_root:str)->int:rows=list(csv.DictReader(open(csv_in,encoding="utf-8-sig")))Path(work_root).mkdir(parents=True,exist_ok=True)# 首轮运行时 work_root 还不存在ledger_path=Path(work_root)/"ledger.tsv"# 断点续跑：先把已成功的 tag 读出来，本轮直接跳过（幂等的另一半）done=set()ifledger_path.exists():withledger_path.open(encoding="utf-8")asold:done={r["tag"]forrincsv.DictReader(old,delimiter="\t")ifr.get("rc")=="0"}withledger_path.open("a",newline="",encoding="utf-8")asfh:w=csv.writer(fh,delimiter="\t")ifnotledger_path.stat().st_size:w.writerow(["tag","mdb","rc","log","force_field","moe_version"])fori,recinenumerate(rows,1):tag=rec.get("tag")orf"rec{i:05d}"iftagindone:print("skip",tag);continuepayload={"seq":rec.get("seq",""),"scheme":rec.get("numbering","")}jd=job_dir(os.path.join(work_root,"jobs"),payload)mdb=jd/f"{tag}.mdb"# 每 job 一个库：并发写隔离log=jd/f"{tag}.log"cmd=["moebatch","-exec",svl_call(mdb)]# 无界面入口，只有这两个形态try:cp=subprocess.run(cmd,capture_output=True,text=True,timeout=3600)rc=cp.returncode(jd/"stdout.txt").write_text(cp.stdout+cp.stderr,encoding="utf-8")exceptsubprocess.TimeoutExpired:rc=-1# 超时也要落一行，缺记录的批次不得出报告w.writerow([tag,mdb,rc,log,FORCE_FIELD,MOE_REQUIRED])fh.flush()# 边跑边刷盘：进程被 kill 也不丢已完成记录print(f"{tag}rc={rc}")bad=sum(1forrincsv.DictReader(open(ledger_path,encoding="utf-8"),delimiter="\t")ifr["rc"]!="0")print(f"total={len(rows)}nonzero_rc={bad}")return0ifbad==0else1# 让调度器据退出码决定是否重试整批if__name__=="__main__":sys.exit(main(sys.argv[1],sys.argv[2]))三个设计决策值得单独说：
| 决策 | 为什么 |
|---|---|
cmd用列表形式传给subprocess.run | 绕开 shell 引号嵌套，SVL 字符串里的双引号不会被 tcsh/bash 吃掉 |
账本里冗余记force_field与moe_version | 半年后回看，能立刻判断某批结果是不是 AmberEHT 之前的不可比数据 |
timeout+rc=-1 | MOE 侧偶发卡死（大库、缺参数），无超时的批量作业会把整个阵列挂住 |
三、常见报错与排查
moebatch报找不到要执行的函数
根因：SVL 文件里没有 callable（即使-script已成功加载），或-exec里的函数名与定义大小写不一致。解法：把逻辑写成function RunJob(...)，再用moebatch -exec "RunJob(\"a.mdb\")"；调试期先写一个只printf的空函数确认通道通了。-exec在 tcsh 下报语法错误 / 参数被截断
根因：引号层级冲突，外层 shell 把内层引号先吃掉。解法：外层双引号 + 内层转义双引号（见 2.2），或改用'…'/ 列表参数（见 2.3），或退一步用-script传文件路径、把参数写进脚本。- 打不开 / 写坏
.mdb
根因：多个moebatch并发写同一库，或收尾没db_Close。解法：一 job 一库 + 只读输入另写输出 + 汇总阶段再合并。 - 能量、最小化结果和上个月对不上
根因：MOE 2024.06 起默认力场改为 AmberEHT，其能量项与 2022.02 及更早可能不同。解法：脚本里显式声明力场并写入结果表（2.3 的force_field列），跨版本对照实验必须重跑基线，不能混用。 - 同一条序列质化结果与去年不一样
根因：2024.06 重训练了 pKa 模型，protomer 枚举可能与 2022 不同。解法：把质化参数与版本一起固定并入库（铁律 4）；发现差异时以结构合理性复核 His/Cys 状态与二硫键，而不是简单回滚版本。 - 老脚本里的 MOPAC 关键字失效
根因：OpenMOPAC 22.1.1 取代 MOPAC 7。解法：以安装版内 Help 为准更新方法名，并把该依赖在账本里标注版本区间。
四、动手练习
- 通道自检：写一个只打印字符串的
function Hello()，分别用moebatch -script与moebatch -exec "Hello()"触发。判定标准：两种方式终端都有你的打印，且echo $status（tcsh）/echo $?（bash）为 0；再删掉function定义重复一次，必须复现"找不到函数"。 - 幂等验证：用 2.3 对同一份 CSV 连跑两次。判定标准：第二次日志全为
skip，ledger.tsv中rc=0的行数不变，且 job 目录数等于去重后的tag数（不是 2 倍）。 - 力场审计：在你站点上打开任意抗体复合物，记录当前 MOE 版本号与工具面板里的默认力场名，并把它填进
ledger.tsv的force_field列。判定标准：任意两次运行的账本中moe_version与force_field组合完全一致；不一致则你的编排层必须报错而不是继续。
五、小结与下一篇预告
MOE 的批量路线是"SVL 写执行单元、moebatch提供无界面入口、.mdb承担数据中枢"，其中唯一必须刻进肌肉记忆的两条契约是：moebatch只会调用函数、db_Open/db_Close决定你的结果是否真的落盘；而工程上更稳的结构是Python 在外、SVL 在内、每 job 一库。同时请记住 MOE 2024.06 的 AmberEHT 默认力场与 pKa 模型重训练——不显式声明版本与力场的脚本，数值上没有可比性。抗体这条链上还有一件事必须先做完：$CDR_H3自动注释、PIPER 打分、CDR 移植人源化都建立在编号之上。下一篇我们打这块地基：VH/VL、CDR-H1/2/3、Fc 与 Asn297 糖基化，以及 Kabat、Chothia、IMGT、Martin、AHo 五套编号体系怎么用 ANARCI 批量统一。
本篇认知问题回显（FAQ）
Q1：MOE 的 SVL 是什么语言，为什么不用 Python？
A：SVL（Scientific Vector Language）是 Chemical Computing Group 自研的科学向量语言，官方归入 MOE 的 Customization 能力（Integrated Programming Environment / SVL IDE、Custom Applications、HTTP Listener for Remote Control）。它是 MOE 内核的脚本层，能直接访问分子、数据库与工具面板；Python 不是 MOE 的一等脚本语言，通常作为外层编排通过moebatch调用 SVL。
Q2：moebatch 的 -script 和 -exec 有什么区别？
A：moebatch -script x.svl加载并执行脚本，moebatch -exec "Func(args)"直接执行一条 SVL 语句。两者共同契约是"加载脚本 + 调用函数"：SVL 文件必须定义可调用函数，否则即使已加载也报"找不到函数"。长逻辑放-script，外层程序动态拼接的单步操作用-exec。
Q3：MOE 批处理里 db_Open 和 db_Close 是做什么的？
A：它们读写 MOE 数据库对象（.mdb），如db_Open('name.mdb')、收尾db_Close。MOE 的批量流程以数据库为中枢，记录、字段、坐标、计算结果都在.mdb内；不db_Close会出现"日志成功但结果打不开"。工程建议一 job 一库、只读输入另写输出、汇总时合并。
Q4：什么时候写 SVL，什么时候用 Python 驱动 MOE？
A：需要在 MOE 内部完成的操作（Protein Patches、High-Throughput Antibody Modeling、Pro:Pro Dock、Loop/Linker 采样）写 SVL；控制流（重试、幂等、断点续跑）、与 pandas/MDAnalysis/ANARCI/Slurm 拼接、结果导出全部交给 Python。推荐三层：Python 编排层 → SVL 执行层（短、无状态）→.mdb数据层。
Q5：MOE 2024.06 默认力场改成 AmberEHT 对抗体脚本有什么影响？
A：AmberEHT 基于 MOE 2024 新 EHT 角度/二面角参数化 + Amber19 CMAP，官方明确 Amber10:EHT 的能量项与 2022.02 及更早可能不同，故跨版本能量与最小化结果不可比；另有 AmberEHTo（OpenFF 2.1 Sage 二面角）可选，重训练 pKa 模型会使 protomer 枚举与 2022 不同，OpenMOPAC 22.1.1 取代 MOPAC 7。对策是脚本显式声明力场与版本并写入结果表。
