Semiempirical (DFTB) Subsystem — v0.9.0 Release Handover

Date: 2026-05-22
Owner: Semiempirical DFTB subsystem
Status: Feature-complete, tests green, ready for v0.9.0 tag

1. What Shipped

Methods

Method

Molecular

Periodic Γ

Periodic k-points

Open-shell

DFTB0 (non-SCC)

✅

✅

✅

✅ (UDFTB0)

SCC-DFTB

✅

✅

✅

✅ (USCC-DFTB)

Gradients

Method

Analytic

FD

DFTB0

✅

—

SCC-DFTB

✅ (fixed-charge approx)

—

UDFTB0

✅

—

USCC-DFTB

—

✅

Features

  • 68 elements (H–Bi, no lanthanides — need 4f STO-NG tables)

  • D3(BJ) dispersion via DispersionCorrectedModel wrapper

  • Variable-cell optimization (ASE ExpCellFilter bridge)

  • Preoptimization workflow (preoptimize_molecule, preoptimize_periodic)

  • Stress tensor (finite-difference)

  • STO-6G minimal basis (s, p, d; HSP 1969 tables)

  • R⁻¹² repulsive with automatic default_repulsive_A estimator (no explicit pair table needed)

  • Ohno-Klopman γ matrix for SCC charge interactions

  • Wolfsberg-Helmholtz H⁰ construction (κ = 1.75)

Python API

from vibeqc.semiempirical import (
    DFTB0Model, SCCDFTBModel,        # closed-shell
    UDFTB0Model, USCCDFTBModel,      # open-shell
    DispersionCorrectedModel,        # D3(BJ) wrapper
    run_dftb0, run_scc_dftb,         # one-shot
    d3bj_energy, DFTB_D3_DEFAULTS,   # dispersion
    compute_stress_fd, optimize_cell, # periodic optimization
)
from vibeqc.semiempirical.preoptimize import (
    preoptimize_molecule, preoptimize_periodic,
)
# Periodic + k-points via C++ submodule:
from vibeqc._vibeqc_core.semiempirical import (
    run_dftb0_gamma, run_scc_dftb_gamma,
    run_dftb0_kpoints, run_scc_dftb_kpoints,
    run_dftb0_bandpath,
)

Examples

examples/semiempirical/
├── 01_water_dftb0.py              # Basic DFTB0
├── 02_formic_acid_scc.py          # SCC-DFTB + charge analysis
├── 03_carbon_chain_periodic.py    # Periodic + k-points + bands
└── 04_optimize_and_preoptimize.py # Geometry opt + D3 dispersion

2. Files Inventory

C++ (20 files)

cpp/include/vibeqc/semiempirical/
├── parameters.hpp           # ElementData, RepulsivePair, SemiempiricalParameters
├── basis.hpp                # SemiempiricalBasis (STO-6G)
├── hamiltonian.hpp          # H⁰, Mulliken, γ matrix, SCC correction
├── dftb0.hpp                # DFTB0Result, UDFTB0Result, run_dftb0, run_udftb0
├── scc_dftb.hpp             # SCCOptions, SCCDFTBResult, USCCDFTBResult
├── gradient.hpp             # compute_dftb0_gradient, compute_scc_dftb_gradient,
│                            #   compute_udftb0_gradient
├── periodic_dftb0.hpp       # PeriodicDFTB0Result, run_dftb0_gamma
├── periodic_scc_dftb.hpp    # PeriodicSCCDFTBResult, run_scc_dftb_gamma
├── kpoints_dftb0.hpp        # KPointDFTB0Result, run_dftb0_kpoints, run_dftb0_bandpath
└── kpoints_scc_dftb.hpp     # KPointSCCDFTBResult, run_scc_dftb_kpoints

cpp/src/semiempirical/
├── parameters.cpp           # 68-element default table + default_repulsive_A
├── basis.cpp                # STO-6G tables (HSP 1969) for s/p/d
├── hamiltonian.cpp          # WH H⁰, Mulliken charges, γ, H^{SCC}
├── dftb0.cpp                # DFTB0 + UDFTB0 drivers
├── scc_dftb.cpp             # SCC + USCC SCF loops
├── gradient.cpp             # Analytic gradients (DFTB0, SCC, UDFTB0)
├── periodic_dftb0.cpp       # Periodic Gamma-point DFTB0
├── periodic_scc_dftb.cpp    # Periodic SCC-DFTB
├── kpoints_dftb0.cpp        # k-point DFTB0 + bandpath
└── kpoints_scc_dftb.cpp     # k-point SCC-DFTB

Python (8 files)

python/vibeqc/semiempirical/
├── __init__.py              # Public API exports
├── model.py                 # SemiempiricalModel ABC
├── parameters.py            # default_parameters(), supports_element()
├── basis.py                 # (thin)
├── dftb0.py                 # 6 model classes + convenience functions
├── periodic.py              # compute_stress_fd, optimize_cell
├── preoptimize.py           # preoptimize_molecule, preoptimize_periodic
└── dispersion.py            # DispersionCorrectedModel, d3bj_energy

Modified core files

cpp/CMakeLists.txt           # +10 semiempirical source files
cpp/src/bindings.cpp         # ~300 lines pybind11 bindings
cpp/src/lattice_integrals.cpp # Bug fix: missing compute_1e_lattice_matrix_explicit
python/vibeqc/output/citations/database.toml  # +3 DFTB citations, +2 routes

3. Parameter Status (Honest-Scope)

Provenance (§1 licensing)

ALL 68-element parameters are in-house estimates. Constructed from:

  • Slater’s rules for STO exponents

  • Periodic-trend scaling for on-site energies

  • Approximate Hubbard U estimates

  • R⁻¹² repulsive form with automatic default estimator

No values sourced from dftb.org (mio, mio-0-1, 3ob, matsci, trans3d, etc.). No redistribution issue.

Quality

These are APPROXIMATE, ORDER-OF-MAGNITUDE parameters. NOT production-grade DFTB.

  • Intended use: fast screening and geometry preoptimization before HF/DFT

  • Bond lengths: roughly correct (±0.3 bohr for organics)

  • Energies: NOT transferable, NOT comparable to experiment/high-level theory

  • Repulsive: physics-inspired R⁻¹² placeholder (real DFTB uses DFT-fitted splines)

  • No systematic validation against DFT/DFTB+/experiment

Citation requirements

Runs using DFTB0 should cite: Porezag et al., Phys. Rev. B 51, 12947 (1995). Runs using SCC-DFTB should additionally cite: Elstner et al., Phys. Rev. B 58, 7260 (1998). STO-NG basis: Hehre, Stewart, Pople, J. Chem. Phys. 51, 2657 (1969).

4. Testing

Test file: tests/test_semiempirical_dftb0.py

75 non-slow tests passing across 15 test classes:
  TestParameters (5)          — element data, Hubbard U, repulsive
  TestDFTB0Energy (11)        — energies, dims, symmetry, reproducibility
  TestDFTB0Gradient (5)       — FD force checks
  TestSemiempiricalModel (2)  — ABC contract
  TestSCCDFTB (8)             — SCC convergence, charges, gradient
  TestPeriodicDFTB0 (4)       — periodic energy, molecular limit
  TestPeriodicSCCDFTB (3)     — periodic SCC
  TestStress (2)              — FD stress tensor
  TestDispersion (4)          — D3 energy, wrapping, gradient
  TestExtendedElements (9)    — new element sanity
  TestFullPeriodicTable (5)   — wide element coverage
  TestTransitionMetals (6)    — d-orbital systems
  TestUDFTB0 (5)              — unrestricted DFTB0
  TestUSCCDFTB (3)            — unrestricted SCC
  TestKPointsDFTB0 (2)        — k-point vs Gamma, band dispersion
  +3 slow tests (geometry optimization, variable-cell, preoptimization)

Run

.venv/bin/python -m pytest tests/test_semiempirical_dftb0.py -v
.venv/bin/python -m pytest tests/test_semiempirical_dftb0.py -m 'not slow' -q

5. Known Issues

Issue

Severity

Notes

Au₂ dimer test intermittently returns 1e169

Low

State pollution from adjacent tests; passes in isolation

No 4f-orbital STO-6G table

Medium

Blocks lanthanide support (Z=57-71)

SCC-DFTB open-shell gradient is FD-only

Medium

Analytic USCC gradient deferred

k-point SCC uses molecular γ, not periodic γ

Low

Gamma-point γ matrix used for k-averaging; periodic lattice-summed γ deferred

Repulsive is R⁻¹², not DFT-fitted splines

High (doc)

Documented as approximate; bond lengths are ballpark only

No ECP support

Medium

Heavy elements (5d/6p) use all-electron minimal basis

6. Resumption Notes

To continue development:

  1. Read docs/semiempirical_roadmap.md for the full handover

  2. Build: pip install -e . --no-build-isolation

  3. Test: pytest tests/test_semiempirical_dftb0.py -m 'not slow'

Natural next steps

  • Add 4f STO-6G table → lanthanide support (Z=57-71)

  • Implement analytic USCC gradient

  • Periodic γ matrix for k-point SCC

  • DFT-fitted repulsive splines (replaces R⁻¹²)

  • Wire semiempirical methods into vibeqc.runner.run_job()

  • General k-point mesh symmetry reduction