Feature matrix

The capability matrix as of v0.11.0 (codename Sun’s Stingray). For when each feature shipped, see CHANGELOG.md. For what’s coming next, see roadmap.md.

Molecular SCF

Method	Driver	Open-shell	Gradient	Hessian (FD)	Hessian (analytic)	MP2	Validated vs PySCF
RHF	run_rhf	—	✓	✓ (compute_hessian_fd)	✓ (compute_hessian_rhf_analytic)	✓ (run_mp2)	✓ machine precision
UHF	run_uhf	✓	✓	✓	(roadmap 17c)	✓ (run_ump2)	✓ machine precision
RKS	run_rks	—	✓	✓	(roadmap 17e)	—	✓ grid-accuracy
UKS	run_uks	✓	✓	✓	(roadmap 17f)	—	✓ grid-accuracy
ROHF	—	—	—	—	—	—	(roadmap)

Any functional libxc supports works through RKS / UKS (500+ functionals including LDA, GGAs, hybrid GGAs, the τ-dependent meta-GGA family (TPSS, TPSSh, M06-L, M06-2X, SCAN, r²SCAN), and the range-separated hybrids ωB97X and ωB97X-D). HF and DFT analytic gradients are available for LDA, GGA, hybrid-GGA, and the τ-dependent meta-GGA family (modulo the f-shell gradient bug on open-shell UHF / UKS). Meta-GGA analytic Hessians and range-separated-hybrid analytic gradients are still queued. Range-separated hybrids run via direct SCF (not yet density-fitting).

Wavefunction methods (vibeqc.solvers, v0.9.0)

Non-mean-field electronic-structure methods that do not conceptually rely on a Hartree-Fock reference. All reachable through run_job(method=…) and as a standalone vibeqc.solvers import. See user_guide/non_hf_solvers.md and the non_hf_solvers tutorial.

Method	run_job(method=…)	Solver entry point	Notes
Full CI	"fci"	(dense eigh on the full determinant Hamiltonian)	Exact within the (active) orbital space; reference for the approximate solvers. Small active spaces only.
Selected CI (CIPSI)	"selected_ci"	solve_selected_ci	Iterative perturbative selection; target_size, pt2_threshold, optional PT2 correction.
DMRG	"dmrg"	solve_dmrg	Two-site sweep, MPS wavefunction, bond-dimension schedule. Minimal Python implementation — ≤12 orbitals.
Variational 2-RDM	"v2rdm"	solve_v2rdm	Augmented-Lagrangian SDP; currently only the ²D ≥ 0 (P) constraint — not strictly variational yet.
Transcorrelated CI	"transcorrelated_ci"	build_transcorrelated_hamiltonian + solve_selected_ci	Similarity-transformed Hamiltonian (Gaussian / Jastrow correlator) fed to selected CI.

• Active-space truncation: pass active_space=(n_orbitals, n_electrons) to run_job to restrict any solver to a frozen-core / CAS-style window. The runner builds a truncated Hamiltonian from the selected MO block before handing it to the solver. Caveat: the truncation is exact for active_space=(norb, nelec) (full-space identity) but does not yet add the frozen-core h1e dressing or the E_core offset for genuine n_active < norb CAS runs, so absolute energies on real-CAS runs are off by ~E_core. Energy differences at fixed n_active are still meaningful. Tracked by strict xfail in tests/test_solvers_active_space_api.py; see python/vibeqc/solvers/ACTIVE_SPACE.md for the contract.

• Orbital source is decoupled — the solvers operate on an abstract Hamiltonian in an orthonormal MO basis; get_hf_orbital_provider is a convenience, not a requirement.

• Geometry optimisation — wavefunction methods optimise via numerical gradients (run_job(method="fci", optimize=True)); analytic gradients are roadmap.

• Parity — He / OH FCI parity tests and DMRG-vs-FCI cross-checks ship in tests/test_solvers_*.

Density fitting + RIJCOSX (v0.8.0)

JKBuilder polymorphic Fock build via three concrete kernels; see user_guide/density_fitting.md.

Kernel	Driver flags	When
FourIndexJKBuilder	(default)	small (≤250 BFs)
DFJKBuilder (RIJK)	density_fit=True, aux_basis="..."	medium (~250–1000 BFs), hybrid DFT
COSXJKBuilder (RIJCOSX)	density_fit=True, cosx=True, aux_basis="..."	large (>1000 BFs), hybrid DFT

• RIJK gradient: production-ready. The historical ~115 mHa glycine bug closed in v0.8.0; see user_guide/density_fitting.md.

• RIJCOSX SCF + analytic gradient: validated to 0.13 mHa vs ORCA 6.1.1 on glycine / def2-TZVP.

• default_aux_basis_for(orbital_basis_name, kind="jk"/"ri") helper picks aux basis automatically.

Periodic SCF (native GDF/FFTDF in progress)

Method	Driver	k-point support	Notes
RHF, Γ-only GDF	run_rhf_periodic_gamma_gdf	Γ, dim=1/2/3	native vibe-qc J/K via Gaussian density fitting; no in-process PySCF
RKS / hybrids, Γ-only GDF	run_rhf_periodic_gamma_gdf(functional=…)	Γ, dim=1/2/3	native libxc V_xc; hybrid exact exchange uses the functional’s HF fraction
KRHF multi-k GDF	run_krhf_periodic_gdf	Γ + multi-k, dim=1/2/3	native k-dependent GDF; Γ delegates to the Γ-GDF path, any other Monkhorst-Pack mesh runs the full multi-k loop. Also reachable via run_periodic_job(..., gdf_kmesh=(n,n,n))
KRKS multi-k GDF	run_krks_periodic_gdf	Γ + multi-k, dim=1/2/3	native multi-k RKS / hybrid path; PySCF / CRYSTAL are out-of-process references only
Cell-resolved DF integral blocks	compute_2c_eri_lattice_blocks, compute_3c_eri_lattice_blocks, bloch_sum_*_eri_blocks, build_lpq_bloch_native	dim=1/2/3	native translation-resolved 2c/3c storage and Bloch/Lpq assembly for k-dependent GDF; Γ tensors are recovered by summing blocks
BIPOLE RHF / UHF / RKS / UKS, Γ-only	run_pbc_bipole_rhf, ..._uhf, ..._rks, ..._uks	Γ	v0.9.0 CRYSTAL-style BIPOLE Fock build; DIIS-validated on MgO, diamond, silicon. This is the production periodic path today, including open-shell
RHF / RKS / UHF / UKS Ewald-3D (legacy)	run_*_periodic_*_ewald3d	Γ + multi-k	native debug path; not the CRYSTAL-parity target
Multi-k UHF / UKS via GDF	—	—	roadmap (paired with the periodic GDF parity chain, in progress)
ROHF periodic	—	—	roadmap
Atomic gradients (periodic)	compute_gradient_periodic_*	Γ + multi-k	Phase G1; ships for RHF / UHF / RKS / UKS
Periodic stress tensor	compute_stress_tensor	Γ + multi-k	Phase G2; available on all periodic backends

Reference benchmark: ΔE = -6.8e-12 Ha for MgO/sto-3g/Γ RHF vs out-of-process PySCF.pbc.GDF. Multi-k KRHF / KRKS GDF is now native — the multi-k Ewald-gauge fix brings a multi-k mesh to within 0.000 mHa of the Γ-point energy in the molecular limit; there is no in-process PySCF backend.

See user_guide/multi_k_scf.md for the full multi-k story including the dense-Lpq RAM ceiling caveat.

Effective core potentials

libecpint 1.0.7 vendored. Heavy-element chemistry (d-block, lanthanides, actinides) reachable without all-electron basis.

ECP library	Family	Coverage
ecp10mdf	Stuttgart-Köln MDF, 10-electron core	post-K (rows 4+)
ecp28mdf	Stuttgart-Köln MDF, 28-electron core	post-Cd
ecp46mdf	Stuttgart-Köln MDF, 46-electron core	post-Hg
ecp60mdf	Stuttgart-Köln MDF, 60-electron core	f-block (post-Yb)
ecp78mdf	Stuttgart-Köln MDF, 78-electron core	actinides
lanl2dz	Hay-Wadt LANL	post-Na (rows 3+)

Two recipes: manual ECPCenter (always shipped) and vq.auto_ecp_centers(mol, basis_name) (basissetdev- conditional). See user_guide/ecp.md for the full story including the basissetdev policy gating.

Reference: Pt UHF/LANL2DZ = −118.227 Ha (22 BFs, 125 SCF iters).

SCF convergence aids

Aid	API	Coverage	Notes
DIIS extrapolation	*_options.use_diis	molecular + periodic Γ + multi-k	default on, ~10× iter speedup
EDIIS + EDIIS+DIIS hybrid (v0.8.0)	*_options.scf_accelerator=SCFAccelerator.EDIIS_DIIS	molecular + C++ direct-truncated periodic + Python Γ-Ewald (RHF/RKS/UHF/UKS)	flagship for stiff convergence; rollout to Python multi-k Ewald / BIPOLE / GDF in progress
KDIIS (Kollmar)	*_options.scf_accelerator=SCFAccelerator.KDIIS	molecular + C++ Γ-only periodic + Python Γ-Ewald (RHF/RKS/UHF/UKS)	orbital-rotation gradient error; ORCA’s strict-convergence default; multi-k path needs per-k MO-basis design
ADIIS (Augmented Roothaan-Hall)	*_options.scf_accelerator=SCFAccelerator.ADIIS	molecular + C++ direct-truncated periodic + Python Γ-Ewald	EDIIS sibling, no per-iter energy needed
Dynamic damping (Zerner-Hehenberger 1979)	*_options.dynamic_damping, dynamic_damping_min/_max	molecular + C++ direct-truncated periodic + Python Γ-Ewald (RHF/RKS/UHF/UKS)	adaptive density mixing α; composes freely with the accelerator family
Damping (static)	*_options.damping	all	density mixing
CRYSTAL-style FMIXING	*_options.fock_mixing; run_periodic_job(fmixing_percent=30)	molecular + native periodic direct/GDF	Fock/KS matrix mixing; FMIXING 30 = 0.30, separate from density damping
Saunders-Hillier level shift	*_options.level_shift	molecular + periodic Γ + multi-k	Phase C1a
Level-shift warm-up/restart	*_options.level_shift_warmup_cycles; run_*_periodic_gdf(..., level_shift_warmup_cycles=...)	native Γ-GDF + Γ KRHF/KRKS bridge	-1 auto, 0 persistent shift, positive values restart unshifted after that many cycles
Quadratic (“Newton”) SCF	*_options.quadratic_fallback_iter	molecular + periodic Γ + multi-k	Phase C1c — fallback for small-gap systems
Fermi-Dirac smearing	*_options.smearing_temperature; `run_periodic_job(smearing_temperature=”auto”	“metal”	…); vq.SmearingOptions, vq.apply_smearing(), vq.resolve_smearing_temperature()`
auto_optimize_truncation	PeriodicRHFOptions(auto_optimize_truncation=True)	periodic	default on; jointly optimises lattice cutoffs + Schwarz screening

XC functionals (v0.8.0 expanded)

Resolved through libxc 7.0.0; see user_guide/functionals.md. Short aliases the resolver knows:

Alias	Type	HF-exchange	libxc id
lda / svwn	LDA	0 %	1 + 7
pbe	GGA	0 %	101 + 130
blyp	GGA	0 %	106 + 131
b3lyp	hybrid	20 %	475 (was 402; behaviour change at v0.8.0)
b3lyp/g	hybrid	20 %	402 (Gaussian/VWN3 variant; mirrors ORCA B3LYP/G)
pbe0 / pbeh	hybrid	25 %	406
pw1pw	hybrid	20 %	weighted-sum
hse06 (queued)	range-sep hybrid	25 % SR	425

Plus everything libxc accepts directly + custom weighted-sum strings (PW1PW pattern: "0.2*HF + 0.8*GGA_X_PW91, GGA_C_PW91").

B3LYP behaviour change at v0.8.0: b3lyp now resolves to libxc id 475 (VWN5 — the ORCA / ADF convention) instead of id 402 (VWN-RPA / VWN3 — the libxc default and Gaussian convention). Energies move ~10–15 mHa per heavy atom. The new b3lyp/g alias selects the Gaussian-compatible VWN3 variant (libxc 402), mirroring ORCA’s B3LYP / B3LYP/G keyword pair.

Ewald summation (Phase 12e, mostly shipped)

See user_guide/ewald.md for the math

• API.

Sub-phase	Scope	Status
12e-a	Classical Ewald nuclear lattice sum (CoulombMethod.EWALD_3D)	✅
12e-b	erfc-screened nuclear attraction compute_nuclear_erfc_lattice	✅
12e-c-1	Gaussian-charge Ewald V(g) via grid integration	✅
12e-c-2	erfc-screened ERIs for Ewald short-range J/K	✅
12e-c-3a	FFTW3 build dep + solve_poisson_*	✅
12e-c-3b	build_j_long_range + auto_grid	✅
12e-c-3c	Saunders-Dovesi multipolar splitting	⏳ in progress
12e-c-4	End-to-end EWALD_3D SCF dispatch (RHF/RKS/UHF/UKS, Γ + multi-k)	✅

Madelung-constant validation:

Crystal	M reproduced	Reference
NaCl rocksalt	1.7475645946 to 1e-8	1.7475645946…
CsCl	1.76267477 to 1e-6	1.76267477 (±1e-8)
ZnS zincblende	1.63805 to 1e-4	1.63805 (±1e-5)
Simple-cubic jellium	1.4186487 to 1e-6	1.4186487 (Nijboer-De Wette 1957)

External data fetcher (vqfetch, v0.8.0)

Pulls structures + reference data from public databases on demand. Per-record provenance + license preserved.

Subcommand	Source	Default license
vqfetch optimade --formula MgO	OPTIMADE federation	per-provider
vqfetch mp --id mp-1265	Materials Project	CC-BY 4.0
vqfetch cod --id 1011027	COD	CC0 / public domain
vqfetch canonical <slug>	(5 round-trip-verified slugs)	(per primary)
vqfetch reference --cas 7732-18-5	NIST CCCBDB	US Govt public domain

See user_guide/external_structures.md

• user_guide/reference_data.md. End-to-end planetx round-trip: MgO sto-3g RKS-LDA E = −950.4204308512 Ha (13 SCF iters).

Job queue (vq v0.5.6, v0.8.0)

SSH-backed remote job submission co-shipped in vibe-queue/. Cgroup-v2 enforcement, web dashboard, pause/resume, multi-venv --branch routing. See user_guide/queue.md.

Capability	Since
Local queue + CLI + daemon + JobSpec v1 + systemd unit	v0.1.0
Cross-machine SSH submit + ~/.config/vq/config.toml + vq fetch	v0.2.0
Resource watchdog (--mem-mb, --wall-time-seconds, OOM_KILLED / STARVED / TIME_EXCEEDED)	v0.3.0
Cgroup-v2 enforcement (systemd-run scope), pgid-based daemon recovery	v0.4.0
ABORTED_BY_QUEUE terminal state	v0.4.1
Read-only web dashboard (FastAPI + htmx)	v0.5.0
vq pause / vq resume + bearer-token auth + write API	v0.5.1
--all flag on pause/resume + queue-wide POST /api/v1/queue/*	v0.5.2
CRYSTAL14 + PROPERTIES14 reachable through dispatched jobs	v0.5.3
Parallel CRYSTAL14 (Pcrystal/Pproperties default --np 14) + clean systemd PATH drop-in	v0.5.4–5
Multi-venv routing via --branch for vibe-qc dev/release dispatch	v0.5.6

Properties

Property	API	Methods	Notes
Mulliken charges	mulliken_charges	RHF / UHF / RKS / UKS	atomic populations
Löwdin charges	loewdin_charges	all	symmetric-orth populations
Mayer bond orders	mayer_bond_orders	all	per-pair indices
Dipole moment	dipole_moment	all	with optional origin
Natural orbitals	natural_orbitals	all	for post-SCF analysis
Static polarizability α	dipole_polarizability_rhf	RHF (closed-shell)	via CPHF, Phase 17b-1; UHF/KS roadmap
Vibrational frequencies (FD)	compute_hessian_fd + HessianResult.frequencies_cm1	all	FD on analytic gradient; trans/rot projection
Vibrational frequencies (analytic)	compute_hessian_rhf_analytic	RHF	CPHF + libint deriv_order=2; Phase 17b-3
IR intensities	ir_intensities	all	dipole derivatives along normal modes
Thermochemistry (ZPE / U / H / S / G / Cv)	compute_thermochemistry	all	rigid-rotor + harmonic-oscillator + ideal-gas
D3(BJ) dispersion	compute_d3bj	all	Grimme D3 with Becke-Johnson damping
D4 dispersion (v0.8.0)	compute_d4	all	Caldeweyher-Bannwarth-Grimme 2019
Cube file output	write_cube	all	density / orbital / spin density
Molden file export	write_molden	RHF / UHF / RKS / UKS	verified by PySCF round-trip
Periodic band structure	compute_bands	periodic SCF	k-path sampling
Periodic density of states	compute_dos	periodic SCF	tetrahedron + Gaussian smearing

Input / output

Capability	API	Notes
High-level “run-a-job” driver	run_job / run_periodic_job	dispatches to right SCF driver, writes .out + .molden, runs BFGS if asked
Formatted SCF log	format_scf_trace, log_scf_trace	banner, iteration trace, energy components, orbital table, HOMO-LUMO gap
Molden export	write_molden	verified by PySCF round-trip
Geometry trajectory	run_job(..., optimize=True)	ASE .traj file
XYZ load	Molecule.from_xyz	picks up charge / multiplicity
POSCAR load / save	read_poscar, write_poscar	VASP 5 format
Cube load / save	read_cube, write_cube	volumetric data
BXSF (band structure)	write_bxsf	XCrySDen 3D Fermi-surface format

Basis sets

• 142 standard sets bundled (curated subset of libint 2.13.1’s 450+) — STO-nG, 6-31G**, cc-pVxZ, def2 family, ANO-RCC, Karlsruhe core-valence, JKFIT / RIFIT / CABS aux.

• 3 custom sets in python/vibeqc/basis_library/custom/: pob-TZVP, pob-DZVP-rev2, pob-TZVP-rev2 (Bredow-group periodic-tuned).

• CRYSTAL-format parser — imports arbitrary CRYSTAL per-element basis files; converts to libint-compatible .g94. Phase 14f adds CRYSTAL INPUT ECP-block parsing (basissetdev-conditional).

• ECP basis sets — fully wired through libecpint (see ECP section above).

• Future — 87 BSE-fetched sets on basissetdev branch (NOT shipping in v0.8.0; on-demand fetcher design queued for the eventual basissetdev merge — see docs/license.md).

Crystal / lattice infrastructure

• spglib integration: Crystal, analyze_symmetry, to_primitive, irreducible_kpoints.

• POSCAR I/O (VASP 5 format).

• Monkhorst-Pack k-mesh generation with IBZ reduction.

• 1D / 2D / 3D PeriodicSystem geometry.

• Hexagonal and other skew-cell geometry support; the native EWALD_3D Hartree path uses the analytical AO-pair FT on the full reciprocal metric.

Validation

Test class	Count	Level
Molecular 1e integrals vs PySCF	24	machine precision
RHF / UHF / RKS / UKS energies vs PySCF	59	machine precision (HF), grid-accuracy (DFT)
MP2 / UMP2 / RI-MP2 / SCS-MP2 / SOS-MP2 / B2PLYP vs PySCF	55	1e-9 Ha (MP2 family) / 1e-7 Ha (B2PLYP)
Gradients (HF, DFT) vs FD / PySCF	17	1e-6 Ha/bohr
FD Hessian skeleton vs FD-on-gradient	8	1e-4 to 1e-3
Analytic RHF Hessian vs PySCF analytic	8	2.5e-9 Ha/bohr², freqs <0.01 cm⁻¹
FD Hessian + IR + thermochemistry vs PySCF	51	1e-7 Ha
CPHF + polarizability vs PySCF FD	11	1e-5 a.u.
Periodic machinery (invariants, molecular limit, Bloch folding)	76	machine precision
Periodic SCF convergence aids	27	per-test scoped
Periodic native GDF/FFTDF parity	planned	compare parsed out-of-process CRYSTAL and PySCF outputs
Multi-k KRHF/KRKS native parity	planned	no in-process PySCF backend
JKBuilder + RIJCOSX vs ORCA 6.1.1 (v0.8.0)	curated	RIJCOSX max |Δ| = 0.13 mHa on glycine def2-TZVP
vqfetch acceptance harness (v0.8.0)	5 structures + 8 molecules	round-trip end-to-end
Crystal / POSCAR / basis parsing	18	—
Parametrised basis-load + single-atom SCF (basissetdev)	366 cases / 236 files	360 pass + 18 xfail (basissetdev branch only)

Plus the full regression suite at examples/regression/ (since v0.7.2 Boys’ Crucible) covers the cross-code parity matrix (vibe-qc vs PySCF vs ORCA) on a curated S22 / X23 / pob-TZVP test set.

Full pytest suite: ~1800 test functions across ~190 files covering the molecular, periodic, wavefunction-solver, and output stacks; runs in ~3–4 minutes on an M-class MacBook (faster with pytest -n auto).

Known issues

See the warning admonition on docs/index.md for the live open-bugs list. Highlights:

• Periodic GDF parity (compcell + multi-k + AFT) is the in-progress flagship (held to PySCF parity as the only gate; not yet closed — see the roadmap). The Γ-only BIPOLE driver is the production periodic path today.

• Multi-k dense Lpq RAM ceiling (multi-TB on production systems). Streaming-Lpq tracks with the periodic GDF work.

• Si-diamond × 3 + C-diamond / PBE / pob-TZVP ~mHa drift vs PySCF (suspected DIIS-tightness, not algorithmic).

• Open-shell UHF / UKS analytic gradient on f-shells with two or more different second-row elements still disagrees with ORCA. Closed-shell direct gradients now auto-route through the DF gradient path; the open-shell auto-route is queued.

• AUTO initial guess (SAP on closed-shell light-atom systems) oscillates on long n-alkanes and on H2CO + PBE. Pin InitialGuess.SAD to work around.

• pob-TZVP / pob-TZVP-rev2 missing Ne entry.

• Heavy-atom basis-load test OOMs a 16 GB laptop in batch mode; route via vq submit to a larger box.

• ωB97X / ωB97X-D UKS on orbital-near-degenerate radicals needs a level shift to converge.

• 3c composite methods are calibrated on molecular systems; the periodic flavours need recalibration before being trusted.

The B3LYP local-correlation convention change (libxc 402 to 475) is documented on the homepage as informational, not a bug.