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 + Saunders–Dovesi multipolar splitting for the far field. Adds FFTW3 as a build dependency. After this, EWALD_3D end-to-end gives quantitative 3D bulk SCF.

• 12e-c-4 — end-to-end CoulombMethod.EWALD_3D SCF dispatch and CRYSTAL benchmark validation.

• 12f — periodic Becke weight partition for DFT integration in tight crystals.

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.

• ✅ 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.3.0 — visualisation + 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 (currently only molecular density is grid-evaluable in vibe-qc; needs a periodic AO evaluator with phase factors).

• V5b projected DOS (atom-projected, l-projected) — needs a Mulliken-like projector against the Bloch-summed overlap.

• 16 hybrid periodic DFT (PBE0, B3LYP) validated against CRYSTAL reference energies.

v0.4.0 — heavy elements + open-shell periodic + tight-cell SCF

This is the milestone that unblocks the bulk of the CRYSTAL “Modelling Specific Systems” tutorials. The SCF convergence work (Phase C1) is new in this round and was promoted to top of the queue after the ORCA/CRYSTAL parity audit — it’s the single biggest reason 2D / 3D periodic SCF currently oscillates on metallic and small-gap cells.

• C1a — level shifting for periodic and molecular SCF.

• C1b — Fermi–Dirac smearing + fractional occupations for metallic / small-gap systems. Required for any defensible metal / oxide / interface calculation. Carries an electronic-entropy contribution that flows through to free-energy reporting.

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

• 15 periodic UHF / UKS — open-shell periodic SCF for magnetic systems, defects, spin-polarised transition-metal compounds.

v0.5.0 — forces, vibrations, dispersion, solvation

The “molecular chemistry” milestone — turns vibe-qc from “computes energies” into “does chemistry.” Rebalanced after the ORCA tutorial audit: dispersion and implicit solvation moved in (previously “out of scope”), and the molecular Hessian was promoted as the single biggest force multiplier (unlocks frequencies, thermochemistry, TS search, IR intensities, KIE, VCD all at once).

• 17 molecular analytic Hessian → vibrational frequencies, IR intensities (dipole-derivative), thermochemistry (H, S, G).

• D1 Grimme D3-BJ dispersion correction — post-SCF add-on, promoted out of “out of scope” after parity audit. Defensible DFT on non-covalent systems (dimers, layered materials, MOFs, molecular crystals).

• D2 Grimme D4 dispersion correction.

• S1 implicit solvation (CPCM or COSMO, molecular). Aqueous chemistry is most users’ default.

• G1 periodic atomic gradients — geometry optimisation for surfaces, molecular crystals, defect cells. Unlocks the CRYSTAL “Geometry optimisation” tutorial line.

• G2 periodic stress tensor → cell-parameter optimisation + exact equation-of-state.

• 21 Γ-point and finite-displacement phonons (periodic Hessian via finite difference of G1 forces) → phonon dispersion + QHA thermodynamics.

• B1 slab / surface builder helper (thin wrapper over ase.build.surface), gated on C1 so the resulting SCFs converge.

v0.6.0 — density fitting + canonical CCSD(T)

• 20 density fitting / RI-MP2 — 5-10× speedup for DFT and MP2 via auxiliary basis sets. Prerequisite for DLPNO.

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

v0.7.0 — DLPNO-CCSD(T)

• 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.8.0 — periodic correlation

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

v0.9.0 — periodic coupled cluster

• Periodic canonical CCSD(T) for small unit cells.

• DLPNO-periodic-CCSD(T) as the scalable variant.

v0.10.0 — multireference + excited states

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

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

• Finite-field response (dielectric tensor, polarisability, Born effective charges) for the CRYSTAL response-properties tutorials.

• Miscellaneous bug fixes uncovered in the larger correlation / excited-state / periodic stacks.

v2.0.0 — cyclic cluster model

Phase 13: CCM + local CASCI on the embedded cluster. Benchmarked against the multi-k crystalline-orbital stack from v0.9.0. The headline feature of the project.

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.3.0 is independent of the remaining 12e-c work — visualisation is useful even before quantitative bulk SCF lands.

• v0.4.0 needs v0.2.0 for the Ewald infrastructure that tight-cell SCF will lean on.

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

• v1.0.0 sums everything above.

• v2.0.0 (CCM) builds on v1.0.

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 optimisation	✅	—
Charges (Mulliken, Löwdin)	✅	Phase 18
Bond analysis (Mayer)	✅	Phase 18
Dipole moment	✅	Phase 19
Vibrational frequencies	🟡	Workable via ase.vibrations; native: Phase 17
Thermodynamics	🟡	Same as freqs; native: Phase 17
Conformer search (GOAT)	❌	Needs xTB
Implicit solvation	❌	Phase S1 (v0.5.0)
Explicit solvation (SOLVATOR)	❌	Out of scope (use ASE + classical FF)
Dispersion (D3 / D4)	❌	Phase D1 / D2 (v0.5.0)
NEB-TS	🟡	Workable via ase.neb today
IRC	🟡	Manual scan after frequencies land
KIE	❌	Needs Phase 17 (analytic Hessian)
Fukui functions	🟡	Scriptable: N±1 densities
LED energy decomposition	❌	Needs DLPNO-CCSD(T) (v0.7.0)
FOD analysis	❌	Needs finite-T DFT (post-1.0)
IR / Raman intensities	❌	Needs Phase 17 + polarisability derivatives
UV/Vis (TDDFT)	❌	Phase T1 (v0.10.0)
ECD / VCD	❌	Needs T1 + magnetic dipole
NMR (GIAO)	❌	Major v1.0 item
EPR / hyperfine	❌	Needs spin-orbit
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)	⚠️	Blocked: Phase C1 (level shift, smearing, second-order SCF)
SCF convergence tools	⚠️	Damping only today; Phase C1
Geometry optimisation (periodic)	❌	Phase G1 (v0.5.0)
Equation of state	❌	Phase G2
Surfaces / slabs	❌	Phase B1 + Phase C1
Defects / supercells	❌	Needs Phase 15 + charge-correction infra
Magnetic systems	❌	Phase 15 (periodic UHF/UKS)
Metallic systems	❌	Phase C1b (smearing)
Metal/oxide interfaces	❌	Phase 14 (ECPs) + C1 + 15
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
Charge-density map (molecular)	✅	Phase V1 (cube)
Periodic Bloch-orbital map	❌	Phase V3 (needs phase-aware AO evaluator)
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
Spin-orbit / noncollinear	❌	Post-1.0
Electron transport	❌	Out of scope

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 “Modelling 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.

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

These are documentation-only items — every underlying capability already ships:

1. Hello water — promote input-h2o-rhf.py into the tutorial index proper.

2. Geometry optimisation — H₂O / dimer / trimer optimisation walk.

3. Running in parallel — 1-pager on num_threads= and the reported timing block.

4. Bond analysis + charges + dipole — uses Phase 18 + 19.

5. Vibrational frequencies via ASE — ase.vibrations.Vibrations driving the VibeQC calculator (slow but correct; the native Phase-17 path will replace it later).

6. Thermodynamics at T — chain ase.thermochemistry from (5).

7. NEB-TS reaction path via ASE — ase.neb + VibeQC calculator.

8. 3D Madelung constants via Ewald — promote input-3d-madelung.py into the tutorial index.

9. Basis-set convergence — sweep STO-3G → 6-31G* → def2-TZVP on one molecule, plot E(basis).

10. Solid-state hello world (1D molecular crystal) — input-h-chain-uniform.py rewritten as docs.

11. Peierls dimerisation scan — input-h-chain-peierls.py rewrite.

12. pob-TZVP rationale — short explainer on why solid-state bases differ (Bredow ancestry, small-exponent removal).

That’s 12 tutorials available before any new C++ lands.

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

• QM/MM and embedding — CCM itself is an embedding method for solids; other flavours 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.