workflow-engine-mapper

工作流引擎映射器

目标

为材料模拟任务选择最精简的工作流结构，同时保留可复现性、可重启性和溯源能力。

要求

• Python 3.10+
• 无外部依赖
• 支持 Linux、macOS 和 Windows

需要收集的输入

输入	说明	示例
任务	工作流用途	VASP relax-static-DOS for 200 structures
代码	主要模拟引擎	vasp、qe、lammps、ase
运行数	预计计算次数	200
溯源	是否需要审计追踪	true
重启	作业失败后是否可能恢复运行	true
HPC	是否需要远程调度器	true

决策指南

• 对少于 5 次的本地探索性运行（无溯源、无 HPC），使用一次性脚本。
• 当工作流以 Python 为原生环境，且需要 Materials Project 风格的输入集时，使用 jobflow/atomate2。
• 当溯源至关重要，且任务需要远程运行（HPC）或规模较大（>= 50 次运行）时，使用 AiiDA——也就是说，适用于长期运行、由数据库支持的计算项目。对于规模较小的本地溯源需求，atomate2（Materials Project 代码，>= 10 次运行）或 jobflow 存储库已能记录输入、输出、代码版本和环境，因此映射器会推荐它们，而非更重量级的 AiiDA 技术栈。
• 当交互式原子工作流、笔记本和作业管理是用户的主要操作界面时，使用 pyiron（ASE/LAMMPS，无严格溯源要求）。

推荐结果按固定优先级生成，以确保说明文字与实际实现的阈值一致：显式指定 --preferred 引擎会覆盖其他所有规则；否则依次为一次性脚本（小规模本地运行，无溯源/HPC）-> AiiDA（需要溯源，且需要远程运行或规模较大）-> atomate2（VASP/QE/CP2K/力场，>= 10 次运行）-> pyiron（ASE/LAMMPS，无溯源要求）-> jobflow（兜底）。

脚本输出

scripts/workflow_engine_mapper.py 会输出：

• recommended_engine
• dag_pattern
• provenance_requirements
• restart_strategy
• storage_layout
• migration_triggers
• notes

工作流

python3 skills/simulation-workflow/workflow-engine-mapper/scripts/workflow_engine_mapper.py \
  --task "relax static dos for 200 oxides" \
  --code vasp \
  --runs 200 \
  --needs-provenance \
  --needs-restart \
  --hpc \
  --json

在编写特定引擎的代码之前，先使用输出搭建工作流框架。

错误处理

如果任务细节不足，请选择保守的模式，并在实施前询问引擎、运行次数和重启需求。

局限性

此技能不能替代 atomate2、jobflow、AiiDA 或 pyiron 的官方 API；它负责选择并说明工作流结构。

验证清单

• 记录 workflow_engine_mapper.py 返回的完整 --json 负载（包括 inputs），并确认回显的 runs、code、needs_provenance、needs_restart 和 hpc 与实际要执行的任务一致，而不是基于猜测的默认值。
• 确认 recommended_engine 符合这些输入对应的文档优先级：--preferred 覆盖 -> 一次性任务（runs<5、不需要溯源、非 HPC）-> aiida（需要溯源，且（hpc 或 runs>=50））-> atomate2（code 为 vasp/qe/cp2k/forcefield，且 runs>=10）-> pyiron（ase/lammps，不需要溯源）-> 回退到 jobflow；如果结果出乎意料，请重新检查输入命中了哪个分支，而不是盲目覆盖。
• 确认 dag_pattern 能反映任务关键词：分支词（dos/band/phonon/static）和扫描词（screen/sweep/campaign/many/batch）会组合成 map+branch 模式；只有传入 --needs-restart 时才会追加 with restart checkpoints。
• 根据任务意图检查 provenance_requirements 和 restart_strategy：store_code_version/store_environment、checkpoint_jobs（当 runs>=20 时也会自动设为 true）以及 resume_by_job_id_or_name（一次性任务时为 false）都应符合实际的活动审核和恢复方式。
• 阅读 migration_triggers；如果建议采用一次性方案，请确认其中包含并已规划前瞻性条目 “results are compared/published/screened/resumed or runs reach ~5+ 后迁移”，而不是把一次性方案当作永久方案。
• 使用 storage_layout（inputs/、runs/<job-id>/、outputs/、metadata/workflow.json、reports/）搭建磁盘目录结构，并在编写引擎专用代码前确认它映射到所选引擎的原生存储。
• 确认映射器的退出代码为 0（若为 2，则表示输入验证拒绝了这些参数，且未生成建议），再信任任何输出。

常见误区与借口

看似省事的做法	为什么不对 / 应该怎么做
“现在只需运行几次，所以一次性脚本可以永远用下去。”	映射器会生成 migration_triggers 条目，正是因为一次性方案只适用于探索阶段；一旦需要比较、发布、筛选或恢复结果（或运行次数达到约 5 次以上），就应升级为引擎方案。应将一次性方案视为起点，而不是终点。
“我需要溯源，所以答案肯定是 AiiDA。”	只有在需要溯源，且（使用 HPC 或 runs>=50）时才会选择 AiiDA。对于规模较小或本地的溯源需求，映射器会有意选择 atomate2 或 jobflow；它们的存储已能记录输入、输出、代码版本和环境。轻量存储够用时，不要选择更重的技术栈。
“引擎运行成功并打印了建议，所以输入肯定正确。”	脚本验证的是参数范围，而非任务意图。忘记传入 --needs-provenance 或 --hpc，或让 --code general 使用默认值，都会悄然改变命中的分支。请重新阅读 JSON 中回显的 inputs 部分，并确认每个标志都符合实际任务。
“这是一个筛选活动，所以 DAG 只是遍历结构的映射。”	如果任务还指定了某项性质（dos/band/phonon/static），正确模式会组合两者：map over structures -> (relax -> static -> property branches) -> collect -> rank。请确认分支词和扫描词都出现在 dag_pattern 中。
“重启不重要，所以可以跳过检查点。”	无论是否传入 --needs-restart，当 runs>=20 时，checkpoint_jobs 也会被强制设为 true，因为大规模扫描可能中途失败。请遵循输出的 restart_strategy，不要凭直觉判断重启是否重要。
“建议的引擎和我的选择不一样，所以我直接用 --preferred。”	在运行任何启发式规则前，--preferred 就会覆盖所有选择，因此可能掩盖输入中的真实不匹配。应先确认 runs/code/溯源/HPC 都已正确填写；只有在有具体理由时才覆盖，并记录原因。

安全

输入验证

• 脚本仅接受标量命令行输入和布尔标志（--needs-provenance、--needs-restart、--hpc、通过 store_true 设置的 --json）。
• runs 必须是正整数（拒绝布尔值、非整数以及 <= 0 的值），上限为 MAX_RUNS = 1,000,000；main() 还会通过 math.isfinite 拒绝非有限值。
• 自由文本字段有长度限制：task 不得超过 2000 个字符（MAX_TASK_LEN），且去除首尾空白后不能为空；code 和 preferred 各不得超过 100 个字符（MAX_FIELD_LEN）。
• preferred 必须是允许的引擎名称之一：auto、one-off、jobflow、atomate2、aiida、pyiron。
• 除长度限制和（对 task）非空要求外，task 和 code 字符串不受其他限制，也不使用允许列表进行验证。
• 所有无效输入都会引发 ValueError，错误信息会打印到 stderr，并在计算任何推荐结果之前以退出码 2 退出。

文件访问

• 脚本不读写任何文件；所有 I/O 均为：输入 CLI 参数，输出到 stdout（JSON 或两行摘要）。
• 脚本不接受路径参数，因此无需担心路径沙箱问题；由于不会从磁盘读取内容，也不存在磁盘读取大小限制。

工具限制

• frontmatter 声明了 allowed-tools: Read, Bash, Write, Grep, Glob。
• Bash 仅用于运行随附的 scripts/workflow_engine_mapper.py。
• Read、Grep 和 Glob 用于检查该 skill 自身的文件和参考资料（例如 references/workflow_engines.md），以及用户任务的上下文；Write 可用于根据推荐结构搭建工作流文件。

安全措施

• 不使用 eval/exec、subprocess，脚本内部也不调用 shell。
• 不访问网络：脚本不会连接远程服务、提交作业或反序列化不可信数据。
• 输出通过 json.dumps 生成结构化 JSON（使用 --json 时），或输出纯文本摘要行。
• DoS 上限可限制资源使用：runs 上限（1,000,000）以及 task/code/preferred 的长度上限可防止输入无限增长。

参考资料

• 引擎选择的启发式规则请参阅 references/workflow_engines.md。

版本历史

• 1.2.2：添加 Verification checklist（将证据与 mapper 的 JSON 输出、优先级、DAG 组合和退出码关联起来），以及 Common pitfalls & rationalizations 表格，涵盖 one-off 的永久性、过度选择 AiiDA、未读取输入标志和强制检查点。
• 1.2.0：通过确定性的 script_checks 强化评测，固定 mapper 的精确输出（recommended_engine、dag_pattern、provenance_requirements、restart_strategy、migration_triggers），使每个案例都能区分该 skill 与基于记忆作答的基线。
• 1.1.0：组合分支与 sweep 的 DAG 模式，而非相互覆盖；为 one-off 运行输出前瞻性的迁移触发条件；记录 AiiDA 的门控规则与优先级；添加与 Security 部分一致的输入验证保护措施（边界、长度上限）。
• 1.0.0：初始版本的工作流引擎映射 skill。