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 across hot kernels (overlap, kinetic, nuclear, ERI, gradient, Fock build, XC grid integration). Engine-per-thread + thread-local accumulator pattern.
✅ 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 driver. PeriodicRHFOptions.smearing_temperature / PeriodicSCFOptions.smearing_temperature / PeriodicKSOptions.smearing_temperature (Hartree, default 0.0). 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 PeriodicRHFMultiKEwaldResult carries 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 only — molecular RHF/UHF/RKS/UKS smearing is a follow-up; periodic UKS smearing lands with Phase 15.
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).

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, dk_2pi_per_A) (Materials Project / ASE); KPoints.auto(sys, length_A) (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 moves to v0.11 alongside the geometry-symmetrize pipeline.

`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.7
Phonons (Phase 21)	v0.8
Implicit solvation (S1)	v0.9
Grimme D4 dispersion (D2)	v0.10
Geometry-symmetrize pipeline (GS) + DOC1-full	v0.11
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.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.8.x` — fast multipole methods (long-range Coulomb)¶

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.9.x` — locality exploitation (hybrid DFT for big cells)¶

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` — reciprocal-space and basis tricks¶

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.15+:

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.7.x
Guess	MINAO (minimal-AO projection of SAD)	v0.7.x
Guess	FRAGMO (fragment-MO assembly)	v0.8.x
Guess	READ / restart (orbitals from prior calc)	v0.8.x
Guess	Broken-symmetry (high-spin → GUESSMIX → 45° rotation)	v0.7.x
Guess	Manual atomic occupation override (CRYSTAL-style)	v0.6.x
Conv	Linear damping	shipped
Conv	Dynamic damping (Zerner–Hehenberger 1979)	v0.6.x
Conv	Pulay DIIS	shipped
Conv	EDIIS (Kudin / Scuseria / Cancès 2002)	v0.7.x
Conv	ADIIS (Hu / Yang 2010); EDIIS+DIIS hybrid	v0.7.x
Conv	LIST family / ODA (Cancès & Le Bris 2000)	v0.7.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)	v0.8.x flagship
Conv	Augmented Hessian / TRAH (Helmich-Paris 2022)	v0.8.x
Conv	ARH (Host et al. 2008) / CIAH (Sun, PySCF 2017)	v0.8.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 — extend at v0.10.x

`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.
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.
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.
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.
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.x` — second-order convergence (flagship: SOSCF / TRAH)¶

🎯 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.
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.
D2c SOSCF strict (Bacskay 1981, Fischer & Almlöf, J. Phys. Chem. 96, 9768 (1992)) — full orbital Hessian, exact Newton step.
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. Critical for CASSCF / state-averaged variants.
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.9.x` — direct minimisation for big solids (flagship: OT)¶

🎯 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` — density mixing for periodic metals (flagship: Anderson + Kerker + Pulay-Kerker)¶

🎯 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.

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 bumped to v0.8.

🎯 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	FFT Poisson on triclinic cells (long-range)

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.8.0` — periodic stress tensor + slab builder¶

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.8.0` — phonons¶

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.9.0` — implicit solvation¶

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

🎯 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.10.0` — Grimme D4 dispersion¶

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

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

D2a Charge-dependent c6ab table + parameter set (Caldeweyher 2019).
D2b Hirshfeld atomic charges from the SCF density.
D2c D4 energy + gradient + stress.
D2d dftd4 reference Python backend as optional dep (mirrors the D1b pattern).

`v0.11.0` — geometry symmetrize + full reference outputs¶

Codename TBD (candidate: Wyckoff’s Mole, Hermann’s Pangolin).

🎯 Headline feature — vq.symmetrise(system, symprec) snaps imperfect input cells to the nearest perfect symmetry, refining the lattice. Critical for making large calculations feasible: the SYM2b orbit-compression machinery requires symmorphic + origin-fixed atoms, which a typical user input rarely has out of the box.

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.
DOC1-full bundled reference outputs across the entire documentation — the original DOC1 scope. Ships .out / .molden / .cube / .traj artefacts for every numbered tutorial under docs/_static/examples/<name>/, with a 30-line excerpt inline + download link in each tutorial.

`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¶

Codename TBD (candidates: Wisesa’s Fox, Mueller’s Marten).

🎯 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.

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 min- distance for the given target k-count.
Critical for making metallic systems and large-cell defects feasible — the user-emphasised motivation when this milestone was first proposed. .molden / .cube / .traj as binary so git diff doesn’t try to render them.

Resolved scope decisions:
- Periodic centerpiece — bundle both LiH bulk and H-chain. They answer different questions (“does periodic HF work for an insulator?” vs. “for a 1D metal?”) and the marginal storage cost is negligible (~30 KB of .out text combined).
- Cube screenshots via vmd -dispdev text -e render.tcl. Avogadro is interactive-only and not reproducible; ChimeraX is heavyweight; VMD scripts cleanly from a .tcl file that lives alongside the cube. The regen script invokes VMD headlessly. Each cube subdirectory carries its own render.tcl so screenshots are reproducible from the repo state.
- Regeneration discipline — trust manual pre-tag step, no CI verification at v0.5.0. Cheaper to ship the discipline first (regen on the tagged commit, eyeball the diff, commit) than to harden a CI job that re-runs every canonical calculation on every push. Revisit post-1.0 if output-vs-code drift becomes a recurring problem.
Total static-asset budget ≈ 8.5 MB (15 .out × 15 KB + 8 .molden × 50 KB + 4 .cube × 1.5 MB + 9 new .png × 200 KB + smaller artefacts). Five-day spread across the cycle: (1) script + storage skeleton + .gitattributes, (2) Level-1 outputs (4 calcs) + gallery page + quickstart inline, (3) remaining text outputs (10 more calcs), (4) cube + render.tcl + headless VMD screenshots (2 calcs), (5) tutorial-by-tutorial integration (25 tutorials × 30-line excerpt + download link), (6) release-process doc update + final size verification. Closes the recurring “I have no idea what a converged vibe-qc output looks like” gap that nothing in the v0.4 docs answers.

`v0.14.0` — density fitting + canonical CCSD(T)¶

Codename TBD (candidates: Pople’s Eagle, Bartlett’s Goose). 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.

Density fitting (DF, also “resolution of the identity” / RI) is vibe-qc’s biggest single performance multiplier short of new hardware. The canonical four-index ERI is the formal O(N⁴) bottleneck of every HF / KS calculation; replacing it with a three-index ERI on an auxiliary basis is the standard ORCA / PySCF acceleration that turns hybrid DFT and MP2 from “small molecules only” into “routine on > 50 atoms”.

The five sub-phases below are ordered for incremental impact — each one builds on the previous and is independently shippable.

Sub-phase	Speedup target	Notes
20a RI-J — molecular pure DFT	~5× on the Coulomb build, neutral on accuracy	Easy first sub-phase. Establishes the auxiliary-basis plumbing (def2-J, def2-JK, cc-pVnZ-RIJK loaders), the three-index `(P\|μν)` integral kernel, and the J-build contraction. PBE / BLYP / LDA on small-and-medium molecules immediately benefit.
20b RIJCOSX / RI-K — molecular hybrid DFT	~10× on B3LYP / PBE0	Bigger code, high impact. Adds the chain-of-spheres (COSX) numerical exchange and the proper RI-K formulation. Turns hybrid DFT (B3LYP, PBE0, ωB97X-D, M06-2X) from “expensive” into “routine”. Default COSX grids give ~10 µHa loss on neutral organics — within the noise of every other approximation in DFT. Validates against ORCA (which ships RIJCOSX as the default for hybrids).
20c RI-MP2 — molecular	makes MP2 usable for > 50 atoms	Mostly “different contraction order” once 20a + 20b ship the three-index machinery. `(ia\|jb) = Σ_P (ia\|P) · (P\|jb)` with the same auxiliary basis, then the standard energy expression. Prerequisite for DLPNO (v0.7.0).
20d RI-J — periodic	~5× on the multi-k Coulomb build	Lattice-summed three-index ERIs `(P_h\|μν_g)`. Same speedup ratio as 20a but on the periodic side; biggest near-term win on multi-k pure DFT. Reuses the auxiliary-basis loaders from 20a; the new code is the lattice sum on the three-center integrals.
20e RI-K — periodic	the real prize for periodic hybrids	Hardest sub-phase. The v0.4.0 multi-k Ewald hybrid path is O(N²·k) per Fock build, which is what gates hybrid bulk DFT on real crystals. RI-K (or a periodic COSX) brings this down to O(N·k log k)-ish; once it lands, hybrid DFT on TM oxides, perovskites, etc. becomes practical. Validates against CRYSTAL’s GUESSP / EXCHSIZE machinery.

Plus, gated on RI-MP2 (20c):

24a-c canonical CCSD(T) — gold-standard molecular correlation. Benchmarkable against NWChem / Psi4 for small systems.

`v0.15.0` — DLPNO-CCSD(T)¶

Codename TBD (strong candidate: Neese’s Cheetah — Frank Neese made DLPNO fast). Renumbered through v0.7 → v0.16 → v0.15.

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”).

24d-h DLPNO-CCSD(T) — near-linear-scaling CCSD(T) accurate to ~1 kcal/mol vs canonical, production-grade correlation method.
24i open-shell DLPNO-UCCSD(T).

`v0.16.0` — periodic correlation¶

Codename TBD. Renumbered through v0.8 → v0.17 → v0.16.

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

`v0.17.0` — periodic coupled cluster¶

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

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

`v0.18.0` — multireference + excited states¶

Codename TBD. Renumbered through v0.10 → v0.19 → v0.18.

25a-c FCI solver, CASCI.
25d-e CASSCF with state-averaging.
25f NEVPT2 — multireference perturbation on CASSCF.
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).

`v0.19.0` — properties suite¶

Codename TBD. Renumbered through v0.11 → v0.20 → v0.19.

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.10. 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; LED in v0.7.0) 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) already shipped via v0.7.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.11 properties milestone where it belongs alongside the rest of the response-theory work.)

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

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.7.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.7.x maintenance release. Functionality won’t change; imports will get a nicer vq.basis_screening.* umbrella.

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

CRYSTAL’s OPTBASIS keyword (manual p. 65) optimises a basis set’s exponents and contraction coefficients while penalising the condition number of the overlap matrix:

Ω({α,d}) = E_tot({α,d}) + γ · ln κ({α,d})

This steers the basis-optimiser away from regions of basis-function space that produce ill-conditioned overlap matrices — the cure is built into how the basis is constructed, not patched at run time.

Real piece of work: needs a basis-parameter optimiser, gradients of E and ln(κ) with respect to exponents (analytic or finite-difference), BDIIS or similar quasi-Newton outer loop. Ties into the broader basis- set development infrastructure (which doesn’t exist yet — vibe-qc ships fixed bases). Slot into v0.8.x or later; needs its own design pass.

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.

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.

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.6 (density fitting / RIJCOSX) that might be Frank Neese (RIJCOSX in ORCA) or Boys / Whitten / Dunlap (early density-fitting theory).
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.6.0 can be started in parallel with v0.3.0 / v0.4.0 because molecular correlation is independent of the periodic stack.
v0.7.0 needs v0.6.0.
v0.8.0 needs v0.7.0 (shared DLPNO machinery applies to periodic).
v0.9.0 needs v0.8.0.
v0.10.0 needs v0.6.0.
v0.11.0 (properties suite) needs v0.5.0 (Phase 17 Hessian for Raman / VCD; Phase G2 stress for elastic / piezo / photoelastic), v0.9.0 (periodic CCSD if PR16–PR22 want correlated dielectric / Born), and v0.10.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.

Release codenames¶

Starting with v0.5.0, every minor release gets a Scientist + Animal codename. The scientist is loosely tied to whatever’s flagship in the release; the animal is random + cute. The current-release codename appears on the landing-page banner via Sphinx substitution; the catalog below is the source of truth.

Version	Codename	Why this scientist
v0.1.0	First Light	bootstrap tag; pre-codename era
v0.4.0	Schrödinger’s Llama	retroactive — v0.4 shipped “everything down to the ground state of a real solid”
v0.5.0	Wilson’s Otter	E. B. Wilson’s Molecular Vibrations (1955) — v0.5 ships forces + frequencies
v0.6.0	(TBD)	density fitting + canonical CCSD(T). Candidates: Whitten’s Wombat (Whitten 1973 — DF foundations), Coester’s Cobra (Coester-Kümmel CC), Almlöf’s Aardvark (direct SCF + DF).
v0.7.0	(TBD)	DLPNO-CCSD(T). Candidate: Neese’s Narwhal (Neese-group DLPNO authors)
v0.8.0	(TBD)	periodic correlation. Candidate: Pisani’s Panda (Pisani — CRYSCOR / periodic local CC)
v0.10.0	(TBD)	TDDFT + multireference. Candidate: Runge’s Raccoon (Runge-Gross TDDFT theorem)
v0.11.0	(TBD)	properties suite (NMR / ESR / CD / Born / dielectric / ELF / EDA). Candidate: Stone’s Sloth (A. J. Stone — molecular response properties)
v1.0.0	(TBD)	feature complete. Open call.
v2.0.0	(TBD)	CCM track lights up. Candidate: Bredow’s Beaver (Bredow + collaborators — original cyclic-cluster-model authors)

Patch releases inherit their parent minor’s codename — so v0.4.1 + v0.4.2 are also Schrödinger’s Llama. The codename only updates on minor-version bumps.

If a name doesn’t sit right when its release approaches, propose an alternative in the chat that’s cutting it. The table is a backlog, not a contract — names should be in good taste, vaguely on-theme, and amusing rather than self-serious.

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.

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; D4 queued at v0.10.0
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.11.0)
LED energy decomposition	❌	Needs DLPNO-CCSD(T) (v0.15.0); EDA variant PR26 (v0.11.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.11.0) — needs polarisability derivatives
UV/Vis (TDDFT)	❌	Phase T1 (v0.10.0) + PR28 spectrum reconstruction (v0.11.0)
ECD / VCD	❌	T1 + Phase PR29 (ECD) / PR14 (VCD) (v0.11.0)
NMR (GIAO)	❌	Phase PR10 (v0.11.0)
Spin-spin coupling (J)	❌	Phase PR11 (v0.11.0)
EPR / hyperfine	❌	Phase PR12 (v0.11.0); spin-orbit terms post-1.0
ESP charges (CHELPG / RESP)	❌	Phase PR3 (v0.11.0)
Hirshfeld / Bader / NBO	❌	Phases PR1 / PR2 / PR4 (v0.11.0)
Quadrupole / higher multipoles	❌	Phase PR5 (v0.11.0)
Polarisability / hyperpolarisability	❌	Phases PR8 / PR9 via CPHF substrate PR7 (v0.11.0)
ELF / NCI / RDG plots	❌	Phases PR23 / PR24 (v0.11.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) shipped; C1c (second-order SCF) pending for the hardest oscillating cases
SCF convergence tools	🟡	Damping + Pulay DIIS (default) + Saunders-Hillier level shift (C1a) + Fermi-Dirac smearing (C1b) all shipped; C1c (second-order SCF fallback) pending
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)
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
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; no dedicated tutorial yet
Magnetic systems	🟡	API shipped via Phase 15a (Γ-UHF) / 15b (multi-k UHF) / 15c-3 (Γ + multi-k UKS) — no dedicated tutorial yet
Metallic systems	🟡	C1b Fermi-Dirac smearing shipped (periodic Ewald RHF only — molecular + UKS smearing follow up); no dedicated tutorial yet
Metal/oxide interfaces	🟡	Phase 14a-c+e (ECPs) + C1a/C1b + Phase 15a/b/c shipped — only blocker remaining is 14d (CRYSTAL ECP-block parser); 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)	❌	Phase v0.8.0
4f-in-core ECPs	❌	Phase 14
Born effective charges	❌	Phase PR16 (v0.11.0)
Dielectric tensor (ε∞ / εstatic)	❌	Phases PR17 / PR18 (v0.11.0)
Elastic constants	❌	Phase PR19 (v0.11.0; needs G2 stress)
Piezoelectric tensor	❌	Phase PR20 (v0.11.0)
Photoelastic tensor	❌	Phase PR21 (v0.11.0)
Periodic IR / Raman intensities	❌	Phase PR22 (v0.11.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.11.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.18)¶

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.18 MR plans.
SPEC4 MCD (magnetic CD) on top of TDDFT (extends PR29 ECD in the v0.11 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.11.
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.11 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.18 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 PySCFCalculator / vibeqc ASE 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 v0.20+ 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.11 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.18 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.11)¶

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.11; 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.11.
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.11).
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; we ship a built-in shim in `vibeqc.benchmark.PySCFCalculator` to avoid the extra dep. An upstream wrapper would let us drop the shim.	low priority — our shim is small + maintained

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.6.x — separate exchange threshold + gradient screening¶

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

v0.8.x — fast multipole methods (long-range Coulomb)¶

v0.9.x — locality exploitation (hybrid DFT for big cells)¶

v0.10.x — 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.x — second-order convergence (flagship: SOSCF / TRAH)¶

v0.9.x — direct minimisation for big solids (flagship: OT)¶

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

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.8.0 — periodic stress tensor + slab builder¶

v0.8.0 — phonons¶

v0.9.0 — implicit solvation¶

v0.10.0 — Grimme D4 dispersion¶

v0.11.0 — geometry symmetrize + full reference outputs¶

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

v0.13.0 — Generalised Regular k-grids¶

v0.14.0 — density fitting + canonical CCSD(T)¶

v0.15.0 — DLPNO-CCSD(T)¶

v0.16.0 — periodic correlation¶

v0.17.0 — periodic coupled cluster¶

v0.18.0 — multireference + excited states¶

v0.19.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¶

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

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

v0.7.x — module consolidation (deferred)¶

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

Automated regression / parity test suite (separate chat)¶

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

Release codenames¶

Dependencies¶

Release codenames¶

Tutorial parity (ORCA + CRYSTAL)¶

ORCA — molecular chemistry¶

CRYSTAL — solid-state chemistry¶

ASE — workflow tutorials¶

Critical-path summary¶

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

Theory-layer roadmap¶

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

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

`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.6.x` — separate exchange threshold + gradient screening¶

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

`v0.8.x` — fast multipole methods (long-range Coulomb)¶

`v0.9.x` — locality exploitation (hybrid DFT for big cells)¶

`v0.10.x` — 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.x` — second-order convergence (flagship: SOSCF / TRAH)¶

`v0.9.x` — direct minimisation for big solids (flagship: OT)¶

`v0.10.x` — 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.8.0` — periodic stress tensor + slab builder¶

`v0.8.0` — phonons¶

`v0.9.0` — implicit solvation¶

`v0.10.0` — Grimme D4 dispersion¶

`v0.11.0` — geometry symmetrize + full reference outputs¶

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

`v0.13.0` — Generalised Regular k-grids¶

`v0.14.0` — density fitting + canonical CCSD(T)¶

`v0.15.0` — DLPNO-CCSD(T)¶

`v0.16.0` — periodic correlation¶

`v0.17.0` — periodic coupled cluster¶

`v0.18.0` — multireference + excited states¶

`v0.19.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.7.x` — module consolidation (deferred)¶

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