Gmx Workflow Packer
Overview
把一次性的 GROMACS 常规 MD、tREMD 或 REST2 操作整理成可复用、可交付的目录和脚本。 默认目标不是只解释参数,而是留下一个能在本地准备、上传目标机器并适配提交的运行包;如果当前模块不支持某种增强采样,必须生成阻断式说明,不能给出会失败的提交脚本。
入口判断
先把请求归到下面五类入口之一:
- 常规 GROMACS MD
- 适用于标准 EM -> position-restrained/NVT -> NPT -> production MD。
- 可从已有
topol.top和能量最小化坐标开始,也可从蛋白 PDB 生成准备脚本。 - 使用
assets/md-config-template.yaml和scripts/build_md_bundle.py。
- 已有 GROMACS 体系直接打包为 tREMD
- 适用于用户已经有
topol.top、1EM.gro或等价起始坐标。 - 直接生成
step1/step2/analysis/run.sh/state.yaml。 - 这是最稳的主路径。
- 标准蛋白本地准备后打包为 tREMD
- 适用于用户只有蛋白
PDB。 - 生成本地准备脚本,执行
pdb2gmx -> editconf -> solvate -> genion -> EM。 - 再生成标准 tREMD 运行目录。
- 蛋白配体本地准备后打包
- 适用于蛋白配体复合物做标准 tREMD。
- 支持两种配体入口:
- 独立
ligand.mol2或ligand.sdf - 从
complex.pdb中拆出配体 - 配体默认用
ACPYPE/GAFF,但不自动安装依赖。
- REST2/HREX 打包
- 适用于用户已有
1EM.gro或等价起始坐标、topol.top,希望只升温溶质或 hot region。 - 默认使用 PLUMED 官方
partial_tempering生成每个 replica 的缩放拓扑。 - REST2 v2 默认按能力检查结果决定是否生成生产脚本。
- 如果
mdrun -h能看到-plumed但没有-hrex,只生成拓扑准备与预检包,生产run.sh必须阻断并解释“缺少-hrex,不能直接做 PLUMED 多拓扑 REST2 交换”。 - 只有在用户明确提供带
-hrex的 GROMACS/PLUMED 模块,并把rest2.hrex_available=true时,才生成真正的 REST2-HREX 生产脚本。 - REST2 细节读取 references/rest2-workflow.md。
- 如果用户要求非 PLUMED 的手工拓扑缩放、CHARMM CMAP、或复杂自定义 Hamiltonian,先说明需要人工审查,不要盲目自动化。
默认工作流
默认按下面顺序推进:
- 先检查环境
- 运行
scripts/check_env.py。 - 如果缺少
gmx、gmx_mpi、perl,先停止。 - 如果是蛋白配体路径,再额外检查
acpype、antechamber、obabel。 - 如果是 REST2 路径,运行
scripts/check_env.py --mode rest2 --check-hrex,并在目标模块中确认gmx_mpi mdrun -h是否同时支持-hrex和-plumed。 - 如果检查结果缺少
-hrex,必须阻断 REST2 生产提交,只允许生成准备和预检包。
- 读取或生成 YAML 配置
- 常规 MD 默认使用
assets/md-config-template.yaml作为起点。 - tREMD/REST2 默认使用
assets/config-template.yaml作为起点。 sampling.mode=md使用scripts/build_md_bundle.py。sampling.mode=tremd使用scripts/build_remd_bundle.py。sampling.mode=rest2使用scripts/build_rest2_bundle.py。
- 确定温度梯度
- tREMD:如果配置里已经给出
temperature_ladder.temperatures,直接使用;否则运行scripts/optimize_remd_ladder.py估算。 - REST2:使用
rest2.effective_temperatures;如果为空,用rest2.tmin/tmax/n_replicas生成几何 effective-temperature 梯度,缩放因子为scale_i = T0 / T_i。 - 所有梯度都只是经验初值。默认提醒用户先短跑检查交换率,再决定是否加密或拉宽梯度。
- 生成运行包
- 常规 MD 运行
scripts/build_md_bundle.py。 - tREMD 运行
scripts/build_remd_bundle.py。 - REST2 运行
scripts/build_rest2_bundle.py。 - 常规 MD 输出目录保留
mdp/run/analysis/prep/system/state.yaml/UPLOAD_AND_RUN.md语义。 - tREMD 输出目录固定保留
step1/step2/analysis语义。 - REST2 输出目录使用
prep/rest2/analysis/run.sh/state.yaml,其中rest2/replica_00等目录直接对应 REST2 replica。 rest2.hrex_available=false时,run.sh是阻断脚本,不能提交生产;rest2.hrex_available=true时,run.sh才是生产脚本。- 副本目录统一使用
replica_00风格,不再沿用旧的equ_0或MD_0命名。
- 生成后处理包
- 运行
scripts/render_postprocess_bundle.py,或让build_remd_bundle.py自动调用它。 - 输出
demux.pl、demux.sh、交换效率分析脚本、按温度轨迹分析骨架。
集群配置原则
step1和step2可以使用 GPU 队列,正式多副本run.sh常用 CPU 或 MPI 队列,具体以目标集群为准。- GPU/CPU partition、QOS、module、account、wall-time、MPI launcher 和最大任务数必须由用户或集群文档确认。
cluster.cpu.max_total_tasks必须大于等于 replica 数;否则停止并要求用户减少 replica 数或提供更高资源限制。- GROMACS 可执行入口通常是
gmx或gmx_mpi,不要把某个集群路径写成公开默认。
关键约束
始终遵循这些约束:
run.sh使用单脚本分段续跑。- 续跑必须依赖
-cpi -append和state.yaml。 - 默认不要在任何提交脚本里写
#SBATCH --time。 - 默认不要在生产
run.sh中使用-maxh。 - 不要复用旧版
step2.sh的逗号字符串温度循环。 - 副本目录必须零填充,避免
replica_1 replica_10 replica_2这种字典序问题。 - 正式 CPU 多副本任务默认
--ntasks-per-node等于副本数;如果超过cluster.cpu.max_total_tasks,必须停下来让用户调整配置。 - REST2 的 effective temperature 不是 thermostat 真实温度;REST2 各 replica 的
md.mdp默认使用同一个参考温度,采样增强来自缩放 Hamiltonian。 - REST2 拓扑必须从
grompp -pp生成的 processed topology 开始标记 hot atoms,不要直接改带#include的原始topol.top。 - PLUMED
partial_tempering多拓扑 REST2 生产脚本必须包含-hrex -plumed plumed.dat -dlb no,并要求nstlist能整除replex。 - 如果
mdrun -h只有-plumed没有-hrex,不要用-replex伪装 REST2;这只会变成错误的普通多模拟或在运行时报错。 - GROMACS 官方原生 HREX 是 free-energy lambda 路线,不等价于 PLUMED
partial_tempering多拓扑 REST2;除非用户专门要求并提供 lambda 拓扑设计,不要自动切换。
主要资源
优先使用这些资源,不要现场重写:
- 环境检查:
scripts/check_env.py- 温度梯度估算:
scripts/optimize_remd_ladder.py- 运行包生成:
scripts/build_md_bundle.pyscripts/build_remd_bundle.py- REST2 运行包生成:
scripts/build_rest2_bundle.py- 后处理生成:
scripts/render_postprocess_bundle.py- 标准 tREMD 工作流:
references/core-workflow.md- REST2 教程:
references/rest2-workflow.md- HREMD/复杂 REST2 注意事项:
references/future-rest2.md- 默认配置模板:
assets/md-config-template.yamlassets/config-template.yaml- 默认
mdp模板: assets/templates/- demux 资源:
assets/demux.pl
输出要求
把目录视为“已完成可交付”之前,至少要满足:
- 有完整 YAML 配置副本。
- 常规 MD 包有
mdp/run/analysis/system/run.sh/state.yaml/UPLOAD_AND_RUN.md。 - tREMD 包有
step1/step2/analysis/run.sh/state.yaml/UPLOAD_AND_RUN.md。 - REST2 包有
prep/rest2/run.sh/state.yaml/UPLOAD_AND_RUN.md;只有rest2.hrex_available=true时才要求analysis/后处理脚本。 - 有温度表 YAML 和 CSV。
- 有中文说明,写清首跑、续跑、demux 和效率分析命令。
- REST2 包还必须有 effective-temperature/scale 表、
prep/prepare_rest2_topologies.sh、prep/mark_rest2_hot_atoms.py,以及每个 replica 的plumed.dat。 - 如果只是 dry-run,要明确说明哪些输入文件还未准备好。


