科研 Skill
多代码仿真故障分诊
simulation-failure-triage
Provides first-response triage for cross-code LAMMPS/VASP/QE/MOOSE simulation failures: classifies nonconvergence, NaN/Inf. Use when a simulation crashes and the cause is unclear.
SKILL.md
Simulation Failure Triage
Goal
Classify common simulation failure signatures and return immediate actions, retry ladders, and stop conditions.
Requirements
- Python 3.10+
- No external dependencies
- Works on Linux, macOS, and Windows
Inputs to Gather
| Input | Description | Example |
|---|---|---|
| Code | Simulation code | LAMMPS, VASP, MOOSE, QE |
| Stage | Setup, runtime, postprocess | runtime |
| Symptoms | Failure signs | nan,pressure-blowup |
| Log text or file | Error evidence | Lost atoms, ZBRENT |
| Recent change | Last modified setting | larger timestep |
Decision Guidance
- First preserve evidence: logs, inputs, executable version, and scheduler output.
- Separate setup errors from numerical instability and physical model issues.
- Retry with a single controlled change.
- Stop retrying when the result becomes scientifically meaningless or a required model input is missing.
Script Outputs
scripts/failure_triage.py emits:
likely_causesimmediate_actionsretry_ladderstop_conditionsevidence
Workflow
python3 skills/robustness/simulation-failure-triage/scripts/failure_triage.py \
--code LAMMPS \
--stage runtime \
--symptoms nan,pressure-blowup \
--recent-change "increased timestep" \
--json
Error Handling
Invalid stages or oversized log files stop with exit code 2. Unknown symptoms are retained as custom evidence.
Limitations
This skill gives first-response triage. It does not guarantee that a failed simulation can be repaired.
Verification checklist
- Recorded the preserved-evidence set BEFORE any rerun: copied logs, input decks, scheduler output, and the executable/version string (per the first
immediate_actionsitem) so the original failure is reproducible. - Quoted the FIRST warning/error from the run, not just the final crash line, and confirmed
evidence.log_excerpt(first 500 chars, original casing) captures it; re-run with--log-file/--log-textif the excerpt misses the root signature. - Logged every
likely_causesentry with itssymptom,category, andfirst_action, and verified no real signature landed in thecategory: custombucket because its keyword was absent fromLOG_HINTS/PATTERNS. - Confirmed the failure category is correct rather than mislabeled: a segfault/SIGSEGV/signal 11/core-dumped maps to
crash(notcorrupted-output), and an OOM/bad_alloc/oom-killmaps toout-of-memory(notincomplete-run). - Applied the
retry_ladderstrictly one change at a time, recording the single parameter changed and its effect at each rung (including the memory rung when memory-bound). - Checked every
stop_conditionsentry and halted the retry loop instead of stacking arbitrary stabilizing tweaks when any condition is met (e.g. unverifiable potential/pseudopotential, results dependent on arbitrary stabilizers). - After any numerical recovery, handed off to the
simulation-validatorskill for conservation / physical-bounds / "can I trust these results" checks rather than declaring success here.
Common pitfalls & rationalizations
| Tempting shortcut | Why it's wrong / what to do |
|---|---|
| "The last line of the log is the error, so I'll fix that." | The final crash line is often a downstream symptom; the script's second immediate_actions item exists because the FIRST warning/error is the real cause. Capture it in evidence.log_excerpt and triage from there. |
| "It segfaulted, so it's a corrupted-output / disk issue." | A crash (SIGSEGV/signal 11/core dumped) is a memory-fault category pointing at out-of-bounds/null-pointer/ABI bugs and a gdb/valgrind/ASan repro — not I/O. Do not treat it as corrupted-output. |
| "The job got killed, so I'll just bump the walltime." | killed alone is genuinely ambiguous and stays incomplete-run; an OOM signature (bad_alloc, oom-kill, "out of memory") is a distinct out-of-memory cause needing memory reduction / --mem increase, not more walltime. |
| "I'll lower dt AND change the preconditioner AND adjust the barostat to get it running." | The retry ladder is one controlled change per rung; stacking fixes makes results "depend on arbitrary stabilizing changes" — an explicit stop_conditions trigger. Change one parameter, record its effect, then proceed. |
| "I added the missing PAIR coeff path and it ran, so the physics is fine." | A clean run after fixing missing-potential/bad-pseudopotential resolves setup, not validity; species mapping, valence, or functional may still be wrong. Run completion is not correctness. |
| "It runs now, triage is done." | Triage only restores execution. Conservation, physical bounds, and convergence are out of scope here — defer to simulation-validator before trusting any number. |
Security
Input Validation
--stageis checked against a fixed allowlist (setup,runtime,postprocess,unknown); any other value exits with code 2.--codemust be non-empty and at most 100 characters; an empty or oversized value exits with code 2.--symptomsare split on commas and capped at 50 entries, each at most 100 characters; exceeding either limit exits with code 2.- Unknown symptoms are not rejected; they are retained as
customevidence rather than silently dropped. - There are no numeric arguments, so no finite/positive checks apply.
- All input-validation failures (and log read errors) are caught and exit with code 2 and a stderr message.
File Access
- The only file read is the optional
--log-filepath; when omitted, the script reads no files. - Before reading, the log file's size is checked via
stat; if it exceeds the 10 MB cap (MAX_LOG_SIZE) the script raises and exits with code 2. Both file content and--log-textare then truncated to 10 MB. - The script writes no files; all results go to stdout (JSON with
--json, otherwise plain text). - Path-sandboxing caveat: the log path is not restricted to a working directory, so the script can read any file the invoking process has permission to read; only pass trusted paths.
Tool Restrictions
allowed-toolsisRead, Bash, Write, Grep, Glob.Bashruns only the bundledscripts/failure_triage.py.Readopens the skill's own files and a user-provided log to inspect failure evidence;Grep/Globlocate log files, inputs, and prior output;Writerecords triage notes or preserved evidence at the user's direction. The bundled script itself does not write files.
Safety Measures
- No
eval/execand no dynamic code execution; log text is treated as data and never run. - The script spawns no subprocesses and runs no external solvers.
- Output is structured JSON (
--json), making results machine-checkable. - DoS caps bound resource use: 10 MB log size/text limit, 50 symptoms, and 100-character limits on
codeand each symptom.
References
- See
references/failure_patterns.mdfor common failure signatures and retry ladders.
Version History
- 1.1.3: Add
Verification checklist(evidence-based checks tied tofailure_triage.pyoutputs — preserved-evidence set, first-error excerpt, category-mislabel guards, one-change retry ladder, stop conditions, simulation-validator handoff) andCommon pitfalls & rationalizationstable covering last-line-only triage, segfault-as-I/O, OOM-vs-walltime, stacked stabilizing changes, and "it ran so it's valid". - 1.1.1: Strengthen evals to be discriminating — each case now pins the exact
failure_triage.pyJSON output viascript_checks(specificcategory/first_actionstrings, log-hint symptom inference, fixed retry-ladder/stop-condition text, recent-change immediate action), so the suite measures the skill's actual output rather than generic triage knowledge. - 1.1.0: Add dedicated
out-of-memoryandcrash(segfault) classifications; segfaults and OOM are no longer mislabeled as I/O or interrupted-execution. Preserve original-case log excerpt. Add input-validation caps (symptoms, code length). Sharpen description to defer deep validation to simulation-validator. Fixmissing-potentialeval token. - 1.0.0: Initial cross-code simulation failure triage skill.
示例提示词
我的VASP计算一直不收敛还报NaN,帮我诊断失败原因并提出修复方案。
所属插件
安装该插件会一并获得同领域的 23 个 Skill / MCP。
同插件的其他科研 Skill
- 制造解法验证与基准测试规划Plans verification and validation campaigns using manufactured solutions, canonical benchmarks. Use when an agent must prove a solver is correct before trusting results.
- 数值解空间时间收敛性分析Performs spatial/temporal convergence analysis for solution verification: observed order, Richardson extrapolation. Use when checking that a simulation result is grid/timestep independent.
- PDE数值微分格式选择Selects and applies numerical differentiation schemes for PDE/ODE discretization: finite-difference stencils. Use when choosing a spatial discretization scheme.
- 仿真结果FAIR归档打包Creates FAIR-minded reproducibility bundles for simulations: file inventories, hashes, units, engine versions. Use before publishing or archiving a simulation dataset.
- HPC作业运行诊断Diagnoses HPC runtime and scheduler problems for materials simulations: MPI/OpenMP/GPU layout, modules, scratch paths, walltime. Use when a cluster job fails, hangs, or underperforms.
- 线性方程组求解器选型Selects and configures linear solvers for Ax=b systems: direct (LU, Cholesky) versus iterative (CG, GMRES, BiCGSTAB) methods, sparsity. Use when choosing a linear solver for a simulation.
- 分子动力学分析方案规划Plans molecular dynamics post-processing for materials simulations: RDF, MSD/diffusion, VACF/VDOS, coordination numbers. Use when deciding which MD analysis to run and in what order.
- 数值模拟网格生成规划Plans and evaluates mesh generation for numerical simulations: grid resolution from physics scales, aspect ratio/skewness checks. Use when designing or auditing a simulation mesh.
- 非线性方程组求解器选型Selects and configures nonlinear solvers for root-finding, optimization, and least-squares problems: Newton, quasi-Newton, Broyden, Anderson acceleration. Use when choosing a nonlinear solver.
- 时间积分方法选择Selects and configures time-integration methods for ODE/PDE simulations: explicit Runge-Kutta, BDF, Rosenbrock. Use when choosing a time-stepping scheme for a solver.
- 偏微分方程数值稳定性分析Analyzes numerical stability for time-dependent PDE simulations: CFL/Fourier criteria, von Neumann analysis. Use when a simulation blows up or to check a scheme’s stability limits.
- 材料科学本体浏览查询Parses, navigates, and queries materials science ontology structures: class hierarchies, property domain/range lookup. Use when exploring an unfamiliar materials ontology.
- 材料术语本体映射Maps materials science terms, crystal structures, and sample descriptions to standardized ontology classes with confidence scores. Use when annotating data for ontology interoperability.
- 本体标注一致性校验Validates material sample annotations against ontology constraints: class/property existence, domain/range consistency. Use before publishing ontology-annotated materials data.
- 仿真参数优化与敏感性分析Explores and optimizes simulation parameters via design of experiments, sensitivity analysis, and optimizer selection: Latin Hypercube, quasi-random. Use when calibrating simulation parameters.
- 仿真计算性能剖析Identifies computational bottlenecks, parallel scaling, and memory requirements for materials simulations: parses timing logs for dominant phases. Use when a simulation is slow or scales poorly.
- 仿真输出数据后处理Extracts, analyzes, and summarizes simulation output data: spatial fields at timesteps, time-series trends, steady-state detection. Use when turning raw simulation output into summary statistics.
- 多任务仿真批量编排Orchestrates multi-simulation campaigns: generates parameter sweeps (grid, linspace, Latin Hypercube), tracks batch job status. Use when running and managing many related simulation jobs.
- 仿真三阶段有效性校验Validates simulations across three stages: pre-flight config checks, runtime log monitoring for NaN/Inf and residual growth. Use to catch simulation errors before, during, and after a run.
- SLURM作业脚本生成Generates correct SLURM sbatch job scripts and sanity-checks HPC resource requests: nodes, MPI/OpenMP layout, memory, GPUs, walltime. Use when writing or debugging a SLURM submission script.
- 瞬态仿真时间步策略Plans and controls time-step policies for transient simulations: CFL and physics-based stability limits, adaptive stepping. Use when setting up a time-stepping strategy for a solver.
- 计算材料工作流引擎选型Maps computational materials tasks onto workflow engines (atomate2, jobflow, AiiDA, pyiron) or a one-off script. Use when deciding how to structure a reproducible campaign or DAG.
常见问题
多代码仿真故障分诊能做什么?
Provides first-response triage for cross-code LAMMPS/VASP/QE/MOOSE simulation failures: classifies nonconvergence, NaN/Inf. Use when a simulation crashes and the cause is unclear。
如何安装多代码仿真故障分诊?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「多代码仿真故障分诊」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
多代码仿真故障分诊需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
多代码仿真故障分诊经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。