JSON output

Use JSON when another program needs calculation results. run writes only the machine-readable result to standard output:

cargo run --locked -- run samples/h2/sto-3g/calculation.toml --format json

Run commands from the repository root and make the named basis available first. To save machine-readable output, redirect standard output and disable color explicitly:

cargo run --locked -- run samples/h2/sto-3g/calculation.toml --format json --color never > result.json

For readable terminal inspection, add --pretty:

cargo run --locked -- run samples/h2/sto-3g/calculation.toml --format json --pretty

--pretty requires --format json. Compact JSON is unstyled; when saving pretty output for another tool, use --color never to disable syntax colors.

A TOML input produces one calculation result. A one-entry Nickel array also uses the single-result schema. A multi-entry Nickel study produces a batch document with one outcome per input, in source order. Each entry can be success, non_converged, or error. Later calculations continue after a recoverable per-calculation error, but fatal infrastructure errors stop the batch. Any recorded error or nonconvergence makes the overall command exit unsuccessfully. A valid JSON document can therefore accompany a failing exit status. For a batch, any entry error or non-convergence makes the command exit unsuccessfully while retaining the batch document. A single HF-only calculation that does not converge still produces the single result document with converged: false; its energy and diagnostics describe the final iterate, and the command exits successfully. If MP2 was requested, non-converged HF prevents MP2 execution and the run is reported as an error instead. Input, preparation, or runtime errors for a single calculation are reported as CLI diagnostics, so there is no single-result JSON document for that failed run. See the Nickel studies guide for batch outcomes.

Results include schema_version, which lets consuming software select the matching contract. The single-calculation contract is calculation-output-v1.schema.json; batch output uses batch-output-v1.schema.json. These versioned schemas are authoritative; this guide does not repeat their field definitions. See also the reference index.

When run uses --reuse or --artifact, calculation results add an optional artifacts field describing AO ERI selection and its origin. For example, a bundle hit appears as:

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

decision describes whether the archive supplied a compatible AO ERI; origin identifies the archive, enabled local cache, or fresh computation that supplied the ERIs actually used. A bundle hit also includes its zero-based source_index. The field is omitted when neither option is used, and batch results report it on each calculation entry. See the portable bundle guide for the full workflow and the CLI reference for details.

Nickel batch JSON

The checked-in Nickel study runs two calculations. Follow that guide’s basis-set setup first, especially when running offline, then produce pretty JSON with colors disabled:

cargo run --locked -- run samples/h2/study.ncl --format json --pretty --color never

The output follows the versioned batch schema. Each successful calculation contains a result following the single-calculation schema linked above. Inspect the status of every calculation; a batch can include non-converged or failed entries even when it produces valid JSON. --color never prevents ANSI escape sequences in redirected output.

Energies are in Hartree. JSON preserves full floating-point values for comparison and downstream processing, while terminal tables round energies for readability. Do not compare a rounded terminal value against a tight numerical tolerance. Existing JSON CLI tests validate both schemas and full-precision H₂ output in tests/json_output_cli.rs. The checked-in reference tests compare JSON values against PySCF 2.14.0 for selected systems; see scientific scope. For terminology used in result fields, see the glossary.