A high-performance Valence Bond Self-Consistent Field (VBSCF) engine written in C++23.
Valence Bond theory provides direct chemical insight into bonding, reactivity, and electron correlation that molecular orbital methods cannot reveal. xmvb-cpp is an independent open-source VBSCF engine designed for computational chemistry researchers who need VB-level analysis of molecular electronic structure.
src/
core/ Pair indexing and lightweight timing
linalg/ Eigensolvers, eigen response, metric solves, and Krylov algebra
parallel/ Shared OpenMP execution and work partitioning
integrals/ Shared exact/RI AO operators, active transforms and derivatives
mcscf/ Shared direct-CI, state contracts, and CIAH/NEO solvers
casscf/ Orthogonal CASCI model (orbital optimization not yet exposed)
vbscf/ Canonical VBSCF implementation
orbitals/ Sparse/full-AO charts, gauges, and pullbacks
integrals/ VB orbital-preparation and integral-adjoint adapters
determinants/ Determinant-pair algebra and caches
structures/ VB structure expansion and state matrices
derivatives/ Gradient and matrix-free Hessian-vector products
optimization/ VB coordinates, physical preconditioners, and solver adapters
workflow/ End-to-end VBSCF evaluation
input/ XMI deck contracts and VBSCF input loading
libcint/ Method-independent libcint providers (no VB dependency)
guess/ Initial orbitals and restricted-HF construction
output/ Molden and accepted-iteration output
cli/ Command-line entry point and reporting
tools/ Benchmarking and diagnostic tools
basis/ Standard basis set library (Pople, Dunning, etc.)
testdata/vbscf/ Versioned VBSCF regression decks
tests/vbscf/ Unit and numerical-regression tests
tests/mcscf/ Independent integrals, CI, CASCI, and common-solver tests
tests/linalg/ Linear-algebra tests with no electronic-model dependency
tests/parallel/ Shared-buffer and nested-team execution tests
The component dependency rules and numerical naming conventions are recorded in Code Organization and Naming.
| Library | Purpose |
|---|---|
| Eigen3 | Dense linear algebra |
| OpenBLAS | BLAS/LAPACK routines |
| libcint | Gaussian integral evaluation |
| libxc | Exchange-correlation functionals |
Use a C++23 compiler (tested with GCC14), CMake3.20 or newer, and an environment providing ninja, eigen, openblas (with LAPACKE headers), libxc, and libcint, then build with CMake:
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallelThis produces build/src/xmvb-cpp.exe.
To enable optional diagnostic and test targets:
cmake -B build -G Ninja -DXMVB_BUILD_DEV_TARGETS=ON
cmake --build buildOMP_NUM_THREADS=1 build/src/xmvb-cpp.exe <input.xmi>Input files use the .xmi format. See testdata/vbscf/ for the versioned
regression decks and testdata/vbscf/F2.xmi for the compact HAO smoke case.
Within $CTRL, ISCF=7 selects TNHVP,
ISCF=8 selects preconditioned L-BFGS (P-LBFGS), and
ISCF=9 selects co-iterative augmented Hessian (CIAH). The project default
when ISCF is omitted is P-LBFGS.
EIGENSOLVER=DAVIDSON selects the default matrix-free structure solver,
while EIGENSOLVER=DENSE selects the explicit dense reference solver. An
explicit --optimizer-backend or --eigensolver command-line option overrides
the corresponding input keyword.
P-LBFGS uses the same local orbital-block initial inverse and transported
secant recursion as the TNHVP predictor, without exact HVP correction. The
native raw-coordinate L-BFGS backend and its Moré--Thuente line search have
been removed. ISCF=5 and --optimizer-backend lbfgs are rejected, not
redirected to another method. Use --optimizer-backend plbfgs for P-LBFGS.
Use --optimizer-backend ciah and --ciah-trace path.tsv for CIAH. The retired
neo, block_lbfgs, and --neo-trace CLI spellings are not aliases; numeric
ISCF=7/8/9 selections are unchanged.
NSTATE=n selects an equal-weight average over the consecutive lowest n
VB states. Omitting it is equivalent to NSTATE=1. The optimizer uses the
same normalized weight 1/n for the energy, analytic gradient, and TNHVP
Hessian-vector product. See testdata/vbscf/F2_SA2.xmi for a two-state input.
Davidson runs retain only the requested roots, the structure-overlap diagonal, and the matrix-free products needed for exact Coulson--Chirgwin weights. Their reports omit the full structure Hamiltonian/overlap matrices and the Lowdin and inverse weights that require global overlap-matrix functions. Dense reference runs retain the complete matrices, spectrum, and all four weight definitions.