科研 Skill
分子动力学分析方案规划
md-analysis-planner
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.
SKILL.md
MD Analysis Planner
Goal
Choose the right MD trajectory analyses and prerequisites before writing post-processing code.
Requirements
- Python 3.10+
- No external dependencies
- Works on Linux, macOS, and Windows
Inputs to Gather
| Input | Description | Example |
|---|---|---|
| System | Material or molecular system | oxide glass, liquid water |
| Goals | Analysis goals | rdf,diffusion,coordination |
| Trajectory format | Dump, DCD, XYZ, H5MD, etc. | LAMMPS dump |
| Velocities | Whether velocities are stored | true |
| Stress | Whether stress/virial is stored | true |
| Unwrap needed | Whether atoms cross PBC | true |
| Timestep | fs per saved frame | 10 |
Decision Guidance
- Use RDF and coordination for local structure.
- Use MSD for diffusion, but unwrap trajectories and verify diffusive regime.
- Use VACF/VDOS only when velocities or reliable finite-difference velocities exist.
- Use stress-strain only if stress/virial and deformation history are available.
- Always perform equilibration checks before fitting transport or thermodynamic properties.
Script Outputs
scripts/md_analysis_planner.py emits these fields (JSON under results):
| Field | Description |
|---|---|
analysis_plan | One entry per goal: goal, method, and status |
required_data | Sorted, de-duplicated data needed across all goals |
equilibration_checks | Standard pre-fit equilibration checklist |
pbc_handling | unwrap_needed, minimum_action, format_note |
warnings | Safety-critical caveats and blockers |
Status values
status is one of, from most to least severe: blocked > needs time axis >
needs review > ready. A more-severe status is never demoted by a less-severe
one. For example, a VACF/VDOS goal with no stored velocities reports blocked
even when the timestep is also missing (both warnings are still emitted).
Default (non-JSON) output
Without --json the script prints the plan lines, a Required data: list, a
one-line PBC: note, and a Warnings: section (also mirrored to stderr) so the
safety-critical caveats are visible even when stdout is piped.
Workflow
python3 skills/simulation-workflow/md-analysis-planner/scripts/md_analysis_planner.py \
--system "oxide glass" \
--goals rdf,coordination,bond-angle \
--trajectory-format dump \
--unwrap-needed \
--timestep-fs 10 \
--json
Error Handling
If velocities, stress, or timestep information is missing, downgrade dependent
analyses and report warnings. The script exits with code 2 and a message on
stderr for invalid input (empty system, no goals, non-positive or non-finite
timestep, or inputs exceeding the size caps below).
Limitations
This skill plans analysis and prerequisites; it does not parse large trajectories directly.
Verification checklist
Do not trust trajectory-derived results until each applicable item below is recorded against the planner's own output:
- Ran
scripts/md_analysis_planner.pyand confirmed noanalysis_planentry isblockedorneeds time axis; record anyneeds reviewgoal and how its custom analysis was resolved. - Confirmed every item in the planner's
required_datalist is actually present in the trajectory (e.g.velocitiesfor VACF/VDOS,stress or virial+strain historyfor stress-strain) before running the corresponding analysis. - For diffusion/MSD: recorded the log-log MSD-vs-time slope and confirmed it is ~1 (diffusive regime) over the fit window, excluding ballistic/sub-diffusive transients, before quoting D = lim MSD/(2dt).
- For diffusion/MSD: assessed whether a hydrodynamic finite-size correction is applicable. For isotropic bulk fluids in 3D periodic cubic cells, record L, T and shear viscosity eta if applying Yeh-Hummer (D_0 = D_PBC + k_BTxi/(6pieta*L), xi~=2.837). Report the measured D_PBC, the correction and its assumptions separately. Do not apply this formula automatically to solids, confined or anisotropic systems, non-cubic cells or ballistic trajectories.
- For any displacement-based analysis when
pbc_handling.unwrap_neededis true: confirmed positions were unwrapped usingcell+image flagsbefore computing displacements (not raw wrapped coordinates). - Worked through the planner's
equilibration_checks: discarded the startup transient, confirmed temperature/pressure plateaus, and compared first-half vs second-half property estimates before any transport/thermodynamic fit. - Reported an uncertainty from block averaging (or independent trajectories) for every quoted transport/thermodynamic property, not a single-window point value.
Common pitfalls & rationalizations
| Tempting shortcut | Why it's wrong / what to do |
|---|---|
| "MSD vs time looks straight, so it's diffusive — just fit a line." | A straight-looking MSD can still include ballistic/sub-diffusive transients. Confirm the log-log slope is ~1 over the fit window first, then fit D = lim MSD/(2dt). |
| "D from the simulation is the diffusion coefficient." | Assess size dependence and report D_PBC. The Yeh-Hummer 1/L hydrodynamic correction applies under bulk-fluid, 3D periodic cubic-cell assumptions; justify those assumptions and the viscosity before separately reporting a corrected D_0. |
| "Positions are in the dump, so MSD is fine." | Wrapped coordinates make atoms jump across the box and corrupt displacements. When unwrap_needed is true, unwrap using cell + image flags before any displacement analysis. |
| "No velocities stored, but I can get VACF/VDOS from positions." | The planner marks VACF/VDOS blocked without velocities for a reason. A finite-difference velocity estimate must be explicitly justified (frame spacing, aliasing); otherwise the result is unreliable. |
| "The run finished, so I can fit transport properties on the whole trajectory." | Run completion is not equilibration. Discard the startup transient and verify temperature/pressure plateaus (the equilibration_checks) before fitting. |
| "One window gave a clean number, no need for error bars." | A single window hides correlation-driven variance. Use block averaging or independent trajectories so every transport/thermodynamic value carries an uncertainty. |
Security
Input Validation
Inputs are scalar CLI values and booleans only. plan_md_analysis validates and
bounds every field before use; any violation raises ValueError, which main
catches to print a message on stderr and exit with code 2:
systemmust be non-empty (after stripping) and at most 256 characters.- At most 64 goals are allowed; each goal at most 256 characters.
trajectory_formatat most 256 characters.timestep_fs, if given, must be a positive, finite number (math.isfiniteand> 0).
Goals are not allowlisted: an unrecognized goal is not rejected but is reported
with status needs review and an "unknown goal" warning. The --has-velocities,
--has-stress, and --unwrap-needed flags are plain booleans and need no
validation.
File Access
The script reads and writes no files; all I/O is stdin/args -> stdout (plain text or JSON), with warnings additionally mirrored to stderr. It takes no path arguments and opens no trajectory or output files, so there is no filesystem sandboxing concern. There are no per-file size limits because no files are read; input size is instead capped by the field/goal limits above.
Tool Restrictions
Frontmatter allowed-tools is Read, Bash, Write, Grep, Glob:
Bashis used only to run the bundledscripts/md_analysis_planner.py.Read,Write,Grep, andGlobare used only to inspect, edit, and search this skill's own files (the script, references, and SKILL.md) when authoring analysis plans; they are not used to touch trajectory data.
Safety Measures
- No use of
eval,exec,os.system, or dynamic imports. - The script spawns no subprocesses and executes no external analysis programs;
it only parses arguments with
argparseand computes a plan in-process. - Output is structured JSON produced via
json.dumps(or deterministic plain text), never interpolated shell. - Denial-of-service caps (
MAX_GOALS = 64,MAX_SYSTEM_LEN = 256,MAX_FIELD_LEN = 256) bound the work so a planning helper never materializes pathological input.
References
For a final readiness explanation from trusted, input-verified tool JSON, use the deterministic explanation renderer. A blocked VACF plan means readiness is false; the explanation and boolean must agree. Null means unresolved, and a ready plan does not validate a computed material property.
- See
references/md_analysis_checks.mdfor analysis prerequisites and failure modes. - Yeh and Hummer (2004), https://doi.org/10.1021/jp0477147: bulk-fluid periodic finite-size correction, not a universal correction for all materials.
Version History
-
v1.2.3 (2026-10-19): Limit finite-size diffusion corrections to their justified physical regime.
-
1.2.0: Add deterministic
script_checksto all three eval cases that pin the exact planner output (statuses, sortedrequired_data, PBC note, and the specific diffusive-regime / Yeh-Hummer / blocked-not-demoted warnings) so the evals discriminate the skill from a from-memory baseline. -
1.1.0: Fix status demotion (blocked never downgraded to needs time axis), surface warnings/required-data/PBC in non-JSON mode, add diffusive-regime and Yeh-Hummer finite-size guidance, and enforce documented input caps.
-
1.0.0: Initial MD analysis planning skill.
示例提示词
我要分析一条MD轨迹,帮我规划该做哪些扩散系数和平衡性检测。
所属插件
安装该插件会一并获得同领域的 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 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.
- 多代码仿真故障分诊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.
- 多任务仿真批量编排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.
常见问题
分子动力学分析方案规划能做什么?
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。
如何安装分子动力学分析方案规划?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「分子动力学分析方案规划」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
分子动力学分析方案规划需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
分子动力学分析方案规划经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。