科研 Skill
仿真结果FAIR归档打包
fair-simulation-packager
Creates FAIR-minded reproducibility bundles for simulations: file inventories, hashes, units, engine versions. Use before publishing or archiving a simulation dataset.
SKILL.md
FAIR Simulation Packager
Goal
Build a minimal reproducibility manifest for materials simulation results so another person or agent can understand what was run, with which inputs, and how outputs should be interpreted.
Requirements
- Python 3.10+
- No external dependencies
- Works on Linux, macOS, and Windows
Inputs to Gather
| Input | Description | Example |
|---|---|---|
| Project name | Human-readable bundle name | al-cu-diffusion-study |
| Engine | Simulation code | LAMMPS, VASP, MOOSE |
| Input files | Files needed to rerun | in.lammps,data.lmp |
| Output files | Files needed to verify results | log.lammps,traj.dump |
| Structure ID | Database or local identifier | mp-149 |
| Units | Field/unit mapping | energy=eV,length=angstrom |
Decision Guidance
- Always include input files, output files, code version, and units.
- Include hashes for every file that exists locally.
- Include structure identifiers when using Materials Project, NOMAD, OPTIMADE, CIF, POSCAR, or internal database records.
- Record missing files as warnings instead of silently dropping them.
Script Outputs
scripts/fair_packager.py --json prints an envelope with two top-level keys:
inputs: the parsed CLI arguments echoed back (note:inputs.inputsis the raw comma-separated string passed via--inputs, not the per-file records).results: contains a single keymanifest.
results.manifest contains these fields:
project_name,engine,engine_version,structure_id,unitsfile_inventorywithinputsandoutputs, each a list of per-file records (path,exists, and when the file exists,size_bytesandsha256)missing_files: paths that do not exist on diskprovenance(working_directory,manifest_schema)fair_checks:has_inputs,has_outputs,has_units,has_engine_version, andhas_hashes_for_existing_files(true/false, ornullwhen no files exist so the check is not applicable)recommended_next_steps
Parse fields at results.manifest.<field>. When --out PATH is given, only the bare
manifest object (not the inputs/results envelope) is written to PATH.
Workflow
python3 skills/data-management/fair-simulation-packager/scripts/fair_packager.py \
--project-name al-cu-diffusion \
--engine LAMMPS \
--inputs in.lammps,data.lmp \
--outputs log.lammps,traj.dump \
--units energy=eV,length=angstrom,time=ps \
--structure-id local:alcu-cell-001 \
--json
Use --out manifest.json only when the user wants a manifest file written.
Error Handling
Missing files are reported in missing_files (exit code 0). Invalid input stops with
exit code 2: malformed unit entries, fields containing control characters, fields longer
than 4096 characters, more than 1000 input or output entries, or a file larger than
500 MB. Note that ordinary file paths — including absolute paths and paths containing
.. — are accepted and inventoried; the tool reads file contents only to compute
metadata and SHA-256 hashes.
Limitations
This skill creates a metadata manifest. It does not upload to NOMAD, Materials Project, or an OPTIMADE provider.
Verification checklist
- Confirmed
fair_checks.has_hashes_for_existing_filesistrue(notnullorfalse); anullmeans no listed file existed on disk, so re-run from the directory where the files actually live before trusting the manifest. - Reviewed
missing_filesand confirmed it is empty, or recorded an explicit reason for each entry — every missing path means an input/output was named but not hashed, so the bundle is not reproducible as-is. - Spot-checked at least one
sha256inresults.manifest.file_inventoryagainst an independentsha256sum/Get-FileHashof the same file to confirm the recorded digest matches the bytes on disk. - Confirmed
engine_versionis a real version string and not the default"unknown"; pass--engine-versionso the bundle records the exact code build. - Verified
unitsis non-empty and every reported quantity (energy, length, time, etc.) has an entry, so downstream consumers do not have to guess the unit system. - Confirmed
structure_idis populated when a Materials Project / NOMAD / OPTIMADE / CIF / POSCAR structure was used, so the structure identity is recoverable. - When
--out PATHwas used, openedPATHand confirmed it holds the baremanifestobject (not theinputs/resultsenvelope) and that no unintended path outside the working directory was written.
Common pitfalls & rationalizations
| Tempting shortcut | Why it's wrong / what to do |
|---|---|
| "It exited 0, so the bundle is complete." | Exit 0 only means no validation error; missing files are reported in missing_files with exit 0. Inspect missing_files and fair_checks before trusting completeness. |
"has_hashes_for_existing_files is null, close enough to true." | null means no listed file existed on disk — nothing was hashed. Re-run from the correct directory so the files are found and actually digested. |
"Skip --engine-version, the engine name is enough." | The script defaults engine_version to "unknown", which silently breaks reproducibility. Always pass the concrete build/version. |
"Parsing inputs.inputs from the JSON gives me the per-file records." | inputs.inputs is the raw comma-separated CLI string echoed back, not the records. Read per-file data from results.manifest.file_inventory.inputs/outputs. |
| "The manifest captures the structure, so the run is fully reproducible." | This skill only inventories files, hashes, units, and IDs. It does not record code commit, container digest, or parser versions — follow recommended_next_steps and add those yourself. |
"Absolute paths or .. will be rejected, so the inventory is sandboxed." | Paths are not sandboxed — absolute and .. paths are inventoried as given, and --out can write outside the working directory. Verify the paths you pass are the intended ones. |
Security
Input Validation
--project-nameand--engineare required and must be non-empty after stripping whitespace; an empty value stops with exit code 2.--project-name,--engine,--structure-id(when given), and every file path are checked for control characters (ord < 32) and a 4096-character maximum length; either condition stops with exit code 2.--inputsand--outputsare split on commas and capped at 1000 entries each; more entries stop with exit code 2.--unitsentries must bekey=value; both the key and the value must match the allowlist^[A-Za-z0-9_.:/@+-]+$. A missing=or a non-matching key/value stops with exit code 2.- There are no numeric inputs, so no finite/positive numeric checks are performed.
File Access
- The script reads each existing input/output file in 1 MB chunks to compute its
size_bytesand SHA-256 hash; files that do not exist are recorded but not read. - A file larger than 500 MB stops with exit code 2 before it is hashed.
- The script writes no files unless
--out PATHis given, in which case it writes exactly one file (the bare manifest JSON) to that path; otherwise all output goes to stdout. - Paths are not sandboxed: absolute paths and paths containing
..are accepted for both the inventoried files and--out. If--outpoints outside the working directory, the file is written there as requested.
Tool Restrictions
Bashis used to run the bundledscripts/fair_packager.py.Read,Write,Grep, andGlobare declared so the skill can inspect the working directory and read or write manifest/metadata files when guiding the user; they are not invoked by the script itself, which performs all of its own file I/O directly.
Safety Measures
- No
eval,exec,os.system, orsubprocesscalls; the script does not shell out and parses arguments withargparse. - Output is emitted as JSON via
json.dumps(or a short plain-text summary without--json). - DoS caps bound resource use: 500 MB per file, 1000 entries per input/output list, and 4096 characters per field.
References
- See
references/fair_manifest.mdfor recommended manifest fields.
Version History
- 1.2.0: Made eval cases discriminating by pinning the script's exact
--jsonoutput (per-filesha256/size_bytes,units,structure_id,engine_version,missing_files, and the tri-statehas_hashes_for_existing_files) against committedevals/files/fixtures. - 1.1.0: Documented the real
--jsonenvelope shape; madehas_hashes_for_existing_filestri-state (nullwhen no files exist); added entry-count (1000) and field-length (4096) caps; corrected the Error Handling and Security wording to describe actual path behavior. - 1.0.0: Initial FAIR simulation packaging skill.
示例提示词
我要把这批DFT计算结果打包成符合FAIR原则的可复现归档文件。
所属插件
安装该插件会一并获得同领域的 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.
- 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.
- 多代码仿真故障分诊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.
常见问题
仿真结果FAIR归档打包能做什么?
Creates FAIR-minded reproducibility bundles for simulations: file inventories, hashes, units, engine versions. Use before publishing or archiving a simulation dataset。
如何安装仿真结果FAIR归档打包?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「仿真结果FAIR归档打包」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
仿真结果FAIR归档打包需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
仿真结果FAIR归档打包经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。