Roadmap¶

vibe-qc follows semantic versioning. Pre-1.0 releases are milestone-based: each 0.N.0 tag marks the completion of a major capability. 1.0 is reserved for “feature complete across both molecular and periodic methods — everything a standard QC program offers.” 2.0 delivers the cyclic cluster model, the original motivating feature.

The milestone list below is the engineering roadmap. The Tutorial parity matrix at the bottom is the user-facing roadmap, pinned against ORCA’s molecular tutorials and CRYSTAL’s solid-state tutorials so we can see what works today and what’s blocking the next chunk of “real chemistry.”

Milestones¶

`v0.1.0` — shipped 2026-04-18¶

Molecular HF/DFT/MP2 stack validated against PySCF; periodic scaffold with one-electron infrastructure, Γ-only RHF, multi-k RHF, and multi-k KS-DFT (LDA/GGA) all validated in the molecular-limit regime; spglib integration; pob-* basis sets integrated from a CRYSTAL-format parser; documentation scaffold; MPL 2.0 license.

`v0.2.0` — quantitative 3D bulk¶

Phase 12e: Ewald + Saunders–Dovesi multipolar splitting, shipped in sub-phases.

✅ 12e-a — classical Ewald for point-charge nuclear lattice sum. CoulombMethod.EWALD_3D routes nuclear_repulsion_per_cell through Ewald; Madelung constants of NaCl, CsCl, ZnS, simple-cubic jellium reproduced to literature precision. See user_guide/ewald.md.
✅ 12e-b — erfc-screened nuclear attraction as an Ewald building block. Public API vibeqc.compute_nuclear_erfc_lattice; real-space, exponentially convergent.
✅ 12e-c-1 — Gaussian-charge Ewald for the long-range V(g) via grid integration of the smooth complement. α-invariant to 1e-4.
✅ 12e-c-2 — erfc-screened ERIs for the short-range Ewald J/K. omega parameter on build_jk_gamma_molecular_limit and build_fock_2e_real_space.
✅ 12e-c-3 — long-range Hartree J via FFTW3 Poisson convolution. ✅ 12e-c-3a adds FFTW3 as a build dependency and ships solve_poisson_erf_screened / solve_poisson_coulomb. ✅ 12e-c-3b ships build_j_long_range + auto_grid (J_LR via density-on-grid sampling, FFT convolution, AO-pair re-integration). ⏳ 12e-c-3c — Saunders–Dovesi multipolar splitting for the tight-core far field (handles e.g. STO-3G O 1s analytically; flips the H₂O xfail test in 12e-c-4a to pass).
✅ 12e-c-4 — end-to-end CoulombMethod.EWALD_3D SCF dispatch. ✅ 12e-c-4a composed Ewald-3D Hartree J + ω-invariance validation. ✅ 12e-c-4b Γ-point periodic RHF SCF using EWALD_3D (run_rhf_periodic_gamma_ewald3d). ✅ 12e-c-4c-i multi-cell periodic density grid + periodic J_LR. ✅ 12e-c-4c-ii Pulay DIIS in the Γ-Ewald driver. ✅ 12e-c-4c-iii-a multi-k Ewald Fock builder. ✅ 12e-c-4c-iii-b multi-k Ewald RHF SCF driver (run_rhf_periodic_multi_k_ewald3d). ✅ 12e-c-4c-iv Madelung-cancellation helpers for neutral crystals. ✅ 12e-c-4-end-to-end CoulombMethod-aware SCF dispatcher (run_rhf_periodic_scf + run_rhf_periodic_gamma_scf) routing on lattice_opts.coulomb_method, plus internal-consistency bulk-benchmark suite covering H₂ / LiH / MgO / Ne (convergence, ω-invariance, EOS scan, multi-k = Γ-only at [1,1,1] equivalence). ✅ 12e-c-4c-iii-c Pulay DIIS in the multi-k Ewald driver — per-k commutator error vectors with a k-weighted Frobenius inner product on the Pulay B matrix; lifts tight-cell [2,2,2] meshes from non-converging-under-pure-damping to converged in O(few) iters. ⏳ CRYSTAL cross-check pass on LiH / NaCl / MgO / Si at published geometries is the remaining gating item for the v0.2.0 tag — needs reference CRYSTAL output to tighten the witness bounds.
✅ 12f — periodic Becke weight partition for DFT integration in tight crystals. Ships C++ build_grid_periodic(grid_mol, partition_atom_positions, opts) (extends the Becke fuzzy-cell partition denominator over home + image atoms within a radius), Python helpers vibeqc.build_periodic_becke_grid and vibeqc.extended_partition_atoms, and the PeriodicKSOptions.use_periodic_becke / becke_image_radius_bohr flags wiring it into run_rks_periodic. Tight-cell volume sanity (Σ_g w_g ≈ V_cell) and molecular-limit equivalence both validated.

Concurrent infrastructure shipped in 0.2.x¶

These landed alongside the Ewald work and aren’t gated on it:

✅ P1: OpenMP shared-memory parallelism on the main hot kernels (one- and two-electron integrals via libint, the direct / DF / RIJCOSX Fock builds, MP2 / UMP2 AO-to-MO transforms, analytic gradients including the periodic gradient path, the Schwarz prescreener, the periodic XC integrator, lattice multipole moments, and the CCSD intermediates). Engine-per-thread plus thread-local accumulator pattern. The in-tree COSX Obara-Saika kernel, the FFT-Poisson J build, the ECP integral evaluator, and the SAD / SAP guess builders are still serial; those are tracked under the perf roadmap as parallelism gaps rather than under P1.
✅ P1.1 — gradient parallelism completion + set_num_threads() / get_num_threads() API + num_threads= keyword on run_job + per-section timing report. See user_guide/scf_convergence.md.
✅ P1.2 — close remaining OpenMP parallelism gaps: dipole integrals, the AO→MO transform and energy accumulation in MP2 / UMP2, and the per-cell loops in build_xc_periodic. With this, every compute-heavy kernel vibe-qc ships is OpenMP-parallel.
✅ Reliability — canonical orthogonalisation for linearly-dependent AO bases (handles tight diffuse-basis cases like H₂ at 0.5 bohr / aug-cc-pVTZ); pre-flight linear-dependence diagnostic; empty-BasisSet rejection (catches missing LIBINT_DATA_PATH entries); Functional dtor crash fix (the real cause of the meta-GGA segfault flagged in tutorial 15).
✅ P2 — pre-flight memory estimator with abort-on-overflow and memory_override= escape hatch. vq.estimate_memory(), vq.check_memory(), InsufficientMemoryError. See user_guide/memory.md.
✅ I/O workflow — run_job driver writing .out (banner + geometry + memory budget + SCF trace + orbital table + properties + timing), .molden for orbital viewers, optional .traj.

`v0.2.5` — space-group symmetry exploitation (core)¶

The biggest single periodic-performance lever we can pull: use the crystal’s space-group operators to reduce real-space matrix block storage, integral evaluation, and (later) k-point sampling. For high-symmetry ionic crystals (NaCl, MgO; O_h, |G|=48) this is an order-of-magnitude speedup and a |G|-fold memory reduction. For low-symmetry cells (P1) it’s a no-op with no cost — the phase is strictly a performance enhancement, never a correctness change.

What’s already shipped as substrate:

spglib integration (v0.1.0) — detects the space group and returns the operator set {(R_i, t_i)}.
IBZ k-point reduction (v0.1.0) — vibeqc.irreducible_kpoints.

What Phase SYM adds:

✅ SYM1 — AO-basis representation of every symmetry operator. For each operator R and each shell of angular momentum l, compute the Wigner D-matrix D^l(R) that maps χ under R. Pure spherical-harmonic basis (vibe-qc forces set_pure(true)) keeps the rep block-diagonal in l. Validated against the standard Wigner identities: D^l(R_1 R_2) = D^l(R_1) D^l(R_2) and D^l(R)^T D^l(R) = I. A follow-up commit extended wigner_d_real to improper rotations (det R = −1) via the inversion factorisation, unlocking the full O(3) coverage that real point groups need.
✅ SYM2 — real-space matrix-block reduction. Three sub-phases: ✅ SYM2a ships build_ao_permutation_matrix — the full (n_bf, n_bf) AO permutation matrix P(R) composing SYM1’s Wigner D’s with the per-atom permutation induced by (R, t). ✅ SYM2b ships orbit identification + LatticeMatrixSet compression for the origin-fixed-atom case: store one representative per h ↦ R·h orbit; reconstruct via block(R·h) = P(R) · block(h) · P(R)^T. ✅ SYM2c ships atom-pair-resolved orbits for the general (non-origin-fixed) case — covers ionic crystals like NaCl where sub-lattices pick up shifts under most operators. Orbits are triples (a, b, h) under (a, b, h) ↦ (π(a), π(b), R·h + s_a − s_b).
✅ SYM3a — symmetry-reduced storage for one-electron lattice integrals. Ships vibeqc.compute_overlap_lattice_with_orbits, compute_kinetic_lattice_with_orbits, and compute_nuclear_lattice_with_orbits plus the OrbitReducedLatticeMatrix view, symmorphic_operations filter, and verify_lattice_matrix_set_symmetry debug witness. Storage shrinks by the orbit compression ratio (~|G|× on high-symmetry crystals; 6.6× on simple cubic Pm-3m He / sto-3g with cutoff 10 bohr). Round-trip compress / reconstruct is exact to machine precision (~10⁻¹⁶) for S, T, V on Pm-3m.
SYM3b — symmetry-reduced compute: integral kernels skip shell-pair × cell triples equivalent under the point group and scatter the result to all orbit members. Applies to every one- and two-electron integral kernel vibe-qc ships. (Not yet shipped — the natural next symmetry phase, where the |G|-fold reduction hits wall-clock instead of just memory.)

Validation: reproduce the v0.2.0 bulk energies (LiH, NaCl, Si) to machine precision with and without symmetry enabled. Measure wall-clock reduction across the symmetry-enabled / disabled pair on simple-cubic (|G|=48) vs monoclinic (|G|=4) vs triclinic (|G|=1).

The remaining symmetry pieces (SYM4 IBZ Fock build, SYM5 symmetrized gradient, SYM6 SALC/irrep projection during SCF) ship in later milestones where they pay for themselves:

SYM4 bundles with Phase C1 (v0.4.0 — tight-cell SCF convergence).
SYM5 bundles with Phase G1 (v0.5.0 — periodic gradients).
SYM6 ships when we need irrep-controlled SCF for transition-metal / open-shell periodic cases (v0.4.0 or later).

(The SYM label avoids a collision with Phase S1 — implicit solvation — in v0.5.0. Tag namespaces: SYM* = symmetry core; S1 alone = solvation.)

Reference path: public group-theory texts (Bradley & Cracknell; Altmann & Herzig) and PySCF.pbc.symm are enough to implement and cross-check; CRYSTAL source access is helpful for edge-case coverage but not required.

`v0.3.0` — visualization + post-SCF properties¶

User-facing observables and the writers viewers actually consume.

✅ V1 cube files (molecular density + MOs, multi-volume MO stacks). Read by VMD, Avogadro, PyMOL, ChimeraX. See user_guide/volumetric_data.md.
✅ V2 Molden export (libint→Molden AO permutation handled).
✅ V3b XSF + BXSF writers (periodic structure, periodic volumetric, BXSF Fermi-surface band data). Read by VESTA / XCrySDen.
✅ V4 vibeqc.bands.band_structure + kpath_from_segments + matplotlib plotter (vibeqc.plot.band_structure_figure). See user_guide/band_structure.md.
✅ V5 vibeqc.bands.density_of_states over a Monkhorst–Pack mesh
- matplotlib plotter (vertical or horizontal, combined bands+DOS panel).
✅ 18 Mulliken / Löwdin charges + Mayer bond orders. See user_guide/properties.md.
✅ 19 dipole moment (RHF/UHF/RKS/UKS), validated against PySCF to ~1e-6 a.u. on H₂O / 6-31G*.
✅ V3 periodic Bloch-orbital cube / XSF writers. Ships vibeqc.evaluate_bloch_orbital, make_primitive_cell_grid, write_cube_mo_periodic, write_xsf_density, write_xsf_mo in vibeqc.periodic_orbitals — periodic AO evaluator with the proper Bloch phase factors so periodic MOs export to formats VESTA / XCrySDen / VMD read directly.
✅ V5b projected DOS — atom-projected and (atom, l)-projected via a Mulliken-style projector against the Bloch-summed overlap. Ships vibeqc.density_of_states_projected, density_of_states_projected_hcore, ao_groups_per_atom, ao_groups_per_atom_l, and the ProjectedDensityOfStates dataclass (re-exported from vibeqc.bands).
✅ NO natural orbitals + idempotency diagnostic on SCF results. Ships vibeqc.natural_orbitals(D, S) returning a NaturalOrbitals dataclass (occupations + coefficients) and vibeqc.idempotency_deviation(D, S) for SCF density health checks. Useful for post-SCF visualization, bonding analysis, and catching density-matrix drift.
16 hybrid periodic DFT (PBE0, B3LYP) validated against CRYSTAL reference energies.

`v0.4.0` — shipped 2026-04-27 — heavy elements + open-shell periodic + tight-cell SCF¶

Second tagged release, and the first one that’s defensibly “production-grade for real solid-state chemistry.” The line of reasoning was: tagging earlier (“research preview” at v0.2.0 / v0.3.0) would have shipped a code that hit a wall the moment a user tried a metal, oxide-surface, or magnetic system and watched SCF oscillate. v0.4.0 added the SCF-convergence machinery (Saunders- Hillier level shift, Fermi-Dirac smearing), end-to-end EWALD_3D across {RHF, UHF, RKS, UKS} × {Γ-only, multi-k}, ECPs via libecpint, and the doc-side polish (six new tutorials, push-deployed CI). See the v0.4.0 changelog for the full release notes.

This release also unblocked the bulk of the CRYSTAL “Modeling Specific Systems” tutorials — see the parity matrix below for the new ✅ / 🟡 entries.

✅ C1a — Saunders-Hillier level shifting for periodic SCF. PeriodicRHFOptions.level_shift / PeriodicSCFOptions.level_shift / PeriodicKSOptions.level_shift (Hartree, default 0.0) add b · (S − ½ S D S) to F before diagonalisation, raising virtual MO eigenvalues by b while leaving the SCF fixed point unchanged. Wired into the Γ-Ewald and multi-k Ewald drivers; reported MO energies are physical (un-shifted). Molecular RHF/UHF/RKS/UKS level shifting deferred to a follow-up.
✅ C1b — Fermi-Dirac smearing + fractional occupations in the multi-k Ewald RHF/RKS drivers. PeriodicRHFOptions.smearing_temperature / PeriodicSCFOptions.smearing_temperature / PeriodicKSOptions.smearing_temperature (Hartree, default 0.0). vq.kelvin_to_hartree_temperature(T_K) converts user-facing Kelvin temperatures to the k_B T value stored in the options. When set, occupations follow n_i = 2 / (1 + exp((ε_i − μ) / T)) with bisection on μ to satisfy the per-cell electron-count constraint; introduces an electronic-entropy contribution to the free energy A = E − T S. The multi-k Ewald result objects carry free_energy, entropy, fermi_level, and per-k occupations arrays. Convergence is checked on the free energy (variational under smearing). C++ side ships real_space_density_from_kpoints_fractional for the inverse-Bloch fold over fractional occupations. Currently periodic Ewald RHF/RKS only — molecular RHF/UHF/RKS/UKS smearing and periodic UKS smearing are follow-ups.
C1c — second-order / quadratically-convergent SCF as a fallback when DIIS + smearing still oscillate. Targets the hardest tight-cell cases.
14 libecpint integration (ECPs) — unlocks pob-* for Rb–I, Cs–Po, La–Lu. Metal oxides, perovskites, lanthanoids accessible. ✅ 14a vendored libecpint build (v1.0.7 pinned alongside pugixml 1.15 and libcerf 3.3 via scripts/build_libecpint.sh; same self-contained pattern as third_party/libint/). CMake find_package(ecpint) + RPATH baked so the compiled module resolves @rpath/libecpint.1.dylib from the vendored install with no Homebrew / system fallback. vibeqc.libecpint_version() smoke test passes; full regression unaffected by the new link. ✅ 14b ECP matrix elements via libecpint’s built-in XML library. vibeqc.compute_ecp_matrix(basis, ecp_centers, library_name, share_dir) returns V_ECP_{μν} = ⟨χ_μ|V_ECP|χ_ν⟩ in the spherical AO basis. Cartesian → spherical transform per shell-pair via libint’s solidharmonics::tform_cols/tform_rows primitives. Supports the standard Stuttgart-Köln ECPs (ecp10mdf, ecp28mdf, ecp46mdf, ecp60mdf, ecp78mdf) plus LANL2DZ. share_dir defaults to the vendored third_party/libecpint/install/share baked at build time. Empirical witness: Zn / 6-31G + ecp10mdf → 27×27 symmetric V_ECP, eigenvalues bounded in [-0.5, 472] Ha (core projector pushes core orbitals up — physically correct). ✅ 14c ECP wiring into all four molecular SCF drivers (RHF / UHF / RKS / UKS). Added ecp_centers: List[ECPCenter] and ecp_library: str fields on RHFOptions / UHFOptions / RKSOptions / UKSOptions (defaults: empty list, empty string = "ecp10mdf"); when ecp_centers is non-empty the SCF adds V_ECP to Hcore once before the iteration loop. Empty list reproduces the all-electron path bit-for-bit. Empirical witness: Zn²⁺ at 6-31G with ecp10mdf converges in 9 iterations to E ≈ −551.5 Ha (10-electron core replaced; 18 valence electrons in 3d¹⁰). ✅ 14e validation against PySCF (which also links libecpint). Caught a real correctness bug: when ECPs are used the bare nuclear V double-counts because libint’s compute_nuclear uses the full Z while the ECP already encodes the core’s nuclear contribution. Fixed by adding compute_ecp_one_electron(basis, mol, ecp_centers, ecp_library) that builds V_n with effective charges Z_eff = Z − ncore, computes V_ecp via libecpint, and computes the effective nuclear repulsion Σ_{A<B} Z_eff_A Z_eff_B / R_AB. Each of the four molecular SCF drivers now routes through this shared helper. Empirical witness: vibe-qc Zn²⁺ / 6-31G + LANL2DZ matches PySCF to better than 1 µHa (E = −62.456043 Ha — exact to printed precision). ⏳ 14d CRYSTAL parser ECP block reader.
15 periodic UHF / UKS — open-shell periodic SCF for magnetic systems, defects, spin-polarized transition-metal compounds. ✅ 15a Γ-point periodic UHF with the EWALD_3D Coulomb dispatch (vibeqc.run_uhf_periodic_gamma_ewald3d). Independent α / β density matrices, Hartree J via the composed Ewald split + per-spin K via the full-range real-space builder, per-spin Pulay DIIS, ⟨S²⟩ contamination diagnostic. Closed-shell H₂ matches RHF to ~10⁻¹⁰ Ha; H atom doublet reports ⟨S²⟩ = 0.75 = S(S+1) exactly; PySCF cross-check on H atom UHF passes within the Makov-Payne finite-box bound (~50 mHa). ✅ 15b multi-k periodic UHF (run_uhf_periodic_multi_k_ewald3d) on top of the multi-k Ewald RHF substrate. Per-spin Pulay DIIS, per-spin level shift, ⟨S²⟩ from the Γ-block MOs. Six lattice-ERI builds per iteration vs three for the closed-shell driver (J_SR(D_total) + J_LR(D_total) + 2 × {J_full(D_σ) + F_full(D_σ)} for K extraction). Closed-shell H₂ at [1,1,1] mesh matches the multi-k Ewald RHF energy bit-for-bit; H atom doublet reports ⟨S²⟩ = 0.75 exactly. Surfaced and fixed a quiet binding bug: LatticeMatrixSet.blocks returns a fresh Python list copy each access, so lms.blocks[i] = matrix writes to a transient list and never reaches the C++ vector — silently a no-op. Affected the multi-k Ewald RHF damping path (_damp_lattice_matrix) which appeared to work because every existing test runs with DIIS active. Fixed by exposing a LatticeMatrixSet.set_block(i, M) method that mutates the underlying C++ storage in place. ✅ 15c periodic Ewald-DFT (closed- and open-shell, Γ-only and multi-k). Shipped end-to-end in three sub-phases:
- 15c-1 Γ-only periodic RKS SCF with EWALD_3D Coulomb (run_rks_periodic_gamma_scf dispatch / run_rks_periodic_gamma_ewald3d backend). DFT counterpart of 12e-c-4b (Γ-only RHF Ewald): F = Hcore + J_ewald(ω, D) + V_xc[ρ(D)] − (α/2) K(D) with α = func.hf_exchange_fraction.
- 15c-2 multi-k periodic RKS SCF with EWALD_3D Coulomb (run_rks_periodic_scf dispatch / run_rks_periodic_multi_k_ewald3d backend). DFT counterpart of 12e-c-4c-iii (multi-k RHF Ewald).
- 15c-3 Γ + multi-k periodic UKS SCF with EWALD_3D Coulomb (run_uks_periodic_gamma_scf / run_uks_periodic_scf). Per-spin Fock construction; closed-shell H₂ at any k-mesh matches the RKS Ewald energy bit-for-bit. Open-shell DFT companion to 15a/15b (UHF Ewald).

`v0.5.0` — molecular Hessian + full k-point sampling¶

Codename: Wilson’s Otter. First release under the Scientist’s-Animal codename policy (see § Release codenames). E. Bright Wilson — FG-matrix vibrations pioneer, co-author of Molecular Vibrations (1955) — anchors the milestone’s primary flagship feature: molecular Hessian → vibrational frequencies → thermochemistry.

Milestone shape note. The original v0.5 plan bundled dispersion, solvation, periodic forces + stress + phonons, and a job queue all into a single 30–50-day release. After a user-driven scope rebalance the kitchen-sink was split into smaller single-headline releases (v0.5 → v0.13, see below). Each subsequent minor release has exactly one flagship feature so bug reports against a specific version are actionable, regression hunts are bounded, and ship cadence stays brisk. v0.5 itself absorbs two flagships because the K-Phase work landed during the same development cycle as the molecular Hessian — both were ready to ship together.

🎯 Primary headline feature — molecular analytic Hessian + IR intensities + thermochemistry. Turns vibe-qc from “computes energies” into “does chemistry”: frequencies, ZPE, ΔG, TS verification, KIE-ready, all at once.

🎯 Secondary headline feature — full k-point sampling support (K-Phase). Public vibeqc.KPoints builder with seven construction modes — Monkhorst-Pack, Γ-centered, shifted, Γ-only, IBZ-reduced, HPKOT band paths via seekpath, explicit user lists, density-based auto-mesh (KPPRA / kspacing / VASP Auto). Closes the “manual k-list construction” gap versus CRYSTAL’s SHRINK and VASP’s KPOINTS.

Molecular Hessian (Phase 17)¶

✅ 17a-1 finite-difference Hessian + harmonic frequencies (Wilson FG analysis, mass-weighted projection, trans/rot zero-mode enforcement).
✅ 17a-2 IR intensities — dipole-derivative tensor, Wilson–Decius–Cross intensity formula in km/mol.
✅ 17a-3 thermochemistry — translational + rotational + vibrational partition functions → ZPE / U / H / S / G at any T, p.
✅ 17b-1 CPHF infrastructure — Krylov solver with PySCF- compatible orthonormality fix and orbital-energy response.
✅ 17b-2 skeleton 2nd-derivative integral wrappers around the vendored libint deriv-order=2 build.
✅ 17b-3 analytic RHF Hessian — assembles the full closed-shell HF Hessian from skeleton + CPHF mo1 / mo_e1. Matches PySCF analytic Hessian to <1e-7 Ha/bohr².
✅ 17c analytic UHF Hessian — per-spin extension. Validated against PySCF on triplet O₂ and OH radical (LGMRES converges where vanilla GMRES stalls on small open-shell CPHF).
✅ 17d analytic RKS Hessian — KS extension with libxc fxc kernel in the CPKS response, FD-on-gradient skeleton (avoids 2nd-deriv AO
- Becke partition machinery). LDA + hybrid (B3LYP) covered.
✅ 17e analytic UKS Hessian — closes the open-shell-DFT branch. LDA + pure-GGA covered analytically; hybrid-GGA UKS (B3LYP UKS) marked xfail and falls back to the FD path until 17e-2 lands the polarized-GGA fxc kernel (queued for v0.5.1).
✅ 17e-2 (kernel) spin-polarised GGA fxc kernel — Functional::eval_polarised_gga_fxc (libxc xc_gga_fxc, spin = 2; the 15 second-derivative pieces). Shipped in v0.8.x and consumed by UKS-GGA / hybrid-GGA second-order SCF (Newton / TRAH) via make_polarised_gga_xc_kernel_builder. Wiring this kernel into the analytic UKS Hessian CPKS response (closing the B3LYP-UKS xfail above) is the remaining 17e-2 sub-task.

K-Phase — full k-point sampling support¶

✅ K1 public vibeqc.KPoints Python builder with Monkhorst-Pack / Γ-centered / shifted / Γ-only constructors; classical-MP auto-shift convention (even meshes shift=1, odd meshes shift=0); back-compat with native BlochKMesh via as_bloch_kmesh().
✅ K2 IBZ reduction via spglib — wires the use_symmetry=True C++ codepath. Hex/trigonal cells (SG 143–194) refuse non-zero MP shifts with an actionable error pointing at gamma_centred (the classical (½,½,½) offset breaks the three-fold symmetry). KPoints.symmetry_reduce() builder method.
✅ K3 band-path k-points via seekpath (HPKOT convention, Hinuma 2017). KPoints.band_path(sys) autodetects Bravais type from spglib spacegroup, returns the canonical Hinuma path; manual override via scheme="manual" + segments.
✅ K4 explicit user-supplied list — KPoints.from_list(sys, k_frac, weights=None) with auto-normalisation.
✅ K5 density-based auto-mesh — KPoints.from_kppra(sys, n_kpts_per_atom, metallic=False) (AFLOW convention, Curtarolo 2012); KPoints.from_kspacing(sys, kspacing) (Materials Project / ASE); KPoints.auto(sys, length) (VASP Auto mode). The metallic flag bumps the default density and warns if smearing isn’t enabled.
✅ K7 unified integration — run_rhf_periodic_scf and run_rks_periodic_scf accept KPoints directly via the boundary helper as_bloch_kmesh(). Demo: examples/periodic/input-k-mesh-convergence.py.

Other v0.5 deliverables¶

✅ D1 Grimme D3-BJ dispersion correction — shipped early in 0.2.x. D1a C++ framework (CN-dependent c6, BJ damping, gradient); D1b reference dftd3 Python backend; D1c wired through run_job + ASE calculator. See tutorial 14.
✅ M1 ORCA .hess ASCII writer — drops vibe-qc Hessians into the moltui / chemcraft / avogadro / VMD-nmwiz visualization ecosystem. vq.write_orca_hess(path, mol, hessian_result, ...).
✅ M2 Multi-XYZ trajectory + .opt writers — geometry- optimization animations, NEB images, normal-mode movies, MD snapshots. vq.write_xyz_trajectory(path, frames), vq.write_opt_trajectory(path, frames, energies) (auto-formats "step N E = … |grad| = …" into the comment line), vq.normal_mode_trajectory(mol, hess, mode_index) helper for one-line normal-mode-movie construction. Reads in moltui / OVITO / ASE / Avogadro / PyMOL.
✅ ASE-A/B/C vibeqc.ase Calculator extensions — exposes Hessian, dipole, polarizability, free energy as ASE properties so Atoms-driven workflows (ase.vibrations, ase.optimize, ase.neb) drive vibe-qc end-to-end without per-property glue code.
DOC1-light bundled reference outputs for the canonical Hessian / IR / thermo workflows. Trimmed from the original DOC1 scope (which covered every tutorial) to just the v0.5 headline calcs: H₂O HF/STO-3G frequencies, B3LYP IR intensities, NH₃ inversion ΔG. Full tutorial-wide coverage is now the per-quarter docs-cadence chore (DOC1-full) — see docs/release_process.md § “Documentation cadence”. Demoted from a tagged minor so a docs sprint does not gate a tag.

`v0.5.x` — observability patch series¶

The v0.5.0 ship surfaced a recurring need: users running multi-minute periodic / large-basis calcs want to see what’s happening during the run and where the time went afterwards. Two sibling patch releases address this — both extend the v0.5.0 surface, neither breaks API.

v0.5.1 — live SCF logging. (In progress, separate dev chat.) Real-time per-iteration progress to stdout / file. Shows the user that the SCF is actually doing something during a 20-min build, with iteration energy / |ΔE| / max-gradient / DIIS-error / per-iteration wall-time. Opt-in via run-options flag and / or env var. The user-facing reason the SCF “hangs” silently today.
v0.5.2 — performance / debug log (M3). Opt-in post-mortem breakdown to a sibling output.debug (or output.perf) file recording per-major-code-path:
- Wall-time + CPU-time per phase (overlap / kinetic / nuclear / ERI / J / K / XC quadrature / Bloch sums / DIIS / eigensolver)
- Memory footprint snapshots at major SCF transitions (peak + current RES, swap on Linux)
- Thread utilisation (omp_get_max_threads() vs measured per-phase utilisation; flags under-parallelised hot paths)
- Cell-list / grid statistics for periodic + DFT runs (n_cells, n_grid_points, integral-screening efficiency)
- Per-iteration SCF breakdown (ΔE, max-grad, DIIS B-matrix condition number, error-vector L2 norm, Fock-build time, density-update time)
Implementation: python/vibeqc/perf.py PerfTracker + a perf_log(path) context manager. Off by default; enabled via VIBEQC_PERFLOG=output.debug env var, programmatic with vq.perf_log("output.debug"): ..., or run_job(..., perf_log="output.debug"). Hot-loop C++ instrumentation guarded behind #ifdef VIBEQC_PERFLOG so release builds without it pay zero runtime cost.

Pairs with v0.5.1 live logging — live shows progress; perf gives the post-mortem breakdown. Together they close the observability gap that surfaced in real-world v0.5.0 usage.

Deferred from the original v0.5 scope — each gets its own focused minor release below:

Item	New milestone
Periodic atomic gradients (G1)	v0.6
Periodic stress tensor (G2) + slab builder (B1)	v0.x.x (deferred — did not ship in v0.8.0)
Phonons (Phase 21)	v0.x.x (deferred — did not ship in v0.8.0)
Implicit solvation (S1)	v0.9
DFT+U / Dudarev rotationally-invariant Hubbard correction (U1)	v0.9 ✅
Grimme D4 dispersion (D2)	v0.10
Geometry-symmetrize pipeline (GS)	v0.13 (alongside GR k-grids)
DOC1-full (tutorial-wide bundled outputs)	per-quarter docs-cadence chore — see `release_process.md`
Personal job queue (JQ1) + cluster-bridge docs (JQ2)	v0.12
Generalised-Regular k-grids (K6)	v0.13
ML k-mesh predictor (K-ML)	post-1.0

Acceleration program (multi-release)¶

Wall-clock performance is the gating axis between vibe-qc as a research playground and vibe-qc as a production tool. The acceleration work splits into integral / Fock-build acceleration, locality exploitation, reciprocal-space and basis tricks, SCF convergence acceleration, and algorithmic / hardware. Each sub-release below targets one box and stacks multiplicatively on the ones below. Pre-v0.5.5 the periodic Fock build had no integral screening at all; the very first item here closed a 100-1000× wall- clock gap on real crystals like LiH/STO-3G/4×4×4. The remaining items buy the next 100-1000×.

`v0.5.5` — Cauchy-Schwarz screening (foundation, shipped)¶

🎯 The bedrock under everything below. Pre-screening, periodic build_fock_2e_real_space was O(n_c³ · n_shells⁴) libint quartet calls per Fock build × ~30 SCF iters × 3 builds-per-iter for the Ewald-split HF path — minutes-to-hours on real crystals. Schwarz caps the integral magnitude analytically per quartet × cell triple:

| ⟨μ_0 ν_g | λ_λ σ_σ⟩ | ≤ Q[c_g][μ,ν] · Q[c_σ−c_λ][λ,σ]

with Q[c][s_a,s_b] = √|⟨s_a_0 s_b_c | s_a_0 s_b_c⟩| precomputed once. Quartets bounded below LatticeSumOptions.schwarz_threshold (default 1e-12 Ha) skip the libint call. Translational invariance collapses the Q tensor to a function of one relative lattice vector; Gaussian shell-pair products decay exponentially with |R|, so the lattice-sum truncation becomes rigorous instead of ad-hoc. Wired into both build_fock_2e_real_space (the full real- space ERI path) and build_jk_gamma_molecular_limit (the Γ-only periodic J/K builder); both share the same per-cell Q precompute helper. Coverage stops at the energy-side Fock build for v0.5.5; gradient ERIs use a separate threshold (see v0.6.x below).

References: Häser & Ahlrichs 1989; CP2K’s EPS_SCHWARZ (1e-7 energies, tighter for forces); CRYSTAL’s TOLINTEG 5-vector.

`v0.10.0` — ✅ shipped — multi-k Fock-call coalescing (small, near-free win)¶

Shipped at v0.10.0 via the real Python accelerator family + block-vector multi-k EDIIS (eb8f25bd), with the multi-k Ewald drivers wired through M2b / M2d / M2e (see CHANGELOG [v0.10.0]).

🎯 Drops one full real-space J build per SCF iter on the EWALD_3D multi-k RHF/hybrid path. Motivated by a 2026-05-25 pyinstrument run on LiH/STO-3G/4×4×4 (/tmp/lih_pyinst.txt) showing ~99.5% of the multi-k iter wall lives in the C++ build_fock_2e_real_space kernel — so any redundant call to that kernel is wall-time visible.

The pre-2026-05-25 build_fock_2e_ewald3d_blocks (python/vibeqc/periodic_fock_multi_k.py:59) made three real-space 2e-build calls per invocation for hybrid/HF:

build_fock_2e_real_space(α=0, ω>0) → J_SR
build_fock_2e_real_space(α=0, ω=0) → J_full
build_fock_2e_real_space(α, ω=0) → F_full = J_full − ½α·K_full

then extracted K via K_full = (J_full − F_full)·(2/α). Calls 2 and 3 both traverse the shell-quartet × cell-triple lattice loop at ω = 0, redundantly computing J_full twice. Switching to build_jk_2e_real_space (already exposed at cpp/src/bindings.cpp:3924 for the symmetry-reduced builds) returns (J_full, K_full) from a single traversal, eliminating one full J pass per SCF iter.

Expected savings: ~25-33% per-iter wall on RHF/hybrid multi-k. Pure DFT (α = 0) was already short-circuited and is unaffected.

Risk: low — single-file Python wrapper change; the fused C++ entry already exists, is tested via the symmetry-reduced path, and the algebra is exact (F_full − J_full ≡ −½α·K_full is a mathematical identity, not an approximation). Test pin: tests/test_periodic_fock_multi_k.py exercises Hermiticity, Γ-realness, time-reversal symmetry, Hcore composition — all of which should pass bit-exactly under the fused call since K is computed by the same C++ impl.

`v0.11.x` — 🎯 queued — finer-grained `auto_optimize_truncation` step¶

Retargeted from a stale v0.9.x slot (v0.9.x patch line is closed). No CHANGELOG Added entry pinning a shipped state yet.

🎯 Wall-clock observation from the same 2026-05-25 profile run: auto_optimize_truncation jumped LiH/STO-3G’s cutoff 12 → 18 bohr in one ×1.5 step (cutoff_growth_factor default in eigs_preflight.optimize_truncation), landing at overlap min-eig ≈ +1e-1 — orders of magnitude above the PSD danger zone, suggesting the bump was excessive. The C++ Fock cost scales as ~n_c³ ≈ (cutoff/a)⁹/8, so going 18 → 15 bohr would cut work by ~5× on this benchmark.

Two non-mutually-exclusive options:

Tighten the default cutoff_growth_factor from 1.5 → 1.25 (more evaluations, but closer-to-minimal final cutoff).
Run the Phase-2 cutoff-bisection (eigs_preflight.py:730-755, currently gated on joint_growth=False) even when joint_growth is True, so we claw back the cutoff over-shoot using the tighter Schwarz we already paid for.

Validation: should be PSD-safe on every benchmark the v0.5.5 + v0.6.x Schwarz program shipped against. The pob-TZVP case (MgO/4×4×4) needed cutoff 18 bohr in the same profile run; the proposal needs a regression test that pob-TZVP doesn’t undershoot.

`v0.6.x` — separate exchange threshold + gradient screening¶

Sx1 LatticeSumOptions.schwarz_threshold_forces: separate threshold for the gradient ERI pass (CP2K’s EPS_SCHWARZ_FORCES convention). Default 1e-14 — tighter than the energy threshold because force convergence is dominated by the slowly-decaying tail of the integral derivative (loose Schwarz on derivatives is non-rigorous; the standard fix is to tighten by ~100× relative to the energy threshold).
Sx2 Wire screening into eri_lattice_gradient_contribution (the periodic Pulay-derivative pass). Same Q precompute, with schwarz_threshold_forces controlling the per-quartet skip. Required for production-quality periodic forces; the unscreened gradient pass is currently the dominant cost on a relaxation step.
Sx3 Density-weighted screening (LinK-style, Ochsenfeld 1998): fold the local |D_λσ| block into the bound, replacing the conservative D_max envelope. In an insulator the density matrix decays exponentially in real space, which is what enables genuine O(N) exchange for periodic gapped systems. Metallic systems remain harder by construction — the density matrix does not decay, and any production-quality periodic hybrid for metals needs ADMM (see v0.9.x acceleration row) or smearing-aware screening.

`v0.7.x` — RI / density fitting + RIJ-COSX (1st acceleration wave)¶

🎯 The single biggest multiplicative lever. Expands the product density ρ_μν(r) = χ_μ(r)·χ_ν(r) in an auxiliary basis, turning 4-index ERIs into contractions of 3-index and 2-index quantities. Formal cost drops from N⁴ to N³ with a small prefactor; accuracy is controllable via the auxiliary basis.

RI1 RI-J for the Coulomb build — essentially free at chemical accuracy (Eichkorn et al. 1995; Whitten 1973). Auxiliary basis loading from libint’s built-in JKfit / Cfit families.
RI2 RI-K for exchange (loose-fit / chain-of-spheres-style).
RIJCOSX seminumerical exchange via Neese’s chain-of-spheres (COSX) — pairs RI-J with COSX-K for 10–100× speedups on hybrid DFT in molecules. The workhorse in ORCA. Variant: sn-LinK (Laqua / Ochsenfeld) with rigorous integral screening.
PBC-RI Periodic RI — 3-index ERIs over real-space lattice sums + Ewald-split aux Coulomb metric (Sun, Berkelbach et al. for PySCF.pbc). Couples to the v0.5.x Ewald split machinery.

`v0.11.x` — 🚧 partial — fast multipole methods (long-range Coulomb)¶

Partial. The multipole-core machinery shipped via BIPOLE’s L_max ∈ {0, 1, 2} levels (CRYSTAL-style far-field; the BIPOLE chat owns the periodic surface; use_multipole_far_field knob in 584679df). The pure-FMM tree (CFMM / continuous FMM / PBC-FMM proper) is still queued — retargeted from a stale v0.9.x slot.

For the long-range 1/r₁₂ part of the J build. Schwarz alone fails here because the operator decays only conditionally; the standard fix is to hierarchically group distant charge distributions into multipole expansions.

FMM1 Continuous fast multipole method (Strain / White-Head- Gill / GvFMM). O(N) for the Coulomb part of J.
PBC-FMM Periodic FMM (Kudin & Scuseria 1998 / 2004) — handles lattice sums directly without Ewald reciprocal-space machinery. Alternative to the v0.5.x Ewald split for systems where FMM is more efficient.
CSAM Combined Schwarz + multipole (CFMM-style). Schwarz in the near field, multipole estimates in the far field.

`v0.12.0` — 🎯 queued — locality exploitation (hybrid DFT for big cells)¶

Retargeted from a stale v0.9.x slot (v0.9.x patch line is closed). Feature-grade architectural work — promoted to a v0.12.0 slot rather than the patch line.

Once exchange is the bottleneck and gapped systems are the target, the locality of the density matrix becomes the dominant lever.

ADMM Auxiliary density matrix method (VandeVondele, Krack, Mohamed et al., CP2K). Computes exact exchange in a smaller auxiliary basis and corrects with a GGA exchange difference term. The reason HSE06 calculations on 1000+ atom periodic systems are feasible in CP2K. Critical for the catalysis / electrochemistry use case.
OT-SCF Direct minimisation via orbital transformation (VandeVondele & Hutter, JCP 2003). Avoids diagonalisation, scales linearly in nbf for large cells, eliminates the Aufbau / occupation ambiguity. The standard for large CP2K runs.
Linear-scaling DFT for insulators (nearsightedness, Kohn). Localised orbitals (NGWFs / support functions) optimized in situ — ONETEP, BigDFT, CONQUEST, SIESTA’s order-N. Far-future, but the exponential decay of P(R) in gapped systems makes this natural for vibe-qc’s CCM target.

`v0.10.x` — 🎯 queued — reciprocal-space and basis tricks¶

Owned by the gapw chat (PAW / GAPW / GPW / ACE architectural track). v0.10.x is the current patch line and stays as the target slot.

PAW Projector augmented wave (Blöchl 1994). All-electron accuracy at modest plane-wave cutoffs. Standard for VASP / ABINIT / GPAW.
GAPW Gaussian-augmented plane-wave (Lippert / Hutter, CP2K). Pure-Gaussian periodic codes plus an auxiliary plane- wave grid for the Hartree term — linear scaling for J.
GPW Pure GPW (the Hartree-only variant of GAPW; pseudo only).
ACE Adaptively compressed exchange (Lin Lin 2016). Reformulates the non-local exchange operator into a low-rank form. Order-of-magnitude speedups on plane-wave HSE / PBE0 in Quantum ESPRESSO. Translation to Gaussian-based periodic is an open research question; revisit when ACE bibliography matures.
Range-separated split refinements Beyond the v0.5.x Ewald- 3D split: tighter ω heuristics + per-system ω optimization.

`v1.x` — algorithmic and hardware acceleration¶

GPU acceleration Integral evaluation, tensor contractions, cubic-scaling diagonalisations all map well to GPUs (TeraChem / BrianQC / GPU4PySCF / GPU CP2K via DBCSR). Reduced precision (mixed FP32/FP64, FP16 for some steps) gives further 2-4×.
Tensor decompositions THC (tensor hypercontraction) / Cholesky decomposition / ISDF (interpolative separable density fitting — increasingly popular for periodic GW / BSE). CD is essentially RI with a numerically generated auxiliary basis, controllable accuracy for free.

Beyond SCF — local correlation methods¶

Pinned here for completeness; the post-HF analog of v0.9.x locality. Already on the canonical roadmap below as v0.17 (reduced-cost CC):

DLPNO-CCSD(T) (Riplinger / Neese) — near-canonical accuracy at a small fraction of the cost. PNO-MP2 / LNO-CCSD(T) / Kallay’s variants / CIM (Li) are siblings. Periodic translation via fragment methods + embedded cluster (CCM!).

SCF convergence accelerators (mostly at v0.5.x scope)¶

These come earlier than the multi-release waves above because they are mostly Python-level + small C++ hooks:

EDIIS / ADIIS / A-DIIS (Kudin / Garza) — improvements on Pulay DIIS for difficult cases (transition metals, broken symmetry).
Second-order SCF (Newton-Raphson / SOSCF / Augmented Hessian). Essential for transition-metal / open-shell and BS cases that DIIS plateaus on.
Better initial guesses SAD (atomic density superposition), SAP (atomic potential), GWH (generalised Wolfsberg-Helmholz) for molecules. Density mixing across k-points + careful k-mesh for solids.

Prioritisation summary¶

If standing up the periodic capability for catalysis / electrochemistry / solid-state today, the first wave to deploy on top of Schwarz is:

RI-J + ADMM for hybrids (covers HSE06 on 1000+ atoms).
OT-based SCF for large systems (avoids the diagonalisation wall).
DLPNO-CCSD(T) on cluster models for benchmarking.

The second wave layered on top:

COSX / sn-LinK if molecular hybrid DFT dominates workload, ACE if plane-wave hybrids do.
A serious GPU build of whichever code is the production tool.

Schwarz screening sits underneath all of this as the foundation; RI + ADMM + OT + GPU stacked on top is where the wall-clock factors of 100× and 1000× actually come from.

SCF guess + convergence program (multi-release)¶

Performance gets you a fast Fock build per iter; a good guess plus a robust SCF accelerator gets you fewer iters and higher convergence rate on hard cases. Both axes need work. This program tracks the end-to-end SCF workflow: where you start (initial guess), how you progress (damping / DIIS / second-order), and how you stop (how robustly + how cheaply). The whole program is wired uniformly across all four flavors — RHF / UHF / RKS / UKS — and across both molecular and periodic entry points. CRYSTAL-style manual atomic occupations are exposed as an opt-in override on top of all guess methods.

The work splits along two axes:

Axis	Item	Status / target
Guess	CORE (Hcore)	shipped pre-v0.5
Guess	Level shift on virtual block (Saunders–Hillier 1973)	partial — molecular only at v0.5; periodic at v0.6.x
Guess	SAD (atomic density superposition)	v0.6.x flagship
Guess	SAP (atomic potential superposition)	v0.6.x sibling
Guess	Extended Hückel (parameter-free) / PModel	v0.9.x
Guess	MINAO (minimal-AO projection of SAD)	v0.9.x
Guess	FRAGMO (fragment-MO assembly)	v0.9.x
Guess	READ / restart (orbitals from prior calc)	v0.9.x
Guess	Broken-symmetry (high-spin → GUESSMIX → 45° rotation)	v0.9.x
Guess	Manual atomic occupation override (CRYSTAL-style)	v0.6.x
Conv	Linear damping (density-mixing on D)	shipped
Conv	CRYSTAL-style FMIXING (static Fock-mixing on F)	v0.6.x
Conv	Dynamic damping (Zerner–Hehenberger 1979)	v0.6.x
Conv	Pulay DIIS	shipped
Conv	EDIIS (Kudin / Scuseria / Cancès 2002)	shipped (D1a)
Conv	EDIIS+DIIS hybrid (Garza / Scuseria 2012)	shipped (D1c)
Conv	ADIIS (Hu / Yang 2010)	v0.9.x
Conv	LIST family / ODA (Cancès & Le Bris 2000)	v0.9.x
Conv	Saunders–Hillier level shift (level shift on F_vv)	v0.6.x
Conv	SOSCF (Newton–Raphson; Bacskay 1981, Fischer–Almlöf 1992, Neese 2000)	shipped RHF / UHF / RKS / UKS (D2c Newton, D2d SOSCF, D2e TRAH) across LDA / GGA / hybrid-GGA — UKS-GGA via the Phase 17e polarised GGA f_xc kernel; meta-GGA second-order pending (τ-dependent f_xc)
Conv	Augmented Hessian / TRAH (Helmich-Paris 2022)	v0.9.x
Conv	ARH (Host et al. 2008) / CIAH (Sun, PySCF 2017)	v0.9.x sibling
Conv	OT direct minimisation (VandeVondele & Hutter 2003) — periodic	v0.9.x flagship
Conv	Anderson mixing (Anderson 1965)	v0.10.x
Conv	Broyden mixing (Johnson 1988, Eyert 1996)	v0.10.x
Conv	Kerker preconditioner (Kerker 1981)	v0.10.x
Conv	Pulay–Kerker mixing (Kresse & Furthmüller 1996)	v0.10.x
Conv	Periodic Pulay (Banerjee et al. 2016)	v0.10.x
Conv	Fermi–Dirac / Methfessel–Paxton / Marzari–Vanderbilt smearing	partial — Fermi-Dirac shipped on periodic multi-k Ewald RHF/RKS + multi-k GDF KRHF (Γ-only Ewald inherits via dispatch); UHF/UKS, BIPOLE, Γ-GDF, C++-direct Ewald, MP, MV all queued at v0.10.x (see `docs/design_smearing.md` for the matrix + milestone plan, `.release-status/v0.10.x/smear.md` for status)

`v0.6.x` — initial-guess overhaul (flagship: SAD + SAP)¶

🎯 The user-visible win. Closes the v0.5.6 NaCl-bombing-with- Hcore-guess class of failure mode: ionic insulators where the Hcore guess is so far from physical that DIIS amplifies the swing into the +30 000 / −16 000 Ha territory and never recovers. SAD / SAP make NaCl / MgO / Na metal converge in 5–15 iters from the first call.

G2a Atomic density library — precomputed spherical atomic RHF / UHF densities for Z = 1 … 86 across STO-3G, 6-31G(d), cc-pVDZ, def2-TZVP, pob-TZVP. Stored as (nbf_atom, nbf_atom) numpy arrays keyed on (Z, basis_name). Built once via the molecular RHF/UHF path on isolated atoms.
G2b SAD assembly — sum atomic densities into the unit-cell density matrix at AO indices keyed by atom-bf ranges. For periodic, replicate the unit-cell SAD into all cells in the lattice cutoff (D(R) = D₀ · δ(R) is the Γ-only convention; the multi-cell SAD picks up the same atomic density at every image).
G2c SAP assembly — sum tabulated radial atomic effective potentials (Lehtola 2019 / Lehtola, Visscher, Engel 2020 erfc fits) on the AO grid. Skip the Fock build entirely for the guess — diagonalize T + V_SAP → C₀ → D₀.
Cheaper than SAD, especially attractive for solids where the atomic Fock build per Z is dominated by ERIs.
G2d AUTOSAD fallback — for atoms or basis sets without a precomputed atomic density / potential, build it on the fly via a single isolated-atom RHF/UHF run. Cached per (Z, basis, charge, multiplicity) for the rest of the process.

G2e Smart defaults per system type:

System type	Default guess
Closed-shell molecule	SAP
Open-shell molecule	SAD-UHF
Transition-metal complex	SAD-UHF + Saunders–Hillier shift
Ionic insulator (any periodic)	SAD
Covalent semiconductor	SAD
Metallic crystal	SAD + Fermi–Dirac smearing
Slab / surface	SAD; warn if metallic
Wire	SAD; raise on un-implemented Madelung

G2f CRYSTAL-style manual atomic occupations. New API:
```
opts.atomic_occupations = {
    "Cl": {"3s": 2, "3p": [2, 2, 2]},
    "Na": {"3s": 0},
    "Fe": {"3d": [1, 1, 1, 1, 1], "4s": 1},  # high-spin Fe³⁺
}
```
Overrides the SAD-built atomic density for the named elements. Critical for transition-metal SCF stability and for testing specific configurations (e.g. broken-symmetry start). Mirrors CRYSTAL’s EIGSHIFT / ATOMSPIN / manual shell occupation directives — see the CRYSTAL23 manual, §SCF Convergence, for the convention.
G2g Saunders–Hillier level shift (Int. J. Quantum Chem. 7, 699 (1973)). New opts.level_shift_v (Hartree) added to the virtual-block of F in the MO basis. Provably convergent for sufficiently large shift. Wired across RHF / UHF / RKS / UKS, mol + periodic. Default 0.0; auto-set to 0.2 Ha when system type is “transition metal” or “ionic insulator” + heuristic detection of small gap.
G2h Dynamic damping (Zerner–Hehenberger, Chem. Phys. Lett. 62, 550 (1979)). α adjusted on the fly based on energy decrease. Replaces the current static damping for difficult cases. Conservative default for molecules; more aggressive for ionic / metallic systems.
G2h-bis CRYSTAL-style FMIXING (static Fock-matrix mixing). New opts.fock_mixing_pct = N (0..99, integer):
```
F^(it)  =  (N/100) · F^(it-1)  +  (1 − N/100) · F'^(it)
```
where F'^(it) is the freshly-built Fock from the latest density. Mirrors CRYSTAL’s FMIXING N directive (see CRYSTAL23 manual, §SCF Convergence). Distinct from the shipped damping option, which mixes the density matrix D, not F — both are useful, and on tight ionic crystals Fock-mixing often stabilises the residual that density-mixing leaves oscillating. Standard CRYSTAL setting is 30–80% old Fock; vibe-qc default 0 (off). Wired uniformly across RHF / UHF / RKS / UKS, Γ-only + multi-k. Plays cooperatively with DIIS — applied before the DIIS extrapolation on every iter when both are on, identically to CRYSTAL’s ordering. The implementation is a one-line addition in each SCF driver; the user-facing value is the recognised CRYSTAL name + numerical compatibility with CRYSTAL input decks.
G2i SCF divergence-detection on every periodic SCF entry point — generalisation of the v0.5.6 hook on run_rks_periodic_gamma_ewald3d to RHF / UHF / UKS Γ-only
- multi-k. Same heuristics (NaN / |E| > 1e6 / |dE| > 1e4 Ha after iter 5) and same remediation hint targeting initial-guess + damping + level-shift advice.
G2j Broken-symmetry guesses (open-shell singlets, antiferromagnetic coupling). New opts.guess_mix that rotates α HOMO into α LUMO by a user-specified angle (45° default = 50% mixing). Mirrors ORCA’s GUESSMIX. Wired through UHF + UKS only.

References: Lehtola, J. Chem. Theory Comput. 15, 1593 (2019); Lehtola/Visscher/Engel J. Chem. Phys. 152, 144105 (2020); Van Lenthe et al. J. Comput. Chem. 27, 926 (2006); Saunders & Hillier Int. J. Quantum Chem. 7, 699 (1973); Zerner & Hehenberger Chem. Phys. Lett. 62, 550 (1979).

`v0.7.x` — DIIS family expansion (flagship: EDIIS+DIIS hybrid)¶

🎯 Robust by default on transition-metal complexes. Pulay DIIS plateaus or oscillates near stationary points that aren’t minima. EDIIS minimises the OD energy functional rather than the commutator, dominates DIIS far from convergence. The standard production pattern is EDIIS-early, switch-to-DIIS-near.

✅ D1a EDIIS (Kudin, Scuseria, Cancès, J. Chem. Phys. 116, 8255 (2002)) — quadratic energy functional from the Optimal Damping Algorithm. Ships vibeqc::EDIIS (closed-shell + UHF open-shell extrapolate; active-set simplex QP solver), wired into all four run_*_scf_with_jk molecular drivers (RHF, UHF, RKS, UKS) — periodic-Γ callers driving via the JKBuilder interface inherit it for free. RHFOptions::scf_accelerator = SCFAccelerator::EDIIS activates it.
✅ D1b ADIIS (Hu & Yang, J. Chem. Phys. 132, 054109 (2010)) — augmented Roothaan–Hall energy functional. Sibling to EDIIS; a later analysis (Garza & Scuseria, J. Chem. Phys. 137, 054110 (2012)) showed they’re identical at the HF level. Ships vibeqc::ADIIS (closed-shell + UHF open-shell; reuses the EDIIS active-set simplex QP solver), wired into all four molecular run_* drivers and the periodic-Γ drivers. RHFOptions::scf_accelerator = SCFAccelerator::ADIIS activates it.
✅ D1c EDIIS+DIIS hybrid — the production default. EDIIS until error is below threshold, then switch to plain DIIS for the asymptotic regime. Garza & Scuseria’s analysis identifies this as the method of choice. RHFOptions::scf_accelerator = SCFAccelerator::EDIIS_DIIS with ediis_diis_switch_threshold (default 1e-1, PySCF convention).
D1d Optimal Damping Algorithm (Cancès & Le Bris, Int. J. Quantum Chem. 79, 82 (2000)) as a standalone option, primarily for diagnostic comparison and educational use.
D1e LIST family (Wang et al., J. Chem. Theory Comput. 7, 3045 (2011)) — for systems where DIIS stagnates on its own.
D1f Extended Hückel / PModel guess (Hoffmann 1963 + the parameter-free variant). Mostly equivalent to SAP at first order but useful as a back-up for systems where SAP/SAD numerics struggle (deep core states with very high Z).
D1g MINAO guess — project SAD onto a minimal-basis reference, then re-expand. Cheap; very stable for molecules.

`v0.8.0` — ✅ shipped — second-order convergence (flagship: SOSCF / TRAH)¶

Shipped at v0.8.0 — SOSCF (D2c) and TRAH proper (D2e trust-region augmented-Hessian level shift) landed via the v0.8.0 SCF accelerator / converger / aid unification (see CHANGELOG [v0.8.0] entries “TRAH proper” and “SCF accelerator / converger / aid unification”).

🎯 Quadratic convergence for the hard cases. DIIS family methods stall on transition-metal complexes, broken-symmetry solutions, and small-gap systems. Once the gradient is below a “trust threshold”, switch to a Newton-step on the orbital rotation manifold. Quadratic convergence in ~3-5 final iters.

✅ D2a Orbital-rotation parametrisation: C(t) = C₀ · exp(A) with A antihermitian, so the constraint C† S C = I is trivially preserved. Standard convention. (Shared with the pre-existing C1c quadratic-fallback step in vibeqc::expm_skew.)
✅ D2b Pre-SOSCF DIIS warm-up — gradient must be below ~1.0 (Fischer–Almlöf 1992 convention) before SOSCF activates. Otherwise the Newton step overshoots. Implemented as the RHFOptions::soscf_threshold field (default 0.0 = disabled; set to 1.0 for the production setting).
✅ D2c SOSCF strict (Bacskay 1981, Fischer & Almlöf, J. Phys. Chem. 96, 9768 (1992)) — full orbital Hessian via preconditioned CG, exact Newton step on the orbital-rotation manifold. Shipped for RHF / UHF / RKS / UKS across LDA / GGA / hybrid-GGA — closed-shell RHF first, then the open-shell + KS extensions; UKS-GGA closed by the Phase 17e polarised GGA fxc kernel. One Fock build per CG iter via the same JKBuilder (KS adds one XCKernelBuilder matvec per CG iter). Meta-GGA second-order SCF still pending (τ-dependent polarised fxc).
D2d Approximate SOSCF (Neese, Chem. Phys. Lett. 325, 93 (2000)) — diagonal-dominant orbital-Hessian approximation. ORCA’s standard. Cheaper than strict, almost as fast in iters.
✅ D2e Augmented Hessian (AH) / Trust-Region (TRAH; Helmich-Paris, J. Chem. Phys. 156, 204104 (2022)) — step restriction prevents Newton overshoot. Ships the full trust-region subproblem solve: the interior unconstrained Newton step when ‖A⁻¹g‖ ≤ Δ, else the level-shifted boundary step κ(λ) = −(A + λI)⁻¹g found by a More-Sorensen secular root-find (λ is the negated lowest eigenvalue of the scaled augmented Hessian). Non-positive-definite Hessians are handled by escalating λ above −λ_min(A) inside the same loop. Adaptive trust radius from Powell’s ρ test. Wired into RHF / UHF / RKS / UKS via trah_threshold + TRAHOptions (vibeqc::trah_step / uhf_trah_step).
D2f ARH — Augmented Roothaan–Hall quasi-Newton (Host et al., J. Chem. Phys. 129, 124106 (2008)). Iterative Hessian build avoids the explicit-Hessian bottleneck.
D2g CIAH — Co-Iterative Augmented Hessian (Sun, J. Chem. Theory Comput. 13, 5053 (2017)) — PySCF’s general second-order solver, decorator-style API.
D2h FRAGMO guess — converge SCF on isolated fragments, superimpose. Excellent for non-covalent complexes; foundation of ALMO / EDA. Pairs naturally with second-order convergence for the fragmented start.
D2i READ / restart from prior orbitals — for opt / scan / extrapolation workflows. Re-orthogonalize across basis-set or geometry changes. Project from smaller to larger basis when stepping up. Supersedes any guess method.

`v0.10.x` — 🎯 queued — multi-secant / quasi-Newton SCF acceleration (Anderson + Broyden)¶

Owned by the scf-mix chat alongside the v0.10.x density-mixing flagship below. Retargeted from a stale v0.9.x slot (v0.9.x patch line is closed).

🎯 Density-mixing acceleration beyond DIIS. Anderson acceleration and Broyden quasi-Newton mixing are derivative- free, multi-secant techniques that excel on the cases where DIIS oscillates: small-gap or near-metallic periodic systems, charge-sloshing regimes, and any SCF where the residual spectrum has multiple comparable modes. Standard in periodic DFT codes (SIESTA, CP2K, ADF/BAND, VASP) and increasingly in molecular codes (ORCA’s DIIS_GDM hybrid, Q-Chem’s GDM/RCA_DIIS).

Background: Anderson (Donald G. Anderson, J. ACM 12, 547 (1965)) minimises a least-squares linear model over the m most recent residuals fₖ = g(xₖ) − xₖ — effectively a quasi-Newton update without forming an explicit Jacobian. Broyden (J. Math. Phys. 12, 347 (1965); “good Broyden” Type-I updates the Jacobian, “bad Broyden” Type-II updates the inverse) builds a secant-condition- based Jacobian approximation. Type-II Broyden is mathematically equivalent to Anderson at the multi-secant level; they diverge in implementation detail (history weighting, restart criteria, line-search safeguards).

D3a Anderson acceleration on the density-matrix iteration — drop-in alongside the existing DIIS family in python/vibeqc/scf_acceleration.py. History length m=5–10; Tikhonov-regularised least-squares to handle near-linear- dependent residual columns. Anderson-restart on residual norm increase (Walker–Ni safeguard).
D3b Broyden Type-II mixing — same multi-secant least- squares but updates the inverse Jacobian. Equivalent in theory to Anderson but with different numerical stability; worth shipping both for benchmarking and as fallbacks.
D3c Hybrid policy: warm-start with FMIXING/damping + Anderson, transition to DIIS once the gradient is “tame” (||[F,DS]|| < some threshold). Mirrors the CRYSTAL recipe pattern (FMIXING-then-DIIS) but with a smarter accelerator during the rough phase.
D3d Periodic-friendly variant: Kerker preconditioning (damp the small-G charge modes that drive charge-sloshing oscillation on metallic systems). Mainly relevant for conducting / small-gap targets; pairs naturally with Fermi-Dirac smearing.
D3e Multi-secant on per-k density list — when running multi-k SCF, the residual vector is the concatenation of per-k Fock errors; Anderson / Broyden act on the full concatenated vector, weighted by k-mesh.

This is the second-line solver for cases where DIIS struggles but SOSCF/TRAH (v0.9.x flagship) is overkill (no second-order Hessian needed). Ships together with D2 — users get a scf_accelerator = "diis" | "anderson" | "broyden" | "soscf" selector with sensible AUTO defaults per system type.

`v0.x.x` — SCF diagnostics: “possibly conducting state” warning¶

⏳ Deferred — not shipped in v0.8.0 (no CHANGELOG [v0.8.0] entry); still planned, re-target TBD.

🎯 Surface the SCF’s view of the band gap. CRYSTAL emits POSSIBLY CONDUCTING STATE - EFERMI(AU) <ε_F> (RES. CHARGE <q>; IT. <n>) when HOMO and LUMO collapse and fractional occupations are needed. vibe-qc should do the same — silent SCF convergence on a “no gap” Aufbau-filled state is the wrong answer dressed up as right.

Compute the band gap from converged mo_energies (per k for multi-k; global Fermi level via the existing occupations.py helpers).
If gap < conducting_state_warning_threshold (default 1e-4 Ha ≈ 3 meV — narrow enough that it’s an actual metal, not a small-gap insulator), emit a warning to the SCF log + add a warnings field on the result object.
Document the warning as a hint to enable Fermi-Dirac smearing on metallic / near-degenerate cases.

`v0.12.0` — 🎯 queued — direct minimisation for big solids (flagship: OT)¶

Retargeted from a stale v0.9.x slot (v0.9.x patch line is closed). Feature-grade architectural work — promoted to a v0.12.0 slot rather than the patch line.

🎯 Skip diagonalisation entirely. Unconstrained minimisation on the manifold of orthonormal orbitals via exponential parametrisation. Linear-scaling alternative to SCF; the workhorse for 1000+ atom periodic CP2K runs.

D3a OT framework (VandeVondele & Hutter, J. Chem. Phys. 118, 4365 (2003)). Cubic in nbf for the basis transform but no diagonalisation in the inner loop. Critical for big cells.
D3b OT preconditioners — FULL_ALL, FULL_SINGLE_INVERSE, FULL_KINETIC, with ENERGY_GAP as the primary tuning knob. Quality of the preconditioner dominates iteration count.
D3c OT minimisers — CG (default), DIIS-OT (faster but less reliable), Broyden-OT (Weber et al., J. Chem. Phys. 128, 084113 (2008)). CG with Wolfe line search.
D3d ADMM — auxiliary density matrix method (VandeVondele / Krack / Mohamed) for hybrid DFT compatibility with OT. The HSE06-on-1000-atoms enabling technology. Already on the acceleration roadmap as a v0.9.x sibling.

`v0.10.x` — 🎯 queued — density mixing for periodic metals (flagship: Anderson + Kerker + Pulay-Kerker)¶

Owned by the scf-mix chat. v0.10.x is the current patch line and stays as the target slot. Composes with the smear chat’s SmearingOptions for metallic-system tests.

🎯 Make periodic metals tractable. OT is contraindicated for metals (no smearing-aware variant). Density mixing on the charge-density grid is the standard plane-wave path. Without Kerker preconditioning, charge sloshing at small G destroys SCF convergence in any metallic cell with > 50 atoms.

D4a Anderson mixing (Anderson, J. ACM 12, 547 (1965)) on the real-space density. Closely related to DIIS in spirit.
D4b Kerker preconditioner (Kerker, Phys. Rev. B 23, 3082 (1981)). Damps small-G modes that cause charge sloshing in metallic cells. Indispensable for metals.
D4c Modified Broyden II / Johnson–Eyert (Johnson, Phys. Rev. B 38, 12807 (1988); Eyert, J. Comput. Phys. 124, 271 (1996)). Quasi-Newton dielectric Jacobian. Default in many plane-wave codes.
D4d Pulay–Kerker (Kresse & Furthmüller, Phys. Rev. B 54, 11169 (1996)). Pulay extrapolation + Kerker preconditioning. VASP’s default for metals.
D4e Periodic Pulay (Banerjee, Suryanarayana, Pask, Chem. Phys. Lett. 647, 31 (2016)) — the recent plane-wave variant with provably better robustness for diverse materials.
D4f Fermi–Dirac / Methfessel–Paxton / Marzari–Vanderbilt smearing — already partially in place; extended here to smearing-aware DIIS / Pulay so the SCF inner loop respects the smeared occupations consistently.

Post-dimensional-method SCF parity agenda¶

Once the general 1D / 2D / 3D method stack is in place for HF, MP2, DFT, hybrids, and their open-shell variants, the SCF-control surface should be consolidated against CRYSTAL and the wider code ecosystem. The goal is not a pile of ad-hoc knobs; it is a small set of composable, method-independent strategies that work across molecular and periodic drivers.

Method	Strengths	Weaknesses	Best for	CRYSTAL notes
FMIXING	Simple Fock/KS damping; stabilizes early iterations	Slow alone	Initial cycles, metals	`FMIXING <value>`; CRYSTAL default behavior
LEVSHIFT	Stabilizes small HOMO-LUMO gaps and open shells	Can slow final precision	Semiconductors, open-shell systems	`LEVSHIFT <n> <e>`; combinable with FMIXING
DIIS	Fast asymptotic convergence	Orbital swapping, early failure on poor guesses	Good guesses, non-metals	`DIIS`; CRYSTAL disables in some massive-parallel defaults
FMIXING + LEVSHIFT	Robust for stubborn cases	Slower than pure DIIS	Difficult periodic SCF	Common CRYSTAL tutorial recipe
FMIXING + DIIS	Good speed/stability compromise	DIIS can still oscillate	Default hybrid strategy	FMIXING warm-up before DIIS

Observed operating principle: DIIS is usually 2-3x faster than linear mixing on easy cases, but fails more often on hard systems unless damping, level shifting, smearing, or a hybrid strategy prepares the SCF state first. CRYSTAL’s periodic stability bias is FMIXING + LEVSHIFT first, DIIS when the state is sane; vibe-qc should expose the same pattern as reusable policy rather than per-driver special cases.

CRYSTAL-specific follow-up items:

Retain FMIXING / LEVSHIFT / DIIS as the CRYSTAL14-compatible core.
Add post-CRYSTAL14 metallic smearing semantics where they affect parity inputs; keep CRYSTAL14 references separate from CRYSTAL23.
Provide pure-mixing fallback profiles for DIIS oscillations.
Investigate DIISALLK-style full-k-space DIIS for hybrids, guarded by memory diagnostics because the full k-space history is expensive.

Cross-code convergence controls to mirror or learn from:

Code	Key methods	Notes
Q-Chem	DIIS, GDM, RCA, RCA_DIIS, DIIS_GDM, MOM	RCA is a reliable downhill fallback; MOM guards orbital swaps.
ORCA	DIIS, damping, level shift, SOSCF-style fallbacks	Strong open-shell stability bias.
ADF/BAND	DIIS, MultiSecant, density mixing	BAND defaults to conservative mixing and smearing for metals.
PySCF	DIIS, SOSCF / CIAH, Newton variants	External reference only; useful design comparison.
Gaussian	DIIS, damping, SCF=QC/XQC	QC/XQC is the canonical quadratic fallback pattern.

For metals, occupation treatment and charge-density response must come before plain Fock extrapolation:

Approach	Description	Examples / target
Smearing	Fractional occupations via Fermi-Dirac and later Gaussian / Methfessel-Paxton / Marzari-Vanderbilt variants	First-line setting for any metallic periodic calculation
Broyden mixing	Quasi-Newton density mixer	Robust against charge sloshing; SIESTA / CP2K style
MultiSecant	DIIS-like multi-secant density update	ADF/BAND-style post-DIIS fallback
Kerker / preconditioned mixing	Damp small-G charge modes	Plane-wave metal standard; CP2K / VASP style
LEVSHIFT + FMIXING	Virtual shift plus Fock/KS damping	CRYSTAL / ORCA-compatible stabilizer for difficult starts

Practical metallic workflow target: start with smearing (typical electronic broadening 0.01-0.1 Ry), use FMIXING in the 0.5-0.8 range for difficult charge-sloshing starts, combine with LEVSHIFT when occupied/virtual ordering is unstable, and delay pure DIIS until the charge response is tame. This should become a named policy profile usable from molecular, 1D, 2D, and 3D drivers rather than a periodic one-off.

Recommended workflows by system¶

System type	Initial guess	Convergence accelerator
Routine closed-shell mol	SAP	DIIS
Difficult mol (anything else)	SAD	EDIIS+DIIS + level shift
Transition-metal complex	SAD-UHF + manual occupations	EDIIS+DIIS → SOSCF (warm-up below grad ~1)
Open-shell singlet / BS	SAD-UHF + GUESSMIX	EDIIS+DIIS → SOSCF + AH
Periodic insulator (small-medium cell)	SAD	DIIS
Periodic insulator (large cell)	SAD	OT-CG with FULL_ALL
Periodic metal	SAD + smearing	Pulay-Kerker (small) / Periodic Pulay (large)
Periodic hybrid DFT	First converge semilocal, then read for hybrid	DIIS (small) / OT + ADMM (large)
Slab (insulating)	SAD	DIIS
Slab (metallic)	SAD + smearing	Pulay-Kerker
Wire	SAD + 1D Madelung	DIIS

Key reference list (initial guess + convergence)¶

This table is the single source of truth for citations across the program; each section above references this list.

Method	Reference
Hcore guess	tradition (Roothaan 1951)
GWH	Wolfsberg & Helmholz, J. Chem. Phys. 20, 837 (1952)
Extended Hückel	Hoffmann, J. Chem. Phys. 39, 1397 (1963)
Anderson mixing	Anderson, J. ACM 12, 547 (1965)
Saunders–Hillier level shift	Int. J. Quantum Chem. 7, 699 (1973)
Zerner–Hehenberger damping	Chem. Phys. Lett. 62, 550 (1979)
Pulay DIIS	Chem. Phys. Lett. 73, 393 (1980); J. Comput. Chem. 3, 556 (1982)
Bacskay quadratic SCF	Chem. Phys. 61, 385 (1981)
Kerker preconditioner	Phys. Rev. B 23, 3082 (1981)
Johnson modified Broyden II	Phys. Rev. B 38, 12807 (1988)
Fischer–Almlöf SOSCF	J. Phys. Chem. 96, 9768 (1992)
Eyert Broyden mixing	J. Comput. Phys. 124, 271 (1996)
Kresse–Furthmüller VASP mixing	Phys. Rev. B 54, 11169 (1996)
Kudin/Scuseria/Cancès EDIIS / Cancès–Le Bris ODA	J. Chem. Phys. 116, 8255 (2002); Int. J. Quantum Chem. 79, 82 (2000)
Neese SOSCF (ORCA)	Chem. Phys. Lett. 325, 93 (2000)
VandeVondele–Hutter OT	J. Chem. Phys. 118, 4365 (2003)
Van Lenthe et al. SAD	J. Comput. Chem. 27, 926 (2006)
Host et al. ARH	J. Chem. Phys. 129, 124106 (2008)
Weber et al. OT refinements	J. Chem. Phys. 128, 084113 (2008)
Hu & Yang ADIIS	J. Chem. Phys. 132, 054109 (2010)
Wang et al. LIST	J. Chem. Theory Comput. 7, 3045 (2011)
Garza & Scuseria EDIIS+DIIS analysis	J. Chem. Phys. 137, 054110 (2012)
Sun PySCF CIAH	J. Chem. Theory Comput. 13, 5053 (2017)
Banerjee–Suryanarayana–Pask Periodic Pulay	Chem. Phys. Lett. 647, 31 (2016)
Lehtola SAP guess	J. Chem. Theory Comput. 15, 1593 (2019)
Lehtola–Visscher–Engel SAP Gaussian implementation	J. Chem. Phys. 152, 144105 (2020)
Helmich-Paris TRAH	J. Chem. Phys. 156, 204104 (2022)

CRYSTAL23 manual (CRYSTAL solid-state code) is the reference for manual atomic occupation conventions, EIGSHIFT, ATOMSPIN, broken- symmetry workflows for solids, and the canonical wisdom on the shell-by-shell guess override that vibe-qc’s opts.atomic_occupations is modeled on.

`v0.6.0` — periodic atomic gradients — Pulay’s Owl¶

Codename: Pulay’s Owl — Pulay’s correction terms (1969) are the conceptual core of this release; Pulay also gave us DIIS (1980), which the SCF stack underneath the gradient pass relies on. Owl: nocturnal, sees what others miss — sub-meV displacement- derived forces.

🎯 Headline feature — analytic forces on solids. Unlocks geometry optimization for surfaces, molecular crystals, defect cells. The single biggest “vibe-qc can now do solids the way ORCA does molecules” deliverable; gates v0.8 stress and v0.9 phonons.

✅ G1a Hellmann–Feynman force (electronic + nuclear, no Pulay) — Γ-only RHF gradient.
✅ G1b Pulay corrections — basis-set-dependent ∂χ/∂R terms via the libint deriv-order=1 path (already vendored for molecular gradients). Γ-only RKS gradient via molecular-fallback XC Pulay (LDA exact; GGA σ-coupled term as v0.6.x patch).
✅ G1c Multi-k RHF + RKS gradient drivers via Bloch-folded density.
✅ G1d Open-shell UKS multi-k gradient (pure DFT only; hybrid-UKS via per-spin periodic K is v0.6.x).
✅ G1e ASE bridge — vibeqc.ase_periodic.atoms_to_periodic_system
- periodic_forces round-trip eV/Å forces with Newton’s-3rd-law obeyed.
⏳ G1f Validation against CRYSTAL gradient outputs on small reference systems (LiH, MgO, diamond Si). Tracked as v0.6.x.
⏳ G1a-2 Periodic K-piece gradient routing bug — masked by Sx2 default screening (schwarz_threshold_forces = 1e-14), root cause still tracked. Setting schwarz_threshold_forces = 0.0 reproduces the historical 6e-3 Ha/bohr disagreement vs FD on H-chain a=2 Å. Production users with default thresholds are unaffected; HF / hybrid-DFT users probing the regression handle should use the FD reference until the root-cause fix lands.

Sibling work shipped alongside the gradient flagship in this same v0.6.0 release:

✅ Sx2 — Cauchy-Schwarz screening on the gradient ERI pass (eri_lattice_gradient_contribution). Default schwarz_threshold_forces = 1e-14 (100× tighter than the energy-side default since plain Schwarz on derivatives is non-rigorous, matching CP2K’s EPS_SCHWARZ_FORCES convention). Per-quartet + cell-level skip just like the energy side.
✅ Banner print at SCF entry on every periodic SCF surface (RHF / RKS Γ-only + multi-k + UKS) so the version + codename shows in any .out file before the SCF header.
✅ G1d export (compute_gradient_periodic_uks_multi_k) at top-level vibeqc.* namespace; was inadvertently dropped during a rebase before v0.5.5.

`v0.6.x` — molecular ORCA parity (sibling validation track)¶

🎯 Same idea as the v0.7 PySCF.pbc parity, but for the molecular stack and against ORCA. Runs in parallel with v0.7 and ships in patch releases as fixtures land.

Why both PySCF and ORCA: they implement HF / DFT / MP2 with different code paths (different integrators, different DIIS variants, different XC quadrature implementations). A 1:1 vibe-qc match against both is a much stronger correctness signal than against either alone. ORCA also exposes the SCF iteration trace cleanly via the .out file, so iter-by-iter SCF convergence (energy, |ΔE|, max-grad, DIIS error) can be compared in addition to the final total energy.

Settings discipline (per user): vibe-qc and ORCA must use the same SCF settings — same convergence thresholds, same DIIS config, same XC grid, same initial guess (Hcore vs SAD). Start with loose criteria; tighten step by step as parity holds. ORCA defaults are documented in §SCF Convergence of the ORCA manual; mirror them by:

RHF/UHF: conv_tol_energy = 1e-6 Ha, DIIS subspace 8, Hcore guess.
RKS/UKS: same, plus grid.level = 4 (ORCA’s “Grid4”).
MP2: conv_tol = 1e-7 Ha for the underlying SCF.

MOL1 Test fixtures: H₂, H₂O, CH₄, NH₃, HF, CO, N₂, formaldehyde, methanol, ethanol (small molecules ORCA’s tutorials ship with). Multiple basis sets: STO-3G, 6-31G(d), cc-pVDZ, def2-TZVP. Methods: RHF, UHF (radicals — OH·, CH₃·, NO·), RKS / UKS for LDA / PBE / B3LYP, RMP2, UMP2.
MOL2 Cached ORCA reference outputs in tests/fixtures/orca_reference/<system>/<basis>/<method>/output.out. Re-run when ORCA version bumps.

MOL3 tests/test_molecular_orca_parity.py — parametrised over MOL1 fixtures, asserts vibeqc ↔ ORCA agreement on:

Quantity	Loose (initial)	Tight (final)
Final total energy	1e-4 Ha	1e-7 Ha
SCF iter count	within ± 5	within ± 2
Per-iter energy trace	1e-3 Ha	1e-6 Ha
Final MO energies (sorted)	1e-3 Ha	1e-6 Ha
Mulliken charges	0.05 e	1e-3 e

Tighten one row at a time once each loosened tolerance passes on all fixtures.

MOL4 ORCA .out parser (tests/fixtures/orca_reference/_parser.py) so parity tests read cached ORCA output rather than re-running ORCA on every CI.

Existing PySCF molecular parity (since v0.4.x) — RHF / UHF / RKS / UKS / MP2 / UMP2 on H₂ / H₂O / CH₄ × {STO-3G, 6-31G*, cc-pVDZ} to 1e-10 Ha total + 1e-9 MO — is solid (78 tests, all green at v0.6.2). ORCA parity adds an independent second reference and the iteration-trace match.

`v0.7.0` — periodic SCF correctness + PySCF.pbc parity¶

Codename TBD (candidates: Sun’s Crane (after Qiming Sun / PySCF), Pisani’s Hawk (after Cesare Pisani / CRYSTAL)).

Promoted to flagship after v0.6.1 / v0.6.2 surfaced that the v0.6.x periodic SCF is correct in the atomic limit but off by orders of magnitude on dense ionic crystals (LiH conventional cell: ~−1060 Ha vs ~−32 Ha expected). The Madelung-correction formula in v0.6.1 fixes the single-charge-in-vacuum case but doesn’t capture the structural Madelung of complex ionic arrangements. Periodic stress + slab builder deferred past v0.8.0 (now v0.x.x — did not ship in v0.8.0).

🎯 Headline feature — vibe-qc periodic SCF gives the same absolute energies as PySCF.pbc on realistic systems, then beats it on speed via CRYSTAL-style space-group symmetry exploitation.

Phase 1 — PySCF.pbc parity (port their gauge convention)¶

The bug is in the gauge consistency between V_nuc lattice sum and Ewald-3D Hartree J. PySCF’s pyscf.pbc.df.fft.FFTDF and pyscf.pbc.tools.pbc.madelung already solve this — port their convention into vibe-qc’s vibeqc.ewald_composed.build_j_ewald_3d + vibeqc.nuclear_repulsion_per_cell.

PBC1a Audit pyscf.pbc.df.fft.FFTDF and pyscf.pbc.tools.pbc.madelung. Document the gauge convention they use — single neutralizing background applied to nuclei + electrons together, not separately. Document where vibe-qc diverges.
PBC1b Refactor build_j_ewald_3d to use the PySCF convention. Drop the G=0 pinning of J alone in favour of the combined-system neutralizing background. Replace the v0.6.1-shipped madelung_energy_correction formula with the cell-dependent Madelung from pyscf.pbc.tools.pbc.madelung-equivalent.
PBC1c Rebuild the multi-k Ewald drivers on top of the refactored J. Verify Bloch-sum consistency.
PBC1d Rebuild the periodic XC contribution on the same gauge — V_xc must integrate against the same density that J sees.

Phase 2 — PySCF parity test set¶

Realistic systems with PySCF reference inputs/outputs checked into the repo. Both vibe-qc and PySCF run side-by-side; absolute energy agreement to ≤ 1 mHa per cell.

PBC2a Test fixtures — start with what PySCF converges trivially. The point is to match PySCF where PySCF runs cleanly with default settings (no SAD / SAP guess, no level shift, no aggressive damping). If PySCF needs a feature, we understand we need it too — but we add it when its absence blocks parity, not preemptively. Easy systems first (high-symmetry, gapped insulators, primitive or small conventional cells):

System	Cell	Atoms	Gap	Why easy
H₂ in big box	cubic	2	huge	molecular limit, trivial
Solid Ne (FCC)	cubic conv	4	huge	rare-gas, no bonding ambiguity
LiH rocksalt	cubic conv	8	wide	textbook ionic insulator
NaCl rocksalt	cubic conv	8	wide	textbook ionic insulator
MgO rocksalt	cubic conv	8	wide	gap ~7 eV, classic CRYSTAL test
Diamond C	cubic conv	8	wide	classic covalent, large gap
Si diamond	cubic conv	8	mid	standard semiconductor benchmark
BN cubic	cubic conv	8	wide	mixed covalent / ionic

Hard systems (need fancy features) are explicitly OUT of the PBC2 scope and added only when needed:

System	Why hard	Feature blocked on
Al / Cu metal	metallic, Fermi smearing	smearing-aware DIIS / OT
TM oxides	open-shell, broken-symmetry	SAD-UHF + GUESSMIX
Surfaces	2D Ewald + slab	v0.8 slab work
FCC primitive cells	non-orthorhombic	native FFTDF/GDF parity and benchmarks

STO-3G first for speed; pob-TZVP after STO-3G parity holds.

Sourcing fixtures from PySCF’s tutorials. Use the smallest cells that PySCF.pbc’s own tutorials / examples ship with — they’re already laptop-friendly (run in seconds to a minute). Concretely:

examples/pbc/00-intro.py → H₂ chain at small a
examples/pbc/03-band_structure.py → diamond C (8-atom conv)
examples/pbc/12-mole_2_cell.py → small Si supercell
examples/pbc/17-disabled_for_isdf.py → various small cells
examples/pbc/df_intro.py → small LiH

Cell-size budget for the parity tests: each fixture must run on a developer laptop (8-16 cores, 16-32 GB RAM) in under ~60 s for vibe-qc and PySCF combined. That keeps the CI pipeline fast and lets the fixtures double as fast iteration cases during the gauge refactor.

PBC2b Each fixture has a paired examples/parity/<system>/pyscf_reference.py and examples/parity/<system>/vibeqc.py, plus a checked-in pyscf_reference.energies.json so the parity test runs against the cached PySCF numbers without re-running PySCF on every CI. Re-run periodically when PySCF version bumps.
PBC2c tests/test_periodic_pyscf_parity.py — parametrised over all PBC2a fixtures, asserts vibe-qc ↔ PySCF agreement to 1 mHa absolute.
PBC2d Extend to pob-TZVP (the basis set that’s standard for ionic-crystal PBC work) once STO-3G parity is solid. pob- TZVP / pob-DZVP-rev2 / pob-TZVP-rev2 already ship in basis_library.

Phase 3 — CRYSTAL-style speedups¶

Once PySCF parity is solid, add the CRYSTAL-style symmetry-driven optimisations that make CRYSTAL fast on LCAO PBC:

PBC3a Space-group symmetry on the unit-cell density — symmetrise D after each SCF iteration so symmetry-equivalent blocks share one set of integrals. Mirrors CRYSTAL23’s SYMM defaults.
PBC3b Symmetry-equivalent atom + shell-pair pruning in the ERI lattice sum. CRYSTAL exploits f_n (number of operators mapping pair n → equivalent pair) to reduce the unique shell-pair count by a large factor (3-12× depending on spacegroup).
PBC3c TOLINTEG-style 5-vector thresholds (overlap, penetration, exchange-overlap, pseudo-overlap; see CRYSTAL23 manual §SCF) layered on top of v0.5.5 / v0.5.6 Schwarz.
PBC3d Symmetry-equivalent k-point folding in the Bloch sums (already partially in place via KPoints.symmetry=True; full integration with the symmetrised D update).

Stress + slab — moved to v0.8¶

The original v0.7 stress + slab work moves to v0.8 because the gauge-consistency fix in PBC1 changes the periodic energy expression and therefore the Pulay-aware analytic stress derivation. We need correct absolute energies before the energy gradient with respect to lattice strain is well-defined.

`v0.x.x` — periodic stress tensor + slab builder¶

⏳ Deferred — not shipped in v0.8.0 (no CHANGELOG [v0.8.0] entry); still planned, re-target TBD.

Codename TBD (candidates: Born’s Hare, Neese’s Magpie, Vinet’s Pangolin).

🎯 Headline feature — periodic stress tensor σ_αβ → cell- parameter optimization, exact equation-of-state, surface energies. Was originally v0.7; promoted out of the way of the periodic-SCF- correctness flagship.

G2a Analytic stress from the SCF energy (Pulay-aware).
G2b ASE calculator stress property; vc-relax routine driven by ase.optimize.BFGS on cell + coordinates.
G2c Equation-of-state utilities (Birch–Murnaghan, Vinet) on a few-volume EOS sweep.
B1 slab / surface builder — thin wrapper over ase.build.surface, gated on C1 so the resulting SCFs actually converge for the metallic surfaces it produces.

`v0.x.x` — phonons¶

⏳ Deferred — not shipped in v0.8.0 (no CHANGELOG [v0.8.0] entry); still planned, re-target TBD.

Codename TBD (candidates: Debye’s Stork, Born’s Hedgehog).

🎯 Headline feature — Γ-point + finite-displacement phonon dispersion + quasi-harmonic thermodynamics for solids.

21a Γ-only periodic FD Hessian — straight extension of the molecular FD Hessian (17a-1) to periodic, single supercell.
21b Phonon dispersion — FD on G1 forces across a phonopy-style supercell, dynamical matrix at arbitrary q-points.
21c Quasi-harmonic approximation thermodynamics — V(T), C_p, thermal expansion from G2 EOS + 21b phonons.

`v0.8.0` — shipped 2026-05-17 — basis-set library expansion¶

✅ Shipped in v0.8.0 (Grimme’s Gecko, 2026-05-17). See the CHANGELOG [v0.8.0] entry “basis-set library expansion + ECP integration completion”. Plan text below retained for provenance.

🎯 Headline feature — first-class support for every basis-set family discussed in user guide § basis sets. Shipping every recognised family closes the prerequisite gap that gates GMTKN55 / S22 / S66 / TM-benchmark ingestion in the regression-suite test-set queue further down this page (item 2: “BSE-driven basis-set ingestion”).

The driving design choice: adopt the Basis Set Exchange (BSE) JSON format as the canonical loader so every family below works without hand-coded .g94 files. The BSE catalog (Pritchard et al. 2019) is authoritative; vibe-qc tracks it.

BS1 Karlsruhe def2 family (the molecular default). def2-SVP, def2-TZVP, def2-TZVPP, def2-QZVP, def2-QZVPP + def2-ECP for Rb–Rn + diffuse-augmented variants (def2-XVPD per Rappoport & Furche 2010, ma-def2-XVP minimally-augmented per Truhlar-Zheng).
BS2 Dunning correlation-consistent. cc-pVnZ for n ∈ {D,T,Q,5,6}, aug-cc-pVnZ, cc-pV(n+d)Z (tight-d for second-row hypervalent per Dunning 2001), cc-pwCVnZ for explicit core-valence. Generally contracted; requires the integral path to handle that efficiently.
BS3 Jensen polarisation-consistent. pcseg-n for n ∈ {0,1,2,3,4}, aug-pcseg-n. The pure-DFT-optimal segmented alternative to def2-TZVP; Pitman 2024 endorses pcseg-2 as the best TZ basis for DFT thermochemistry.
BS4 Pople family completion + deprecation warnings. STO-3G, 3-21G, 6-31G(d,p), 6-31++G(d,p), 6-311G(d,p), 6-311+G(2d,p), 6-311+G(2df,p). Surface a UI warning on the 6-311G family per Pitman 2024 and on unpolarised DZ in general.
BS5 ANO-RCC and ANO-R for multireference. Generally contracted; gates CASSCF / CASPT2 / NEVPT2 ingestion (Roos 2005, Zobel 2020).
BS6 Relativistic counterparts. x2c-SVPall / x2c-TZVPall / x2c-QZVPPall (Pollak-Weigend 2017, Franzke 2020), dhf-SVP / dhf-TZVP / dhf-QZVP. Pairs with an X2C / DKH2 / ZORA Hamiltonian in the relativistic phase.
BS7 Composite-method bases. def2-mSVP, def2-mTZVP, def2-mTZVPP, vDZP — each tied to its 3c composite (HF-3c, PBEh-3c, B97-3c, r²SCAN-3c, ωB97X-3c). Gates the composite-method shortcuts (r2scan-3c keyword that bundles basis + D4 + gCP + modified short-range correction).
BS8 Periodic Gaussian — extras. Already-shipped pob-* family stays; add MOLOPT (SZV / DZVP / TZVP / TZV2P) for cross-code parity with CP2K, and dcm-TZVP for system-specific reference work.
BS9 Auxiliary basis sets for RI / DF. def2/J, def2/JK, cc-pVnZ-RIJK, def2-TZVP/C. Required prerequisite for the RI / DF acceleration track (v0.7.x of the acceleration roadmap).
BS10 Property-specific. pcS-n (NMR shielding, Jensen 2008), pcJ-n (J-coupling, Jensen 2006), x2c-TZVPall-s (relativistic NMR/EPR, Franzke 2019), EPR-II / EPR-III, Sadlej (polarisability). Wired alongside their property machinery (NMR / EPR / response).

This sweep is the prerequisite for several other v0.8 / v0.9 / v1.0 items: composite-method shortcuts (BS7), high-throughput TM benchmarking (BS1 + BS6), property runs (BS10), and DLPNO-CCSD(T) benchmark targets (BS1 + BS9 RI auxiliaries). User guide: user_guide/basis_sets.md is the authoritative survey + recommendation surface.

`v0.8.0` — shipped 2026-05-17 — XC functional library expansion¶

✅ Shipped in v0.8.0 (Grimme’s Gecko, 2026-05-17). See the CHANGELOG [v0.8.0] entry “XC functional library expansion”. Plan text below retained for provenance.

🎯 Headline feature — first-class support for every XC functional the test-set queue and the v0.9 composite-method track depend on, with the range-separated-hybrid (RSH) and meta-GGA machinery wired in. libxc resolves any registered name today, but several chemistry-critical functionals need infrastructure beyond a name lookup — RSH needs erf/erfc Coulomb splitting in the K build, double-hybrids need MP2 wired into the SCF, custom hybrids like PW1PW need their fractions registered, and grid coverage for post-PBE meta-GGAs needs auditing.

This entry consolidates “Functional additions” — prerequisite #4 of the regression-suite test-set queue further down this page — into a formal v0.8.0 milestone. Pairs with the basis-set sweep (BS7 wires the composite-method bases; F-series here wires the matching functionals).

F1 Range-separated hybrid machinery (HSE06, ωB97X-V, ωB97M-V, ωB97X). Needs the K-build to handle range-separated Coulomb (erf / erfc kernels) so the short-range and long-range Fock exchange can be mixed at different fractions. ωB97M-V is what current benchmarks (Bursch 2022, Najibi-Goerigk 2018) settle on as the best general-purpose hybrid; HSE06 is the de-facto solid-state hybrid. Both are gated behind RSH.
F2 PW1PW (Bredow’s 1-parameter hybrid) — 20 % HF + 80 % PW91 exchange, PW91 correlation. Not a libxc preset; requires registering the custom mixing as a named functional. Gates parity against the pob-TZVP paper SI (Peintinger, Vilela Oliveira, Bredow 2013, J. Comput. Chem. 34, 451 — published HF and PW1PW totals for ~60 reference compounds; the regression suite consumes Table 2 once PW1PW is wired). Smallest-effort item in this entry.
F3 r²SCAN and the r²SCAN-3c stack. Meta-GGA τ-dependent XC; r²SCAN itself ships in libxc but the periodic Becke-grid path needs auditing for τ-density evaluation correctness. Gates the headline 3c composite (r2scan-3c) — combined with BS7 (def2-mTZVPP) + D4 dispersion + gCP, this becomes the Grimme-recommended “Swiss army knife” default for routine work.
F4 Double-hybrid functionals (DSD-PBEP86-D4, B2PLYP-D4, PWPB95-D4, ωB97M(2), revDSD-PBEP86-D4). Double-hybrids do MP2 on top of a hybrid SCF; this requires the SCF→post-SCF dispatch (already exists) and a configurable MP2 fraction. Gates the GMTKN55 top-tier benchmarking (these functionals win on WTMAD-2 by ~50 % over the best plain hybrid).
F5 D4 dispersion (Caldeweyher et al. 2019). vibe-qc ships D3(BJ) today; D4 is the modern successor with charge- dependent dispersion coefficients and is what every 3c composite
- every modern functional benchmark expects. Companion to F1–F4 rather than a separate functional, but listed here because composites depend on (functional + D4) as a single unit.
F6 libxc coverage audit + UI surfacing. libxc 7.x registers ~600 XC functionals; the user-guide functional table lists six. Audit which of the chemistry-relevant ones (Bursch 2022 table, Najibi-Goerigk WTMAD-2 winners, Mardirossian-Head-Gordon ωB97 family) are reachable today and surface them by name with per-functional notes (kind, HF fraction, D-correction default, recommended use-case). Drive-by: surface a deprecation warning on functionals that newer benchmarks have superseded (e.g. plain B3LYP-without-dispersion for noncovalent binding).

This sweep gates the v0.9.0 composite-methods milestone — once F1 (RSH) + F3 (r²SCAN) + F5 (D4) + BS7 (composite bases) are shipped, wrapping them into single keyword shortcuts (r2scan-3c, ωb97x-3c, etc.) is the v0.9 work. User guide: user_guide/functionals.md is the authoritative recommendation surface.

`v0.8.0` — shipped 2026-05-17 — molecular methods polish (RIJCOSX + JKBuilder + B3LYP-VWN5)¶

✅ Shipped in v0.8.0 (Grimme’s Gecko, 2026-05-17). See the CHANGELOG [v0.8.0] entry “molecular methods polish (RIJCOSX + JKBuilder + B3LYP-VWN5)”. Plan text below retained for provenance.

🎯 Headline feature — molecular SCF / J-K dispatch unified behind a polymorphic JKBuilder abstract base; RIJCOSX (chain-of-spheres exchange, Neese 2009) shipped for all four SCF flavours with analytic gradient (Bykov 2015 frozen-grid); B3LYP convention corrected to VWN5 (Becke 1993 / Stephens 1994 / Gaussian / ORCA convention). Sourced from the molecular methods main chat’s 8-stacked-feature-branch handover (2026-05-09).

Sub-items:

MM1 JKBuilder polymorphic dispatch (branch feature/jk-builder-refactor, commit 09ce308). Polymorphic abstract base with concrete classes FourIndexJKBuilder / DFJKBuilder / COSXJKBuilder / PeriodicGammaJKBuilder. Each factory returns shared_ptr<JKBuilder>. Clean architectural unification of molecular + periodic-Γ J/K dispatch.
MM2 PeriodicGammaJKBuilder adapter (branch feature/periodic-jk-builder, commit 3c80016). Plugs the existing periodic-Γ Fock build into the new JKBuilder base.
MM3 run_*_scf_with_jk SCF body factor (branches feature/run-rhf-scf-with-jk a5d5bf4 and feature/run-scf-with-jk-uhf-rks-uks 31cb3cd). Same SCF body drives RHF / UHF / RKS / UKS molecular AND periodic-Γ calculations — the only difference is the JKBuilder instance passed in.
MM4 RIJCOSX SCF + analytic gradient (branch feature/rijcosx, commit 2dacff6). Chain-of-spheres exchange (Neese, Wennmohs, Hansen, Becker, Chem. Phys. 356, 98, 2009); analytic gradient via the frozen-grid approximation (Bykov, Petrenko, Stoychev, Auer, Neese, Mol. Phys. 113, 1961, 2015). All four SCF flavours; sparse default 110-Lebedev × Treutler-Ahlrichs radial COSX grid; Q-junction overlap fit. Validation: vibe-qc vs ORCA 6.1.1 RIJCOSX on glycine / def2-TZVP, max |Δ| = 0.13 mHa across 6 K-using methods (RHF / UHF / RKS-B3LYP / RKS-PBE0 / UKS-B3LYP / UKS-PBE0).
MM5 b3lyp → libxc id 475 (VWN5) (commit 822e350, lands the intent of branch feature/b3lyp-vwn5-fix, b3273d6). Behaviour break: B3LYP energies move by ~10–15 mHa per heavy atom. Was id 402 (VWN-RPA, libxc default and Gaussian convention); now id 475 (VWN5, the ORCA / ADF convention). Pre-fix vs ORCA’s bare B3LYP disagreed by ~150 mHa on 10-atom organics. New b3lyp/g alias → libxc id 402 selects the Gaussian-compatible VWN3 variant, mirroring ORCA’s B3LYP / B3LYP/G keyword pair. Document loudly in v0.8.0 release notes + the functionals user-guide page, plus a cross-code-parity sidebar in the JCC release paper.
MM6 pbe0 alias (branch feature/pbe0-functional, commit 4c5e4c4). Resolves to libxc id 406 (PBEh).
MM7 New options fields: cosx: bool, cosx_grid: GridOptions on RHF / UHF / RKS / UKS Options + GradientOptions. Default grid via vq.cosx.default_cosx_grid_options().
MM8 New COSX C++ kernels: compute_cosx_k, compute_cosx_k_gradient_contribution.

Resolved in v0.8.x maintenance: DF gradient on glycine / def2-TZVP / RHF disagreed with the direct gradient by ~115 mHa/bohr (energies matched to ~60 µHa). Root cause was a libint engine state leak in compute_3c_eri_gradient_weighted: the inner ket-shell loop reused one libint2::Engine across BraKet::xs_xx deriv_order=1 compute() calls, leaking derivative-buffer state. The earlier per-(sP, sM) engine-freshness fix (commit dc02c69) cut the leak for H2CO but two adjacent same-l heavy atoms (carboxyl O=C-O-H) still mis-attributed ~5–13 mHa per component. Fix: copy a fresh engine per (sP, sM, sN) call. Post-fix the 3c-kernel residual vs finite-difference is ~1e-7 Ha/bohr. Regression guard: tests/test_df_gradient.py::test_df_rhf_gradient_hcooh_def2_tzvp_matches_direct. density_fit=True gradients are now safe at def2-TZVP-class basis sets.

Continuation chats (post-handover):

“Continue vibe-qc molecular methods main chat” — picks up EDIIS+DIIS hybrid, SOSCF/TRAH, periodic DF, periodic COSX, multi-k JKBuilder generalisation, wave-2 functionals (M06-2X, ωB97X-D, TPSSh, r²SCAN).
“PW1PW + weighted-sum xc alias path” — implements PW1PW (gates parity against the pob-TZVP paper SI Table 2) plus the weighted-sum aliasing infrastructure for HSE-3c, B97-3c, etc.

`v0.8.0` — periodic SCF chain (restricted HF/DFT, all Bravais, no-fit + DF + RIJCOSX)¶

Status — partly historical, with maturity additions through v0.10.0.

v0.8.0 baseline (shipped 2026-05-17 as Grimme’s Gecko): the restricted periodic surface is the Ewald-3D stack at its v0.7.x maturity. The molecular-methods work (B2PLYP / DSD-PBEP86 double hybrids, direct SCF, RIJCOSX, D4 dispersion, EEQ, grid expansion) was the actual v0.8.0 headline. See the CHANGELOG [v0.8.0] section for what shipped.

v0.10.0 maturity additions (over the v0.8.x → v0.10.0 arc): multi-k Ewald EDIIS via the real Python accelerator family (eb8f25bd), SYM6 / cluster-A1 EWALD_3D auto-gauge enforcement

CRYSTAL α parity (859efe0a), and BIPOLE L_max levels for the Γ-only correlated-periodic surface.

Periodic GDF deferral chain (compcell + multi-k + AFT) — four cycles: v0.8.0 → v0.9.0 → v0.10.0 → v0.11.0. The GDF route still does not converge to PySCF parity on real systems: LiH primitive FCC was off by +22 Ha at v0.9.0; MgO 8-atom conv cell off by ~+1500 Ha. The remaining gap is a 3c AFT convention mixing for L>0 chg shells in the bare lattice sum, isolated in the M1 investigation at b8f1e509. Full state in handover_gdf_v0_11_2026_05_29.md; the v0.11.0 milestone entry (below, headed “periodic GDF chain (compcell + multi-k + AFT)”) is the closing slot. The parallel BIPOLE periodic route is further along and is the nearer-term periodic-correlated surface. The PSCF0–PSCF5 sub-items below are the original v0.8.0 plan, retained for provenance — treat their version targets and the GDF maturity claims as superseded by this note.

🎯 Headline feature — restricted (closed-shell) periodic HF and DFT made rock-solid for v0.8.0, exercised across all Bravais lattices (cubic / tetragonal / orthorhombic / hexagonal / monoclinic / triclinic, in 1D / 2D / 3D) and all three Coulomb-method modes:

Standard (no fitting) — direct 4-center periodic ERIs.
DF (GDF) — native Gaussian density fitting.
RIJCOSX — RI-J + chain-of-spheres semi-numerical exchange, with the four CRYSTAL/ORCA-style tuning knobs (COSX grid density, !NOCOSX last-cycle, no-RI last- cycle, UHF/RHF scaling note).

Scope correction (2026-05-13): open-shell UHF / UKS (Γ and multi-k) slip to v0.9.x. The earlier v0.8.0 bundle that included UHF/UKS predates the current rock-solid-restricted- first directive. The PSCF1 + PSCF5 sub-items below describe work that needs to be rewritten on the new gamma-GDF scaffold (the old PySCF-Lpq feature branches were retired on 2026-05-13).

Sourced from the periodic-QC main-dev chat (current ownership chain documented in project_periodic_rhf_gdf_spike.md).

Sub-items:

PSCF0 (NEW, restricted-foundation) Restricted RHF/RKS rock-solid on all Bravais. The v0.8.0 release gate. Three Coulomb modes, applied uniformly:
- PSCF0.std — Standard (no fitting): direct 4c-ERIs. Audit DIRECT_TRUNCATED + EWALD_3D across all Bravais; CRYSTAL14 cross-check on cubic / hexagonal / triclinic.
- PSCF0.df — DF (GDF): native Lpq via aux_basis.build_lpq_native (Γ) and build_lpq_bloch_native (multi-k, shipped on feature/multi-k-gdf-scf-loop 2026-05-13 with the SCF loop).
- PSCF0.cosx — RIJCOSX: RI-J via the DF path + chain-of- spheres exchange on the periodic Becke grid. Molecular RIJCOSX rewritten from scratch on the new JKBuilder architecture (the stale feature/rijcosx branch was retired). Four tuning knobs (COSX grid density, !NOCOSX last cycle, no-RI last cycle, UHF/RHF scaling note).
PSCF1 (SHIPPED in v0.9.0 via BIPOLE, not GDF) Open-shell periodic SCF at Γ. Ships as run_pbc_bipole_uhf / run_pbc_bipole_uks (the CRYSTAL-style BIPOLE Fock build), DIIS-validated on MgO / diamond / silicon. The earlier run_uhf_periodic_gamma_gdf plan was abandoned because the underlying Γ-GDF chain itself does not yet match PySCF.pbc.GDF (deferred to v0.10.0). The BIPOLE driver supersedes it as the production open-shell-Γ path. Status 2026-05-13: the original feature/uhf-periodic-gdf branch (and its validation companion) was retired on 2026-05-13 because it was built on the old PySCF-Lpq scaffold that codex replaced. Native UHF Γ-GDF was a fresh rewrite on top of the new periodic_rhf_gdf.py foundation, ~1 day. Historical validation numbers from the old branch are preserved below for reference. Validation parity numbers (refreshed 2026-05-09 from the UHF-A.1 chat handover):
- Closed-shell sanity: MgO sto-3g UHF (mult=1) ≡ RHF to 1.4×10⁻¹² Ha.
- H atom in 20 Å vacuum-padded cubic cell, mult=2: vs pyscf.pbc.scf.UHF + GDF → 5.6×10⁻¹⁷ Ha (literally machine zero).
- OH radical 9 e⁻, mult=2: vs PySCF UHF → 2.5×10⁻⁹ Ha.
- Iter-1 J/K parity vs pyscf.pbc.UHF.get_jk to machine precision (max|ΔJ|≤10⁻¹⁴, max|ΔK_σ|≤4×10⁻¹⁵) on H, OH, NO, MgO closed-shell.
Caveat at this release: GDF UHF lacks Saunders-Hillier level shift; ‖[F,DS]‖ can stall on UHF radicals (OH, NO) even though energy parity is sub-nHa. result.converged may report False while the energy is correct. Workaround: trust the energy if the iter trace stabilises; OR fall back to run_uhf_periodic_gamma_ewald3d (legacy, has level shift) for cells where the Ewald path is valid; OR wait for the level-shift port (~10 lines, travels with the open-shell GDF chain to v0.9.0). NO converging to a different stationary point than PySCF is a known UHF instability, not a vibe-qc bug — H-atom and OH suffice as parity oracles.

Design point worth noting: one J build per iter on D_α + D_β, two per-spin K builds; per-spin Madelung correction madelung·S·D_σ·S matches PySCF’s _ewald_exxdiv_for_G0 per-spin convention.
PSCF2 Multi-k periodic SCF (restricted, closed-shell): run_krhf_periodic_gdf(..., kmesh) + run_krks_periodic_gdf(..., kmesh, functional) + result classes. Status 2026-05-13: native SCF loop landed on feature/multi-k-gdf-scf-loop @ c19e451, built on top of aux_basis.build_lpq_bloch_native(q_cart). 15 local tests green (cubic / hexagonal / triclinic; Γ delegation matches gamma driver to 3.6×10⁻¹⁵ Ha on H₂). Real-system parity vs CRYSTAL14 + PySCF KRHF on planetx is the v0.8.0 gate.
PSCF3 Streaming-Lpq for multi-k production scale. Dense Lpq[k1,k2] storage hits multi-TB on large unit cells (a ~290-atom cell at a [2,2,2] mesh ≈ 5 TB). Streaming chunks the Lpq tensor along k-pairs; chemistry unchanged, peak-memory dramatically reduced.
PSCF4 Native-GDF Lpq drop-in. Drops the PySCF dependency on the integral side. Already shipped: C++ compute_2c_eri_lattice / compute_3c_eri_lattice (4958b4e / 3c0c239) + aux_basis.build_lpq_native (~5% residual on native 2c metric; design at docs/design_native_gdf.md). Slice 3d (compcell + Ewald-split for the long-range periodic 2c metric) closes the residual at v0.8.0.
PSCF5 (SLIPPED TO v0.9.x — open-shell) UKS + PW1PW Γ-only. Same scaffold caveat as PSCF1: needs rewrite on the new gamma-GDF foundation. PW1PW + the per-component Functional scaling that lands with it stays on the v0.9.x slate. Concrete in-flight pieces:
- C++ Functional: per-component scaling + extra_hf_fraction infrastructure. Built; new aliases pbe0 and pw1pw resolve correctly (PW1PW α=0.20, PBE0 α=0.25). pw1pw is the first non-libxc-built-in custom hybrid in vibe-qc; per-component scaling in Functional::Impl makes future custom hybrids (mPW1PW, BHandHLYP, …) a one-line alias-table addition.
- python/vibeqc/periodic_uks_gdf.py — α/β GDF driver (V_xc from PySCF as in RKS GDF; will move to native once build_xc_periodic V_xc gauge bug closes in v0.9).
- run_periodic_job(method="UKS", functional="pbe"|"pbe0" |"pw1pw"|"b3lyp") dispatch.
Gates parity against the pob-TZVP paper SI Table 2 (Peintinger-Vilela Oliveira-Bredow JCC 34, 451 (2013)) — authoritative ~60-compound oracle for periodic hybrids. Cite Bredow & Gerson PRB 61, 5194 (2000) for the PW1PW recipe.

Workaround for users today: run_uks_periodic_gamma_ewald3d is broken on ionic crystals (same Fock-gauge issue as the RHF Ewald path). Don’t use; wait for the GDF UKS dispatch.
PSCF6 run_periodic_job(..., kmesh, method, multiplicity) extended dispatch. Single high-level entry point handles RHF/UHF/RKS/UKS × Γ-only/multi-k via the same run_periodic_job keyword API.

Already on main (foundation work):

run_rhf_periodic_gamma_gdf Γ-only RHF + RKS GDF driver (3fd242a + b196337 + ece5cb4)
BasisSet ShellInfo ctor + aux_basis.modrho_renormalise
- slice-3c diagnostics (91662ce / 4ba3ac1 / c933503)
C++ periodic 2c/3c ERI bindings + native Lpq builder (4958b4e / 3c0c239)
OPTIMADE structure fetcher (1bec644)

Headline parity result (already validated on main): MgO/sto-3g/Γ RHF parity vs PySCF.GDF, ΔE = −6.8×10⁻¹² Ha (machine precision). 8-system × 3-method × 2-basis sweep: 20/23 sub-µHa parity (3 outliers convergence-protocol differences). UHF closed-shell parity gate passes (UHF M=1 ≡ RHF on MgO/sto-3g/Γ to <10⁻⁹ Ha).

Open known bugs (carry into v0.9.x maintenance):

Si-diamond × 3 + C-diamond / PBE / pob-TZVP converge to different stationary point vs PySCF (~mHa); suspected DIIS-tightness difference, not algorithmic.
Multi-k dense Lpq[k1, k2] RAM ceiling (workaround until PSCF3 ships: small-system × full-kmesh OR full-system × small-kmesh).
pob-TZVP missing Ne entry (KeyError); workaround branch fix/pob-tzvp-add-ne exists.

Library-only design philosophy (de-PySCF audit 2026-05-09): vibe-qc’s runtime dependencies are libxc + libint + spglib + libecpint only — no other QC programs as engines. PySCF appears in pyproject.toml only in [test] and [dev] extras, never base. ASE is opt-in only via vibeqc[ase]. The 3 core files that currently import PySCF (periodic_rhf_gdf.py, _basis_g94.py, benchmark.py) are the closure points for the de-PySCF migration: removing PySCF from periodic_rhf_gdf.py is the v0.8.0 slice-3 modrho work (PSCF4); the other two close in v0.9+. This is a strong differentiator vs codes that require ASE / PySCF / etc. as engines — vibe-qc + libint + libxc + spglib + libecpint = a closed dependency graph among open-source MIT/LGPL/MPL libraries with no QC-program runtime peer.

v0.9.0+ carry-forward (from periodic SCF chain):

Native V_ne gauge alignment (periodic_rhf_gdf.py:53-57) — closes the gauge-difference workaround that the GDF-default driver applies today.
Fix build_xc_periodic O(10 Ha)/atom V_xc gauge bug (periodic_rhf_gdf.py:541). Loud, not silent. Default driver routes around it via PySCF Becke grid; v0.9 ports V_xc to a native gauge-aligned grid. Same bug surfaces in the UKS path (build_xc_periodic_uks); UKS GDF driver sidesteps via the same PySCF route.
Drop _basis_g94.load_g94_for_pyscf() once no caller needs it. Closes one of the 3 PySCF-importing core files.
Migrate [test] extra off PySCF long-term. Even the test deps want to drop PySCF eventually; cross-code parity oracles shift to ORCA + CRYSTAL reference data.

`v0.8.0` — shipped 2026-05-17 — basis-set library + ECP integration completion¶

✅ Shipped in v0.8.0 (Grimme’s Gecko, 2026-05-17). See the CHANGELOG [v0.8.0] entry “basis-set library expansion + ECP integration completion”. Plan text below retained for provenance.

🎯 Headline feature — completes the basis-set + ECP infrastructure: 87 new BSE-fetched bases bundled (142 → 236 .g94 files), libecpint integration end-to-end, and Phase 14e auto-population of ecp_centers from BasisSet ECP info so vDZP / dhf-* / x2c-* SCF works without manual ECP wiring. Sourced from the basissetdev chat’s 2026-05-09 handover.

Sub-items:

BSC1 87 new BSE-fetched bases bundled (commit a5f4906 on basissetdev branch; pending rebase). Includes: pcseg-{0..4}, aug-pcseg-{0..4}, pc-{0..4}, Pople diffuse, def2-mTZVP/mTZVPP, dhf-* and x2c-* relativistic, Grimme vDZP, full LANL family, cc-pV(n+d)Z + aug-, cc-pCV{D,T,Q}Z, ANO-RCC-VxZP variants, ANO-R0..3, Sadlej, pcS/pcSseg/pcJ, Sapporo / Cologne / SARC DKH. Closes most of BS1–BS6 in the v0.8.0 basis-set library expansion entry above.
BSC2 libecpint integration end-to-end (commit add8163; banner now lists libecpint 1.0.7). .g94 ECP- block splitter (Phase 14d); total_ncore valence-electron accounting in all 4 SCF drivers. Pt UHF/LANL2DZ converges (E = −118.227 Ha) as the smoke test.
BSC3 Phase 14e — auto-populate ecp_centers from BasisSet ECP info so vDZP / dhf-* / x2c-* SCF works without manual [ECPCenter(Z=, xyz=)] wiring. Needs libecpint set_ecp_basis(...) inline-primitive feed for vDZP.
BSC4 CRYSTAL 200+Z ECP parser → 5th-period pob. Currently the CRYSTAL parser recognises ECP blocks but raises NotImplementedError; this closes that gap.
BSC5 Pob S d-polarisation column-swap fix (commit f059b37). Latent bug since 2013: exp/coeff column swapped on the S d-polarisation entry in upstream pob-TZVP / -rev2 / pob-DZVP-rev2; CRYSTAL’s parser tolerated it; libint exposed it. All 3 pob bases now byte-clean to the corrected upstream. Cross-code-parity success story for the JCC paper.
BSC6 Basis-set optimisation engine scaffold (commit 0ac5fb9). Parametrise / objective / scipy + iminuit drivers / TempBasisLibrary. Live H-atom UHF smoke validated end-to- end. Foundation for v0.9 multi-compound LD-aware basis optimisation.
BSC7 13 cubic-ionic test-set inputs (commit 6a77356) covering PT2013 SI Table 4 reference systems. Self-contained; reproducibility-package quality.

User-facing API (post-rebase): RHFOptions.ecp_centers, .ecp_library on all 4 SCF; vq.ECPCenter class; vq.compute_ecp_matrix(...); vq.libecpint_version(); 87 new basis-set names resolvable via vq.BasisSet(mol, name).

Open known issues (carry into v0.9.x): heavy-atom load test cumulative-OOMs the laptop on full 366-case batch (workaround: route via vq submit to planetx); 3c composite methods (r²SCAN-3c, B97-3c, ωB97X-3c) basis carriers ship but gCP + D3/D4 aren’t wired through the molecular runner (don’t promise turnkey 3c — workaround: def2-TZVP + matching ECP + D3(BJ) until v0.9.0 composite-methods milestone).

Branch state: basissetdev is rebased onto current main and 6 commits ahead. NOT merged. User reserved the rebase for “after the papers ship” — coordinate timing with the release chat.

`v0.8.0` — vq queue v0.4 (web UI + cgroups v2 enforcement)¶

Codename TBD (candidates: Manticore, Kraken — sister to vibe-qc’s Scientist+Animal scheme but vq has its own).

🎯 Headline feature — vq queue tool gains cgroup-v2-based in-kernel resource enforcement (replacing v0.3’s signal-based watchdog) plus a read-only web UI for monitoring jobs without SSH’ing into the daemon host. Sourced from the vq chat’s 2026-05-09 handover.

Sub-items:

VQ4a cgroups v2 enforcement via systemd-run --user --scope. The v0.3 watchdog samples every 5 s; a runaway alloc faster than that can still OOM the host. Cgroup enforcement is in-kernel and immediate.
VQ4b Read-only web UI — FastAPI over JSON state. Browse the queue, click into a job, see the live stdout/ stderr/system manifest. No write actions yet (those land in v0.5).
VQ4c Per-job event log for the dashboard timeline.

Already shipped on main since v0.7.0: vq v0.1 → v0.3 covering the local queue, daemon, submit/queue/status/kill/ fetch CLI, cross-machine SSH submit, watchdog (mem / wall-time / CPU-starvation), JobSpec v2 with three new terminal states (oom_killed, starved, time_exceeded), _vq/samples.jsonl event sampling. planetx daemon under systemd-user with --max-jobs 1 test phase; laptop has vq on PATH and config at ~/.config/vq/config.toml. 251 tests on macOS, 253 on Linux.

Note — this entry is a v0.8.0 snapshot, now superseded. vq has moved far past the v0.4 headline above: as of 2026-05-17 it is at vq v0.5.43, with the web UI, bearer-token auth, write API, webhook notifications, retry, auto-resume, priorities, throttle / drain, and the vq cleanup lifecycle all shipped. The forward plan is no longer the stale list that used to sit here — see the vq job-queue program below for the current state and roadmap.

vq lives in the same repo as vibe-qc (under vibe-queue/); canonical handover at vibe-queue/docs/handover.md; design spec at vibe-queue/docs/SPEC.md; its own roadmap at vibe-queue/docs/roadmap.md.

`v0.8.0` — shipped 2026-05-17 — `vqfetch` external-data integration (Phase 1: structures)¶

✅ Shipped in v0.8.0 (Grimme’s Gecko, 2026-05-17). See the CHANGELOG [v0.8.0] entry “vqfetch external-data integration (Phase 1: structures)”. Plan text below retained for provenance.

🎯 Headline feature — first-class structure fetcher pulling from open databases (OPTIMADE federation primary; Materials Project, COD, NOMAD secondaries) into ready-to-run vibe-qc inputs. Every fetched record carries source DB + ID + URL + DOI + license + fetched_at + fetcher_version in a structured Provenance so downstream calculations are reproducible by construction, not retroactively. Phase 2 (NIST CCCBDB experimental references) is design-only at v0.8.0 and ships in v0.9.0+.

Sourced from the vqfetch chat’s 2026-05-09 handover (corrected in the docs chat’s file 16). 3 commits queued on claude/tender-wright-9ce8c8:

ae80516 — schema (Provenance, dataclasses)
dc9f877 — OPTIMADE + cache + CLI
514423b — COD + smoke harness

Plus 4b2e67b already on main: CHANGELOG flag for the v0.8 fetcher deliverable.

Branch state: claude/tender-wright-9ce8c8 is behind main on unrelated DF + basis-library reshuffle work; merge needs conflict resolution. Don’t block v0.8 release planning; merge before v0.8 ships, OR punt to v0.8.1.

Sub-items shipping at v0.8.0:

VFETCH1 vqfetch console script + vibeqc.fetch package. New [project.scripts] entry; new [project.optional-dependencies] fetch extra. CLI: vqfetch <optimade|cod|mp|nomad|canonical> <identifier> with shared flags --out, --no-cache, --cache-only, --quick. Pinned deps: optimade>=1.0,<2, beautifulsoup4>=4.12,<5, lxml>=4.9 in the fetch extra.
VFETCH2 OPTIMADE federation primary + Materials Project, COD, NOMAD secondaries (structure pulls). Round- trip live-verified on 5 canonical structures (MgO / NaCl / LiH rocksalt; Si / C diamond) — MP → SPEC → vibe-qc input within 1%. Live-resolved canonical IDs (mp-1265, etc., resolved 2026-05-05 — not training-data inventions). Accepts general 3D lattice matrices; production parity remains tied to the native FFTDF/GDF benchmarking track.
VFETCH4 Schema dataclasses: Provenance, ExperimentalReference, ReferenceKind Literal, TestSystem union — added to examples.regression.core.spec. Backward-compatible recommended_basis, magnetic_moments, is_open_shell, provenance fields on PeriodicSpec / MoleculeSpec. Bridge: examples.regression.core.expected_bridge.attach_reference_to_expected.
VFETCH5 Regression-suite report wiring + smoke harness. Currently in flight in the v0.7.x window. Includes a NIST column placeholder for v0.9 Phase-2 occupancy.

Python API exports:

from vibeqc.fetch import (
    fetch_optimade, fetch_cod,
    emit_input_script, emit_spec_module,
    FetchCache,
)

Env vars:

$VIBEQC_FETCH_CACHE_ROOT — override cache location
$VIBEQC_FETCH_CACHE_ONLY — never hit network
$MP_API_KEY — Materials Project API key

No deprecations.

Documentation: a user-guide page exists in design-worktree form at claude/awesome-noether-2de783:docs/user_guide/external_structures.md

docs/handover_structure_fetcher.md. Should land on main if v0.8 ships the fetcher.

v0.9.0+ — Phase 2 (NIST CCCBDB experimental references):

Reference-data fetcher (vibeqc.fetch.references): atomization energies, ΔHf, vibrational frequencies, IE/EA, dipoles. Design drafted at docs/handover_reference_data_fetcher.md in the worktree; no code at v0.8.0.
Single exp2x.asp parser strategy (NIST simpler than docs suggest).
Footgun to document: CCCBDB’s atomization_energy_kcal_per_mol is D₀ (ZPE-included), not the QC-textbook D_e — must be flagged in Provenance.notes per record; readers who skip it could miscompare.

v0.9.0+ — polish:

Phase-1: NOMAD raw-archive hook, Materials Project property fields beyond OPTIMADE, cross-provider consistency check, and broader bulk-sweep tooling across all crystal systems.
Phase-2: NIST WebBook fallback when CCCBDB misses, CCCBDB geometry → MoleculeSpec bridge, bulk-sweep tooling, ATcT (Active Thermochemical Tables) integration.

Citations:

OPTIMADE — Andersen et al., Sci. Data 8, 217 (2021). doi:10.1038/s41597-021-00974-z
Materials Project — Jain et al., APL Mater. 1, 011002 (2013). doi:10.1063/1.4812323
COD — Gražulis et al., J. Appl. Crystallogr. 42, 726 (2009). doi:10.1107/S0021889809016690
CCCBDB (v0.9 forward-mention) — NIST SRD 101, doi:10.18434/T47C7Z

`v0.8.x` — native molecular geometry optimizer (shipped)¶

✅ Shipped in v0.8.x (2026-05-22).

vibeqc.optimize_molecule — an ASE-free molecular geometry optimizer using analytic SCF gradients wrapped in scipy L-BFGS-B. Supports RHF, UHF, RKS, UKS (analytic gradients), wavefunction methods via central finite differences, D3(BJ) dispersion, and CPCM solvation. Trajectory frames and energies are collected in memory for direct QVF embedding (vibe-view animation player).

run_job exposes it through optimizer_backend="native" — no pip install ase needed. The default (optimizer_backend="auto") prefers ASE when installed and falls back to the native path otherwise, so existing workflows are unchanged.

`v0.9.0` — ✅ shipped — composite “3c” methods stack¶

Codename TBD (candidates: Grimme’s Gerbil, Sure’s Skink, Brandenburg’s Beaver). Shipped in the v0.9.0 Knowles’s Kingfisher cycle (per CHANGELOG [v0.9.0]).

Status (2026-05-19) — LANDED. All 7 composites (hf-3c, pbeh-3c, b97-3c, b3lyp-3c, r2scan-3c, wb97x-3c, hse-3c) are RUNNABLE end-to-end via vq.run_job(method="<name>", ...). The vibeqc.composites registry + vibeqc.gcp standalone API + the data_library/ TOML parameter-storage standard + 5 bundled 3c orbital bases all shipped. Sits on the RSH (F1) + meta-GGA (F3) + D4 (F5) machinery, all of which landed independently in the v0.8.x → v0.9.0 functional sweep. Remaining polish tracked as v0.9.x patches: vDZP gCP per-element data (ωB97X-3c gCP currently logs SKIPPED), canonical r0ab-table SRB for B97-3c, and the Direct/DF/COSX long-range-K paths for large-system RSH SCF.

🎯 Headline feature — keyword-shortcut support for the modern Grimme-school composite “3c” methods: a single name (r2scan-3c, ωb97x-3c, b97-3c, pbeh-3c, hf-3c, b3lyp-3c, hse-3c) bundles a tuned basis + dispersion + gCP counterpoise + (sometimes) a modified short-range correction into one user-facing method. These are the highest-leverage addition for routine users today: GMTKN55 MAEs comparable to much-more-expensive plain-functional + triple-zeta calculations, at small-basis cost.

Sits on top of v0.8.0: BS7 (composite-method bases: def2-mSVP, def2-mTZVP, def2-mTZVPP, vDZP) + F1 (range-separated hybrids for ωB97X-3c) + F3 (r²SCAN family for r²SCAN-3c) + F5 (D4 dispersion). Once those land, the remaining work is the wiring — registering the keyword shortcuts and the counterpoise machinery — which is a small layer on top.

C1 Keyword-shortcut machinery. vq.run_job(method="r2scan-3c", ...) resolves to the right (functional, basis, dispersion, gCP) tuple per the Grimme group’s published recipes. Recipe table registered as a static dict; failure if a recipe references a basis or functional that’s not yet shipped (forces ordering with v0.8.0).
C2 gCP — geometric counterpoise correction (Kruse & Grimme, J. Chem. Phys. 136, 154101, 2012). Pure-Python addon over the SCF; per-atom-pair correction; needs only the geometry + element list + basis-set name. Standalone API vq.compute_gcp(mol, basis_name) plus auto-wiring inside the 3c keyword shortcuts.
C3 Modified short-range corrections per composite. PBEh-3c uses a modified PBE0 with re-tuned HF-exchange fraction + range-separation parameters; same shape for HSE-3c, B3LYP-3c. Per-recipe in the C1 table.
C4 Per-recipe parameter table. One static dict mapping composite_name → (functional, basis, dispersion, gCP, sr_mod). Sourced from the original publication tables; pinned to specific paper versions. Editable in one place.
C5 Per-composite documentation pages under user_guide/composites/ (or one consolidated chapter): when to use each composite (system class), MAE on benchmarks (GMTKN55, TorsionNet206, S22, X23), citation, runtime cost relative to the parent functional + basis without the corrections.

Per-composite slot (recommended use, adapted from the basis-set survey § Composite “3c” methods):

Composite	Best for	Cost vs. plain TZ-hybrid
r²SCAN-3c	“Swiss army knife” — geometries, thermochemistry, noncovalent, transition-metal complexes	~10-20× cheaper
ωB97X-3c	Drug-like / pharma; barrier heights; vDZP basis with ECPs	~5-10× cheaper
B97-3c	Workhorse GGA; especially good for transition metals	~30× cheaper
PBEh-3c	Strong noncovalent geometries	~20× cheaper
HF-3c	Mean-field qualitative; very large systems	~100× cheaper
B3LYP-3c	IR spectra (B3LYP frequencies are particularly accurate)	~20× cheaper
HSE-3c	Solid-state range-separated variant (gates on the periodic GDF SCF)	~20× cheaper

User guide chapter — to be authored alongside the implementation. Cross-link from tutorial set once a “recommended first calculation” recipe per composite is settled.

`v0.9.x` — ✅ shipped — semiempirical platform (3 families, 7 methods)¶

Status — shipped. All SE1–SE4 gaps resolved (v0.9.x cycle). NDDO periodic drivers + OMx Loewdin parity fix landed in v0.10.x (b74c86d9–a4b8cd04). GFN2-xTB max_iter fix (695bc7be). Cell-optimization wrappers optimize_pm6_cell / optimize_omx_cell (35c098db + 2253b315). ASE lattice guard (32c28329). Slater overlap dedup (4ee5c79f). GFN2 H0 AO-order bug fixed in the 2026-05-31 audit; GFN2 remains gated experimental and non-quantitative.

A self-contained semiempirical platform covering three method families — DFTB, GFN-xTB, and NDDO — across seven methods for molecules and periodic solids. The platform is vibe-qc’s own implementation, not a wrapper around external programs (cf. CLAUDE.md §10). GFN2-xTB parameters are LGPL-3.0 and fetched on demand (ADR-002); all other code is MPL-2.0.

Shipped — all 7 methods:

Method	Family	Molecular	Periodic	Gradient	Open-shell	Elements
DFTB0	DFTB	✅	✅ Γ+k	exact	✅	91 in-house
SCC-DFTB	DFTB	✅	✅ Γ+k	approx	✅	91 in-house
GFN2-xTB	XTB	⚠ gated	✅ Γ	approx	✅	86 pub (LGPL)
PM6	NDDO	✅	✅ Γ	FD	✅ mol	82 MOPAC
OM1	NDDO	✅	✅ Γ	FD	✅ mol (thin validation)	5 pub
OM2	NDDO	✅	✅ Γ	FD	✅ mol (thin validation)	5 pub
OM3	NDDO	✅	✅ Γ	FD	✅ mol (thin validation)	5 pub

DFTB family (DFTB0, SCC-DFTB, UDFTB0, USCC-DFTB):

Analytic gradients — all four molecular variants (fixed-charge approximation for SCC / USCC).
D3(BJ) dispersion — across all four variants.
Periodic Γ + k-points — analytic gradients, FD stress, variable-cell optimisation.

GFN2-xTB family:

Uses published Grimme-group parameter set (86 elements), fetched on demand at first use (LGPL-3.0 → MPL-2.0 boundary).
Gated experimental. The SCC driver is size-consistent and has symmetric charge response after the 2026-05-31 H0 AO-order audit fix, but it remains non-quantitative.
Known limitations: the current implementation still has a p-shell/deep-state H0/overlap defect, and it does not yet include anisotropic electrostatics (AES), the 3rd-order on-site term, or self-consistent GFN2-D4 dispersion. Do not claim xtb parity.

NDDO family (PM6, OM1, OM2, OM3):

PM6 — closed-shell NDDO Fock builder with MOPAC diatomic pair core-core corrections (alpb/xfac) and Gaussian terms (guess1/guess2/guess3). 82-element coverage via MOPAC parameter set. Periodic Γ-point with lattice-summed two-center terms. Molecular ↔ periodic parity at machine precision (1e-16 Ha).
OM1/OM2/OM3 — Löwdin orthogonalization correction with staged SCF (warmup + density mixing). Published parameters from Dral 2016. Periodic driver with lattice-summed overlap and Loewdin transform. Molecular ↔ periodic parity at machine precision.
Python models — PeriodicPM6Model, PeriodicOMxModel with energy(), gradient() (FD), stress() (FD).
Convenience wrappers — optimize_pm6_cell(), optimize_omx_cell() for one-liner cell relaxation.
FD-only gradients — analytic NDDO gradients deferred.

Shared infrastructure:

Method registry with MethodFamily enum (DFTB, XTB, NDDO).
Single overlap-derivative gradient engine (DFTB/GFN2).
CP-SCC Z-vector charge-response correction.
SemiempiricalModel abstract base → ASE calculator integration.
Benchmark data generator: scripts/generate_semiempirical_benchmarks.py.
Reference comparison scripts: scripts/compare_{dftbplus,xtb,mopac}.py.

Remaining refinements:

GFN2-H1 full anisotropic multipole (H¹ term) — the dominant accuracy gap for GFN2-xTB on multi-atom systems.
SE5a full CP-SCC MO-coefficient response — Z-vector correction shipped; full orbital response pending.
NDDO-ANALYTIC analytic gradients for PM6/OMx — currently FD.
NDDO-OPEN unrestricted NDDO — PM6/OMx currently closed-shell only.

`v0.x.x` — 🚧 in progress — MACE machine-learning interatomic potential (MLIP) interface¶

Status — M1 shipped (df4646d2); M2–M5 queued. vibe-qc’s first interface to an external pre-trained ML interatomic potential. Unlike the semiempirical platform above — which is vibe-qc’s own implementation — MACE is ACEsuit’s pre-trained equivariant-GNN model: vibe-qc drives its forward pass and attributes it as such. This is an explicit, maintainer-approved extension of CLAUDE.md §10 to admit pre-trained-model engines (decided 2026-06-02; §10 note lands in M4).

MACE is a higher-order E(3)-equivariant message-passing neural-network interatomic potential. It predicts energy / forces / stress on a DFT-fitted potential-energy surface — it does not solve the Schrödinger equation, and its energies are reference-shifted (per-element E0 subtracted), not total electronic energies. Exposed as a first-class method="mace" for fast geometry optimization, MD pre-screening, and Hessian preconditioning — substantially more accurate than the semiempirical methods within its trained domain, but with no electronic structure (no orbitals / charges / gap) and only over its trained elements/chemistries.

Licensing (full detail in docs/license.md, M4):

MACE code (mace-torch) is MIT; pulled via an optional [mace] extra, never core. Heavy stack (PyTorch + e3nn, ~650 MB); Python ≤3.13 only (its matscipy dep ships no 3.14 wheel — the repo dev .venv is 3.14, so the extra is a no-op there and the runtime import is gated).
Foundation-model weights are licensed separately and never bundled — fetched on demand into the XDG cache (the vqfetch pattern). MP-0 / MPA-0 (materials) are MIT and ungated; OFF23 / OMAT-0 / MATPES / MH / MDP are ASL (academic, non-commercial) and gated behind an explicit non-commercial acknowledgment.

Milestones:

#	Scope	Status
M1	Plumbing: `[mace]` extra, `vibeqc.mlip.mace` wrapper, `method="mace"` dispatch, `_MLIPResult`	✅ shipped
M2	Weights: XDG on-demand fetch, MIT-ungated / ASL-gated, provenance → SCF log + `.system`	⬜
M3	Periodic: ASE `Atoms`+cell → MACE energy/forces/stress (materials — the MIT sweet spot); geometry-opt wiring	⬜
M4	Provenance: citation DB entries + routes (Batatia 2022, e3nn, PyTorch), `docs/license.md`, banner probe, §10 doctrine note	⬜
M5	Tests/CI: ≤3.13 CI lane installs `[mace]`, parity vs standalone MACE, 3.14 import-gate skip	⬜

Energy-scale caveat. method="mace" returns a reference-shifted DFT-surface energy in its .energy (Hartree), not a total electronic energy — output writers must not mix it with HF/DFT totals. Verified on H₂O / MACE-MPA-0: ≈ −0.507 Ha (vs ab-initio total ≈ −76 Ha).

`v0.9.0` — 🚧 partial — implicit solvation¶

Codename TBD (candidates: Onsager’s Whale, Tomasi’s Octopus).

Status — partial. CPCM energy (S1a continuum cavity + S1b Fock contribution) landed across v0.9.x + v0.10.x; solvent presets (S1d) wired through alongside. The analytic solvation gradient (S1c) deliberately slipped to v0.10.x → v0.11.x per CHANGELOG [Unreleased].

🎯 Headline feature — CPCM / COSMO molecular implicit solvation. Aqueous chemistry is most users’ default reaction medium.

S1a Continuum cavity — solvent-excluded surface (SES) / solvent-accessible surface (SAS) tessellation, Bondi radii, GEPOL defaults.
S1b CPCM Fock / energy contribution — apparent surface charge iterated to self-consistency inside the SCF loop.
S1c Solvation gradient — analytic ∂E_solv/∂R for geometry optimization in solvent.
S1d Solvent presets (water, DMSO, MeCN, DCM, …) wired through run_job + ASE calculator.

`v0.9.0` — ✅ shipped — DFT+U (Dudarev rotationally-invariant)¶

Shipped across the v0.9.0 cycle through ten increments (1 → 4d-bipole-closed-shell). Per-commit SHAs in HANDOVER_DFT_PLUS_U.md. See CHANGELOG entries under v0.9.0 starting “DFT+U (Dudarev) Python machinery” and ending “DFT+U on closed-shell BIPOLE drivers”.

🎯 Headline feature — Hubbard-U correction for strongly- correlated d/f electrons (transition-metal oxides like NiO, late-3d adsorbates on Fe slabs for the haber-bosch target, self-interaction-corrected lanthanide chemistry). Dudarev et al. PRB 57, 1505 (1998) rotationally-invariant E_U = (U_eff/2)(tr n − tr n²) per (atom, l) channel with the variational Fock contribution V_U_fock = S V_AO S required for non-orthogonal AO bases. Cite Cococcioni & de Gironcoli PRB 71, 035105 (2005) for the linear-response U_eff prescription. Both citations fire automatically into the run’s .bibtex / .references / .system when dft_plus_u=[HubbardSite(...)] is passed.

Coverage matrix (shipped 2026-05-29):

Surface	Energy	Gradient	optimize=True
Molecular RHF / RKS / UHF / UKS	✅	✅	✅ via `run_job`
Γ-only periodic RHF / RKS	✅	✅ (standalone API)	—
Multi-k periodic RKS DIRECT_TRUNCATED	✅	—	—
Multi-k BIPOLE RHF / RKS / UHF / UKS	✅	✅	✅ via `run_periodic_job`
Periodic NEB+U (RHF / UHF / RKS / UKS)	✅	n/a	n/a

No DFT+U surface raises NotImplementedError. Full +U test suite (tests/test_dft_plus_u.py): 72/72 green.

User-facing: see docs/user_guide/dft_plus_u.md for the vq.HubbardSite(atom_index, l, U_ev=...) API + driver matrix; worked examples at examples/periodic/input-h-chain-plus-u.py (fast H₂ +U smoke) and examples/periodic/input-bipole-nio-uks-plus-u.py (NiO+U recipe, real-system runtime caveats flagged).

Out of scope for v0.9.x +U, queued separately:

BIPOLE gradient’s intrinsic Γ-W tile noise (~0.1 Ha/bohr on H₂⁺/cc-pVDZ in 20 Å box vs FD) — pre-existing limitation, affects every optimize=True BIPOLE run independent of +U. Tracked in HANDOVER_PBC_BIPOLE.md.
Production NiO bandgap / Fe-slab adsorption benchmarks against the now-complete surface — deliverable for the haber-bosch / NiO physics chats.

`v0.10.0` — ✅ shipped — Grimme D4 dispersion¶

Codename TBD (candidate: Grimme’s Lynx, London’s Lynx).

Status — shipped at v0.10.0. D4 energy + gradient + stress all landed. Known limit: the default-dispersion-backend flip from the dftd4 Python optional dep to the native D4 path is still opt-in pending the production C6 dataset upgrade — the reference table is being re-derived from first principles for clean MPL-2.0 (see the phase mapping below).

🎯 Headline feature — Grimme’s D4 dispersion correction with charge-dependent C6 coefficients. Strict refinement over the D3 already shipped in v0.2.x.

Phase mapping (final): The charge model is EEQ (electronegativity equilibration, Caldeweyher 2019) — not partial-Hirshfeld as the original D2b bullet below proposed; EEQ is what the published D4 model actually uses.

Phase D4a-i — native EEQ atomic-charge model (vibeqc.eeq_charges). Shipped in v0.8.0.

Phase D4a-ii — native EEQ bit-exact with the dftd4 reference (the D3/D4 4/3 covalent-radius fix). Shipped post-v0.8.0 (v0.8.x).

Phase D4b — native D4 dispersion energy (reference C6 table + charge/CN interpolation + BJ damping). Shipped at v0.10.0.

dftd4 optional Python backend (vibeqc.compute_d4, run_b2plyp(dispersion="d4")) — shipped in v0.8.0; remains the production path until the native C6 dataset is upgraded (the default-backend flip noted above).

Full Phase D4b plan + milestone breakdown (D4b-1 … D4b-8): see docs/handover_d4_native.md. The reference C6 dataset is being re-derived from first principles (maintainer call, 2026-05) rather than transcribed from the LGPL dftd4 table — so native D4 ships clean MPL-2.0.

D2a Charge-dependent c6ab table + parameter set (Caldeweyher 2019). — superseded; tracked as Phase D4b (shipped).
D2b ~~Hirshfeld atomic charges from the SCF density.~~ — superseded by Phase D4a (EEQ charges, shipped).
D2c D4 energy + gradient + stress. — all shipped in v0.10.0 (Phase D4b for energy; gradient + stress on top).
D2d dftd4 reference Python backend as optional dep (mirrors the D1b pattern). — shipped in v0.8.0.

`v0.11.0` — periodic GDF chain (compcell + multi-k + AFT)¶

Codename: Sun’s Stingray (locked 2026-05-29 by Mike from the release-chat shortlist of Sun’s Stingray / Mintmire’s Marmot / Berkelbach’s Beaver / Dunlap’s Dingo — the Sun-Berkelbach RSGDF in Sun et al. JCP 147, 164119, 2017 is the algorithm vibe-qc actually implements for the v0.11.0 GDF chain; Qiming Sun also authored PySCF, the µHa-parity reference).

🎯 Headline feature — close the periodic-GDF parity chain against PySCF KRHF.density_fit(). The compcell construction (Sun 2017 — Mintmire-Dunlap modrho rescale + per-(atom, L) smooth compensating Gaussians) is in place on main; the remaining work is the chg-shell L≥1 convention chain in the bare 3c lattice sum and the multi-k AFT correction. When this milestone lands, vibe-qc ships periodic-GDF energies that match PySCF to sub-mHa on LiH primitive FCC and MgO 8-atom — where v0.9.0 was off by +22 Ha and +1500 Ha respectively.

Honest scope — how we got here. This chain has been deferred four cycles: v0.8.0 → v0.9.0 → v0.10.0 → v0.11.0. The v0.10.0 defer surfaced a cluster-A1 EWALD_3D auto-gauge bug that contaminated GDF parity probes (fixed at v0.10.0 in 859efe0a). The M1 investigation at b8f1e509 then isolated the residual gap to a 3c AFT convention mixing for L>0 chg shells in the bare lattice sum. CLAUDE.md §7 governs how this lands: never paper over with damping / threshold tightening. Per the GDF chat’s 2026-05-27 honest-correction baseline (f8c658a2), the optimistic subject line of 018784c0 (“all-FT-Bloch path — LiH within chemical accuracy”) is not the operative claim — see docs/handover_gdf_v0_11_2026_05_29.md for the precise state. Filename pinned for link stability across the four cycles.

Closing this milestone means:

The two GDF parity pytests held red on main through v0.10.0 go green:
- test_run_krhf_periodic_gdf_compcell_multik_smoke
- test_run_krhf_periodic_gdf_compcell_multik_sub_mha_h2
CHANGELOG [v0.10.0] Known limitations § “Periodic GDF” closes: RSGDF SR+LR L=0 (98.5% parity) / L=1 (23.8% — the L≥1 chain) + compcell near-singular conditioning 10¹⁰–10¹⁴.
LiH primitive FCC (multi-k 2,2,2 / STO-3G) at sub-mHa vs PySCF.
MgO 8-atom conv cell (Γ-only) at sub-mHa vs PySCF.

The post-v0.10.0 fix series on main — commits that build into this milestone:

018784c0 — all-FT-Bloch path for RSGDF. Read with the honest baseline f8c658a2, not the optimistic subject line.
871c5f4a — RSGDF G=0 Madelung correction (H₂ sub-µHa parity vs PySCF; McClain-Sun-Chan-Berkelbach exxdiv=’ewald’ lineage).
dfa34b4a — Bloch-summed lattice pair-FT in _compcell_aft_correction_3c.
c949d748 — modrho convention in the RSGDF path (Mintmire-Dunlap lineage; pass modrho basis directly to build_lpq_native).

The companion smear chat coordinates SmearingOptions for the metallic-system test set this milestone exercises — see docs/handover_smear_brief.md.

(The “geometry symmetrize” content previously slotted here at v0.11.0 has moved: GS1–GS3 rides v0.13.0 alongside Generalised Regular k-grids; DOC1-full is now the per-quarter docs-cadence chore in docs/release_process.md § “Documentation cadence”. A docs sprint should not gate a release.)

`v0.12.0` — personal job queue + cluster-bridge docs¶

Codename TBD (candidate: Knuth’s Beaver, Berners-Lee’s Crow).

🎯 Headline feature — personal job queue. A developer working on a laptop SSHs to a more-powerful machine (gaming PC, lab box, small in-house server) and wants to submit a batch of vibe-qc calculations, walk away, and get notified when they finish. New package vibeqc.jobs + CLI vqc-jobs covering:

JQ1 core queue + CLI:
- Submit a Python script to the queue with a working directory and resource hints (cores, memory budget) — file-system-backed queue (no daemon, no DB; one JSON file per job under ~/.vibeqc/jobs/).
- Worker that picks up pending jobs, runs them with the right venv-Python + OMP_NUM_THREADS, captures stdout / stderr to log files alongside the per-job output.
- Status query (vqc-jobs ls, vqc-jobs show <id>, vqc-jobs cancel <id>), priority adjustment.
- Notifications via configurable backend: ntfy.sh push, desktop notify-send, email via stdlib smtplib, plain-stdout for the script-it-yourself path.
- Restart on failure (configurable: never / once / N times / always) — useful when SCFs occasionally don’t converge under DIIS and you want the worker to retry with level_shift bumped.
JQ2 cluster-bridge documentation — how to drive vqc-jobs from a Slurm / PBS / SGE submit script. vibe-qc itself stays shared-memory parallel; the wrapping batch script is what users copy-paste from.

`v0.13.0` — Generalised Regular k-grids + geometry symmetrize¶

Codename TBD (candidates: Wisesa’s Fox, Mueller’s Marten; the GS-themed candidates Wyckoff’s Mole and Hermann’s Pangolin from the prior v0.11.0 slot are also in play).

🎯 Headline feature — Generalised Regular (GR) grids (Wisesa, McGill & Mueller 2016, Comp. Mat. Sci. 110, 1; Balasubramanian, Dwaraknath & Mueller 2021). Searches over reciprocal sublattices for the grid with the largest minimum periodic distance per k-point — typically ~2× more efficient than axis-aligned MP for non-cubic / anisotropic cells.

The matching geometry-symmetrize pipeline (GS1–GS3) rides this release — moved from the previous v0.11.0 slot, which now carries the periodic-GDF chain. Both belong in the same “periodic UX” neighbourhood: a user lands an imperfect input cell, asks for a decent k-grid, gets standardised geometry plus an efficient mesh in one shot.

K6a Database lookup at esd.cos.gmu.edu/tb/kpts.
K6b On-the-fly GR-grid search algorithm (2021 paper).
K6c KPoints.optimal(sys, target_n_kpts, metallic=False) builder method that picks the GR grid with the largest minimum- distance for the given target k-count. Critical for making metallic systems and large-cell defects feasible — the user-emphasised motivation when GR was first proposed.
GS1 vq.symmetrise(system, symprec=1e-4) — calls spglib standardize_cell; returns a new PeriodicSystem plus a metadata report (RMS displacement, spacegroup before / after).
GS2 File readers (read_poscar / read_cif / from_xyz for periodic XYZ) gain a symmetrise=True keyword that runs GS1 on the parsed system. Plus vq.detect_spacegroup(system, symprec) non-modifying introspection helper.
GS3 Wire SYM2b orbit-compression to take the standardised cell so it actually triggers in practice. The SYM2b machinery requires symmorphic + origin-fixed atoms, which a typical user input rarely has out of the box; GS1 closes that loop.

(DOC1-full — tutorial-wide bundled reference outputs, the prior v0.11.0 sibling of GS — has moved out of the milestone list entirely into the per-quarter docs-cadence chore. See docs/release_process.md § “Documentation cadence”. A docs sprint should not gate a release.)

Wavefunction-method ladder — coverage map¶

The correlation-tier milestones below (v0.14.0 → v0.21.0) are the engineering slice through the standard wavefunction ladder. This table is the audit of that slice against the canonical ladder (HF → MPn → CI/CEPA → CC → EOM/response-CC → reduced-scaling CC → multireference → selected-CI/DMRG), so a gap is visible rather than implicit. ✅ = shipped, 🎯 = has a dedicated milestone, 📦 = ships as a named byproduct inside another milestone’s shared engine.

Ladder rung	vibe-qc home	Status
HF (RHF/UHF)	v0.1.0	✅ shipped
MP2 / SCS-MP2 / RI-MP2	v0.1.0, v0.7.2	✅ shipped
CISD / CCD / QCISD / CEPA(n)	v0.14.0 (24a-c-shared)	📦 shared CC engine
CCSD	v0.14.0	🎯
CCSD(T) + A-CCSD(T) / CCSD[T] / CCSD+T(CCSD)	v0.14.0 (24a-c-(T))	🎯
CC2 / CC3	v0.15.0	🎯
EOM-CCSD / EOM-CC2/CC3 / IP-EOM / EA-EOM	v0.16.0	🎯
FNO-CCSD(T)	v0.17.0 (24c-FNO)	🎯
LPNO / DLPNO-CCSD(T) / DLPNO-UCCSD(T)	v0.17.0	🎯
CCSDT / CCSDT(Q) / CCSDTQ / arbitrary-order	v0.18.0	🎯 (post-1.0 priority)
Periodic MP2 / periodic CCSD(T)	v0.19.0 / v0.20.0	🎯
FCI (minimal determinant-basis solver)	v0.9.0 `vibeqc.solvers`	✅ shipped
CASCI / CASSCF (orbital-optimised)	small-active-space `vibeqc.solvers`; production v0.21.0	✅ / 🎯
NEVPT2 / CASPT2 / MRCI	NEVPT2 ✅, CASPT2 gated, small-active-space `vibeqc.solvers`; MRCI v0.21.0	✅ / 🟡 / 🎯
MRCC	v0.21.0 note	post-1.0 specialty
Selected CI (CIPSI) / DMRG	v0.9.0 minimal `vibeqc.solvers`; production v0.21.0	✅ / 🎯
QMC (FCIQMC / DMC)	v0.21.0 note	post-1.0 / research-tier
DF / Cholesky integral factorisation for CC	DF ✅ v0.7.2–0.8.0; CD post-1.0	🟡 partial

Beyond the standard ladder rungs above, v0.9.0’s vibeqc.solvers also ships variational 2-RDM and transcorrelated CI — see the Feature matrix.

Reference types: RHF + UHF references are in-scope for every correlated milestone above; ROHF-based correlation rides with ROHF/ROKS at v1.0.0. The citype= / triples= selector surface that exposes all of the above through one entry point is tracked as AUTOCI1–7.

`v0.14.0` — canonical CCSD(T)¶

Codename TBD (candidates: Bartlett’s Goose, Coester’s Cobra, Pople’s Eagle). Renumbered from the original v0.6 slot during the v0.5 milestone resplit (smaller, single-headline minor releases) and again when K-Phase was absorbed into v0.5 itself.

Gold-standard molecular correlation — coupled cluster with singles, doubles, and perturbative triples — built on the density-fitting substrate. CCSD(T) is the accuracy reference that every cheaper method (MP2, DFT, the v0.17.0 DLPNO approximation) is measured against.

Density-fitting prerequisites — shipped ahead of this slot. This milestone was originally headlined “density fitting”; the DF programme (the five sub-phases below) got pulled forward and landed across v0.7.2–v0.8.0, well ahead of its roadmap position. Recorded here so the renumbering history stays legible:

Sub-phase	Status	Shipped in
20a RI-J — molecular pure DFT	✅ shipped	v0.7.2 Boys’ Crucible — 2-/3-centre RI kernels + def2 / cc-pV*Z / Pople aux-basis library
20b RIJCOSX / RI-K — molecular hybrid DFT	✅ shipped	v0.8.0 Grimme’s Gecko — chain-of-spheres COSX SCF + analytic gradient, validated vs ORCA 6.1.1
20c RI-MP2 — molecular	✅ shipped	v0.7.2 — `density_fit=True` on MP2 / UMP2
20d RI-J — periodic	✅ shipped	v0.8.0 — GDF-default periodic SCF chain (`run_krhf_periodic_gdf` etc.)
20e RI-K — periodic	✅ shipped	v0.8.0 — multi-k KRHF / KRKS periodic hybrids route through GDF

Remaining work for this milestone:

24a-c canonical CCSD(T) — gold-standard molecular correlation. Benchmarkable against NWChem / Psi4 for small systems. The RI-MP2 substrate it builds on (20c) already shipped, so this milestone is no longer gated on outstanding DF work.
24a-c-shared the iterative singles/doubles amplitude solver, the DF-driven integral transformation, and the DIIS/Jacobi amplitude convergence machinery built for CCSD are the same substrate that yields the size-extensive near-CC tier of the ladder (rung 3) at marginal extra cost. Ship them as named byproducts of the same engine, behind one citype= selector (mirrors ORCA’s AutoCI — see AUTOCI1):
- CCD — coupled-cluster doubles (singles dropped). Conceptual / specialist variant; near-free once CCSD exists.
- CISD — the truncated-CI baseline. Not size-consistent — documented as a teaching/comparison method, not a production one.
- QCISD / QCISD(T) — quadratic CI; size-extensive, grouped with the CC family in practice (ORCA’s MDCI).
- CEPA(n) — coupled electron-pair approximation; recovers size-extensivity missing from CISD at sub-CCSD cost.
24a-c-(T) the perturbative-triples correction is not one monolithic object. Ship the standard (T) plus the related variants that differ in how triples are linearised/ordered: A-CCSD(T) (asymmetric), CCSD[T] (the older bracket correction), CCSD+T(CCSD). One triples= flag; the standard (T) is the default.
Reference types: RHF + UHF references ship in this milestone; ROHF-CCSD is parked with ROHF/ROKS at v1.0.0.

`v0.15.0` — approximate coupled cluster (CC2 + CC3)¶

Codename TBD (candidate: Christiansen’s Chameleon — Ove Christiansen, CC2 originator).

🎯 The cheap-CC tier between MP2 and full CCSD/CCSDT. Both methods reuse the v0.14.0 CCSD amplitude engine, intermediates, and DF substrate — they are approximations within the same code, not a new stack.

CC2 (Christiansen, Koch, Jørgensen 1995) — second-order approximate CCSD. Singles treated through CCSD, doubles through second order; O(N⁵). The workhorse for cheap excitation energies and response when CCSD is too expensive.
CC3 (Koch, Christiansen, Jørgensen, Sánchez de Merás, Helgaker 1997) — approximate CCSDT with an economical iterative-triples treatment; O(N⁷). High-quality excitation energies when CCSD is not enough but CCSDT is unaffordable.
Both ship closed- and open-shell ground-state energies here; they are also the reference wavefunctions the v0.16.0 EOM milestone builds excited states on.

`v0.16.0` — equation-of-motion coupled cluster (excited states)¶

Codename TBD (candidate: Stanton’s Stoat — John Stanton, EOM-CCSD).

🎯 The wavefunction-based excited-state branch — vibe-qc’s first correlated route to excited states. Complements, does not replace, the TDDFT path at v0.21.0: EOM-CC is systematically improvable and handles double-excitation / charge-transfer character that TDDFT mishandles.

EOM-EE-CCSD (Stanton & Bartlett 1993) — excitation energies on the CCSD ground state, with transition moments + oscillator strengths.
EOM-IP-CCSD / EOM-EA-CCSD — ionisation potentials and electron affinities from the same similarity-transformed Hamiltonian; the natural route to photoelectron spectra and to well-defined open-shell references.
EOM-CC2 / EOM-CC3 — cheaper / more-accurate variants built on the v0.15.0 CC2 / CC3 references.
Reuses the v0.14.0 CCSD σ-vector / intermediate machinery; the new work is the Davidson eigensolver over the EOM Hamiltonian and the left/right eigenvector bookkeeping for properties.

`v0.17.0` — reduced-cost coupled cluster (FNO + DLPNO-CCSD(T))¶

Codename TBD (strong candidate: Neese’s Cheetah — Frank Neese made DLPNO fast). Renumbered through v0.7 → v0.16 → v0.15 → v0.17; rescoped from “DLPNO-CCSD(T)” to “reduced-cost CC” to also carry FNO.

🎯 The two reduced-cost CC accelerators, ordered by infrastructure weight. FNO ships first as the simpler virtual-space truncation; DLPNO is the production near-linear-scaling method.

Validation reference: Sandler, Chen, Taylor, Sharma, Ho, “Accuracy of DLPNO-CCSD(T): Effect of Basis Set and System Size”, J. Phys. Chem. A 125, 1553 (2021) — basis-set + system-size convergence benchmarks. Use as the test target when DLPNO ships (“vibe-qc reproduces Sandler 2021 cuts within X kcal/mol”).

24c-FNO FNO-CCSD(T) — frozen natural orbitals truncate the virtual space (MP2-density natural-orbital occupations below a threshold are dropped) while preserving most of the correlation energy. A small, well-contained accelerator that reuses the canonical v0.14.0 CCSD(T) code unchanged — only the virtual basis shrinks. Ships ahead of DLPNO as the low-risk first cut at reduced-cost triples.
24d-h DLPNO-CCSD(T) — near-linear-scaling CCSD(T) accurate to ~1 kcal/mol vs canonical, production-grade correlation method. Pair-natural-orbital compression + local domains; substantial new infrastructure (localisation, pair classification, domain construction, threshold hierarchy).
24i open-shell DLPNO-UCCSD(T).
LED — Local Energy Decomposition on the DLPNO-CCSD(T) wavefunction (the correlated counterpart of the SCF/DFT PR26 EDA at v0.22.0).

`v0.18.0` — higher-order coupled cluster¶

Codename TBD (candidate: Kállay’s Kestrel — Mihály Kállay, arbitrary-order CC via string-based code generation).

The benchmark / reference tier — full iterative triples and beyond. Cost rises steeply, so these are small-system reference methods, but they are the standard against which CCSD(T) and the DLPNO approximation are themselves calibrated.

CCSDT — full iterative triples. A major accuracy step over CCSD(T), and the reference for the (T) perturbative approximation.
CCSDT(Q) / CCSDTQ — iterative quadruples (perturbative and full). Reference-grade thermochemistry / spectroscopy.
Arbitrary-order CC — a string-based or code-generated tensor contraction engine (Kállay-style) so CCSDTQP and beyond fall out of one implementation. Design target for vibe-qc’s tensor backend; also the cleanest way to keep the lower-order methods (CCD → CCSDT) consistent. Genuinely post-1.0 in priority — listed here so the ladder is complete and the tensor-engine design is informed early.

`v0.19.0` — periodic correlation¶

Codename TBD (candidate: Pisani’s Panda — Pisani / CRYSCOR periodic local CC). Renumbered through v0.8 → v0.17 → v0.16 → v0.19.

Periodic RI-MP2 — correlated solid-state energies, benchmarkable against CRYSTAL / PySCF.pbc.

`v0.20.0` — periodic coupled cluster¶

Codename TBD. Renumbered through v0.9 → v0.18 → v0.17 → v0.20.

Periodic canonical CCSD(T) for small unit cells.
DLPNO-periodic-CCSD(T) as the scalable variant.

`v0.21.0` — multireference + excited states¶

Codename TBD (candidate: Runge’s Raccoon — Runge-Gross TDDFT theorem). Renumbered through v0.10 → v0.19 → v0.18 → v0.21. The former separate v0.22.0 “strongly-correlated methods” milestone was folded into this one (2026-05-21) once the minimal vibeqc.solvers selected-CI / DMRG were confirmed already shipped in v0.9.0 — see the note below.

The static-correlation milestone — active-space wavefunctions for bond-breaking, transition metals, and the strongly correlated cases single-reference CC cannot reach — plus the linear-response excited-state path.

Already shipped — minimal vibeqc.solvers (v0.9.0). A determinant-basis solver suite landed in v0.9.0: FCI (verified against PySCF FCI to machine precision), selected CI (CIPSI), DMRG (two-site MPS, ≤ 12 orbitals), variational 2-RDM, and transcorrelated CI, all reachable via run_job(method="fci" | "selected_ci" | "dmrg" | "v2rdm" | "transcorrelated_ci"). These are research / prototype-grade — small active spaces, v2RDM not yet strictly variational. This milestone is the production-grade upgrade: scalable solvers wired into a CASSCF orbital-optimisation outer loop.

25a-c FCI / CASCI — production-grade integration on top of the v0.9.0 minimal FCI: larger active spaces, frozen-core / CAS windows, performance work.
25d-e CASSCF with state-averaging: production-scale orbital optimisation plus state-averaging. A small-active-space, single-state CASSCF orbital-optimisation loop landed early in vibeqc.solvers (method="casscf", validated vs PySCF mcscf.CASSCF); state-averaging, excited states, open-shell references, and large-CAS scaling remain.
25f NEVPT2 — multireference perturbation on CASSCF (recovers the dynamic correlation CASSCF misses).
25g CASPT2 — the sibling MR-PT to NEVPT2 (Roos et al.); ships alongside 25f so users can cross-check the two standard MR-PT flavours. IPEA-shift knob exposed.
25h MRCI — multireference CI (uncontracted + internally contracted), with the +Q size-extensivity correction. The benchmark MR method; expensive, small-active-space.
25i production selected-CI + DMRG — scale the v0.9.0 prototypes into large-active-space CASSCF solvers: heat-bath / semistochastic CIPSI (~30–40 active orbitals) and large-bond- dimension DMRG (~50+ active orbitals), lifting the ~18-orbital CASSCF factorial wall. (Folded in from the former v0.22.0 milestone.)
MRCC — multireference coupled cluster (Mukherjee / state- specific variants) is noted here as a post-1.0 specialty target, not in the v0.21.0 scope. QMC (FCIQMC / diffusion Monte Carlo) likewise post-1.0 / research-tier — both flagged so the ladder is complete.
T1 TDDFT (linear-response, singlets) — UV/Vis, ECD, excited-state geometries. Promoted in scope after parity audit (the entire ORCA spectroscopy section is gated on this). The DFT-side excited-state path; the wavefunction-side path is EOM-CC at v0.16.0.

`v0.22.0` — properties suite¶

Codename TBD (candidate: Stone’s Sloth — A. J. Stone, molecular response properties). Renumbered through v0.11 → v0.20 → v0.19 → v0.23 → v0.22.

The user-facing observables milestone. Brings the “wavefunction → number” pipeline up to ORCA / CRYSTAL parity for the properties most physical chemists actually report. Positioned late in the sequence by design: many properties are response-theory derivatives of the SCF / correlated wavefunction (CPHF / CPKS substrate), and a handful depend on excited-state machinery from v0.21. Scattered property bits that already shipped (Mulliken / Löwdin / Mayer in v0.3.0 Phase 18; dipole in v0.3.0 Phase 19; molecular Hessian / IR in v0.5.0 Phase 17) are in-scope for cross-reference and polish; this milestone gathers everything else into one coherent implementation pass.

What this milestone unlocks: the entire ORCA spectroscopy section (NMR, EPR, ECD, VCD, Raman intensities), the CRYSTAL “Response Properties” tutorial line (dielectric tensor, Born effective charges, elastic / piezo / photoelastic constants), and the electron-density topology / NCI / ELF analysis tools standard in modern computational-chemistry workflows.

Charge analysis (extended)

PR1 Hirshfeld + iterative-Hirshfeld charges (density-partitioning).
PR2 Bader / QTAIM charges + critical-point search (density-topology).
PR3 ESP-fit charges (CHELPG, Merz-Kollman, RESP variants).
PR4 NBO / NPA — Natural Bond Orbital analysis + Natural Population Analysis (basis-set-stable charges + Lewis-structure decomposition).

Multipole moments + electrostatic potential

PR5 quadrupole + octupole moments (RHF/UHF/RKS/UKS); arbitrary- order molecular electric multipoles.
PR6 ESP cube / isosurface export (already gridded via Phase V1 infrastructure; needs the V_n + V_e operator on the molecular grid).

Response substrate

PR7 CPHF / CPKS — coupled-perturbed HF / KS solver. The response-theory substrate underlying every static perturbation property below; lands first in the milestone because PR8–PR22 all call into it.

Static electric response (molecular)

PR8 static dipole polarisability α (full tensor).
PR9 static first + second hyperpolarisability β, γ.

Magnetic response (molecular)

PR10 GIAO NMR shielding tensors (chemical shifts, σ).
PR11 indirect spin-spin coupling constants (NMR J-couplings).
PR12 EPR g-tensor + hyperfine A-tensor (open-shell paramagnetic; needs Phase 15 periodic UHF/UKS or molecular UHF/UKS).

Vibrational extensions

PR13 Raman activities — polarisability derivatives via CPHF on the Phase 17 normal modes.
PR14 VCD (Vibrational Circular Dichroism) — atomic-axial-tensor / atomic-polar-tensor pair.
PR15 ROA (Raman Optical Activity) — polarisability + magnetic- dipole derivatives.

Periodic response (CRYSTAL “Response Properties” parity)

PR16 Born effective charges Z* — atomic-displacement → cell-dipole derivatives.
PR17 electronic dielectric tensor ε∞ (high-frequency permittivity) — periodic CPHF.
PR18 static dielectric tensor εstatic = ε∞ + ionic contribution (Z* + Phase 21 phonons).
PR19 elastic tensor C_ij — response to strain; needs Phase G2 stress tensor.
PR20 piezoelectric tensor — strain × electric-field cross- derivative.
PR21 photoelastic tensor — strain × dielectric cross-derivative.
PR22 periodic IR + Raman intensities — Z* + α_q derivatives on the Phase 21 phonon eigenvectors.

Topological / scalar field analysis

PR23 Electron Localisation Function (ELF) — bonding diagnostic (Becke-Edgecombe).
PR24 Reduced Density Gradient / NCI plots — non-covalent interaction visualization (Yang-Johnson).
PR25 Laplacian + kinetic-energy density grids — auxiliary scalar fields for QTAIM and density inspection.

Energy decomposition

PR26 LMOEDA / Hayes-Stone EDA (molecular) — partition the interaction energy of a complex into electrostatic / exchange / repulsion / polarization / charge-transfer / dispersion. (LED for DLPNO-CCSD(T) is targeted at v0.17.0; this is the SCF/DFT variant.)

Excited-state properties (post-T1)

PR27 transition densities + Natural Transition Orbitals (NTOs) — TDDFT post-processing for excited-state visualization.
PR28 oscillator strengths + UV/Vis spectrum reconstruction (Lorentzian/Gaussian broadening).
PR29 ECD (Electronic Circular Dichroism) — magnetic-dipole transition moments on top of TDDFT.

The milestone is large and naturally sub-batches: PR1–PR6 (no CPHF needed) can ship first as a quick win; PR7 lands the substrate; PR8–PR15 are the molecular response stack; PR16–PR22 are the periodic response stack and depend on Phase 21 (phonons) and Phase G2 (stress); PR23–PR25 are scalar-field utilities independent of CPHF; PR26 is molecular-only EDA; PR27–PR29 are TDDFT post-processing.

`v1.0.0` — feature complete¶

Final polish before declaring “feature complete across both molecular and periodic.” Includes:

ROHF / ROKS.
meta-GGA + range-separated hybrid validation across the full functional table.
Thermochemistry polish (corrections, low-frequency treatment, rigid-rotor / quasi-harmonic switches).
Miscellaneous bug fixes uncovered in the larger correlation / excited-state / periodic / properties stacks.

(Finite-field response — dielectric tensor, polarisability, Born effective charges — was previously parked here as v1.0 polish; it moved into the dedicated v0.22 properties milestone where it belongs alongside the rest of the response-theory work.)

`v2.0.0` — HF-CCM (cyclic-cluster-model foundation)¶

Codename TBD (candidate: Bredow’s Beaver — Bredow + collaborators, original cyclic-cluster-model authors).

The original motivating feature of the project. The CCM track is a multi-step progression: each v2.N.0 builds on the previous, with each step a defensible publication-grade deliverable on its own. Cyclic cluster model = a finite cluster carved from the periodic crystal with periodic boundary conditions imposed via image-cell folding, giving a defect-localised treatment that recovers the periodic limit as the cluster grows. Methodological lineage: Peintinger & Bredow, J. Comput. Chem. 35, 839 (2014) — the project author’s PhD-era proof of concept at the HF level (free-access cover article).

v2.0.0 ships: rock-solid HF-CCM in 3D, validated against the project author’s thesis and against CRYSTAL where reference data exists. This is the foundation, and the place where bugs are cheapest to find — every correlated extension below sits on top of it. Includes the cluster-construction utilities, the image-folding lattice machinery, and the convergence-with-cluster-size validation suite that defines what “correct” means for the rest of the v2 sequence.

`v2.1.0` — density fitting in CCM (at HF)¶

Density-fitting / RI infrastructure adapted to the cyclic-cluster context, validated at HF level (where the answer is already known from v2.0 and any DF error is purely auxiliary-basis). The infrastructure that everything correlated will rely on — once DF is solid in CCM, MP2 / CCSD / DLPNO all become tractable. Reuses the molecular DF machinery from v0.6.0 (Phase 20).

`v2.2.0` — MP2-CCM¶

First correlated method on top of CCM, using the v2.1 DF infrastructure. Canonical (non-local) MP2 on the cyclic cluster. Small publication potential by itself if the validation is thorough: benchmark against periodic CRYSCOR / PySCF.pbc MP2 and against the cluster-size convergence series (CCM with N₁×N₂×N₃ → ∞ should match the periodic limit).

`v2.3.0` — orbital localization in CCM¶

Standard localization techniques (Pipek-Mezey, Foster-Boys, Intrinsic Bond Orbitals / IBO) adapted to the cyclic-cluster context, where the periodic boundary conditions force a translation-equivariant treatment of the localising functional. Useful as a tool in its own right (localised orbitals are interpretable; they’re how chemists “see” bonding) and the prerequisite for the local-correlation methods below.

`v2.4.0` — local MP2-CCM (DLPNO or PAO)¶

DLPNO-MP2-CCM or PAO-MP2-CCM — the first local-correlation method in the CCM track. This is where the method starts to be applicable to systems larger than naive MP2-CCM could handle (defect chemistry in the 100–1000 atom range). Genuine methods-paper territory: local correlation in a periodic-boundary cluster framework is a thin publication landscape.

`v2.5.0` — CCSD-CCM (canonical, non-local)¶

Non-local CCSD on moderate cluster sizes — the canonical reference against which v2.6 local CCSD will be validated. Scaling limits the cluster size to roughly the same range that canonical CCSD can handle in molecular calculations.

`v2.6.0` — local CCSD-CCM¶

Local CCSD-CCM (DLPNO or PAO flavor). The method that would actually compete on realistic defect-chemistry problems: chemical accuracy on systems with hundreds of atoms in the cluster, near- linear scaling, defensible against the v2.5 canonical reference.

`v2.7.0` — (T) perturbative triples → CCSD(T)-CCM¶

The (T) correction on top of v2.5 / v2.6 CCSD-CCM. Gets you to chemical accuracy (~1 kcal/mol) on cyclic-cluster correlated energies — the defect-chemistry analogue of CCSD(T) being the “gold standard” in molecular thermochemistry.

`v2.8.0` — projection-based embedding¶

Projection-based embedding combining CCM-high-level with DFT-treated environment. Now you can treat a defect at correlated CCSD(T)-CCM level inside an arbitrarily large DFT-treated matrix — the practical multi-scale tool that makes the entire v2.x stack production-ready for real-materials-chemistry work. The capstone of the project.

Linear-dependence + screening program (multi-release)¶

Mathematically the AO overlap matrix S must be positive definite. In Gaussian-basis periodic codes it routinely becomes ill-conditioned and, with truncated lattice sums and finite arithmetic, can even acquire numerically negative eigenvalues — at which point a silent canonical-orthogonalisation truncation gives a “converged” SCF on a basis with the wrong metric signature, and the total energy is off by orders of magnitude.

CRYSTAL’s stance — refuse to silently truncate; push the problem to basis-set design — is the right one for solid-state SCF. PySCF’s optional remove_linear_dep_ is too quiet by default. Vibe-qc has adopted CRYSTAL’s “loud and explicit” philosophy across this program.

What landed in v0.7 (October 2025 — May 2026 work)¶

Feature	API	What it does
Critical-severity preflight	`vq.scf_preflight_overlap_check`, wired into all 8 periodic SCF drivers	Detects non-PSD `S(k)` per k-point. Aborts SCF by default with a citation-rich error message. Override with `allow_critical=True`.
Standalone EIGS diagnostic	`vq.eigs_preflight(system, basis, kmesh)`	CRYSTAL’s `EIGS` keyword equivalent. Builds `S(k)` at every k, prints the spectrum, returns without running SCF.
TOLINTEG distinction	`vq.disambiguate_critical_overlap(...)`	Re-checks `S` with tightened cutoffs to distinguish basis-set linear dependence from under-converged exchange screening (CRYSTAL ITOL4 / ITOL5 manual p. 130). LiH conventional rocksalt diagnoses as `screening_undertight`, not `basis_set_problem`.
Joint cutoff / Schwarz optimisation	`vq.optimize_truncation(...)` (default ON via `auto_optimize_truncation=True` in all 8 drivers)	Bisects both knobs jointly to find loosest settings keeping `S` PSD at every k-point. Sanity-checked ranges, max 8 evaluations, joint scaling so neither knob runs far from default while the other stays put.
Primitive filter (`exp_to_discard`)	`vq.make_basis(mol, name, exp_to_discard=0.1)`	PySCF-style runtime filter — drops Gaussian primitives below threshold, persisted via `_vibeqc_filtered_*.g94` cache for the SAD initial-guess re-load path.
Per-primitive drop transparency	`vq.format_basis_filter_report(rep)`	Lists every dropped primitive (element, shell, l-letter, exponent, libint coefficient) so the SCF log self-documents any basis-content modification.
PySCF-style canonical orth	`_canonical_orthogonalizer(*, normalize_diag_first=True)`	Sqrt(diag(S)) pre-conditioning so the threshold operates on a unit-diagonal matrix (Lykos & Schmeising 1961, Löwdin 1970 conventions).
Opt-in orthogonalisation methods	`vq.orthogonalise_overlap(S, method="auto")`; `vq.canonical_orth`, `vq.pivoted_cholesky_orth`, `vq.symmetric_orth`	Explicit fallbacks (Lehtola 2019 pivoted Cholesky for extreme overcompleteness) when the user opts past the critical-severity abort.
Pob basis sets bundled	`vq.BasisSet(mol, "pob-tzvp" \| "pob-tzvp-rev2" \| "pob-dzvp-rev2")`	Pre-existing in vibe-qc; the critical-severity error message now actively recommends them as the basis-design fix (Peintinger 2013, Vilela Oliveira 2019).
Active-settings dump	`vq.format_options(opts)`, `vq.dump_active_settings(plog, ...)`	Every SCF run self-documents — the user never has to read driver source to know what defaults were in effect. Required by the v0.7 transparency directive.

References landed in code + docstrings:

Lykos & Schmeising J. Chem. Phys. 35, 288 (1961)
Löwdin Adv. Quantum Chem. 5, 185 (1970)
Peintinger, Vilela Oliveira, Bredow J. Comput. Chem. 34, 451 (2013) — pob-TZVP
VandeVondele & Hutter J. Chem. Phys. 127, 114105 (2007) — MOLOPT
Searle, Bernasconi, Harrison, ARCHER eCSE04-16 (2017) — k-dependent linear dependence
Vilela Oliveira et al J. Comput. Chem. 40, 2364 (2019) — pob-TZVP-rev2
Daga, Civalleri, Maschio J. Chem. Theory Comput. 16, 2192 (2020)
Lehtola J. Chem. Phys. 151, 241102 (2019); Phys. Rev. A 101, 032504 (2020) — pivoted Cholesky
Ye & Berkelbach J. Chem. Theory Comput. 18, 1595 (2022) — GTH-cc-pVXZ
CRYSTAL23 manual: EIGS (p. 103, 398), TOLINTEG (p. 130), OPTBASIS (p. 65), basis-set design discipline (Ch. 17, pp. 394–398)

`v0.9.x` — module consolidation (deferred)¶

The linear-dep work currently lives across five modules (linear_dependence.py, basis_filter.py, eigs_preflight.py, orthogonalisation.py, options_dump.py). The user-requested consolidation into a single coherent module / namespace is deferred to a v0.9.x maintenance release (the v0.7.x window closed at v0.7.14 without the consolidation landing). Functionality won’t change; imports will get a nicer vq.basis_screening.* umbrella.

`v0.9.x` (or later) — OPTBASIS-style basis optimiser (deferred)¶

The condition-number-penalised basis optimiser (Ω = E_tot + γ·ln κ) that closes the linear-dependence problem at its source — by constructing well-conditioned bases rather than patching ill-conditioned ones at run time — has graduated from a deferred one-paragraph note into its own multi-release track. See the Basis-set development + optimisation program below for the full BDEV1–BDEV6 sequence.

Automated regression / parity test suite (separate chat)¶

The 8-system × 2-basis acid test (NaCl / MgO / Al₂O₃ / LiH × {sto-3g, pob-dzvp-rev2}) plus the dual-target runner (release vs dev) are being built in a dedicated chat. Handover prompt and target schema land in examples/regression/HANDOVER.md. Wave 1 covers the linear-dep program above; waves 2/3 generalise to all SCF methods and become the project’s continuous-correctness dashboard.

Status as of v0.7.3 (2026-05-08):

Waves 1.0 through 1.7 shipped across v0.7.0 → v0.7.3. Suite covers ~30 molecules + 4 periodic systems with three-way vibe-qc / PySCF / ORCA cross-code parity at single-point SCF.
Per-case subprocess isolation (v0.7.2, “Boys’ Crucible”) catches C-level crashes in any one runner as error rows without bricking the dispatcher — the design payoff that lets the suite ride out ongoing PySCF.pbc / vibe-qc DF SIGSEGVs.
Wave-1.5+1.6 added 5 noncovalent dimers from S22 (water / NH3 / formamide / methane / benzene-T) + 3 X23 molecular crystals (urea, ice Ih, benzene). See examples/regression/REFERENCES.md for the full bibliography map.

Test-set expansion (queued)¶

Per the basis-set / test-set survey (2026-05 — full document hosted in the docs chat; bibliography distillation in examples/regression/REFERENCES.md §B), the following benchmark sets are queued for incorporation into the regression suite once prerequisite vibe-qc features land. Each line names the set, its prerequisite, and the version slot.

GMTKN55 (1505 reaction energies / 2462 single-points; Goerigk 2017) — needs multi-component reaction-energy machinery in the dispatcher (a “case” becomes E_products − E_reactants, not a single-point). v0.8 territory.
ACCDB / ASCDB / GSCDB137 aggregators — same prerequisite as GMTKN55. ASCDB’s 200-point statistical reduction is the best CI candidate once the machinery exists.
diet-150-GMTKN55 (Gould 2018) — 150-system genetic-algorithm reduction; the recommended basis-set-convergence test surface per Pitman 2024. Drop-in once GMTKN55 ingest works.
W4-17 atomization energies (Karton 2017) — needs isolated- atom calculations as part of every reaction (E_atomization = E_molecule − ΣE_atom). Special case of multi-component machinery.
S22 full / S22A / S66 / S66x8 / A24 noncovalent — geometries available now from GMTKN55 / refdata; interaction-energy comparison requires multi-component (E_int = E_AB − E_A − E_B, with optional counterpoise correction).
MOR41 / ROST61 / MOBH35 / WCCR10 / TMC151 / MME55 / SSE17 transition-metal benchmarks — need (1) def2 family + def2-ECP in vibe-qc’s basis library (BSE adapter), (2) TM-tested functional support (ωB97M-V, B3LYP*-D3BJ, PWPB95, TPSSh) where not already present, (3) robust UHF / UKS for first-row TM open shells. Spread across v0.8 – v1.0.
TorsionNet206 (Behara 2024) drug-like torsion curves — needs automated torsion driver (rigid scan over a defined dihedral)
- def2-TZVP + ωB97M-V or vDZP (composite). v1.0 territory.
ROT34 / LB12 / HMGB11 / MGBL150 geometry benchmarks — need molecular geometry-optimiser harness in the regression suite (today only single-points are tested). v0.8 if the optimiser surfaces gradients reliably; otherwise later.
CCCBDB (NIST experimental thermochemistry, 2186 molecules) — needs scraping or third-party mirror + same multi-component machinery as W4-17.
X23 / ICE13 / DMC-ICE13 / POLY59 molecular crystals — geometry data partially shipping today (urea / ice / benzene); lattice- energy comparison needs both (1) dispersion correction (DFT-D3 / D4 / VV10 — Phase D1/D2 in v0.5.0) and (2) the multi-component machinery (E_lattice = E_crystal/Z − E_isolated).
OMC25 (27M molecular crystals; Gharakhanyan 2026) — bulk ingestion problem; not a regression target, more a stress-test surface for high-throughput periodic SCF once the rest works.

Prerequisites in priority order (gating most of the above):

Multi-component reaction-energy machinery in run_suite.py — converts a “case” from a single SCF + cross-code Δ into a composite Σ stoichiometric_coeff × E_component with cross-code Δ on the composite. Probably v0.8.0 milestone.
BSE-driven basis-set ingestion so def2 / cc-pVnZ / pcseg-n / aug-cc-pVTZ are first-class without hand-coded .g94 files. Required for any of the §3 / §4 benchmark recommendations. v0.8 – v0.9.
Dispersion corrections (DFT-D3, DFT-D4, VV10) — Phase D1/D2, slated v0.5.x in the parity-audit list above. Required for meaningful X23 / S22 / S66 lattice / interaction energies.
Functional additions: PW1PW (Bredow’s 1-parameter hybrid; prerequisite for the Peintinger 2013 / Vilela Oliveira 2019 reference tables — see examples/regression/REFERENCES.md §A). ωB97X / ωB97M-V family for modern thermochemistry. r²SCAN family for the 3c composites. Each is its own libxc-name + grid / range-separation wiring.
Composite-method support (HF-3c, B97-3c, r²SCAN-3c, ωB97X-3c) — bundles small basis + dispersion + gCP. Highest-leverage addition for routine users; ties together (2)–(4). v0.9 – v1.0.

The §B survey list is the full discovery surface; this roadmap entry records which of those we plan to wire and what blocks each.

vq job-queue program (multi-release)¶

vq — the cross-machine job queue at vibe-queue/ — is a first-class subproject, not a vibe-qc feature. It has its own version line (independent of vibe-qc’s milestone numbers), its own pyproject.toml / .venv / test suite, and its own roadmap at vibe-queue/docs/roadmap.md. It is co-located in the monorepo and ships bundled inside vibe-qc releases (the vq v0.4-era code shipped with vibe-qc v0.8.0). This section is the global-roadmap view — the milestones a vibe-qc user or release chat needs to know about; the vq roadmap is authoritative for sequencing.

Shipped — vq v0.1.0 → v0.5.43 (current tip 2026-05-17):

VQ-1 local queue + daemon + submit / queue / status / kill / fetch CLI; file-system-backed JobSpec, no DB.
VQ-2 cross-machine SSH submit (laptop → compute host) via per-host ~/.config/vq/config.toml.
VQ-3 resource watchdog — per-job mem / wall-time / CPU- starvation kill paths; cgroup-v2 in-kernel enforcement via systemd-run --user --scope; daemon-recovery via pgid; per-job event log.
VQ-4 read-only web dashboard (FastAPI + htmx), bearer-token auth, write API (POST /api/v1/...), pause / resume.
VQ-5 operator controls — vq throttle / vq drain (soft back-off under host contention), renice fallback for non-cgroup hosts.
VQ-6 job lifecycle — vq cleanup (archive / delete / restore), job priority, --retry N, --auto-resume after host reboot, --job-name, terminal-state webhook notifications (Slack / Discord / Mattermost), vq admin update fleet refresh.

Forward roadmap:

VQ-7 auto-cleanup policy via config ([cleanup] block; daemon runs the archive / delete sweep once a day). The last open operator-controls item — vq v0.6.x.
VQ-8 multi-user support + pluggable code adapters (raw / vibeqc / orca / python) + per-user tokens — vq v0.6+.
VQ-9 SLURM-backend evaluation — let vq dispatch into a real cluster scheduler rather than a single daemon host — vq v1.0.

Open roadmap question — v0.12.0 vs vq. The milestone-list entry v0.12.0 — personal job queue proposes an in-process vibeqc.jobs + vqc-jobs queue (no daemon, JSON-per-job). That predates vq reaching maturity and now substantially duplicates shipped vq capability. Recommendation for the next roadmap review: either retire v0.12.0, or rescope it narrowly to “vibeqc-side ergonomics for driving vq” (a thin import vibeqc helper that submits to a vq daemon) rather than a second independent queue implementation.

Basis-set development + optimisation program (multi-release)¶

vibe-qc ships fixed, pre-tabulated basis sets today. A real basis-set development capability — editable basis parameters, an optimiser, auxiliary-basis generation — is a coherent multi-release track. It is the structural cure for the linear-dependence problem (a well-constructed basis is well-conditioned by design; see the Linear-dependence + screening program above) and the tooling the basissetdev branch needs.

Branch-model note. Per the standing basissetdev rule (CLAUDE.md §4), basis-set research features live on the basissetdev paper-writing branch and do not merge to main for v0.9.x. The milestones below are the parts intended for main: general-purpose infrastructure and the optimiser itself, not the paper-specific BSE-fetched basis collections.

BDEV1 Mutable basis representation — make BasisSet exponents + contraction coefficients first-class editable parameters (today they are effectively frozen on load). The prerequisite for everything below; also useful on its own for custom-basis workflows and CRYSTAL-style per-element overrides.
BDEV2 OPTBASIS-style optimiser — minimise Ω({α,d}) = E_tot({α,d}) + γ · ln κ({α,d}), the energy plus a condition-number penalty on the overlap matrix, so the optimiser is steered away from ill-conditioned basis-function space. Needs gradients of E and ln κ w.r.t. exponents (analytic or finite-difference) and a BDIIS / quasi-Newton outer loop. Mirrors CRYSTAL’s OPTBASIS keyword (manual p. 65). The user-requested flagship of this program.
BDEV3 AUTOAUX-equivalent — automatic auxiliary-basis generation for RI-J / RI-K (the BAS2 item). Couples to the RI/density-fitting machinery shipped in v0.7.2–v0.8.0; removes the “no JKfit aux for this element” failure mode.
BDEV4 On-demand BSE basis fetcher — pull basis sets from the Basis Set Exchange on first use, cache per-XDG with full per-record provenance + license string (the vqfetch-modeled pattern). Replaces the 87-set basissetdev bundle that CLAUDE.md §1 keeps out of the shipped tree for licensing reasons. Already pinned separately at On-demand BSE basis fetcher; cross-listed here as part of the coherent program.
BDEV5 ECP / pseudopotential parameter optimisation — the same Ω-style optimiser applied to effective-core-potential parameters; pairs with the libecpint ECP machinery on main.
BDEV6 Basis-set quality diagnostics — completeness-profile plots, condition-number reporting, basis-set-superposition-error (Boys-Bernardi counterpoise) tooling so a user can see whether a basis is adequate.

Slot: BDEV1–BDEV2 target v0.9.x – v0.10.x (after the RI substrate is solid); BDEV3–BDEV6 follow. Needs its own design pass before BDEV1 starts.

References: CRYSTAL OPTBASIS documentation (manual p. 65); Daga, Civalleri, Maschio J. Chem. Theory Comput. 16, 2192 (2020) — DIIS-based basis-set optimiser with condition-number penalty.

Visualization program (multi-release)¶

The visualization stack — volumetric writers, band / DOS analysis, and the matplotlib plotters — is mature enough to track as its own program. The V-phases all shipped in v0.3.0; this section gathers them with the forward-looking work currently scattered across the v0.22.0 properties suite and the cross-code gaps list.

Shipped (v0.3.0 V-phases + v0.5.0 M-phases):

Volumetric writers — .cube (molecular density + MO stacks), Molden export, XSF / BXSF (periodic structure, volumetric, Fermi-surface band data), periodic Bloch-orbital cube / XSF with the proper phase factors. Read by VMD / VESTA / XCrySDen / Avogadro / PyMOL / ChimeraX.
Band structure + kpath_from_segments, total + projected DOS, natural-orbital export, and the vibeqc.plot matplotlib plotters (band-structure figure, combined bands+DOS panel).
ORCA .hess writer + multi-XYZ / .opt trajectory writers (the M1 / M2 phases) for the moltui / OVITO / Avogadro ecosystem.

Forward roadmap:

VIZ1 Spectra plotters — broadened (Lorentzian / Gaussian) matplotlib output for IR (Hessian intensities, shipped), UV/Vis (needs T1 TDDFT / PR28), Raman (PR13), ECD (PR29). One consistent vibeqc.plot.spectrum(...) surface.
VIZ2 Scalar-field exports — ELF, reduced-density-gradient / NCI, Laplacian and kinetic-energy-density cube writers + their plotters (the PR23–PR25 phases), surfaced through the existing V1 grid infrastructure.
VIZ3 ESP cube / isosurface export (PR6) and Natural Transition Orbital export (PR27) for excited-state visualization.
VIZ4 MolTUI periodic-format collaboration — teach the terminal viewer to read lattice vectors from CUBE and replicate atoms across PBC, so periodic-SCF results triage the same way molecular ones do (tracked upstream at github.com/kszenes/moltui).
VIZ5 Animation helpers — first-class normal-mode-movie and geometry-optimization / NEB trajectory rendering (building on the shipped M2 trajectory writers).
VIZ6 vibeqc.viz namespace consolidation — gather cube, bands, plot, periodic_orbitals under one coherent umbrella (the same consolidation pattern proposed for basis_screening).

Slot: VIZ1–VIZ3 ride with the v0.22.0 properties suite (they are the visual surface of those properties); VIZ4–VIZ6 are independent ergonomics improvements slottable any time after v0.9.

Long-term vision: language-model-assisted user interaction¶

Looking past the v2.x feature-complete CCM stack, the project’s ultimate ergonomic target is a language-model front-end that removes the input-file barrier between a chemist’s intent and a running calculation. The user describes what they want to compute — in plain language, the way they’d explain it to a colleague — and the system:

Suggests a model. Picks a sensible starting method (functional, basis set, k-mesh, dispersion, solvation) given the chemistry described and the resources available, with reasoning surfaced so the user can override. Defaults to the most-cited choice for the chemistry class (e.g. ωB97X-D/def2-TZVP for organic thermochemistry; PBE+D3/pob-TZVP for periodic transition-metal solids; HF/6-31G* + MP2 single-point for benchmarking).
Generates the input. Translates the natural-language specification into a vibe-qc Python script — molecule from XYZ or SMILES, run_job(...) with the right options, post- processing for the requested observables (energies, geometry, properties, spectra). The script is human-readable and human- editable; the LM is a starting-point assistant, not an opaque wrapper.
Submits and monitors. Bridges to the user’s compute environment (laptop, workstation, HPC cluster via SLURM / PBS / LSF, eventually cloud back-ends), submits the job with appropriate resource requests inferred from the memory estimator + scaling heuristics (Phase P2), and reports status back to the user.
Interprets the output. Reads the .out / .molden / .cube artefacts back, summarises the result in plain language (“the SCF converged in 14 iterations to ‑76.0107 Ha; the dipole moment is 1.85 Debye, in good agreement with the experimental value of 1.85 D”), and surfaces follow-up questions (“would you like to verify this with a tighter basis or run a frequency calculation?”).

This sits on top of the Python API — never replacing it. The Python entry points stay the canonical, scriptable interface for power users and programmatic workflows; the LM front-end is the ergonomic on-ramp for chemists who’d otherwise be paralysed by input-file syntax. The architecture decouples cleanly: a separate Python package depending on vibe-qc, presumably called vibe-qc-assistant or similar, with the LM provider configurable and the underlying engine unchanged.

Concrete prerequisites the rest of the roadmap delivers toward this vision:

Banner provenance (shipped v0.1.0+) — every persisted run log identifies the exact build, so the LM can cite it unambiguously and regenerate identical calculations.
Memory estimator + scaling heuristics (shipped Phase P2) — feeds the resource-request logic in step 3.
run_job .out format (shipped v0.1.0+) — the structured output the LM reads back in step 4.
Tutorial corpus (15+ tutorials shipping by v0.4.x) — training-data foundation; every tutorial is a “what does this chemistry look like in vibe-qc” worked example.
Bug-hunt brief (committed at docs/bug_hunt_brief.md) — the same machine-readable policy artefacts that govern the bug-hunt chats can govern the LM front-end.

No commitment to ship dates yet — this is a vision target, not a milestone. The phasing question (does it land alongside v1.0 feature-complete, or after v2.x CCM?) is open.

Release codenames¶

Starting with v0.5.0, every major and minor release gets a codename of the form “Scientist’s Animal”. Patch releases (v0.5.1, v0.5.2, …) inherit their parent minor’s codename.

Naming rules:

Scientist is chosen for thematic fit with the release’s flagship feature — typically the person whose work the milestone most directly builds on. For v0.5.0 (vibrations / Hessian / thermochemistry) that’s E. Bright Wilson (FG-matrix vibrations). For a future v0.17.0 (DLPNO-CCSD(T)) that might be Frank Neese (DLPNO-CCSD(T) in ORCA) or Riplinger / Hansen (the DLPNO method papers).
Animal is random and intentionally a bit silly. The juxtaposition of a famous physical chemist with an unexpected animal is the joke (“Schrödinger’s Llama”, “Ewald’s Cheetah”, “Mulliken’s Cat”). Avoid animals already used by other projects’ codename schemes (Ubuntu, Debian) where there’s clear conflict; otherwise anything goes.
Format on every public artefact that mentions the release: v0.5.0 "Wilson's Otter" — version number primary, codename in quotes after.

Where the codename appears:

The runtime banner: Release v0.5.0 "Wilson's Otter" on a tagged clean tree, dev 0.5.0.dev0 "Wilson's Otter" (main @ <sha>) on a development build heading toward that release. Dev builds inherit the codename of the upcoming release so the banner is fun even before the tag drops. The lookup logic strips .devN / aN / bN / rcN PEP-440 suffixes; see :func:vibeqc.banner.codename_for_version for the catalog.
The CHANGELOG header for that release: ## [0.5.0] — DATE — "Wilson's Otter".
The git tag -a annotation: title line includes the codename.
The release-notes blog post / website announcement.

Pre-policy releases (v0.1.0, v0.4.0, v0.4.1) carry no codename; their banners read Release v0.4.1 etc. without a quoted suffix — the policy starts cleanly at v0.5.0 with no retroactive back-naming.

Implementation. The catalog lives in python/vibeqc/banner.py as _RELEASE_CODENAMES (plain Python dict). When cutting a new minor release, add the entry there in the same commit that bumps pyproject.toml. Patch releases inherit their parent minor’s codename automatically (the lookup uses the major.minor.patch key but the catalog stores only canonical minors and the lookup falls through). 5 tests in tests/test_banner_codename.py pin the catalog contract.

Codename catalog (filled in as releases ship):

Tag	Codename	Scientist association
`v0.1.0`	(none — pre-policy)	—
`v0.4.0`	(none — pre-policy)	—
`v0.5.0`	“Wilson’s Otter”	E. Bright Wilson — molecular vibrations / FG-matrix

Dependencies¶

Each milestone tag implies everything from earlier milestones. The dependency graph is almost strictly linear:

v0.2.0 needs nothing beyond v0.1.0.
v0.2.5 (symmetry core) needs v0.2.0 — the real-space matrix reduction operates on the Ewald-composed periodic Fock / J. Strictly additive: symmetry-disabled code paths continue to work unchanged.
v0.3.0 is independent of the remaining 12e-c work and of v0.2.5 — visualization is useful even before quantitative bulk SCF or symmetry speedups land.
v0.4.0 needs v0.2.0 for the Ewald infrastructure that tight-cell SCF will lean on. Phase SYM4 (IBZ Fock build) bundles in here and depends on v0.2.5 SYM1/SYM2.
v0.5.0 dispersion + solvation are independent. Periodic gradients / phonons need v0.4.0 C1 for the underlying SCFs to converge cleanly.
v0.14.0 can be started in parallel with v0.3.0 / v0.4.0 because molecular correlation is independent of the periodic stack.
v0.15.0 (CC2 / CC3) needs v0.14.0 — both are approximations inside the v0.14.0 CCSD amplitude engine.
v0.16.0 (EOM-CC) needs v0.14.0 and v0.15.0 — EOM builds on the CCSD / CC2 / CC3 ground states.
v0.17.0 needs v0.14.0.
v0.18.0 (higher-order CC) needs v0.14.0; the arbitrary-order tensor engine is best designed once the CCSD engine exists.
v0.19.0 needs v0.17.0 (shared DLPNO machinery applies to periodic).
v0.20.0 needs v0.19.0.
v0.21.0 needs v0.14.0; its production selected-CI / DMRG (25i) build on the minimal v0.9.0 vibeqc.solvers prototypes.
v0.22.0 (properties suite) needs v0.5.0 (Phase 17 Hessian for Raman / VCD; Phase G2 stress for elastic / piezo / photoelastic), v0.20.0 (periodic CCSD if PR16–PR22 want correlated dielectric / Born), and v0.21.0 (TDDFT for PR27–PR29). Within the milestone, PR7 (CPHF/CPKS) gates PR8–PR22; PR1–PR6 and PR23–PR25 are CPHF-independent and can ship first.
v1.0.0 sums everything above.
v2.x (CCM track) — strictly sequential. Each v2.N.0 depends on v2.(N-1).0; v2.0 builds on v1.0; v2.1 gates everything correlated; v2.3 gates the local-correlation steps v2.4 / v2.6; v2.7 needs v2.5 (canonical CCSD reference) + v2.6 (local CCSD scaling); v2.8 (embedding) is the capstone.

Tutorial parity (ORCA + CRYSTAL)¶

This section is the user-facing lens on the engineering roadmap: how many ORCA / CRYSTAL tutorials a user could reproduce in vibe-qc today, which ones are blocked by which milestone, and which ones we could write up now without any new vibe-qc code. The audit was compiled from the ORCA tutorial index and the CRYSTAL tutorial index.

Last audit refresh: 2026-05-10 (pre-v0.8.0 Grimme’s Gecko forward-looking pass — RIJCOSX, JKBuilder, EDIIS+DIIS, periodic GDF multi-k KRHF/KRKS, libecpint MDF families, vqfetch, vq queue, B3LYP-VWN5, D4; periodic UHF/UKS Γ-only ended up deferred to v0.9.0 per the tag-day scope decision). Per the per-quarter docs cadence, this audit refreshes at every release tag.

Status legend: ✅ works · 🟡 works with glue (ASE / small wrapper) · ❌ needs vibe-qc implementation.

ORCA — molecular chemistry¶

Tutorial	Status	Blocker
Hello water	✅	—
Input / Output	✅	—
Running in parallel	✅	P1.1 (`num_threads=`)
GUI / orbital viewers	🟡	External (Avogadro, Jmol) — `.molden` works
Single points	✅	—
Geometry optimization	✅	—
Charges (Mulliken, Löwdin)	✅	Phase 18
Bond analysis (Mayer)	✅	Phase 18
Dipole moment	✅	Phase 19
Vibrational frequencies	✅	Phase 17a–e: analytic CPHF/CPKS Hessian for RHF/UHF/RKS/UKS; tutorial 9
Thermodynamics	✅	Phase 17a-3: full ZPE/U/H/S/G(T,p) on top of analytic Hessian; tutorial 10
Conformer search (GOAT)	❌	Needs xTB
Implicit solvation	❌	Phase S1 (v0.9.0)
Explicit solvation (SOLVATOR)	❌	Out of scope (use ASE + classical FF)
Dispersion (D3 / D4)	🟡	D3-BJ shipped at v0.6.x; D4 scheduled at v0.10.0 (D2a–D2d)
NEB-TS	🟡	Workable via `ase.neb` today
IRC	🟡	Manual scan after frequencies land
KIE	🟡	Analytic Hessian + thermo ship (Phase 17); ratio script is user-side
Fukui functions	🟡	Scriptable today; native via PR1 (v0.22.0)
LED energy decomposition	❌	Needs DLPNO-CCSD(T) (v0.17.0); EDA variant PR26 (v0.22.0)
FOD analysis	❌	Needs finite-T DFT (post-1.0)
IR intensities	✅	Phase 17a-2: dipole-derivative tensor + Wilson–Decius–Cross
Raman intensities	❌	Phase PR13 (v0.22.0) — needs polarisability derivatives
UV/Vis (TDDFT)	❌	Phase T1 (v0.21.0) + PR28 spectrum reconstruction (v0.22.0)
ECD / VCD	❌	T1 + Phase PR29 (ECD) / PR14 (VCD) (v0.22.0)
NMR (GIAO)	❌	Phase PR10 (v0.22.0)
Spin-spin coupling (J)	❌	Phase PR11 (v0.22.0)
EPR / hyperfine	❌	Phase PR12 (v0.22.0); spin-orbit terms post-1.0
ESP charges (CHELPG / RESP)	❌	Phase PR3 (v0.22.0)
Hirshfeld / Bader / NBO	❌	Phases PR1 / PR2 / PR4 (v0.22.0)
Quadrupole / higher multipoles	❌	Phase PR5 (v0.22.0)
Polarisability / hyperpolarisability	❌	Phases PR8 / PR9 via CPHF substrate PR7 (v0.22.0)
ELF / NCI / RDG plots	❌	Phases PR23 / PR24 (v0.22.0)
Relativistic (ZORA / DKH)	❌	Post-1.0 stack
ONIOM / QM-XTB	❌	Needs xTB

CRYSTAL — solid-state chemistry¶

Tutorial	Status	Blocker
Geometry input	✅	POSCAR I/O + `PeriodicSystem`
Basis set input	✅	pob-* + CRYSTAL-format parser
SCF & other input	✅	`PeriodicSCFOptions`
Single-point energy (1D molecular)	✅	H-chain / H₂-chain examples
Single-point energy (2D / 3D tight cell)	✅	C1a (level shift) + C1b (smearing) all shipped on every periodic backend; C1c (EDIIS / EDIIS+DIIS / ADIIS / KDIIS) is only wired on the C++ direct-truncated periodic path. The Python Ewald-3D / Γ-GDF / multi-k GDF / BIPOLE backends are DIIS-only today and reject non-DIIS values with a clear error. See user_guide/scf_convergence.md for the per-backend support table.
SCF convergence tools	✅ partial	Damping + Pulay DIIS (default on every backend) + Saunders-Hillier level shift (C1a, every backend) + Fermi-Dirac smearing (C1b — on the periodic multi-k Ewald RHF/RKS + multi-k GDF KRHF drivers; Γ-only Ewald RHF/RKS inherits via the Python dispatch path with `n_kpts=1`. UHF/UKS smearing is not wired yet — every periodic UHF/UKS driver raises on `smearing_temperature > 0`. The C++ direct-truncated Γ Ewald drivers also lack smearing wiring. See `docs/design_smearing.md` for the v0.10.x extension plan and `.release-status/v0.10.x/smear.md` for the audited per-cell coverage matrix.) + quadratic-Newton fallback (C1c). EDIIS / EDIIS+DIIS / ADIIS / KDIIS ship on molecular C++ and the C++ direct-truncated periodic path only; not yet wired into the Python periodic backends.
Geometry optimization (periodic)	✅	Full Phase G1 (a-e) shipped on main: 1e + nuclear + S analytic, J piece via true-periodic ERIs, RKS pure-DFT XC Pulay, multi-k assembly, UKS path, ASE bridge for `atoms.get_forces()`. K-gradient (HF / hybrid exchange) deferred to v0.6.x — pure-DFT periodic relaxations work today
Quick tour: single-point energy (CRYSTAL Tutorial port)	✅	`examples/periodic/input-mgo-pob-tzvp.py` (canonical pob-TZVP testbed); v0.8.0 alternate: `vqfetch mp --id mp-1265` end-to-end (Tutorial 33)
Quick tour: band structure (CRYSTAL Tutorial port)	✅	`examples/periodic/input-si-bands.py` (silicon diamond Hcore bands)
Complete solid-state walkthrough (CRYSTAL Tutorial port)	✅	`tutorial 28` + `examples/periodic/input-lih-pob-tzvp.py` — multi-k periodic HF, IBZ reduction, Hcore bands + DOS + PDOS, HOMO Bloch cube, full v0.5.x logging surface. v0.8.0 update: tutorial 34 (LiH multi-k via `run_krhf_periodic_gdf`) targets Peintinger 2013 SI Table 2 reference (-8.149050 Ha/cell) at sub-µHa parity to PySCF.pbc.KRHF
Debug-friendly periodic DFT input (CRYSTAL Tutorial port)	✅	`examples/periodic/input-nacl-sto3g-dft.py` — RKS-LDA / sto-3g / NaCl, `VIBEQC_FAST_DEBUG=1` knob, threads ProgressLogger + perf log + .system manifest
Equation of state	❌	Phase G2
Surfaces / slabs	❌	Phase B1 + Phase C1
Defects / supercells	✅	Phase 15 (UHF/UKS) shipped; Madelung / per-k charge-correction (12e-c-4c-iv) shipped; v0.8.0 tutorial 35 (open-shell Mg⁺• in vacuum-padded cell + Makov-Payne correction) is the worked example. AFM ground-state initial guess (R3) still queued for v0.x.x
Magnetic systems	🟡	API shipped via Phase 15a (Γ-UHF) / 15b (multi-k UHF) / 15c-3 (Γ + multi-k UKS). Open-shell ships on the Ewald3D path (`run_uhf_periodic_gamma_ewald3d` / `run_uks_periodic_gamma_ewald3d` + their `_multi_k_` siblings) and on the new v0.9.0 Γ-only BIPOLE path (`run_pbc_bipole_uhf` / `run_pbc_bipole_uks`). The planned GDF-flavoured open-shell drivers were superseded by BIPOLE; multi-k UHF/UKS via GDF still queued behind the v0.10.0 GDF parity work.
Metallic systems	🟡	C1b Fermi-Dirac smearing shipped for periodic multi-k Ewald RHF/RKS and for multi-k GDF KRHF (Γ-only Ewald inherits via dispatch). UHF/UKS smearing, BIPOLE smearing, Γ-only GDF smearing, and the C++-direct Γ-Ewald path all queued at v0.10.x (per `docs/design_smearing.md` matrix); Methfessel-Paxton + Marzari-Vanderbilt flavors also queued at v0.10.x. No dedicated tutorial yet.
Metal/oxide interfaces	🟡	Phase 14a-c+e (ECPs) + C1a/C1b + Phase 15a/b/c shipped. Phase 14f CRYSTAL ECP-block parser ships on basissetdev; flips to ✅ if/when basissetdev merges. No dedicated tutorial yet
Nanorods / nanocrystals (finite)	🟡	Already work via molecular `run_job`
Fullerenes	🟡	Molecular; runnable, slow
Band structure	✅	Phase V4
Density of states	✅	Phase V5
PDOS (atom / l-projected)	✅	Phase V5b (tutorial 21)
Charge-density map (molecular)	✅	Phase V1 (cube)
Periodic Bloch-orbital map	✅	Phase V3 (tutorial 22)
Madelung constants (Ewald)	✅	Phase 12e-a + example
Vibrational frequencies (periodic)	❌	Phase G1 + 21
Phonon dispersion	❌	Phase 21
Thermodynamics (QHA, EOS at T)	❌	Phase 21
Dielectric / polarisability	❌	Finite-field response (v1.0.0)
Elastic / piezo / photoelastic	❌	CPHF / CPKS, post-1.0
TS search (periodic)	❌	Periodic Hessian, post-Phase 21
Periodic MP2 (CRYSCOR)	❌	Periodic correlation roadmap (v0.19.0; v0.8.0 ships periodic SCF, not periodic correlation)
4f-in-core ECPs	✅	Phase 14a-d shipped at v0.7.x → v0.8.0: libecpint 1.0.7 vendored + `ecp60mdf` library covers f-block (post-Yb). Manual `ECPCenter` recipe; `vq.auto_ecp_centers` helper basissetdev-conditional
Born effective charges	❌	Phase PR16 (v0.22.0)
Dielectric tensor (ε∞ / εstatic)	❌	Phases PR17 / PR18 (v0.22.0)
Elastic constants	❌	Phase PR19 (v0.22.0; needs G2 stress)
Piezoelectric tensor	❌	Phase PR20 (v0.22.0)
Photoelastic tensor	❌	Phase PR21 (v0.22.0)
Periodic IR / Raman intensities	❌	Phase PR22 (v0.22.0; needs Phase 21 phonons)
Spin-orbit / noncollinear	❌	Post-1.0
Electron transport	❌	Out of scope
CCM track (defects, embedded clusters)	❌	v2.x progression — see milestones

ASE — workflow tutorials¶

ASE ships its own tutorial set focused on workflows rather than methods — geometry optimization loops, constrained relaxations, NEB, basin hopping, MD, EOS-from-stress, defect supercells, etc. They’re calculator-agnostic by design: any code that exposes the ASE Calculator interface (energy + forces, optionally stress / dipole / Hessian / magmoms) plugs in directly.

Now that vibe-qc ships vibeqc.ase.VibeQC with energy + forces + dipole + Hessian + polarizability (Phase A, v0.5), most molecular ASE tutorials are reproducible with a one-line calculator swap. Periodic-stress-driven tutorials need G2 (stress tensor, v0.5 roadmap); QM/MM and Wannier-functions tutorials need extensions out of v0.5 scope.

ASE tutorial	Status	Blocker
ASE Databases (introduction)	✅	— (db is calc-agnostic)
ASE Databases — surface adsorption study	🟡	Periodic energy works; surfaces benefit from G1 for relaxation
Atomization energy	✅	— (energy only, ships)
Band Structures of Bulk Structures	🟡	We compute bands directly; ASE’s wrapper assumes plane-wave codes — small adapter needed
Bulk Structures and Relaxations	❌	Needs G1 periodic gradients (v0.5)
Constrained Calculations — Surface diffusion energy barriers	❌	Needs G1 periodic gradients (v0.5)
Defect calculations — ASE Tools	❌	Needs G1 + bulk relaxation; defects are a v0.6+ tutorial topic anyway
Surface diffusion via NEB	❌	Same — needs G1
Dimensionality analysis	✅	— (post-processing, no calc)
EOS — Equation of state introduction	❌	Needs G1 for relax + G2 for stress
EOS — Calculating Delta-values	❌	Same
Equilibrating acetonitrile via MD	🟡	NVE MD works on vibe-qc forces; energy-conservation diagnostic in Phase D
Equilibrating a TIPnP water box	🟡	Same — works for QM forces, classical FF needs ASE’s own calculator
Global optimization — basin hopping	✅	— (energy + forces, ships)
Lattice constants from EOS / stress	❌	Needs G2 stress tensor (v0.5)
Molecular dynamics (general)	✅	— (Phase D ships an NVE example)
NEB — Dissociation of a molecule	✅	— (Phase D ships)
NEB with IDPP	✅	— (IDPP is interpolation-only, calc-agnostic)
NEB + Dimer on Al(110) self-diffusion	❌	Needs G1 periodic gradients
QM/MM Simulations	❌	Needs MM region — out of v0.5 scope; post-1.0
Vibrational Modes of a Molecule	✅	Analytic CPHF/CPKS Hessian via Phase 17a–e (RHF/UHF/RKS/UKS); FD via `ase.vibrations.Vibrations` as a fallback for hybrid-UKS
Partly occupied Wannier Functions	❌	Needs Wannier projector — far future

The Phase D scripts under examples/ase_workflows/ will cover the ✅ rows directly (BFGS opt, Vibrations, molecular NEB, NVE MD), and the user guide page docs/user_guide/ase_integration.md will document the run_*_ase adapter pattern that lets users plug VibeQC into any of these workflows. The 🟡 rows are “works with a small adapter” — for example, ASE’s band-structure plot expects calculators to expose particular grid attributes; we’ll ship a tiny adapter once the v0.5 cycle settles. The ❌ rows wait on engineering’s G1 / G2 work for periodic gradients and stress.

Re-audit on every minor release; cross-link any newly-✅ rows to the corresponding tutorial under docs/tutorial/ or example script under examples/ase_workflows/.

Critical-path summary¶

The single feature that unblocks the most CRYSTAL tutorials at once is Phase C1 — periodic SCF convergence tooling (level shift, Fermi–Dirac smearing, second-order SCF). Without it, every “Modeling Specific Systems” CRYSTAL tutorial (surfaces, defects, magnetism, metals, interfaces) hits an oscillating SCF on realistic 2D/3D cells. C1 is now top-of-queue in v0.4.0.

After that, G1 + G2 (periodic gradients / stress tensor) takes vibe-qc from “I can compute an energy” to “I can do periodic chemistry,” and feeds finite-difference phonons (Phase 21) for free.

On the molecular side, Phase 17 (analytic Hessian) is the single biggest force multiplier — it unlocks vibrational frequencies, thermochemistry, TS confirmation, IR intensities, KIE, and VCD all at once. It pairs with D1/D2 (dispersion) and S1 (solvation) to bring the ORCA “Molecular Properties” section to ~80% parity.

The v0.22.0 properties suite then closes the remaining spectroscopy gap (NMR / EPR / ECD / VCD / Raman) and the CRYSTAL “Response Properties” line (dielectric / Born / elastic / piezo / photoelastic) in one coherent pass on top of a CPHF/CPKS substrate — the highest-leverage late-stage milestone on the road to v1.0.

The v2.x CCM track is the project’s headline feature: a multi- step progression from HF-CCM through DF / MP2 / DLPNO / CCSD(T) on cyclic clusters, capped by projection-based embedding for multi-scale defect chemistry. Each v2.N.0 is independently publishable and gates the next.

Tutorials we can write today with no new vibe-qc code¶

These are documentation-only items — every underlying capability already ships. Status tracks what has landed in docs/tutorial/.

#	Tutorial	Status
1	Hello water → `input-h2o-rhf.py` promoted into tutorial index	✅ `01_molecular_hf.md`
2	Geometry optimization (H₂O / dimer / trimer)	✅ `08_geometry_optimization.md`
3	Running in parallel (`num_threads=`, timing block)	✅ `18_parallel_execution.md`
4	Bond analysis + charges + dipole (Phase 18 + 19)	✅ `07_post_scf_properties.md`
5	Vibrational frequencies — analytic CPHF/CPKS Hessian (Phase 17a–e), ASE-FD as fallback	✅ `09_vibrational_frequencies.md`
6	Thermodynamics at T via `ase.thermochemistry`	✅ `10_thermodynamics.md`
7	NEB-TS reaction path via `ase.neb`	✅ `19_neb_reaction_path.md` (ammonia umbrella inversion at HF/STO-3G)
8	3D Madelung constants via Ewald	✅ `06_madelung_with_ewald.md`
9	Basis-set convergence sweep	✅ `13_basis_convergence.md`
10	Solid-state hello world (1D molecular crystal)	✅ `04_periodic_hf.md` + `05_periodic_dft.md`
11	Peierls dimerisation scan	✅ `17_peierls.md` (also `input-h-chain-peierls.py` example)
12	pob-TZVP rationale (solid-state basis hygiene)	✅ `16_pob_tzvp.md`
13	Orbital & density visualization (molden + cube)	✅ `11_orbital_visualization.md`
14	Band structure + DOS (1D H-chain)	✅ `12_band_structure.md`
15	DFT functional comparison	✅ `15_functional_comparison.md`
16	Dispersion (D3-BJ via `dispersion="d3bj"`)	✅ `14_dispersion.md`

“No new code” tutorial backlog cleared. All four of the originally-scoped items shipped: parallel-execution, pob-TZVP, Peierls-as-tutorial, and now NEB. The NEB tutorial uses the ammonia-umbrella inversion at HF/STO-3G — a symmetric path through a planar D₃h TS, barrier 11.14 kcal/mol (experimental ~5.8). Future tutorial additions will track new vibe-qc features (analytic Hessian, TDDFT, implicit solvation, …).

Theory-layer roadmap¶

Each tutorial today teaches how to run the calculation. The next pass adds a theory layer — the underlying equations, the key canonical references, and where relevant the algorithmic improvements that vibe-qc inherits. The goal is that a chemistry undergrad who reads one tutorial end-to-end leaves knowing both “how to do it” and “why this is the right procedure.” Math is MathJax-rendered via dollarmath (already enabled in docs/conf.py).

Target depth per tutorial is one focused theory section (≤ ½ page, 3–6 key equations) plus a References block. Not a derivation from first principles — a working summary with pointers to the papers.

Tutorial	Theory section content	Canonical refs	Status
`01_molecular_hf`	Roothaan-Hall equations, Fock matrix, self-consistent field, DIIS extrapolation	Roothaan 1951, Hall 1951, Pulay 1980/1982 (DIIS)	✅
`02_molecular_dft`	Kohn-Sham mapping, exchange-correlation decomposition, Becke grid, LDA/GGA hierarchy	Kohn-Sham 1965, Becke 1988 (grid), Treutler-Ahlrichs 1995 (radial grid)	✅
`03_open_shell`	UHF vs RHF vs ROHF, spin contamination, ⟨S²⟩ diagnostic	Pople-Nesbet 1954, Pauncz 1967	✅
`04_periodic_hf`	Bloch’s theorem, real-space vs reciprocal-space representation, k-sampling in a Γ-only cell	Ashcroft-Mermin Ch. 8, Monkhorst-Pack 1976	✅
`05_periodic_dft`	Same as 04, plus KS-DFT in a periodic basis; grid integration per unit cell	Pisani 1988 (CRYSTAL-style crystalline orbitals)	✅
`06_madelung_with_ewald`	Ewald decomposition (real + reciprocal), α-invariance, convergence-rate trade-off	Ewald 1921, Allen-Tildesley Ch. 5	✅
`07_post_scf_properties`	Mulliken / Löwdin population analysis, Mayer bond order as a basis-set-consistent generalisation, dipole moment formula	Mulliken 1955, Löwdin 1950, Mayer 1983	✅
`08_geometry_optimization`	Hellmann-Feynman theorem, BFGS (Broyden-Fletcher-Goldfarb-Shanno) quasi-Newton update, Wolfe conditions for line search	Hellmann 1937 / Feynman 1939, Broyden 1970 (or textbook Nocedal-Wright)	✅
`09_vibrational_frequencies`	Normal-mode analysis, mass-weighted Hessian, analytic CPHF/CPKS construction, IR intensities via dipole-derivative tensor (double-harmonic), FD fallback, harmonic-to-IR scaling factors	Wilson 1955 (normal modes), Pople 1979 (analytic 2nd derivatives + CPHF), Wong 1996 (HF scaling factor 0.89)	✅
`10_thermodynamics`	Ideal-gas partition function factorisation (trans × rot × vib × elec), Gibbs free energy, entropy decomposition	Atkins-de-Paula Ch. 13, McQuarrie Ch. 8	✅
`11_orbital_visualization`	MO isosurface interpretation, sign arbitrariness, Gaussian-cube file format	Gaussian cube format spec (public)	✅
`12_band_structure`	Bloch sum, dispersion relation E(k), density of states histogram, Fermi level, gap closure	Ashcroft-Mermin Ch. 8, 9	✅
`13_basis_convergence`	Contracted Gaussian expansion, correlation-consistent hierarchy cc-pVXZ, Helgaker CBS extrapolation exp(-αX)	Dunning 1989, Helgaker-Klopper-Koch-Noga 1997	✅
`14_dispersion`	Grimme D3 pairwise expression with BJ damping, C₆ coefficients, damping-parameter fit	Grimme 2010 (D3), Grimme 2011 (BJ damping), Becke-Johnson 2006	✅
`15_functional_comparison`	Jacob’s ladder hierarchy, self-interaction error, B3LYP / PBE0 hybrid construction	Perdew 2001 (Jacob’s ladder), Becke 1993 (B3LYP), Adamo-Barone 1999 (PBE0)	✅

Progress (15 of 15). All tutorials now carry a Theory + References section matching the template from tutorial 14. Open follow-up: a round of reference spot-checks (hunt down every [verify] marker, confirm or correct the journal-volume-page triples) and maintenance passes as new features ship (e.g., analytic Hessian will refresh tutorial 09, ROHF will refresh tutorial 03).

Working convention for citations. Foundation-era papers (Roothaan, Kohn-Sham, Pulay, Becke, etc.) I cite directly — those are stable and well known. Anything post-2010 I’ll mark with [Ref: verify] in draft; the user confirms before publication. This catches my weakest failure mode (hallucinated year/volume/page) without slowing the foundation content down.

Order of attack. Start with the most-visited tutorials (01, 02, 08, 14) where theory depth pays back most immediately for new users. Defer 10–12 until the core set lands.

That’s 12 tutorial theory sections + 4 remaining “no-code” tutorials = the documentation backlog before any new C++ feature work is required.

Cross-code feature gaps (ORCA 6.1.1 + CRYSTAL23 manual sweep)¶

A May 2026 inventory pass against the ORCA 6 (1655 pp) and CRYSTAL23 (524 pp) manuals surfaced features neither already shipped in vibe-qc nor explicitly enumerated under one of the milestones above. Grouped into thematic buckets so future milestones can absorb whole buckets at once instead of one-off keywords. Items that ARE already on the roadmap (DLPNO-CCSD(T), NMR/EPR/Mössbauer, CASSCF/NEVPT2, periodic phonons, slab builder, elastic / piezoelectric / photoelastic tensors, periodic Berry charges, periodic MP2, TDDFT, implicit solvation, D4) are omitted from this list to keep the focus on genuinely-new gaps.

Buckets at a glance (~165 items total across two sweeps; ID-prefix in bold; see body for items):

First sweep (~70 items)	Second sweep (~95 items)
3c- Composite-3c methods family	CMP- ORCA Compound scripting (workflow lang)
DIAG- SCF diagnostics + provenance	AUTOCI- AutoCI + advanced correlation knobs
B1.5-12 Geometry editing + nanostructure builders	IO- Restart, interop, on-disk formats
SS- Solid-solution enumeration	MD- / ESD- MD + excited-state dynamics
EOS- / QHA- Equation-of-state + quasi-harmonic	TOOL- orca_* utility binaries
VIB- Beyond-harmonic vibrations	SPEC7-12 Spectroscopy depth (extra)
BOND- / XRD- / EMD- Bond-order, X-ray, EMD	PLT- Density / property cube exports
MR- / EX- Multireference + excited-state extras	CGEO- CRYSTAL geometry builders (extra)
EMB- Embedded-cluster + scalable QM/MM	CBAS- CRYSTAL basis-set library
S5-8 Solvation extras	CALC- CRYSTAL calculation-type + SCF knobs
SPEC1-6 Spectroscopy beyond what’s planned	PROP- CRYSTAL properties keywords
BSSE- Boys-Bernardi counterpoise + BSSE	CTOOL- CRYSTAL post-processing utilities
CHG- Hirshfeld + ESP-fit charge variants	PAR- CRYSTAL job-control + parallelism
POL- Spontaneous polarisation + Berry phase	CECO- CRYSTAL ecosystem tools
BAS- Basis-set automation
CORR- A-posteriori correlation correction

The first sweep is the chemistry surface (methods, properties, builders); the second sweep is the infrastructure surface (workflow languages, file-format interop, restart protocols, parallel-execution knobs, post-processing utilities). Most infrastructure items are small individually; collectively they’re the post-1.0 maturity story.

Composite-3c methods family (extends Phase D + DFT stack)¶

Direct ORCA / CRYSTAL composites that sit on top of dispersion + gCP + a tuned DFT functional. Each pair (HF-3c, r2SCAN-3c, PBEh-3c, B97-3c, HSE-3c) is a fixed recipe — a small wrapper sets the basis + functional + dispersion + counterpoise and prints “3c” in the .out for the user. Modest C++ work.

3c-1 Wrapper functions vq.run_hf_3c, run_r2scan_3c, run_pbeh_3c, run_b97_3c, run_hse_3c (last two: solid-state hybrid composites already in the pob-TZVP family).
3c-2 Solid-state revisions: HFsol-3c, PBEsol0-3c, HSEsol-3c (distinct from the molecular composites; the parametrisation is for periodic).
3c-3 ABC (D3 three-body Axilrod-Teller-Muto) as a flag on the existing D3 driver.
3c-4 gCP geometrical-counterpoise correction as a public function (component of the 3c stack but useful standalone).

SCF diagnostics + provenance (extends v0.5.x observability)¶

Cheap, high-leverage diagnostics ORCA/CRYSTAL surface that vibe-qc doesn’t expose yet:

DIAG1 vq.scf_stability(result) — real / complex / spin stability analysis (orbital-Hessian eigenvalues; flags triplet instability for closed-shell SCFs that should have been UHF).
DIAG2 Spin-contamination diagnostic for UHF/UKS results (<Ŝ²> deviation from S(S+1); CRYSTAL SPINCNTM).
DIAG3 Broken-symmetry workflow scaffold: BROKENSYM ORCA- style, with explicit per-pair antiferromagnetic coupling J via Yamaguchi’s formula.
DIAG4 ORCA Compound script equivalent — chained-job runner for canonical workflows (CBS extrapolation, BSSE-corrected binding curves, DLPNO+composite stacks).

Geometry editing + nanostructure builders (extends Phase B1)¶

CRYSTAL23 has an unusually rich geometry-editing toolkit. Each function is a few-line numpy operation but together they streamline solid-state model building:

B1.5 vq.cluster_carve(system, radius_bohr, saturate_dangling="H") — finite cluster carved from a periodic cell, optionally H-saturated (CRYSTAL CLUSTER / HYDROSUB).
B1.6 vq.nanotube_from_slab(slab, n, m) — single-wall nanotube builder; vq.multiwall_nanotube for concentric variants. CRYSTAL NANOTUBE / SWCNT / NANOMULTI.
B1.7 vq.nanorod_from_crystal(...), nanocrystal_from_crystal(...) — 1D / 0D nanostructure builders. CRYSTAL NANOROD / NANOCRYSTAL.
B1.8 vq.fullerene_from_hexagonal_slab(...) — fullerene builder. CRYSTAL FULLE.
B1.9 vq.wulff_polyhedron(surface_energies) — Gibbs-Wulff equilibrium-shape construction. CRYSTAL WULFF.
B1.10 Atomic-edit primitives: substitute, insert, remove, displace, rotate on PeriodicSystem (CRYSTAL ATOMSUBS / ATOMINSE / ATOMREMO / ATOMDISP / ATOMROT).
B1.11 vq.embed_point_charges(system, charges) — external point charge array (CRYSTAL POINTCHG).
B1.12 vq.apply_sawtooth_field(system, field_au, axis) — external electric field along a periodic axis (CRYSTAL FIELD / FIELDCON).

Solid-solution enumeration¶

SS1 vq.enumerate_configurations(system, substitutions, symprec=...) — list symmetry-inequivalent configurations (CRYSTAL CONFCNT).
SS2 vq.sample_configurations(system, n_samples) — Monte-Carlo sampling for large composition spaces (CRYSTAL CONFRAND).
SS3 vq.run_configurations(configs, calculator) — batch driver across the enumerated set (CRYSTAL RUNCONFS).

Equation-of-state automation (extends G2 stress)¶

Once G2 (stress tensor) ships, EOS is “fit a curve to E(V)”:

EOS1 vq.fit_equation_of_state(volumes, energies, model="birch-murnaghan") — accepts vinet, birch-murnaghan, murnaghan, poirier-tarantola, polynomial. Returns EOSFit with V0, B0, B0p, E0 + reduced-χ². Mirrors CRYSTAL EOS.
EOS2 vq.run_eos_scan(system, calculator, volume_range_pct=(-10, +10), n_points=11) — automated workflow: scale lattice, relax internal coords at each volume (needs G1), fit. Output a dataclass with the fit + raw points.
QHA1 vq.run_qha(...) — quasi-harmonic approximation workflow chaining EOS + phonons. Already mentioned as v0.7-ish; this entry pins the API shape.
QHA2 Quasi-harmonic thermo-elasticity (T-dependent Cij).

Beyond-harmonic vibrations (extends Phase 21)¶

VIB1 vq.compute_vpt2(hess) — vibrational perturbation theory anharmonic corrections. ORCA VPT2 / GVPT2.
VIB2 vq.compute_anharm_xh_stretch(...) — 1D anharmonic treatment of a selected X-H stretch (CRYSTAL ANHARM).
VIB3 vq.compute_vscf(...) and vq.compute_vci(...) — vibrational SCF / CI on a 4th-order PES. CRYSTAL VSCF / VCI.
VIB4 vq.compute_phonon_dos(..., neutron_weighted=True) — neutron-weighted vibrational DOS for inelastic-neutron-scattering comparison. CRYSTAL phonon DOS option.
VIB5 vq.compute_adp(hess, T_kelvin) — anisotropic atomic displacement parameters (Debye-Waller) at temperature. CRYSTAL ADP.

Bond-order / topology / X-ray analyses¶

BOND1 Crystal Orbital Overlap Population (vq.coop) — bond-strength analysis for periodic systems. CRYSTAL COOP.
BOND2 Crystal Orbital Hamiltonian Population (vq.cohp) — energy-resolved bonding analysis. CRYSTAL COHP (also popular via the LOBSTER post-processor on plane-wave codes).
XRD1 vq.compute_xray_structure_factors(system, density) — F(hkl) for X-ray diffraction; CRYSTAL XFAC.
XRD2 Compton profile + reciprocal form factors (CRYSTAL BIDIERD / PROF).
EMD1 Electron-momentum-density maps (vq.compute_emd_line, compute_emd_plane); from the density matrix or per-Wannier- function. CRYSTAL EMDL / EMDP.

Multireference + excited-state extras (extends v0.21)¶

MR1 ICE-CI (iterative configuration expansion) — approximate FCI scaling to ~30 orbitals (ORCA ICE-CI).
MR2 DMRG interface — for FCI in larger active spaces. Likely an interface to BLOCK / CheMPS2 rather than a native implementation.
MR3 Multi-reference EOM-CC (MR-EOM-CC).
MR4 Multiconfigurational RPA (MCRPA) — extends MCSCF to excited states without explicit state-averaging.
MR5 ΔSCF for excited states by orbital occupation (ORCA DELTASCF) — much cheaper than TDDFT for the lowest few states of a single character.
EX1 Minimum-energy crossing point (MECP) optimization between two states (e.g. singlet/triplet, two TDDFT roots).
EX2 Conical intersection optimization (CI-search).

Embedded-cluster + scalable QM/MM (extends post-1.0 QM/MM)¶

The CCM track (v2.x) overlaps with this — items here are the infrastructure it sits on:

EMB1 ORCA-style MOL-CRYSTAL-QMMM / IONIC-CRYSTAL-QMMM — embedded-cluster periodic property calculations on a QM region inside an MM crystal.
EMB2 Fast-multipole-method QM/MM (FMM-QMMM) for >10⁴ point charges — needed for any realistic MM environment.
EMB3 Auto link-atom + boundary-treatment selection (mechanical / electrostatic / IOD / Z1/Z2/Z3 schemes).
EMB4 Partial Hessian Vibrational Analysis (PHVA) for the active region — frequencies from a sub-block of the full Hessian. Pairs naturally with QM/MM.

Solvation extras (extends Phase S)¶

S5 DRACO — dynamic radii adjustment for continuum solvation, gives noticeably better ΔG_solv than fixed radii.
S6 openCOSMO-RS interface — solvent screening and fluid- thermodynamics post-processing on top of the COSMO/CPCM output.
S7 Explicit-solvent shell builder (SOLVATOR-style) — out of v0.x core scope; could be a thin wrapper over packmol or similar.
S8 Docking driver (DOCKER-style) — out of v0.x core scope; would interface to vina / equivalent.

Spectroscopy beyond what’s already planned¶

SPEC1 Resonance Raman simulation (analogous to ORCA orca_asa) — vibronic structure with a fixed reference excited state.
SPEC2 ROCIS / ROCIS-DFT for X-ray and UV-Vis of transition-metal complexes.
SPEC3 STEOM-CCSD and DLPNO-STEOM-CCSD for excited states (similarity-transformed EOM family). Pairs with v0.21 MR plans.
SPEC4 MCD (magnetic CD) on top of TDDFT (extends PR29 ECD in the v0.22 properties suite).
SPEC5 LO/TO splitting in IR for polar crystals — extends Phase 21 phonons.
SPEC6 SOMF (spin-orbit mean-field) operator for property evaluation — cheaper than full 2-component SCF for SOC matrix elements. Useful for EPR g-tensors of heavy elements.

Boys-Bernardi counterpoise + BSSE infrastructure¶

BSSE1 vq.compute_bsse(system_a, system_b, calculator) — Boys-Bernardi counterpoise for intermolecular interactions.
BSSE2 MOLEBSSE / ATOMBSSE for molecular crystals (CRYSTAL): counterpoise corrections for molecules-in-crystal packing energies.

Hirshfeld variant + ESP-fit charge extras (extends PR-suite)¶

CHG1 MBIS (minimal-basis iterative stockholder) charges — a Hirshfeld variant with often-better atoms-in-molecules fidelity. Extends PR1 (Hirshfeld) in v0.22.
CHG2 Updated CHELPG / RESP infrastructure: extend the existing molecular dipole/ESP machinery to fit per-atom point charges to the ESP on a vdW grid.

Spontaneous polarization + Berry phase¶

POL1 SPOLBP — spontaneous polarization via Berry phase (King-Smith / Vanderbilt) on the periodic SCF.
POL2 SPOLWF — spontaneous polarization via localised Wannier orbitals — pairs with the LOCALWF Wannier-function story already on the post-1.0 list.

Basis-set automation¶

BAS1 BASOPT equivalent — internal basis-set optimizer for unusual element / pseudopotential combinations.
BAS2 AUTOAUX equivalent — automatic auxiliary-basis generation for RI-J / RI-K once those land.

A-posteriori correlation correction¶

CORR1 EDFT / ADFT — apply a DFT correlation functional on top of an HF density without re-converging. Cheap “DFT correlation correction” workflow CRYSTAL exposes.

The total here is roughly 70 distinct items spanning ~10 themes. Most slot naturally into existing milestones (3c stack into v0.5.x or v0.6.x; geometry editing into the B1 surface-builder phase; EOS into the v0.7 G2 follow-up; bond-order analyses into the v0.22 properties suite). The few that need their own milestone — embedded cluster QM/MM, multireference extras — fit the post-1.0 stack already in the roadmap.

Cross-code feature gaps — second-pass deep dive¶

The first sweep above caught the user-facing chemistry: methods, properties, geometry builders. A second deeper read of the same two manuals (May 2026, focusing on chapters skimmed the first time — Compound scripting, AutoCI, the orca_* utility binaries, the property exports, the CRYSTAL job-control + tools layer) surfaced ~95 additional items, mostly infrastructure: workflow languages, file-format interop, restart protocols, parallel- execution knobs, post-processing utilities. None of it is bleeding- edge chemistry — it’s the scaffolding that turns vibe-qc from “a correct code” into “a code engineering teams can build on.” Most items are small individually; collectively they’re the post-1.0 maturity story.

ORCA Compound scripting (workflow language)¶

ORCA’s %Compound block is a Turing-complete mini-language for chaining calculations: variables, control flow, geometry manipulation, file I/O, system calls. Vibe-qc’s equivalent today is “write a Python script” — which is fine, but Compound is deliberately persistable and self-contained. A small subset of this surface is high-leverage; the full surface is post-1.0.

CMP1 vq.workflow.Compound — declarative chained-job runner with New_Step (sub-job), Variable (typed value), For / If / Break / Continue (control flow), &{var} string interpolation. Python class with a fluent API, not a parser — the goal is the workflow, not the syntax.
CMP2 Read primitive — pull values from any prior step’s output (energy, gradient, dipole, frequency, occupation, arbitrary scalar) by structured key.
CMP3 Geometry object methods — add_atom, remove_atom, bond_length, bond_angle, dihedral, to_zmat, to_xyz, apply_displacement, superimpose. Mirrors ORCA’s geometry- manipulation calls inside Compound.
CMP4 Dataset primitive — multi-row table with column- typed cells, the natural object for scan / fit workflows (CBS extrapolation, BSSE binding curves, EOS).
CMP5 Linear-algebra primitives in workflow scope — dot, norm, det, inv, eig, solve on small matrices. Lets a Compound script do Yamaguchi-style spin coupling arithmetic without dropping to Python.
CMP6 Timer + file primitives (file_exists, file_read, file_write, file_delete, file_append) — workflow-scope filesystem access. Needed for restart logic.
CMP7 Alias + Basenames[i] — name reuse and step- indexed file naming. Cheap; pure ergonomics.
CMP8 GoTo / Abort / EndRun / sys_cmd — control- flow escape hatches. sys_cmd is the “shell out” backdoor.
CMP9 GOAT (global optimization) hooks — make the Compound runner a first-class consumer of the v0.7 GOAT conformer-search output: For (conformer in goat_results).
CMP10 Bundled examples gallery — helloWorld, ccCA_CBS_2, scan_1D, BSSEOptimization, binding_curve. Each example doubles as a regression test for the workflow runtime.
CMP11 Property-table coverage — every property the SCF + post-SCF stack writes should be Compound-readable by structured key. Audit what’s exposed today vs what ORCA’s %output block surfaces.

AutoCI + advanced correlation knobs¶

ORCA’s AutoCI module exposes CC-family methods with an unusually rich knob surface. v0.5.x ships single-reference CCSD(T); the items here flesh out the AutoCI-equivalent control surface for the v0.21 multireference + post-1.0 correlation push.

AUTOCI1 citype selector — CISD, CCSD, CCSD(T), CC2, CC3, CCSDT, LCCSD, LCCD, BCCD available through one entry point with a string flag.
AUTOCI2 Density variants — unrelaxed vs Z-vector relaxed densities for properties (gradients require the relaxed variant; one-electron expectation values often only need unrelaxed).
AUTOCI3 Convergence options — DIIS / Jacobi diagonal- shifted iteration, residual norm + amplitude norm both monitored, max_iter + level shift exposed in options struct.
AUTOCI4 Analytical gradients for CC family — currently CCSD only on the roadmap; AutoCI has CCSD(T), CC2, CC3 gradients via response theory.
AUTOCI5 Linear response on top of CC reference — TD-CC excitation energies, CC2 / CC3 oscillator strengths.
AUTOCI6 RDM2 export — two-particle density matrix to HDF5 / JSON / FCIDUMP for downstream analysis (NOFs, decomposition into two-electron contributions).
AUTOCI7 %moinp restart — start CC from a converged prior wavefunction, refine with tighter convergence or larger basis. Couples to the orbital-restart story below.

Restart, interop, and on-disk format protocol¶

vibe-qc’s restart story today is BasisSet.checkpoint + MOSet serialization. ORCA’s interop surface is broader: orca_2json, multiple binary encodings, ASCII fallback, and a JSON config schema readable by any tooling. This bucket is the v0.7+ “play well with the ecosystem” story.

IO1 vq.export_calc(result, format="json") — one-line export of a converged calculation to JSON. Mirrors orca_2json -property (properties only) and -gbw (full wavefunction). Default format JSON, optional BSON / UBJSON / MessagePack via flag for byte efficiency on large wavefunctions.
IO2 vq.import_calc(path) — round-trip importer. Schema- versioned; rejects mismatched majors with a clear error.
IO3 Public JSON-schema for the export — published in docs/file_formats.md and pinned to a major version. Other tools (analysis scripts, ML models, web frontends) consume this contract.
IO4 ASCII-fallback dump_text(result, path) — human- readable plaintext form for environments that can’t ingest binary (containers, locked-down clusters).
IO5 Integral exports — vq.export_integrals(basis, kind="ao_2e") writing AO 2e integrals to FCIDUMP / HDF5. Same for kind="mo_2e", kind="ri_3c". Needed for external CI / DMRG / ML-correlation post-processors.
IO6 Fock-matrix decomposition export — per-contribution Fock pieces (J, K, XC, ECP, dispersion) saved separately so downstream tools can re-weight or analyse contributions.
IO7 Orbital-window export (OrbWin) — write a contiguous-or-explicit MO range to disk, the natural shape for active-space pre-selection workflows.
IO8 AuxBasisType exposed in exports — record which auxiliary basis (RI-J / RI-K / RIJCOSX) was used so a restart picks the same one.
IO9 TDDFT data export — Casida (X+Y), (X-Y) vectors, transition densities, NTOs, with the same schema-versioned shape as the SCF export.
IO10 OPI Python interface equivalent — a documented Python wrapper around the on-disk format, so external consumers don’t reinvent the parser. vq.io.OrcaCompat module providing read-only adapters.
IO11 ASE read("file.json", format="vibeqc") round- trip — extends ASE’s existing per-code parsers. Pairs with the existing vibeqc.ase.VibeQC Calculator bridge.

Molecular dynamics + ESD (excited-state dynamics)¶

ORCA’s MD chapter ships a SANscript-like input language for classical-and-mixed dynamics (BOMD, AIMD, MTD, restart, region- based thermostats). vibe-qc has examples/ase_compare/ showing ASE-driven MD; native MD is a post-1.0 topic but the API shape matters now so future engineering doesn’t reinvent it.

MD1 vq.MDDriver — top-level Python class with Run(steps), Restart(path), Initvel(temp), Thermostat(kind, params), Timestep(fs), Cell(npt|nvt|nve). Mirrors ORCA’s MD command surface in Python idioms.
MD2 Region API — MDRegion(atoms, thermostat=..., constraint=...) for per-region thermostats / constraints. Needed for QM/MM and surface MD where bulk and slab want different couplings.
MD3 Constraint — bond / angle / dihedral / SHAKE / RATTLE constraints applied during integration.
MD4 Dump — trajectory write at configurable cadence, including selective per-region dumps and per-property dumps (forces, dipole, charges).
MD5 Metadynamics — Manage_Colvar + Metadynamics primitives; well-tempered MTD as a flag. Pairs with the free-energy methods on the post-1.0 list.
MD6 Restart protocol — checkpoint that captures positions + velocities + thermostat state + colvar history in one file. Pairs with IO1’s schema versioning.
MD7 Units parser — accept times, energies, lengths, temperatures with explicit units in the API; reject ambiguous bare floats.
ESD1 vq.compute_esd(...) — excited-state dynamics driver wrapping the ORCA %ESD block functionality.
ESD2 HESSFLAG Hessian-flow options — VG (vertical gradient), AHAS (adiabatic Hessian, adiabatic shift), AH (adiabatic Hessian), VH (vertical Hessian), HHBS / HHAS (half-and-half), UFBS / UFAS (uniform-field variants). Maps onto how the excited-state PES is approximated.
ESD3 USEJ Duschinsky rotation — full mode-mixing between ground- and excited-state normal modes, beyond the parallel-mode approximation.
ESD4 ESD(FLUOR), ESD(PHOSP), ESD(ISC) — fluorescence / phosphorescence / intersystem-crossing rate calculation modes.
ESD5 LINES parser — line-shape function selection (Lorentzian / Gaussian / Voigt) for the simulated vibronic spectrum.
ESD6 MODELIST selector — restrict vibronic coupling to a chosen mode subset; needed for chromophores embedded in large systems.

orca_* utility binaries (post-processing toolbelt)¶

ORCA ships 20+ standalone post-processing executables. Most are small, single-purpose, and compose with the main run via parsed output. vibe-qc’s vq.tools namespace is the natural home; many of these are already implicit in the v0.22 properties roadmap, but pinning the API shape now keeps the naming consistent.

TOOL1 vq.tools.aim — atoms-in-molecules / QTAIM topology (critical points, basins, integration). ORCA orca_2aim. Pairs with TOPOND on the CRYSTAL side.
TOOL2 vq.tools.to_molden(result) — Molden / MKL / Multiwfn export format. ORCA orca_2mkl.
TOOL3 vq.tools.asa(...) — automatic-spectrum-analysis driver for vibronic / resonance-Raman simulation. ORCA orca_asa.
TOOL4 vq.tools.chelpg(result) — CHELPG ESP-fit charges. Already covered by CHG2 above; this entry pins the standalone CLI shape.
TOOL5 vq.tools.euler(...) — Euler-angle conversion utilities for tensor-property output. Tiny; pure ergonomics. ORCA orca_euler.
TOOL6 vq.tools.export_basis(basis) — basis-set export in NWChem / Gaussian / ORCA / Molpro / CRYSTAL formats. ORCA orca_exportbasis. Pairs with BAS1 / BAS2.
TOOL7 vq.tools.fit_pes(points, model="morse") — 1D PES fitter (Morse / harmonic / quartic / spline). ORCA orca_fitpes. Already partly covered by EOS1.
TOOL8 vq.tools.mapspc(...) — broadens stick spectra to envelope spectra (Lorentzian / Gaussian) with configurable width and lineshape. ORCA orca_mapspc.
TOOL9 vq.tools.merge_fragments(frag_results) — stitches per-fragment SCF results into a fragment- decomposed total (useful for SAPT-style decomposition, embedding workflows). ORCA orca_mergefrag.
TOOL10 vq.tools.plot_vibmodes(hess, mode_indices) — Cartesian displacement vectors as XYZ frames per mode. ORCA orca_pltvib.
TOOL11 vq.tools.pnmr(...) — paramagnetic NMR shifts (combines hyperfine + g-tensor + ZFS). ORCA orca_pnmr. Pairs with v0.12 EPR / NMR.
TOOL12 vq.tools.vib_thermochem(hess, T, P) — rigid-rotor / harmonic-oscillator thermochemistry post- processor. ORCA orca_vib. Probably already in vibeqc via thermo helpers; this entry standardises the CLI.
TOOL13 vq.tools.gcp_correction(system, basis) — geometrical-counterpoise standalone (companion to 3c-4 above). ORCA otool_gcp.
TOOL14 vq.tools.xtb_singlepoint(system) — semiempirical xTB single-point inside vibe-qc workflow (driver-level fast preview before DFT). ORCA otool_xtb. Pairs with the existing xTB-driver discussion in the benchmarks plans.
TOOL15 vq.tools.localize(orbitals, method=...) — orbital localisation with PM (Pipek-Mezey), FB (Foster-Boys), NEWBOYS, AHFB, IAOIBO, IAOBOYS, PMVVO, LIVVO selectors. ORCA orca_loc. Mostly covered today; this pins the full method roster.
TOOL16 vq.tools.fock_block_eig(fock, block) — diagonalise a sub-block of the Fock matrix. ORCA orca_blockf.
TOOL17 vq.tools.plot_orbital(orbital, grid) — cube-grid orbital / density rendering, matplotlib- ready slices. ORCA orca_plot. Already partly covered by tutorial 17; this entry standardises the API.

Spectroscopy depth (extends Phase 19 + post-1.0 spec stack)¶

Beyond the user-facing methods (TDDFT, EOM-CC, MCD), ORCA exposes a long tail of specialised spectroscopy modules. Most are post-1.0 territory but worth itemising so we don’t rebuild the API surface when each lands.

SPEC7 ABSFFMIO / ABSQ — full-frequency-domain absorption with multipole-and-quadrupole oscillator strengths.
SPEC8 MCD / XMCD — magnetic CD on top of TDDFT, with X-ray (XMCD) extension for transition-metal core-level spectroscopy.
SPEC9 XAS / XES family — full-COC, RAS-CI core-hole, damped-response, and ROCIS variants of X-ray absorption / emission. Pairs with v0.21 multireference.
SPEC10 RIXS / RIXSSOC — resonant inelastic X-ray scattering, with spin-orbit coupling for heavy atoms.
SPEC11 TRANSABS / TRANSCD — transient-absorption / transient-CD on top of pump-probe excited-state dynamics.
SPEC12 NRVS / VDOS — nuclear-resonance vibrational spectroscopy, vibrational density-of-states partitioning per-element. Pairs with VIB4 above.

Density / property exports (extends IO bucket)¶

The %plots and %loc blocks in ORCA enumerate density-cube shapes and localisation-method options that the IO layer needs to be able to write.

PLT1 Format selector — Gaussian-cube, Molden, netCDF, HDF5, raw-binary as output formats for any cube property.
PLT2 Density selectors — MOCoefficients, 2elIntegrals, Densities, Vaux (auxiliary-density flag for hybrid + RI workflows). Each is a flag on vq.plot_density(...).
PLT3 %loc full block — localisation method roster on the SCF orbitals (covered by TOOL15 above; this is the input-side analogue).

CRYSTAL geometry input — extra builders¶

The first sweep covered the user-facing builders (CLUSTER, NANOTUBE, FULLE, WULFF, ATOMSUBS family). A second pass catches the more specialised input keywords for symmetry manipulation and finite-cluster construction.

CGEO1 EXTERNAL — read pre-built geometry from a file in CRYSTAL’s external geometry format. Pairs with CIF / ASE-Atoms readers vibe-qc already has; this is the CRYSTAL-native dialect.
CGEO2 SLABCUT / SLABINFO — extract a slab from a bulk crystal by Miller indices, with explicit termination control. Already in B1.x phase; this names the specifically-CRYSTAL options.
CGEO3 NANOROD / NANOCRYSTAL (covered by B1.7 above; this entry is just the CRYSTAL keyword cross-ref).
CGEO4 HYDROSUB — hydrogen substitution at dangling bonds for cluster carving. Already in B1.5; this names the CRYSTAL knob.
CGEO5 MOLEXP / MOLSPLIT — split a molecular crystal into per-molecule subsystems for fragment workflows.
CGEO6 ROTCRY — rotate the unit cell to align a given crystallographic axis with a Cartesian direction (for slab + interface setups).
CGEO7 SUPERCEL / SUPERCON / SCELCONF / SCELPHONO — supercell construction with various conventions (conventional / primitive, phonon-supercell with explicit q-mesh).
CGEO8 ATOMORDE — reorder atoms by Z, by name, or by an explicit list. Pure ergonomics but stabilises output formatting.
CGEO9 BREAKELAS / ELASTIC — symmetry-breaking strains for elastic-constant calculations. Pairs with ELASTCON in the existing roadmap.
CGEO10 MAKESAED — generate the symmetry-adapted external displacements (SAED) for IR / Raman intensity-symmetry analysis.
CGEO11 RAYCOV — modify covalent radii used by the bond / connectivity detector. Niche but cheap.
CGEO12 MOLEBSSE / ATOMBSSE — molecular-in- crystal counterpoise (covered by BSSE2 above).
CGEO13 PLANES — define crystallographic planes for property calculation (potentials, density slices) — pairs with the POTM / ECHG properties.
CGEO14 PRIMITIV / MODISYMM / PURIFY / SYMMREMO / TRASREMO — symmetry-manipulation knobs: reduce to primitive cell, modify symmetry, purify numerically-noisy symmetry, remove symmetry / remove translational symmetry.
CGEO15 FRAGMENT — define explicit fragment partitions for fragment-correlation methods.
CGEO16 EXTPRT / CIFPRT / CIFPRTSYM / COORPRT — output-format selectors (CRYSTAL external, CIF, CIF+symmetry, plain coordinates).
CGEO17 FINDSYM — auto-detect the highest-symmetry setting consistent with the input geometry. Pairs with the spglib integration vibe-qc already has but surfaces a CRYSTAL-shaped API.
CGEO18 STRUCPRT — print the structure tensor (used in elastic-tensor post-processing).

CRYSTAL basis-set library¶

CRYSTAL23 ships a basis-set library with several entries that vibe-qc’s existing basis-loader doesn’t carry yet.

CBAS1 STO-nG family with n = 3, 4, 5, 6 — minimal Slater-fit basis variants. STO-3G is shipped; n > 3 is trivially accessible.
CBAS2 Pople-style 3-21G, 6-21G — covered for most rows by the existing Pople loader; audit gaps.
CBAS3 POB-TZVP family — periodic-optimised TZVP for solid-state work; CRYSTAL’s recommended default for many DFT-on-crystals studies.
CBAS4 f-electron lanthanide / actinide bases — new in CRYSTAL23; needed for f-block solid-state.
CBAS5 g-type AOs — new in CRYSTAL23 (g-functions in the angular-momentum stack). Vibe-qc’s libint integration supports g; verify the basis-loader path doesn’t truncate.
CBAS6 ECP libraries — Hay-Wadt, Durand-Barthelat, Columbus, Stuttgart-Cologne SOREP. Pairs with the existing ECP roadmap.
CBAS7 BASOPT — internal basis optimiser (covered by BAS1 above; this is the CRYSTAL keyword).
CBAS8 GHOSTS — ghost-atom basis-functions for counterpoise / mid-bond functions. Pairs with BSSE1.

CRYSTAL calculation-type + SCF knobs¶

CALC1 OPTGEOM block options — full geometry- optimisation control surface (constraints, line-search variants, redundant internals, Hessian update schemes). Pairs with the v0.7 geometry-opt phase.
CALC2 FREQCALC block — frequency-calculation knobs (numerical-derivative step size, mode-by-mode integration, partial Hessian by atom selection).
CALC3 EOS block — built-in volume scan + EOS fit (covered by EOS2 above; this is the CRYSTAL block).
CALC4 QHA block — quasi-harmonic thermo workflow (covered by QHA1).
CALC5 ELASTCON with AWESOME — automatic-strain elastic-constant determination via the AWESOME-code symmetry analyser. Pairs with the existing ELASTCON entry.
CALC6 PIEZOCON / PHOTOELA — piezoelectric and photoelastic tensor calculation blocks (covered in the existing Berry-phase / properties roadmap; this names the CRYSTAL-side trigger).
CALC7 CPHF block — coupled-perturbed HF for response properties. Pairs with the post-1.0 response- theory roadmap.
CALC8 CONFCNT / CONFRAND / RUNCONFS (covered by SS1 / SS2 / SS3 above; this is the keyword cross-ref).
CALC9 SCF settings — SPINLOCK, LEVSHIFT, BROYDEN, ANDERSON, ATOMSPIN. Most are covered by vibe-qc’s existing SCF options; audit for missing Anderson / Broyden mixing.
CALC10 TWOCOMPON / SOC — 2-component SCF with spin-orbit coupling. Pairs with the existing X2C / DKH relativistic roadmap.

CRYSTAL properties keywords (extends v0.22)¶

CRYSTAL’s properties step is its post-SCF analysis layer (separate executable in CRYSTAL; one vq.properties module in the natural vibe-qc analogue).

PROP1 NEWK — k-mesh densification post-SCF for property evaluation. Pairs with the existing k-point story.
PROP2 COMMENS / NOSYMADA / PATO / PBAN / PGEOMW / PDIDE / PSCF / RDFMWF — properties-step control flags (commensurate, suppress symmetry- adaptation, project to atomic, project to band, geometry weights, projected DOS, project SCF, read formatted wavefunction). Most are flags on existing analysis functions.
PROP3 ADFT / ACOR (covered by CORR1 above).
PROP4 BAND — band-structure plotter along k-paths. Already in v0.22; this is the CRYSTAL keyword.
PROP5 BIDIERD — directional Compton profile (covered by XRD2 above).
PROP6 CLAS — classical (Madelung) potential at selected points; useful for embedded-cluster QM/MM setup (pairs with EMB1).
PROP7 ECHG / ECH3 — charge-density 2D / 3D cube output. Already in v0.22.
PROP8 EDFT (covered by CORR1).
PROP9 EMDLDM / EMDPDM — electron-momentum density on density-matrix (covered by EMD1 above; these are the explicit CRYSTAL flags).
PROP10 HIRSHCHG — Hirshfeld charges (covered by PR1 in v0.22).
PROP11 KINETEMD — kinetic-energy density / EMD on the same grid. Useful for non-covalent index post- processing.
PROP12 PMP2 — periodic-MP2 single-point on the converged SCF (covered in the existing periodic-MP2 roadmap).
PROP13 POLI — Mulliken-style population analysis on a periodic system.
PROP14 POTM / POT3 / POTC — electrostatic potential 2D / 3D / classical-only cube output.
PROP15 PPAN — projected population-analysis printout.
PROP16 XFAC (covered by XRD1).
PROP17 BOLTZTRA — Boltzmann-transport coefficients (Seebeck, electrical / thermal conductivity) from the band structure. Pairs with the post-1.0 transport story.
PROP18 ANISOTRO / ISOTROPIC — anisotropic / isotropic hyperfine coupling tensors (pairs with EPR in v0.12).
PROP19 POLSPIN / SPINCNTM (covered by DIAG2 above).
PROP20 ANBD / BWIDTH / DOSS — band-by-band analysis, bandwidth printout, density-of-states.
PROP21 EMDL / EMDP / PROF — line / plane / profile EMD output formats (covered by EMD1).
PROP22 COOP / COHP (covered by BOND1 / BOND2).
PROP23 SPOLBP / SPOLWF (covered by POL1 / POL2).
PROP24 LOCALWF — Wannier-localisation post- processing (covered in the post-1.0 Wannier story).
PROP25 DIEL — frequency-dependent dielectric function. Pairs with v0.12 spectroscopy.
PROP26 ISO + POTC — isotropic + classical potential printout for QM/MM coupling.
PROP27 TOPO — topology of the electron density (covered by TOOL1 / TOPOND below).
PROP28 ATOMIRR / CRYAPI_OUT / FMWF / INFOGUI / XML — output-format selectors (irreducible atoms, CRYSTAL Python API output, formatted wavefunction, GUI metadata, XML). Pairs with the IO bucket.

CRYSTAL post-processing utilities¶

CTOOL1 MOLDRAW / COORPRT — geometry-export formats (covered by CGEO16).
CTOOL2 crysplot — built-in matplotlib-style plotter for CRYSTAL output. vibe-qc has tutorial-level plotting helpers; this entry pins a unified vq.plot.crystal_style(...) namespace.
CTOOL3 cryapi_inp — programmatic input-builder Python module; mirrors vibe-qc’s existing input-builder ergonomics.
CTOOL4 TOPOND module — full QTAIM topology / basin-integration (covered by TOOL1).
CTOOL5 runcry06 / runprop06 — wrapper scripts for chained SCF + properties. Compound covers this (CMP1).
CTOOL6 AWESOME-code coupling — symmetry-aware strain / Hessian post-processing. Pairs with CALC5.

CRYSTAL job-control + parallelism¶

CRYSTAL ships five executables for different parallel models (Pcrystal, MPPcrystal, crystalOMP, PcrystalOMP, MPPcrystalOMP). vibe-qc has a single executable + OpenMP + optional MPI; the items below cover the operational knobs.

PAR1 Document the replicated-data vs distributed-data modes — replicated (each rank holds full Fock / density; cheap on small systems) vs distributed (ScaLAPACK; needed for large systems). Pairs with the v0.5.x performance docs.
PAR2 ScaLAPACK distributed Fock diagonalisation — for systems where the dense Fock exceeds per-rank memory. v0.7 / v0.8 territory.
PAR3 Dual-level parallelism (MPI × OpenMP) tuning guide — when to bias toward MPI vs OMP. Pairs with the perf-knob scaling scan in examples/debug/.
PAR4 Defaults audit — match MPPcrystal’s default knob settings on equivalent vibe-qc invocations as a sanity reference.
PAR5 REPLDATA flag — explicit replicated-data selector for benchmarking against distributed mode.
PAR6 OMP_NUM_THREADS / MKL_DEBUG_CPU_TYPE cookbook entries in installation.md — already partly there; expand the recommendations for AMD CPUs (the MKL_DEBUG_CPU_TYPE=5 workaround).
PAR7 Memory knobs — BIPOSIZE (bielectronic- integral buffer), EXCHSIZE (exchange buffer), LOWMEM (memory-conservative path), CHUNKS (integral chunking). Pairs with the existing LatticeOptions.cutoff_bohr knob; surface a MemoryOptions struct.

CRYSTAL ecosystem tools beyond the main exec¶

CECO1 Cryscor interface — periodic-MP2 / periodic-CCSD post-processor. Pairs with the existing periodic-MP2 roadmap.
CECO2 Pproperties — the parallel properties executable. Mirrored by parallelising vibe-qc’s property step.
CECO3 INPUT keyword — universal escape hatch in CRYSTAL input that includes another file. The Python API equivalent is just **kwargs forwarding; document the pattern.
CECO4 Migration appendices — CRYSTAL ships detailed migration notes between major versions. Pin a MIGRATION.md doc that does the same for vibe-qc (currently we have CHANGELOG.md but no migration narrative).
CECO5 Appendix D — formal file-formats list (every on-disk format CRYSTAL reads / writes). Pairs with the docs/file_formats.md from IO3.

The second-pass total is roughly 95 items spanning ~12 themes. Themes 1-4 (Compound, AutoCI, IO, MD/ESD) are the “workflow infrastructure” story — most of the C++ work is already done; this is API-shape design + Python plumbing. Themes 5-7 (orca_*, spectroscopy, density exports) flesh out post-processing. Themes 8-12 (CRYSTAL geom / basis / calc / props / parallelism / ecosystem) are the solid- state-side counterparts. Combined with the first-sweep ~70 items, the cross-code feature gap is ~165 items total. This is a multi-year backlog at current cadence; prioritisation will come from user requests, not from ticking off the manuals top-to-bottom.

Long-term documentation goal — the Lecture Series¶

A multi-year goal beyond the existing tutorial set: an educational tour through computational chemistry, structured as a lecture series, that introduces every concept from first principles and uses vibe-qc as the running “lab notebook.” The current 25 tutorials are task-oriented (“how do I run an open-shell DFT calculation?”); the lecture series is concept-oriented (“what is exchange-correlation, why does the Kohn-Sham mapping work, and what does PBE actually parameterize?”). They complement each other rather than overlap.

Audience. Graduate students in chemistry / physics / materials science, advanced undergraduates with a quantum-mechanics background, researchers from adjacent fields (computational biology, materials informatics, ML+chem) who need a working understanding of what an electronic-structure code is doing under the hood — not just how to drive one.

Differentiation from existing material. Textbooks (Szabo-Ostlund, Helgaker-Jørgensen-Olsen, Martin) are excellent but offer no runnable code. Online courses (TCCM-EJD, MolSSI BootCamps) are good introductions but don’t go deep enough on solid-state. CRYSTAL / ORCA / Gaussian have manuals, not curricula. The lecture series fills the “I want to understand what’s happening when I press SCF, with code I can run alongside” gap.

Indicative outline (subject to revision when we actually start writing — currently a backlog item, not a committed structure):

Why electronic structure? — what we’re computing and why, Born-Oppenheimer, the many-body problem
Hartree-Fock from scratch — Slater determinants, antisymmetry, Roothaan-Hall, SCF as a fixed-point iteration
Basis sets — Gaussians vs Slaters, contracted-Gaussian construction, polarization, diffuse functions, cc-pVxZ extrapolation
DFT and the Kohn-Sham mapping — Hohenberg-Kohn theorems, why non-interacting reference, exchange-correlation functionals, Jacob’s ladder
Numerical integration — Becke fuzzy partitioning, Lebedev quadrature, the radial grid choice
Open shells — UHF / ROHF / spin contamination / why DFT often “does the right thing” anyway
Periodic systems — Bloch’s theorem, k-points, Brillouin zone, density of states
The Coulomb problem in 3D — why the periodic Madelung sum is conditionally convergent, Ewald decomposition, ω-invariance
Tight-cell pathologies — what breaks when atoms are close, periodic Becke partition, level shifts, smearing for metals
Symmetry exploitation — space groups, Bloch sums symmetrized over the little group, IBZ k-mesh reduction
Beyond the mean field — MP2, coupled cluster, the CC hierarchy
Local correlation methods — DLPNO, RI / density fitting, why they make canonical CCSD(T) usable
Periodic correlation — CRYSCOR, periodic local CC, the cyclic cluster model

Each lecture is ~30–45 minutes of reading + 15 minutes of running the embedded vibe-qc examples. The reader leaves with both the theory and a working examples/lecture_NN_*.py they can modify.

Cadence. This is a multi-year project, not a v0.5 deliverable. A reasonable starting target is one lecture per quarter (so the full curriculum lands roughly aligned with v1.0). Earlier lectures benefit from earlier publication — we don’t need to write them in order.

Status: queued, not started. The existing 25 tutorials and 15 theory sections are prerequisites — they cover the “lab notebook” side and the equation references the lectures will lean on.

Upstream feature requests¶

These are features we’d like to see in external tools that vibe-qc users rely on. Tracked here so we don’t lose them; cross- referenced from the relevant docs page so users discover the limitation + the upstream issue together.

Tool	Feature	Why it matters	Status
MolTUI	Periodic / crystalline-orbital support — read lattice vectors from CUBE (or new periodic format), render unit-cell box, replicate atoms across PBC, optionally support k-labeled Bloch orbitals	Lets users SSH into a remote machine + triage a periodic-SCF result the same way they triage a molecular one. Currently MolTUI is molecular-only; periodic users have to drop to VESTA / XCrySDen / matplotlib plots.	proposed; track at github.com/kszenes/moltui
MolTUI	Vibe-qc’s `.molden` extension for vibrational data — confirm round-trip reading	Lets users view normal modes via `moltui my.molden`; works in principle since MolTUI parses the `[FREQ]` block. Engineering tracks the round-trip test.	needs verification once vibe-qc Hessian → molden is in CI
ASE	First-class PySCF wrapper in `ase.calculators.pyscf`	Today third-party `ase-pyscf` exists but isn’t pinned. Vibe-qc previously shipped an in-process `vibeqc.benchmark.PySCFCalculator` shim; retired in 6910ce5d per CLAUDE.md § 10 (no in-process imports of external QC programs under `python/vibeqc/`). PySCF parity now runs out-of-process via `examples/regression/core/runner_pyscf.py`; an upstream `ase.calculators.pyscf` would still be useful for ad-hoc user-side ASE-style scripting.	low priority — subprocess runner already covers the cross-code-parity use case

Licensing + redistribution¶

vibe-qc is MPL 2.0; the linked-library and bundled-data licensing inventory is at docs/license.md. Two roadmap items address known caveats in that inventory:

`v0.x.x` — FFT backend abstraction (commercial-friendly binaries)¶

vibe-qc currently dynamic-links FFTW3 (GPL v2 or later) for the FFT-Poisson reciprocal-space Hartree solver. The combined binary is therefore effectively GPL v2 when redistributed — fine for academic users running their own data, restrictive for anyone wanting to embed vibe-qc in a closed-source product or ship a non-GPL precompiled distribution.

Plan: add a CMake build-time option VIBEQC_FFT_BACKEND={fftw3, pocketfft, kissfft} and abstract the four FFTW3 calls in cpp/src/fft_poisson.cpp behind a thin internal interface. Default stays FFTW3 (best performance). pocketfft (BSD 3-Clause) and KissFFT (BSD 3-Clause) cover the GPL-free binary distribution case. Estimated effort: ~1 day for the abstraction + parity tests on the 3D-periodic SCF benchmarks. Tracked as post-v1.0 since no current user has flagged it as blocking; surface here so the intent is visible.

`v0.x.x` — On-demand BSE basis fetcher (replaces 87-set bundle on basissetdev)¶

The basissetdev long-lived branch carries 87 basis sets fetched directly from the Basis Set Exchange (pcseg-N, dhf-, x2c-, vDZP, full LANL family, ANO-RCC-V*, ANO-R0..3, Sadlej, pcS, Sapporo, Cologne SARC DKH, etc.). These are NOT shipped in v0.8.0 per the user’s standing rule that basissetdev stays a paper-writing branch and does not merge into main.

When basissetdev does eventually merge, the architectural decision is to not bundle the 87 BSE sets directly — and instead add a vibeqc.basis.fetch_from_bse(name) helper modeled on vqfetch:

Bases pulled from BSE on first use, cached locally (~/.cache/vibeqc/basis/) per XDG.
Per-basis-set citation surfaced in the SCF log + recorded in the per-run .system manifest.
Wheel size unaffected (~half the size compared to bundling 236 .g94 files).
Avoids any per-basis-set redistribution clearance question for sets whose original publishers might prefer not to be bundled in third-party software (BSE itself doesn’t make a per-record license claim, so the conservative path is fetch-on-demand rather than bundle-and-hope).

Estimated effort: ~half-day; mirrors the existing vqfetch plumbing closely. Gates on the basissetdev merge timing (which is itself gated on Mike’s standing rule per .release-status/v0.8.0/basissetdev.md).

What’s explicitly out of scope (before v1.0)¶

QM/MM and embedding — CCM itself is an embedding method for solids; other flavors deferred.
Coupled-cluster beyond CCSD(T) — CCSDT, CCSDTQ, FCIQMC are benchmark-scale tools outside normal production.
Non-adiabatic methods (CASSCF + SOC, surface hopping) — excited states are covered through TDDFT / NEVPT2 for practical ground-state work.
Relativistic methods (DKH, X2C, spin-orbit coupling) — important for heavy-element chemistry, but a specialised stack of its own. Tracked as a post-1.0 follow-on; ECPs (Phase 14) cover most heavy- element chemistry without it.
MPI parallelism — single-node OpenMP first; cross-node MPI is a scaling concern, not a capability gap.

These aren’t ruled out forever — they’re simply not prerequisites for a “standard QC program” per v1.0’s scope, nor for CCM in v2.0.

Previously listed as out of scope, now in scope after the parity audit:

Dispersion corrections (DFT-D3, DFT-D4) — too central to defensible DFT to omit. Now Phase D1/D2 in v0.5.0.
Implicit solvation (CPCM/COSMO) — too central to organic / aqueous chemistry to omit. Now Phase S1 in v0.5.0.

Roadmap¶

Milestones¶

v0.1.0 — shipped 2026-04-18¶

v0.2.0 — quantitative 3D bulk¶

Concurrent infrastructure shipped in 0.2.x¶

v0.2.5 — space-group symmetry exploitation (core)¶

v0.3.0 — visualization + post-SCF properties¶

v0.4.0 — shipped 2026-04-27 — heavy elements + open-shell periodic + tight-cell SCF¶

v0.5.0 — molecular Hessian + full k-point sampling¶

Molecular Hessian (Phase 17)¶

K-Phase — full k-point sampling support¶

Other v0.5 deliverables¶

v0.5.x — observability patch series¶

Acceleration program (multi-release)¶

v0.5.5 — Cauchy-Schwarz screening (foundation, shipped)¶

v0.10.0 — ✅ shipped — multi-k Fock-call coalescing (small, near-free win)¶

v0.11.x — 🎯 queued — finer-grained auto_optimize_truncation step¶

v0.6.x — separate exchange threshold + gradient screening¶

v0.7.x — RI / density fitting + RIJ-COSX (1st acceleration wave)¶

v0.11.x — 🚧 partial — fast multipole methods (long-range Coulomb)¶

v0.12.0 — 🎯 queued — locality exploitation (hybrid DFT for big cells)¶

v0.10.x — 🎯 queued — reciprocal-space and basis tricks¶

v1.x — algorithmic and hardware acceleration¶

Beyond SCF — local correlation methods¶

SCF convergence accelerators (mostly at v0.5.x scope)¶

Prioritisation summary¶

SCF guess + convergence program (multi-release)¶

v0.6.x — initial-guess overhaul (flagship: SAD + SAP)¶

v0.7.x — DIIS family expansion (flagship: EDIIS+DIIS hybrid)¶

v0.8.0 — ✅ shipped — second-order convergence (flagship: SOSCF / TRAH)¶

v0.10.x — 🎯 queued — multi-secant / quasi-Newton SCF acceleration (Anderson + Broyden)¶

v0.x.x — SCF diagnostics: “possibly conducting state” warning¶

v0.12.0 — 🎯 queued — direct minimisation for big solids (flagship: OT)¶

v0.10.x — 🎯 queued — density mixing for periodic metals (flagship: Anderson + Kerker + Pulay-Kerker)¶

Post-dimensional-method SCF parity agenda¶

Recommended workflows by system¶

Key reference list (initial guess + convergence)¶

v0.6.0 — periodic atomic gradients — Pulay’s Owl¶

v0.6.x — molecular ORCA parity (sibling validation track)¶

v0.7.0 — periodic SCF correctness + PySCF.pbc parity¶

Phase 1 — PySCF.pbc parity (port their gauge convention)¶

Phase 2 — PySCF parity test set¶

Phase 3 — CRYSTAL-style speedups¶

Stress + slab — moved to v0.8¶

v0.x.x — periodic stress tensor + slab builder¶

v0.x.x — phonons¶

v0.8.0 — shipped 2026-05-17 — basis-set library expansion¶

v0.8.0 — shipped 2026-05-17 — XC functional library expansion¶

v0.8.0 — shipped 2026-05-17 — molecular methods polish (RIJCOSX + JKBuilder + B3LYP-VWN5)¶

v0.8.0 — periodic SCF chain (restricted HF/DFT, all Bravais, no-fit + DF + RIJCOSX)¶

v0.8.0 — shipped 2026-05-17 — basis-set library + ECP integration completion¶

v0.8.0 — vq queue v0.4 (web UI + cgroups v2 enforcement)¶

v0.8.0 — shipped 2026-05-17 — vqfetch external-data integration (Phase 1: structures)¶

v0.8.x — native molecular geometry optimizer (shipped)¶

v0.9.0 — ✅ shipped — composite “3c” methods stack¶

v0.9.x — ✅ shipped — semiempirical platform (3 families, 7 methods)¶

v0.x.x — 🚧 in progress — MACE machine-learning interatomic potential (MLIP) interface¶

v0.9.0 — 🚧 partial — implicit solvation¶

v0.9.0 — ✅ shipped — DFT+U (Dudarev rotationally-invariant)¶

v0.10.0 — ✅ shipped — Grimme D4 dispersion¶

v0.11.0 — periodic GDF chain (compcell + multi-k + AFT)¶

v0.12.0 — personal job queue + cluster-bridge docs¶

v0.13.0 — Generalised Regular k-grids + geometry symmetrize¶

Wavefunction-method ladder — coverage map¶

v0.14.0 — canonical CCSD(T)¶

v0.15.0 — approximate coupled cluster (CC2 + CC3)¶

v0.16.0 — equation-of-motion coupled cluster (excited states)¶

v0.17.0 — reduced-cost coupled cluster (FNO + DLPNO-CCSD(T))¶

v0.18.0 — higher-order coupled cluster¶

v0.19.0 — periodic correlation¶

v0.20.0 — periodic coupled cluster¶

v0.21.0 — multireference + excited states¶

v0.22.0 — properties suite¶

v1.0.0 — feature complete¶

v2.0.0 — HF-CCM (cyclic-cluster-model foundation)¶

v2.1.0 — density fitting in CCM (at HF)¶

v2.2.0 — MP2-CCM¶

v2.3.0 — orbital localization in CCM¶

v2.4.0 — local MP2-CCM (DLPNO or PAO)¶

v2.5.0 — CCSD-CCM (canonical, non-local)¶

`v0.1.0` — shipped 2026-04-18¶

`v0.2.0` — quantitative 3D bulk¶

`v0.2.5` — space-group symmetry exploitation (core)¶

`v0.3.0` — visualization + post-SCF properties¶

`v0.4.0` — shipped 2026-04-27 — heavy elements + open-shell periodic + tight-cell SCF¶

`v0.5.0` — molecular Hessian + full k-point sampling¶

`v0.5.x` — observability patch series¶

`v0.5.5` — Cauchy-Schwarz screening (foundation, shipped)¶

`v0.10.0` — ✅ shipped — multi-k Fock-call coalescing (small, near-free win)¶

`v0.11.x` — 🎯 queued — finer-grained `auto_optimize_truncation` step¶

`v0.6.x` — separate exchange threshold + gradient screening¶

`v0.7.x` — RI / density fitting + RIJ-COSX (1st acceleration wave)¶

`v0.11.x` — 🚧 partial — fast multipole methods (long-range Coulomb)¶

`v0.12.0` — 🎯 queued — locality exploitation (hybrid DFT for big cells)¶

`v0.10.x` — 🎯 queued — reciprocal-space and basis tricks¶

`v1.x` — algorithmic and hardware acceleration¶

`v0.6.x` — initial-guess overhaul (flagship: SAD + SAP)¶

`v0.7.x` — DIIS family expansion (flagship: EDIIS+DIIS hybrid)¶

`v0.8.0` — ✅ shipped — second-order convergence (flagship: SOSCF / TRAH)¶

`v0.10.x` — 🎯 queued — multi-secant / quasi-Newton SCF acceleration (Anderson + Broyden)¶

`v0.x.x` — SCF diagnostics: “possibly conducting state” warning¶

`v0.12.0` — 🎯 queued — direct minimisation for big solids (flagship: OT)¶

`v0.10.x` — 🎯 queued — density mixing for periodic metals (flagship: Anderson + Kerker + Pulay-Kerker)¶

`v0.6.0` — periodic atomic gradients — Pulay’s Owl¶

`v0.6.x` — molecular ORCA parity (sibling validation track)¶

`v0.7.0` — periodic SCF correctness + PySCF.pbc parity¶

`v0.x.x` — periodic stress tensor + slab builder¶

`v0.x.x` — phonons¶

`v0.8.0` — shipped 2026-05-17 — basis-set library expansion¶

`v0.8.0` — shipped 2026-05-17 — XC functional library expansion¶

`v0.8.0` — shipped 2026-05-17 — molecular methods polish (RIJCOSX + JKBuilder + B3LYP-VWN5)¶

`v0.8.0` — periodic SCF chain (restricted HF/DFT, all Bravais, no-fit + DF + RIJCOSX)¶

`v0.8.0` — shipped 2026-05-17 — basis-set library + ECP integration completion¶

`v0.8.0` — vq queue v0.4 (web UI + cgroups v2 enforcement)¶

`v0.8.0` — shipped 2026-05-17 — `vqfetch` external-data integration (Phase 1: structures)¶

`v0.8.x` — native molecular geometry optimizer (shipped)¶

`v0.9.0` — ✅ shipped — composite “3c” methods stack¶

`v0.9.x` — ✅ shipped — semiempirical platform (3 families, 7 methods)¶

`v0.x.x` — 🚧 in progress — MACE machine-learning interatomic potential (MLIP) interface¶

`v0.9.0` — 🚧 partial — implicit solvation¶

`v0.9.0` — ✅ shipped — DFT+U (Dudarev rotationally-invariant)¶

`v0.10.0` — ✅ shipped — Grimme D4 dispersion¶

`v0.11.0` — periodic GDF chain (compcell + multi-k + AFT)¶

`v0.12.0` — personal job queue + cluster-bridge docs¶

`v0.13.0` — Generalised Regular k-grids + geometry symmetrize¶

`v0.14.0` — canonical CCSD(T)¶

`v0.15.0` — approximate coupled cluster (CC2 + CC3)¶

`v0.16.0` — equation-of-motion coupled cluster (excited states)¶

`v0.17.0` — reduced-cost coupled cluster (FNO + DLPNO-CCSD(T))¶

`v0.18.0` — higher-order coupled cluster¶

`v0.19.0` — periodic correlation¶

`v0.20.0` — periodic coupled cluster¶

`v0.21.0` — multireference + excited states¶

`v0.22.0` — properties suite¶

`v1.0.0` — feature complete¶

`v2.0.0` — HF-CCM (cyclic-cluster-model foundation)¶

`v2.1.0` — density fitting in CCM (at HF)¶

`v2.2.0` — MP2-CCM¶

`v2.3.0` — orbital localization in CCM¶

`v2.4.0` — local MP2-CCM (DLPNO or PAO)¶

`v2.5.0` — CCSD-CCM (canonical, non-local)¶

`v2.6.0` — local CCSD-CCM¶

`v2.7.0` — (T) perturbative triples → CCSD(T)-CCM¶

`v2.8.0` — projection-based embedding¶

`v0.9.x` — module consolidation (deferred)¶

`v0.9.x` (or later) — OPTBASIS-style basis optimiser (deferred)¶

`v0.x.x` — FFT backend abstraction (commercial-friendly binaries)¶

`v0.x.x` — On-demand BSE basis fetcher (replaces 87-set bundle on basissetdev)¶