Portable calculation bundles

A .rustiq bundle is a portable snapshot of RustiQ calculation inputs and optional reusable atomic-orbital electron-repulsion integrals (AO ERIs). It lets users rerun saved calculations or reuse compatible AO ERIs in new ones without carrying a machine-local cache. The bundle does not save a Hartree–Fock wavefunction or skip a new SCF run.

Create and inspect a bundle

Run the examples from the repository root. First make the checked-in STO-3G basis available, then run the H₂ sample and write a bundle to the current directory:

cargo run --locked -- basis import tests/data/sto-3g.json
cargo run --locked -- run samples/h2/sto-3g/calculation.toml --artifact h2.rustiq

Choose a destination that does not already exist. --artifact writes the current calculation collection as a new bundle, independently of text or JSON result output. For a Nickel study, the bundle contains one entry for each requested calculation.

Inspect a bundle without the original runfile, geometry file, or basis store:

cargo run --locked -- artifact inspect h2.rustiq
cargo run --locked -- artifact inspect h2.rustiq --format json

Inspection displays canonical requested and resolved calculation snapshots, producer information, artifact representations, and captured source names and sizes. Requested values may differ from resolved values: for example, an Auto HF method can resolve to RHF, and requested Angstrom coordinates appear as resolved Bohr coordinates. Text output syntax-highlights the canonical TOML and XYZ when color is enabled by --color or RUSTIQ_COLOR; use --color never for plain text. The optional JSON payloads_verified field is false: inspection validates the archive index, provenance, scientific snapshots and declared artifact sizes, but does not hash or decode numerical payloads. Use artifact verify to check supported payloads eagerly; otherwise, execution checks a payload when its scientific stage selects and reads it. Inspection is structural, not a calculation or an independent scientific validation.

Use artifact verify to eagerly read and validate every supported numerical payload in the bundle:

cargo run --locked -- artifact verify h2.rustiq

The command checks compact AO ERI payload hashes, NPY encoding, array dimensions, and consistency with the declared AO basis. It reports the number of verified payloads and calculations on standard output, and exits unsuccessfully if a payload is invalid or has an unsupported representation. A bundle with no numerical payloads can successfully report zero verified payloads. Verification does not execute the calculation or establish that the scientific method or result is valid. For the H₂ bundle created above, the output is:

Verified 1 payload(s) across 1 calculation(s).

Rerun a saved calculation

Run a .rustiq bundle directly to reconstruct and execute its archived calculation settings, without the original runfile, geometry file, or basis store:

cargo run --locked -- run h2.rustiq
cargo run --locked -- run h2.rustiq --format json --pretty --color never

For a multi-calculation bundle, RustiQ reruns every entry in manifest order and reports a batch, like a multi-entry Nickel study. This is a fresh calculation: RustiQ restores the resolved scientific inputs and reuses compatible AO ERIs when present; otherwise it recomputes them. A corrupt compatible AO ERI payload causes an execution error. It then runs HF again and MP2 again when requested. It does not restore orbitals, density matrices, DIIS history, or prior results, so this command does not resume an SCF trajectory. A saved random seed is restored as an input; it does not guarantee bitwise-identical results across software versions or platforms.

To use different settings, supply a TOML or Nickel input and use --reuse instead. A direct archive rerun cannot be combined with --reuse, --artifact, --cache-dir, --auto-download, or --no-auto-download. With --format json, the rerun uses the normal single-calculation or batch result schema and omits the artifacts reuse-decision array because the bundle is the implicit artifact source. The source bundle remains unchanged; direct reruns do not use the local AO ERI cache or download basis sets.

Reuse AO ERIs in a new calculation

This workflow needs a TOML or Nickel input, its geometry, and an available basis. --reuse does not run the calculation saved in the bundle or restore its captured source files. Instead, RustiQ prepares the supplied input, checks the bundle for compatible AO ERIs, and runs HF again; it also runs MP2 again if the new input requests MP2. The archive itself supplies reusable artifacts and remains read-only.

cargo run --locked -- run samples/h2/sto-3g/calculation.toml \
  --reuse h2.rustiq --format json --pretty --color never

When a runfile is executed with --reuse or --artifact, its JSON result includes an artifacts entry. A reused AO ERI is reported like this:

{
  "artifacts": [
    {
      "name": "ao_eri",
      "decision": "reused",
      "origin": "archive",
      "source_index": 0
    }
  ]
}

decision says whether the bundle supplied a compatible artifact; the CLI reports reused, missing, or incompatible. origin says where the ERIs actually came from: archive, an enabled local cache, or fresh computation. For example, decision: incompatible with origin: cache means no bundle entry matched but an enabled local cache supplied the ERIs. When an archive entry is selected, source_index is its zero-based position in that bundle. In a batch, each result reports its own selection.

The reuse order is:

1. First compatible AO ERI in the archive’s manifest order.
2. Matching entry in the enabled local AO ERI cache.
3. Recompute the AO ERIs.

The local-cache step is used only when [cache].enabled = true in the runfile. --cache-dir selects the cache location but does not enable caching; see the configuration guide for the input setting.

The archive remains read-only during reuse. To publish a new snapshot from the calculation, provide a new destination:

cargo run --locked -- run samples/h2/sto-3g/calculation.toml \
  --reuse h2.rustiq --artifact h2-updated.rustiq

What can be reused?

AO ERIs are reusable when the effective integral inputs match. RustiQ checks the ordered atomic numbers and nuclear coordinates in Bohr, effective AO basis functions, Schwarz screening setting, and integral representation and computation versions. A matching basis-set label or atom count alone is not enough. HF method and convergence settings, and whether MP2 is requested, do not change AO ERI compatibility. The persistence specification defines the complete identity.

The bundle stores scientific input snapshots and optional AO ERIs. It does not store HF energies, convergence status, orbitals, density matrices, DIIS history, or MP2 results. Save the result JSON separately when those outputs matter. Captured input and geometry bytes are provenance for inspection; they do not affect compatibility, and Nickel imports are not captured recursively. The same reconstruction is available to Rust callers; see the Rust API examples in the persistence specification.

Publication and failures

--artifact publishes the current requested collection; it does not append to the source bundle. A new destination must not exist. An existing destination is accepted only when it resolves to the explicit --reuse source, in which case RustiQ replaces that bundle after producing a complete validated snapshot. Other existing destinations are left untouched.

JSON for a completed calculation or batch may already have been written when a later publication error is reported. See the CLI reference for exact exit and publication behavior and the persistence V1 specification for the archive contract and the EZFIO comparison.