Skip to content
Loach1703Public
forked from Tao-Xia/xmvb-cpp

About

A high-performance C++ Valence Bond SCF engine for quantum chemistry

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

xmvb-cpp

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.

Architecture

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.

Dependencies

Library Purpose
Eigen3 Dense linear algebra
OpenBLAS BLAS/LAPACK routines
libcint Gaussian integral evaluation
libxc Exchange-correlation functionals

Build

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 --parallel

This 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 build

Usage

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

License

MIT

About

A high-performance C++ Valence Bond SCF engine for quantum chemistry

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages