Wavefunctions in qcdata¶
What qcdata returns about a calculation's wavefunction, and why. This is output data.
Programs keep their internal structures and their warm-start state: the standardized
wavefunction is not a restart format (a tight-binding program warm-starts from its
multipole moments and densities, an SCF program from its own copy of the orbitals,
inside a session). Given orbitals (ProgramInput.given) may at most seed a guess.
Principles¶
- One home for every number.
- Store what cannot be derived. The SCF density is C n Cᵀ of the returned orbitals
(
Orbitals.density()); AO integrals that any integral library recomputes from the basis wait for a consumer. - A field arrives with a consumer and a definition two programs can test.
- Models always hold arrays; only saving decides between inline JSON and a file.
- TREXIO: the same physics and names where they agree; our own layout.
Orbitals: the one home of the orbital levels¶
| field | meaning |
|---|---|
spin |
restricted: one coefficient matrix, one set of energies, one Hamiltonian, occupations per spin. unrestricted: everything per spin |
kind |
enum. canonical: eigenvectors of hamiltonian, energies required. natural: eigenvectors of a density, occupations, no energies. localized: no energies; localization names the method. Values are added when a program produces them |
energies_a/_b |
Eh; _b only for unrestricted orbitals |
occupations_a/_b |
both always, each between 0 and 1 |
electronic_temperature |
K; 0 for aufbau occupations |
fermi_level_a/_b |
Eh; None at 0 K, both given above it except for a spin that holds no electrons, which has none. Open shells are filled per spin at fixed n_α and n_β, so there are two |
core_electrons |
one per atom: the electrons the orbitals do not represent, ECP cores or the core a valence-only method leaves out (bookkeeping only; Zn's core is 28 in GFN2 and g-xTB). None: all-electron |
coefficients_a/_b |
optional, nao × nmo, in the AOs of Wavefunction.basis; only on request (output orbitals) |
- Tight binding's open shells (GFN2-xTB) are restricted orbitals of one spin-averaged Hamiltonian with per-spin occupations. They are not ROHF.
- Levels and coefficients are separate because their costs differ. Levels are free and wanted on every frame of an optimization; coefficients cost time (GFN2-xTB on (H₂O)₂₀₀: an energy and gradient take 3.4 s without them, 4.9 s with) and nao × nmo numbers per spin (caffeine in def2-SVP: 246 energies against 60,516 coefficients).
core_electronslives with the levels, not the basis set, so the electron count can be checked on every frame, coefficients or not. All-electron producers write nothing; tight-binding programs give their valence-only cores (no ECP involved), and on every ECP atom it equals the ECP's owncore_electrons.- Where the structure is known (a
ProgramOutputor aFrame),core_electronslists its atoms and the occupations add up to Σ(Z − core_electrons) − charge, to 1e-6 electrons. This checks electron populations, not charges: g-xTB 2.0.1's reference occupations are not integers, so its charges for a neutral molecule sum to −7e-10. A given wavefunction (ProgramInput.given) may come from another charge or multiplicity, so only its atoms are checked. density()raises a clear error when coefficients are missing, as Molden export does.Orbitalsholds no basis set. The basis set describes the AO space that the coefficients and every AO matrix share, so it belongs to their common parent,Wavefunction.basis. An overlap requested alone then ships no coefficients, which for unrestricted orbitals would be twice the overlap's own size.
BasisSet¶
shellsandao_convention. Tight-binding orbitals fit this layout exactly: GFN2-xTB and g-xTB orbitals are orthonormal to 4e-15–8e-15 in an independently computed overlap, and their spherical coefficients map onto their Cartesian ones to 1e-16.ecp: a list ofEcp(center, core_electrons, local: list[EcpTerm], semilocal: list[list[EcpTerm]]), at most one per atom.semilocal[l], for l = 0..L−1, is the channel U_l − U_L, as Basis Set Exchange, NWChem, PySCF and Psi4 store it.EcpTerm(power, exponent, coefficient)is coefficient · r^power · exp(−exponent r²).poweris the power of r (−2 or more): Basis Set Exchange JSON and NWChem write n for r^(n−2), so their converters subtract 2. Scalar ECPs only; spin-orbit terms are refused.- An ECP carries the number of core electrons it replaces, as Basis Set Exchange, NWChem,
PySCF and Psi4 keep it with the potential, so a basis set alone (one built for an
input, or one in
given) is a complete potential and converts to another program without the orbitals.Orbitals.core_electronskeeps, per atom, what the orbitals leave out, which is more than the ECPs for a valence-only method; aWavefunctionchecks that the two agree on every ECP atom. - A basis belongs to one geometry. GFN2's is the same per element at any geometry.
g-xTB's q-vSZP contraction depends on each atom's EEQ-BC charge and coordination number
at that geometry (fixed during the SCF), so the frames of a g-xTB trajectory do not
share a
BasisSet. g-xTB's scaled-exponent H0 basis is internal; the wavefunction's basis is the SCF basis.
Wavefunction: the basis set and AO matrices, on request¶
basis is present whenever coefficients or an AO matrix are, and only then: it is the
AO space they share, in its AOConvention. Each AO matrix is requested by its output
name, the field's (overlap, hamiltonian, core_hamiltonian); the conventions list
what each implies. overlap and core_hamiltonian imply only the basis set;
hamiltonian implies overlap and orbitals.
| field | HF and DFT | tight binding |
|---|---|---|
overlap |
yes | yes: the program's own S, with its screening |
hamiltonian_a/_b |
Fock or Kohn-Sham matrix | tight-binding Hamiltonian |
core_hamiltonian |
yes | — (tight binding's H0 is model data) |
- A Wavefunction always has orbitals; GFN-FF and other force fields return none.
- A
hamiltoniancomes withoverlapand the orbitals' coefficients, and H C = S C ε holds with the returned S only: a screened S (a tight-binding program skips distant primitive pairs) can differ from an exact one by up to 3.4e-9. Its orbitals are canonical, and restricted orbitals have one Hamiltonian. core_hamiltonianis every density-independent one-electron term of the run: T, V_ne with charges Z − core_electrons, V_ecp, and external point charges and fields once a program supports them. tr(P h), with P the density of the SCF's last input, isenergy_components'one_electronterm. With P =Orbitals.density(), the density a reader has, the two agree only to the SCF residual, as for thehamiltonian: compare them at SCF tolerance, never at round-off.- Every matrix is nao × nao of
basis, and the coefficients have one row per AO of it; an AO-indexed array without a basis set, or a basis set without one, is refused. Wavefunction.with_conventionconverts the coefficients and every matrix together, each with its variance: coefficients scale by s per AO index, densities by s_μ s_ν, operators (S, H, h) by 1/(s_μ s_ν). A spherical reordering is a permutation either way; a change of Cartesian normalization is not, so the coefficient transform does not apply to matrices.BasisSet.transformtakes the array's kind (coefficients,operator,density) and never guesses it. Large arrays are converted as arrays, never through Python lists.
The Hamiltonian¶
hamiltonian is the operator of one build at the last build's input x (a density, or
tight binding's charges and multipole moments), however that input was mixed. The
returned orbitals are its fresh generalized eigenvectors with the returned S, so
H C = S C ε holds to rounding (max |CᵀHC − diag ε| below 1e-13 for an exact build).
- Allowed: mixing inputs (Broyden or DIIS on moments, damping of densities).
- Not allowed: combining several builds' operators (DIIS on F or H), damping or level shifting the returned matrix, or returning H and C from different iterations.
- Requesting
hamiltonianchanges no other returned number. - H is F[x], not F of C n Cᵀ: the returned orbitals' density is one step ahead, and the two differ by the SCF residual (1.2e-6–1.6e-6 for caffeine at default thresholds).
How SCF schemes meet the rule:
| scheme | what the program does |
|---|---|
| HF/DFT, F rebuilt from the last density and diagonalized | the final build is always complete, never incremental. Against an incremental final build this moves energies by about 1e-11 Eh and orbital energies by up to 3e-9, and costs about 6% of the time for CPU energies with exact J/K, within the timing noise |
| GFN2-xTB, mixers on input moments | nothing: H is one build |
| g-xTB 1.1, ending with one unmixed iteration | nothing |
| DIIS on the Fock matrix (g-xTB 2.0.1) | one unmixed iteration after convergence: one more iteration, 3–4% more time, and closer to convergence in all 14 cases measured (taxol's energy error against tight thresholds: 1.2e-7 → 2.6e-8 Eh); results move by up to 1e-7 Eh and 4e-5 Eh/bohr |
| a mode that must reproduce another program's numbers exactly, and so keeps its DIIS rule | refuses a hamiltonian request (not_applicable) |
| a composite (a solvation model on a base method) | returns its base part's wavefunction; record names it; H and P do not reproduce the composite energy |
| a force field | wavefunction is None |
What H contains:
- DFT: everything in the SCF operator: V_xc on the run's final grid, plus VV10's nonlocal potential; range-separated exchange; J/K as built (density-fitted when the program fits, COSX K on its final grid); the PCM operator. Nothing for D3/D4 or SMD's CDS term, which do not depend on the density.
- Tight binding: GFN2: H0 plus the potentials of the last input moments (shell, multipole, third order). g-xTB: the unmixed Fock matrix at the last input.
Populations and multipoles (SinglePointData)¶
shell_populations: electron populations Σ_{μ∈shell}(PS)_μμ, indexed likeWavefunction.basis.shells, withshell_atomsandshell_angular_momentaso they stand without a basis (and must match its shells when there is one). Not charges, which depend on method-specific reference occupations.atomic_spin_populations: n_α − n_β per atom, withatomic_spin_populations_kindnaming the partition from the values ofatomic_charges_kind.atomic_dipoles,atomic_quadrupoles: the electronic part only, about each atom (μ_A = −Σ_{μ∈A}(P D)_μμ, integrals about the column AO's atom); quadrupoles Buckingham traceless (3/2 M − 1/2 tr M), 3 × 3 per atom.quadrupole_momentis the Buckingham traceless tensor, with no kind beside it. tblite's molecular quadrupole, which the g-xTB 2.0.1 program prints, counts the off-diagonal charge and dipole parts twice and is not a tensor.
Deferred until a consumer is named¶
| data | why it waits |
|---|---|
kinetic, potential_n_e, ecp_potential, dipole_integrals |
programs could fill them, but any integral library recomputes them from the basis and ECP in milliseconds, and each is a definition two programs must test |
solvent_potential |
H already contains the solvent operator and record names the model; for tight binding, removing it gives no gas-phase answer |
| stored densities | only for densities that are not C n Cᵀ of the returned orbitals (relaxed, response, or a mixed density returned without orbitals), with a kind (scf, relaxed, unrelaxed) |
| two-electron integrals, DF and Cholesky tensors | tight binding has none; a 3-index DF tensor is about 200 GB at 2000 functions. For CC or QMC: MO-basis Cholesky vectors of an active space, exported to TREXIO, on demand |
| tight-binding kernels and H0, DFT grids and response intermediates, GFN2's Slater exponents | specific to one model or one program, or not the functions the program computes with |
Large arrays¶
- Models always hold arrays. No field is ever a file reference: that would make equality, hashing, pickling to workers and moving a result between hosts depend on files beside it. Lazy loading is the reader's business.
- Saving decides by float64 size: an array of more than 1 MiB (131,072 numbers; square matrices from nao ≥ 363) goes to a file beside the JSON, so the same result always saves the same way. Caffeine in def2-SVP stays inline; def2-TZVP does not.
- Each such array is its own
.npyfile beside the saved file, named by the file's stem and the field path (output.results.wavefunction.orbitals.coefficients_a.npy): little-endian float64, C order, uncompressed (compression saves about 4% on coefficients). The JSON holds a pointer in its place with the file's path, the shape, the dtype and the file's sha256. - Inline floats round-trip exactly.
- JSON costs 21.8–23.2 bytes per float64, against 8 in binary. A 2000-function matrix is
32 MB binary and 87–93 MB as JSON (1.2 s in
json.dumps).
TREXIO¶
The same physics and names; our own layout. A converter in qcinf, built on the trexio
package (an optional extra), writes real TREXIO files, tested by a round trip: orbitals →
TREXIO → PySCF energy at the same density.
| TREXIO | qcdata |
|---|---|
nucleus.* |
Structure |
basis.* (flat per-primitive arrays; shell_factor × prim_factor × coefficient) |
Wavefunction.basis.shells (per-atom Shell, one normalization convention) |
ecp.* |
BasisSet.ecp (local and semilocal channels; power of r; z_core as Ecp.core_electrons), Orbitals.core_electrons |
ao.cartesian, ao.normalization |
Shell.pure, AOConvention (spherical_order="trexio" selectable, never the default) |
ao_1e_int.overlap, core_hamiltonian |
Wavefunction.overlap, core_hamiltonian |
ao_1e_int.kinetic, potential_n_e, ecp, dipole |
deferred |
mo.coefficient [mo, ao], mo.spin |
Orbitals.coefficients_a/_b [ao, mo] |
mo.energy, mo.occupation, mo.type, mo.electronic_temperature |
energies_*, occupations_* (per spin, 0..1, where TREXIO keeps one occupation per orbital: the converter checks whether a restricted file's are totals, 0..2), kind, electronic_temperature |
| — | fermi_level_a/_b |
rdm.1e_up/_dn (MO basis) |
Orbitals.density() (AO basis, computed) |
| — (no Fock matrix) | hamiltonian_a/_b |
ao_2e_int, mo_2e_int, determinant, amplitude, jastrow, qmc |
not in qcdata |