Skip to content
Tao-XiaPublic

About

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

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1,301 Commits

Folders and files

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
  scf/             Common restricted SCF/DIIS and Hartree-Fock evaluation
  dft/             Molecular grids, Libxc LDA/GGA, and RKS/UKS models
  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

Shared numerical modules do not depend on VB-specific model types. AO basis counts use n_bf; active orbital counts use n_active.

Dependencies

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

Binary distribution

The Linux x86-64 CPU distribution consists of a reusable Apptainer runtime SIF and the versioned xmvb-cpp-0.1.4-linux-x86_64-cpu.tar.gz program archive. Both are published in GHCR. Select them with XMVB_RUNTIME_IMAGE and XMVB_PROGRAM_DIR, then run "$XMVB_PROGRAM_DIR/bin/xmvb" input.xmi. The program archive includes basis files and a CIAH example.

See BUILDING.md for installation, source compilation, the CPU Release preset and the persistent release-build cache.

C++ and CUDA code style

Use clang-format and clang-tidy 20.1.0 with the repository's .clang-format and .clang-tidy. The formatter uses four-space indentation, a 100-column limit, and the formatter's Latest syntax mode for C++23 sources; it preserves include order and comment wrapping. Format the files you change rather than reformatting unrelated code:

clang-format --dry-run --Werror path/to/file.cpp path/to/kernel.cu
clang-format -i path/to/file.cpp path/to/kernel.cu
clang-tidy -p build path/to/file.cpp

Configure the matching build first so clang-tidy can use its exported compile_commands.json. The enabled tidy checks target correctness; review findings individually and do not apply automatic fixes to numerical code. CUDA formatting uses the same rules; CUDA compilation remains C++20 as set in CMake. Run builds and numerical validation through Slurm on compute nodes.

Usage

OMP_NUM_THREADS=1 build/src/xmvb-cpp.exe <input.xmi>

CPU VBSCF emits SCF_CONVERGED program_wall_seconds=<seconds> on stdout, followed by an immediate flush, as soon as its optimizer confirms convergence. The clock starts at main() entry, before argument parsing. The final report also lists Program entry to SCF convergence and Post-SCF wall time; the latter includes final diagnostics, orbital export and structure analysis/output through the report, before the timing footer. These two fields partition the internal End-to-end wall time. The existing SCF iteration wall time is a nested optimizer timer, not the startup-to-convergence metric. Unconverged runs emit no convergence marker or successful-convergence timing fields. A marker certifies SCF convergence, not successful completion of subsequent output; also check the process exit code. To include launcher/container startup and dynamic-library loading, start an external clock before the run command and stop it when this marker arrives. Ordinary file or pipe output is sufficient; no PTY or line-buffering override is needed.

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. In a CUDA-enabled build, replace the $CTRL method flag vbscf with cuvbscf to run GPU VBSCF through the normal executable:

$ctrl
cuvbscf
int=libcint
$end

Run xmvb-cpp.exe example.xmi. GPU calculations default to CIAH (ISCF=9), Davidson, and the analytic Hessian-diagonal preconditioner. The current GPU solver supports single-state exact integrals. CPU-only builds reject cuvbscf; they do not fall back to CPU. The standalone cuvbscf example.xmi executable uses the same GPU driver.

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.

Molecular DFT

Molecular RKS and collinear UKS support Libxc LDA/GGA and global-hybrid functionals with exact AO Coulomb/exchange integrals, using the common SCF/DIIS core. Select DFT rather than VBSCF in $CTRL:

$CTRL
DFT BASIS=CC-PVDZ INT=LIBCINT
XC=LDA_X,LDA_C_VWN NRAD=80 NANG=590 SCF_TOL=1.0D-9
$END
$GEO
He 0.0 0.0 0.0
$END

The defaults are LDA exchange plus VWN correlation and an unpruned 80-by-590 atom-centered grid with Becke partitioning. SCF_TOL applies to the maximum AO density change and commutator residual; ITMAX sets the iteration limit. Angular grids of 302 or 590 points are supported. XC accepts LDA/SVWN5, PBE, BLYP, BP86, PW91, revPBE, PBEsol, PBE0, B3LYP, and B3LYP5. Explicit Libxc component names remain available, e.g. XC=GGA_X_B88,GGA_C_LYP. Names are case-insensitive; output reports the resolved definition.

PBE0 includes 25% exact exchange. B3LYP uses Libxc 402 (VWN-RPA), while B3LYP5 uses Libxc 475 (VWN5); both include 20% exact exchange. Exact exchange is included consistently in energy, Fock and analytical density response. The output distinguishes the semilocal XC energy from the total energy. GGA density gradients and AO potentials use the same shared grid tiles as LDA; all admitted components must provide analytical first and second derivatives.

NMUL fixes the alpha/beta populations: its default of 1 selects RKS, while values greater than 1 select UKS. KS=UKS also allows an equal-population UKS calculation; KS=RKS explicitly requires equal populations. For example, OH uses DFT NMUL=2 XC=PBE. UKS fixes the spin projection, not a pure total-spin eigenfunction; the output reports the determinant spin-square expectation. Both spins share one Coulomb matrix and one coupled DIIS extrapolation.

See testdata/dft/ for closed- and open-shell examples. Converged restricted MO coefficients are written to <input>.orb; UKS writes <input>.alpha.orb and <input>.beta.orb, all in fixed-point GUS-body format.

The initial guess diagonalizes the core Hamiltonian with the requested spin occupations. Range-separated hybrids, meta-GGA, double hybrids, nonlocal VV10, RI DFT, supplied guesses, nuclear derivatives and periodic DFT are not implemented and are not silently substituted by another functional or HF.

License

MIT, with quadrature attribution in NOTICE.

About

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

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages