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

• 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.
• 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.
• 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.
• Confirmed engine_version is a real version string and not the default "unknown"; pass --engine-version so the bundle records the exact code build.
• 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.
• Confirmed structure_id is populated when a Materials Project / NOMAD / OPTIMADE / CIF / POSCAR structure was used, so the structure identity is recoverable.
• 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.

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.