Gaussian basis sets

A basis set is a finite collection of functions used to represent molecular orbitals. RustiQ’s Gaussian basis functions are built from Gaussian functions centered on atoms. The chosen basis affects the size of the orbital space and the numerical result. A small basis such as STO-3G is useful for examples but does not guarantee accurate energies or properties.

Import or download a basis

basis import reads a Basis Set Exchange JSON file from the path you provide. It works with the release binary and does not require Cargo or a source checkout. For example, if sto-3g.json is in the current directory:

rustiq basis import sto-3g.json
rustiq basis list

The import itself is local and needs no network access; you must obtain the JSON file separately. On a connected computer, choose a basis and JSON format from the Basis Set Exchange, download the file, and transfer it to the calculation computer if needed. Then import it with the executable command above. In a source checkout, the checked-in STO-3G fixture is available at tests/data/sto-3g.json, and the sample calculation is at samples/h2/sto-3g/calculation.toml:

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

The test suite exercises the fixture using an isolated store in tests/cli_samples.rs and basis import/storage behavior in crates/rustiq-core/src/basis/basis_store.rs.

List, import, or remove locally stored bases with:

rustiq basis list
rustiq basis import /path/to/basis.json
rustiq basis remove sto-3g

The default store is in the platform’s application data directory. Set RUSTIQ_DATA_BASIS to choose its exact path, or RUSTIQ_DATA_HOME to choose the data root. The CLI guide in existing workflows lists platform paths and migration notes.

Online workflow

The default CLI build enables the online feature. Use it to list or download bases:

rustiq basis list --online
rustiq basis download sto-3g

Online commands require network access. A normal run uses the local basis store; automatic downloading can be enabled with --auto-download, disabled with --no-auto-download, or set using RUSTIQ_AUTO_DOWNLOAD. Builds without the online feature can import, list local files, and remove bases but cannot download or query online listings. The commands reflect the CLI tests in tests/cli_samples.rs.

Supported input features

Basis files are imported in the Basis Set Exchange JSON form. A shell groups functions with the same center and angular momentum: \(l=0,1,2\) denote s, p, and d functions. Cartesian and spherical describe two function forms that differ in how angular dependence is represented. For elements used by a molecule, the current loader accepts Gaussian-type and Cartesian Gaussian shells through angular momentum \(l=15\), and spherical Gaussian shells through \(l=2\). It rejects Slater-type shells and effective core potentials (ECPs). Higher angular momentum or other basis-file features should not be assumed to work just because a basis is downloadable. This describes loader support, not numerical validation of all those cases. The checks are in basis.rs.

During basis construction, RustiQ normalizes each Cartesian primitive using its three angular momentum components, then normalizes the contraction for its shell. Spherical functions are formed from normalized Cartesian components. The imported contraction coefficients therefore set the relative primitive weights; their overall scale does not set the resulting function norm. A coefficient group that cancels to the zero function, or whose computed norm is not finite and positive, is rejected with a shell and coefficient-group diagnostic. Contractions that cannot be normalized reliably and unrepresentable normalized primitive coefficients are also rejected. The contraction norm is checked again after normalization; an absolute deviation from unity of \(10^{-6}\) or greater causes rejection. These safeguards do not establish support for arbitrary extreme exponents throughout the integral engine.

Basis choice is one part of a calculation’s accuracy. Convergence, independent agreement, basis quality, and physical validity are distinct checks; see scientific scope. See the glossary for shared basis vocabulary.

Next: TOML configuration.