TOML calculation configuration

Examples in this chapter that use samples/ or tests/data/ require a cloned repository and should be run from its root. Release binaries do not include those files; the first-calculation guide shows how to create equivalent local inputs and obtain a basis.

A TOML input describes one calculation. TOML is the simplest choice: you do not need to learn Nickel or install its executable. RustiQ embeds Nickel internally to supply the same defaults and validation as optional Nickel studies. For a standalone input, reuse calculation.toml generated by rustiq init in the first-calculation guide, keep its geometry and downloaded or imported STO-3G basis available, and run rustiq run calculation.toml.

The checked-in neutral H₂ example below is for a source checkout:

[basis]
name = "sto-3g"

[molecule]
geometry = "../molecule.xyz"

[method.hf.guess]
type = "CoreHamiltonian"

From the repository root, import the basis if needed and run the input:

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

The [molecule] section points to an XYZ geometry and can set charge, multiplicity, and coordinate units. [basis] names a locally available basis. [method.hf] controls Hartree–Fock, and [method.mp2] requests a correlation calculation after HF. See the HF and MP2 guides for interpreting those methods.

For example, the existing MP2 sample adds an MP2 section:

[basis]
name = "sto-3g"

[molecule]
geometry = "../molecule.xyz"

[method.hf]
method = "Rhf"

[method.hf.guess]
type = "CoreHamiltonian"

[method.mp2]
frozen_orbitals = 0

Defaults such as neutral charge, Angstrom coordinates, automatic HF selection, 100 SCF iterations, and a \(10^{-8}\) convergence threshold are filled by the embedded Nickel contracts. The same contracts reject unknown fields and validate values; TOML parsing alone does not describe the full input rules. See calculation inputs and execution for how TOML and Nickel inputs pass through the shared contracts. See the authoritative Nickel input contracts.

Important HF numerical controls include convergence_threshold, max_iterations, diis.enabled, diis.max_history, and orthogonalization.linear_dependency_threshold. MP2 has frozen_orbitals and memory_limit; the latter is a workspace budget, not a process memory limit. The defaults and detailed validation rules belong to the Nickel source, not a second specification in this guide.

Optional local AO ERI cache

The directory-backed AO ERI cache is local, disposable storage. It is disabled by default; enable it in the runfile to allow reuse across runs. The checked-in cache sample below is a complete calculation input; its geometry path is relative to the sample file and points to samples/h2/molecule.xyz:

[basis]
name = "sto-3g"

[molecule]
geometry = "../molecule.xyz"

[method.hf.guess]
type = "CoreHamiltonian"

[cache]
enabled = true

With only the release binary, follow the first-calculation workflow to create calculation.toml, then add this section to that file and rerun it:

[cache]
enabled = true

The short block is a fragment to append to the existing input, not a complete runfile. Then run the local input and inspect its cache entries with:

rustiq run calculation.toml --cache-dir ./rustiq-cache
rustiq cache list --cache-dir ./rustiq-cache

--cache-dir DIR selects the directory for this run but does not enable the cache. The cache can be used as a fallback when a portable bundle has no compatible AO ERI; it is not itself a portable .rustiq bundle. See the portable bundle guide for that reuse order.

The geometry path is resolved relative to the TOML file. If the input is read from standard input, its geometry path is resolved from the current working directory. Geometry file structure and coordinate units are explained in the geometry guide.

The CLI reports diagnostics for malformed TOML, unknown or invalid fields, unavailable bases, and invalid molecular states. Tests cover valid examples and grouped diagnostics in tests/cli_samples.rs and tests/nickel_cli.rs. Successful validation means the requested input is internally acceptable; it does not validate the scientific choice of state or method. See the glossary for shared configuration and scientific terms.