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.inputs is the raw
comma-separated string passed via --inputs, not the per-file records).
results: contains a single key manifest.
results.manifest contains these fields:
project_name, engine, engine_version, structure_id, units
file_inventory with inputs and outputs, each a list of per-file records
(path, exists, and when the file exists, size_bytes and sha256)
missing_files: paths that do not exist on disk
provenance (working_directory, manifest_schema)
fair_checks: has_inputs, has_outputs, has_units, has_engine_version, and
has_hashes_for_existing_files (true/false, or null when 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
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-name and --engine are 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.
--inputs and --outputs are split on commas and capped at 1000 entries each; more
entries stop with exit code 2.
--units entries must be key=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_bytes and 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 PATH is 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 --out points outside the working directory, the
file is written there as requested.
Tool Restrictions
Bash is used to run the bundled scripts/fair_packager.py.
Read, Write, Grep, and Glob are 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, or subprocess calls; the script does not shell out and
parses arguments with argparse.
- 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.md for recommended manifest fields.
Version History
- 1.2.0: Made eval cases discriminating by pinning the script's exact
--json
output (per-file sha256/size_bytes, units, structure_id, engine_version,
missing_files, and the tri-state has_hashes_for_existing_files) against
committed evals/files/ fixtures.
- 1.1.0: Documented the real
--json envelope shape; made
has_hashes_for_existing_files tri-state (null when 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.
1---2name: fair-simulation-packager3description: >4 Create FAIR-minded reproducibility bundles for materials simulations by5 collecting input/output file inventories, hashes, units, engine versions,6 structure identifiers, provenance, and NOMAD/OPTIMADE/Materials Project7 friendly metadata. Use before publishing, sharing, archiving, or handing8 simulation results to another agent.9allowed-tools: Read, Bash, Write, Grep, Glob10metadata:11 source: https://skillmd.com/skills/heshamfs/fair-simulation-packager12 author: HeshamFS13 version: "1.2.2"14 security_tier: high15 security_reviewed: true16 tested_with:17 - claude-code18 last_evaluated: "2026-06-23"19 eval_cases: 320 last_reviewed: "2026-06-24"21 standards:22 - "FAIR Guiding Principles (Wilkinson et al. 2016, Sci. Data)"23 - "OPTIMADE API specification"24 - "NOMAD Metainfo / Materials Project metadata schema"25 - "FIPS 180-4 Secure Hash Standard (SHA-256)"26---2728# FAIR Simulation Packager2930## Goal3132Build 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.3334## Requirements3536- Python 3.10+37- No external dependencies38- Works on Linux, macOS, and Windows3940## Inputs to Gather4142| Input | Description | Example |43|-------|-------------|---------|44| Project name | Human-readable bundle name | `al-cu-diffusion-study` |45| Engine | Simulation code | `LAMMPS`, `VASP`, `MOOSE` |46| Input files | Files needed to rerun | `in.lammps,data.lmp` |47| Output files | Files needed to verify results | `log.lammps,traj.dump` |48| Structure ID | Database or local identifier | `mp-149` |49| Units | Field/unit mapping | `energy=eV,length=angstrom` |5051## Decision Guidance5253- Always include input files, output files, code version, and units.54- Include hashes for every file that exists locally.55- Include structure identifiers when using Materials Project, NOMAD, OPTIMADE, CIF, POSCAR, or internal database records.56- Record missing files as warnings instead of silently dropping them.5758## Script Outputs5960`scripts/fair_packager.py --json` prints an envelope with two top-level keys:6162- `inputs`: the parsed CLI arguments echoed back (note: `inputs.inputs` is the raw63 comma-separated string passed via `--inputs`, not the per-file records).64- `results`: contains a single key `manifest`.6566`results.manifest` contains these fields:6768- `project_name`, `engine`, `engine_version`, `structure_id`, `units`69- `file_inventory` with `inputs` and `outputs`, each a list of per-file records70 (`path`, `exists`, and when the file exists, `size_bytes` and `sha256`)71- `missing_files`: paths that do not exist on disk72- `provenance` (`working_directory`, `manifest_schema`)73- `fair_checks`: `has_inputs`, `has_outputs`, `has_units`, `has_engine_version`, and74 `has_hashes_for_existing_files` (`true`/`false`, or `null` when no files exist so the75 check is not applicable)76- `recommended_next_steps`7778Parse fields at `results.manifest.<field>`. When `--out PATH` is given, only the bare79`manifest` object (not the `inputs`/`results` envelope) is written to `PATH`.8081## Workflow8283```bash84python3 skills/data-management/fair-simulation-packager/scripts/fair_packager.py \85 --project-name al-cu-diffusion \86 --engine LAMMPS \87 --inputs in.lammps,data.lmp \88 --outputs log.lammps,traj.dump \89 --units energy=eV,length=angstrom,time=ps \90 --structure-id local:alcu-cell-001 \91 --json92```9394Use `--out manifest.json` only when the user wants a manifest file written.9596## Error Handling9798Missing files are reported in `missing_files` (exit code 0). Invalid input stops with99exit code 2: malformed unit entries, fields containing control characters, fields longer100than 4096 characters, more than 1000 input or output entries, or a file larger than101500 MB. Note that ordinary file paths — including absolute paths and paths containing102`..` — are accepted and inventoried; the tool reads file contents only to compute103metadata and SHA-256 hashes.104105## Limitations106107This skill creates a metadata manifest. It does not upload to NOMAD, Materials Project, or an OPTIMADE provider.108109## Verification checklist110111- [ ] Confirmed `fair_checks.has_hashes_for_existing_files` is `true` (not `null` or `false`); a `null` means no listed file existed on disk, so re-run from the directory where the files actually live before trusting the manifest.112- [ ] Reviewed `missing_files` and 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.113- [ ] Spot-checked at least one `sha256` in `results.manifest.file_inventory` against an independent `sha256sum`/`Get-FileHash` of the same file to confirm the recorded digest matches the bytes on disk.114- [ ] Confirmed `engine_version` is a real version string and not the default `"unknown"`; pass `--engine-version` so the bundle records the exact code build.115- [ ] Verified `units` is non-empty and every reported quantity (energy, length, time, etc.) has an entry, so downstream consumers do not have to guess the unit system.116- [ ] Confirmed `structure_id` is populated when a Materials Project / NOMAD / OPTIMADE / CIF / POSCAR structure was used, so the structure identity is recoverable.117- [ ] When `--out PATH` was used, opened `PATH` and confirmed it holds the bare `manifest` object (not the `inputs`/`results` envelope) and that no unintended path outside the working directory was written.118119## Common pitfalls & rationalizations120121| Tempting shortcut | Why it's wrong / what to do |122|-------------------|-----------------------------|123| "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. |124| "`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. |125| "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. |126| "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`. |127| "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. |128| "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. |129130## Security131132### Input Validation133134- `--project-name` and `--engine` are required and must be non-empty after stripping135 whitespace; an empty value stops with exit code 2.136- `--project-name`, `--engine`, `--structure-id` (when given), and every file path are137 checked for control characters (`ord < 32`) and a 4096-character maximum length; either138 condition stops with exit code 2.139- `--inputs` and `--outputs` are split on commas and capped at 1000 entries each; more140 entries stop with exit code 2.141- `--units` entries must be `key=value`; both the key and the value must match the142 allowlist `^[A-Za-z0-9_.:/@+-]+$`. A missing `=` or a non-matching key/value stops with143 exit code 2.144- There are no numeric inputs, so no finite/positive numeric checks are performed.145146### File Access147148- The script reads each existing input/output file in 1 MB chunks to compute its149 `size_bytes` and SHA-256 hash; files that do not exist are recorded but not read.150- A file larger than 500 MB stops with exit code 2 before it is hashed.151- The script writes no files unless `--out PATH` is given, in which case it writes exactly152 one file (the bare manifest JSON) to that path; otherwise all output goes to stdout.153- Paths are not sandboxed: absolute paths and paths containing `..` are accepted for both154 the inventoried files and `--out`. If `--out` points outside the working directory, the155 file is written there as requested.156157### Tool Restrictions158159- `Bash` is used to run the bundled `scripts/fair_packager.py`.160- `Read`, `Write`, `Grep`, and `Glob` are declared so the skill can inspect the working161 directory and read or write manifest/metadata files when guiding the user; they are not162 invoked by the script itself, which performs all of its own file I/O directly.163164### Safety Measures165166- No `eval`, `exec`, `os.system`, or `subprocess` calls; the script does not shell out and167 parses arguments with `argparse`.168- Output is emitted as JSON via `json.dumps` (or a short plain-text summary without169 `--json`).170- DoS caps bound resource use: 500 MB per file, 1000 entries per input/output list, and171 4096 characters per field.172173## References174175- See `references/fair_manifest.md` for recommended manifest fields.176177## Version History178179- 1.2.0: Made eval cases discriminating by pinning the script's exact `--json`180 output (per-file `sha256`/`size_bytes`, `units`, `structure_id`, `engine_version`,181 `missing_files`, and the tri-state `has_hashes_for_existing_files`) against182 committed `evals/files/` fixtures.183- 1.1.0: Documented the real `--json` envelope shape; made184 `has_hashes_for_existing_files` tri-state (`null` when no files exist); added entry-count185 (1000) and field-length (4096) caps; corrected the Error Handling and Security wording186 to describe actual path behavior.187- 1.0.0: Initial FAIR simulation packaging skill.