Command-line reference

Run these commands from any working directory with the installed rustiq binary. From the repository root in a source checkout, replace rustiq with cargo run --locked --. rustiq --help and rustiq <command> --help show the options supported by the installed build.

Commands

The geometry tools and basis storage are utilities around a calculation; they do not create a .rustiq portable artifact. See the geometry guide and existing workflows for examples of geometry, init, and basis management commands.

init options include --output (calculation.toml by default), --force, --basis (sto-3g), --charge (zero), --multiplicity, --units (angstrom by default, or bohr), --hf (auto, rhf, or uhf), and --mp2. Without an explicit multiplicity, it selects singlet for an even electron count and doublet for an odd count. This is a starting convention; choose the physical state appropriate to the molecule. The existing workflows documents path and overwrite behavior.

run options and input selection

The input filename extension selects TOML, Nickel (.ncl), or a portable .rustiq bundle. TOML describes a single calculation. Nickel can describe one calculation or an ordered array; an array of one uses the single-calculation output contract, while a larger array uses the batch contract. A .rustiq input reconstructs and reruns its archived resolved calculation(s); multi-entry bundles use the batch contract. Nickel imports resolve relative to the importing file. Geometry paths resolve relative to the top-level input file; for TOML read from standard input, they resolve from the current working directory. Direct archive reruns cannot be combined with --reuse, --artifact, --cache-dir, --auto-download, or --no-auto-download; the source bundle is read-only and provides its resolved basis and inputs. Archive reruns do not use the local ERI cache or basis-download settings. Text output shows SCF progress; JSON output suppresses progress and writes only the result document.

Important options:

The cache directory path is resolved from the caller’s current working directory. Pass the same --cache-dir to cache list or cache remove to manage entries from a run that used a custom cache root.

The CLI reports input, basis, preparation, and single-run calculation errors as diagnostics. A single HF calculation that reaches its iteration limit returns its final-iteration result with a successful process status and, in JSON, converged: false. MP2 requires converged HF. For a multi-calculation Nickel or .rustiq batch, recoverable per-entry errors do not prevent later entries from running; the JSON document records each outcome, but any error or non-convergence makes the overall process exit unsuccessfully. Fatal infrastructure failures stop the batch. JSON output for an unsuccessful batch is still a valid document. The exact output fields are defined by the versioned schemas; see the JSON guide for examples and interpretation. For a single calculation, an input, preparation, or runtime failure is reported as a diagnostic and does not produce result JSON. A non-converged single HF run is a result, not a runtime failure.

Feature availability

Basis downloads and online basis listing require a build with the online feature. The standard CLI enables it; offline builds provide import, local listing, and removal. Geometry transformations are CLI utilities, not calculation input transformations unless their output file is then used as an input.

From the repository root, import the checked-in STO-3G and 6-31G basis fixtures before running these examples:

cargo run --locked -- basis import tests/data/sto-3g.json tests/data/reference/RustiQ/basis_sets/6-31g.json
cargo run --locked -- run samples/h2/sto-3g/calculation.toml
cargo run --locked -- run samples/h2/study.ncl --format json --pretty --color never
cargo run --locked -- run samples/h2/sto-3g/calculation-cache.toml --cache-dir ./rustiq-cache
cargo run --locked -- cache list --cache-dir ./rustiq-cache

The Nickel study uses both STO-3G and 6-31G; importing only STO-3G is insufficient unless basis auto-download is enabled in an online build. The TOML and cache examples require only STO-3G. See the Nickel studies guide for the individual import commands. The relative ./rustiq-cache directory is resolved from the caller’s working directory on Windows, Linux, and macOS.

The H₂ TOML and Nickel examples are exercised by tests/cli_samples.rs, tests/nickel_cli.rs, and tests/json_output_cli.rs. The JSON tests also check pretty-printing of Nickel batches. The cache-enabled input is samples/h2/sto-3g/calculation-cache.toml; its store-then-hit behavior is covered by test_cli_h2_sample_uses_eri_cache_when_enabled_in_runfile in tests/cli_samples.rs, in addition to the Rust core persistence tests.

Calculation input contracts

TOML and Nickel inputs use the same calculation settings. The embedded Nickel contracts are authoritative for defaults, allowed fields, types, and validation; the CLI does not define a separate TOML-only set of defaults. Consult the TOML guide for sections and checked-in examples, then the geometry, Hartree–Fock, and MP2 guides for the corresponding scientific settings. The Nickel contracts and their validation are linked from the reference index.

The following settings are accepted by both TOML and Nickel. This is a navigation aid, not a second schema: exact defaults, value constraints, and cross-field validation remain defined by the linked Nickel contract.

The accepted density guesses and their fields are defined in the Nickel contract; see the HF guide for their use. The cache stores AO ERI data only; it does not store Hartree–Fock or MP2 results, and a cache hit does not guarantee that every calculation will run faster.

Cache and portable bundles

The local AO ERI cache (atomic-orbital electron-repulsion integrals) is a disposable optimization for deterministic two-electron integrals. It is disabled by default in the calculation input; --cache-dir only selects where enabled cache entries are stored. Use cache list and cache remove to inspect or remove entries. Missing, invalid, or incompatible entries are recomputed. The local cache is not a deliverable or a portable calculation file.

Portable .rustiq bundles use the V1 ZIP/ZIP64 format described by the authoritative persistence specification. The format is conceptually inspired by EZFIO in Quantum Package 2 (qp2), but uses an independent archive structure and APIs; see the comparison. For a guided create, inspect, and reuse workflow, see the portable bundle guide. Bundles are separate from the disposable local AO ERI cache. Reuse opens its source read-only. For each requested calculation, RustiQ selects the first compatible, supported AO ERI in bundle order; when none is available, an enabled local cache is checked before recomputation. A corrupt selected payload is an error. A source entry can supply data to multiple calculations in a Nickel batch.

cargo run --locked -- run samples/h2/sto-3g/calculation.toml --artifact h2.rustiq
cargo run --locked -- run samples/h2/sto-3g/calculation.toml --reuse h2.rustiq --artifact next.rustiq --format json
cargo run --locked -- artifact inspect h2.rustiq --format json
cargo run --locked -- artifact verify h2.rustiq
cargo run --locked -- run h2.rustiq
# Replace the source bundle after all requested calculations produce results:
cargo run --locked -- run samples/h2/sto-3g/calculation.toml --reuse h2.rustiq --artifact h2.rustiq

Publication captures the current requested calculation collection and its compatible known artifacts. It does not append history. An existing destination is accepted only when it resolves to the explicit --reuse source; otherwise the command fails without replacing it. Publication happens after every requested calculation produces a result. Preparation or execution errors prevent publication of the collection and leave the destination unchanged. An HF-only non-converged result can contribute its AO ERI. A Nickel batch containing only non-converged HF-only results can publish its bundle even though the command exits unsuccessfully. If MP2 was requested but HF does not converge, execution fails and the bundle is not published. HF orbitals, SCF restart state, DIIS history, and MP2 results are not persisted.

When --reuse or --artifact is used, JSON calculation results include an optional artifacts array. decision reports archive selection (reused, missing, or incompatible); origin reports the ERI actually used (archive, cache, or computation). A reused item includes its zero-based source_index. Without these options the existing JSON result shape is retained. run FILE.rustiq --format json uses the regular single-calculation or batch result schema but does not include this reuse-decision array: the bundle is the implicit artifact source for that mode. Publication failures are reported on stderr and return a failing exit status; JSON results for a completed calculation or batch may already have been written.

artifact inspect PATH displays requested and resolved scientific snapshots, producer details, artifact representations, and captured source names and sizes. In text mode, canonical TOML and XYZ are syntax-highlighted when color is enabled by --color or RUSTIQ_COLOR; JSON output remains structured JSON. It validates the archive index, provenance, snapshots, and declared artifact sizes, but does not hash or decode numeric payloads. Use artifact verify to check supported payloads eagerly; otherwise, execution checks a payload when its scientific stage selects and reads it. Inspection does not execute calculations or establish scientific validity. JSON output follows the artifact inspection V1 schema. artifact verify PATH eagerly reads and validates supported numerical payloads. It currently checks compact AO ERI payload hashes, NPY encoding, array dimensions, and consistency with the declared AO basis. It reports an error for an invalid payload or unsupported representation. Verification does not run a calculation or establish scientific validity. The archive captures exact bytes of the main input and geometry files as shared provenance; it does not capture Nickel’s full import graph. See the persistence specification for the archive contract and API details.

Output contracts

run --format json selects one of two versioned contracts: the single calculation schema or the batch schema. schema_version identifies the contract; schemas, rather than this manual, define the complete field sets. The JSON guide describes output selection, standard output behavior, failure cases, and the existing automated checks.