This document defines the production module boundaries and local naming rules. The directory provides the context, so filenames should describe only the operation or data owned by that directory.
src/
core/ Pair indexing and lightweight timing
linalg/ Method-independent linear algebra
parallel/ Shared OpenMP execution and work partitioning
integrals/ Method-independent AO/active transforms and their derivatives
mcscf/ Method-independent CI, optimization, and state contracts
casscf/ Orthogonal CASCI model and active-integral preparation
vbscf/ VB structures, nonorthogonal orbitals, derivatives, and workflows
input/ XMI deck representation and construction of VBSCF inputs
libcint/ AO integral providers and libcint-specific preparation
guess/ Initial-orbital and restricted-HF construction
output/ Molden and accepted-iteration serialization
cli/ Command-line parsing, execution, and reporting
tools/ Developer diagnostics and benchmarks
There is no application or runtime layer. The command-line interface is one
consumer of independently named production components, not the owner of their
scientific logic.
The method libraries depend on a common numerical library:
xmvb_vbscf ----> xmvb_mcscf <---- xmvb_casscf
| | |
+--------> xmvb_integrals <-------+
|
v
xmvb_linalg
An arrow means "depends on". The common library owns direct-CI actions, spin
operations, state weights, and matrix-free optimization. xmvb_linalg owns
eigensolvers, eigen response, metric solves and general Krylov operations; it
does not depend on mcscf/ or either physical model. CMake rejects direct
VB includes in the common layers or casscf/; public solver tests link only
xmvb_mcscf, not xmvb_vbscf.
Linear-algebra tests link only xmvb_linalg. OpenMP tools live in
parallel/openmp.hpp, use caller-owned storage and avoid nested teams.
xmvb_libcint depends only on the public integral library, not the VB model;
its APIs use xmvb::libcint. The I/O components xmvb_input_deck,
xmvb_guess, xmvb_input, and xmvb_output form an acyclic
graph. xmvb_input_deck is separate because guess construction consumes parsed
deck data, while complete input loading consumes the guess builder.
The xmvb executable owns only files in src/cli/. Diagnostic executables are
excluded from the default build and live in src/tools/.
mcscf/
ci/ Spin strings and direct-CI actions
states/weights.* State-weight validation and normalization
optimization/
actions.hpp Physical dual-norm contract
problem.* Shared quadratic-model contract
ciah/ Co-iterative augmented-Hessian solver
neo/ Norm-extended trust-region solver and globalization
preconditioners/ Algebraic BFGS, coarse, and shifted-metric actions
trust_region/ Spectral trust-region solve
trace.hpp Scalar solver-event logging
These APIs use xmvb::mcscf. A linalg::VectorAction maps a vector to a vector;
the caller defines its coordinates. A DualNorm evaluates a covector norm
using the physical model's metric. A common solver must not infer orbital
coordinates, CI normalization, or a VB structure representation from either
callback. QuadraticProblem supplies the gradient and action/metric/preconditioner
callbacks; CiahWorkspace owns only numerical subspace state.
VB orbital charts, CI transport, physical curvature construction, and macrostep
evaluation remain in vbscf/optimization/. In particular,
vbscf/optimization/neo/coordinates.* and curvature.* are VB model adapters,
not common solvers. Their dependence on VB derivatives is intentional.
There are no forwarding headers or namespace aliases at the old solver paths. Callers include the owning module directly. Shared state weights have one implementation; workflow and derivative code must not normalize independently.
integrals/
ao/ Exact AO-pair graph, Coulomb/exchange actions, libcint/RI contracts
active/ Exact/RI transforms, packed kernels, one-electron projection/adjoint
response/ Integral directions, fixed-adjoint HVPs and accepted-point workspaces
These APIs use xmvb::integrals and are compiled once in xmvb_integrals.
They consume AO operators and numerical orbital coefficients, not VB inputs,
structures, orbital charts or preparation results. Exact forward transforms
borrow AO-row sparse support through std::span; RI transforms borrow an
AO-by-active Eigen matrix. Neither assumes orthonormal active orbitals.
Forward, gradient and HVP consumers share the same data and implementations.
Accepted-point caches explicitly borrow their source matrices; callers own the
data and must keep it alive. This extraction does not change tiling, memory
budgets, threading, screening or numerical tolerances.
vbscf/integrals/ retains orbital-preparation adapters, inactive-density
assembly and lazy RI acquisition from VbScfInput.
vbscf/integrals/active/space.* owns this thin model boundary.
prepare_timed_active_space_context(input) prepares the physical orbitals and
calls the exact/RI common transforms directly. pullback_active_integrals
selects the representation and returns an AO-by-active Eigen gradient from
the common adjoint kernels. The old exact/RI two-electron builder classes,
VB two-electron backpropagator and its single-field result were deleted.
There is no second VB pair-map, packed-adjoint or RI-factor-adjoint formula.
Evaluator constructors no longer inject stateless integral helpers. Forward preparation takes the physical input alone, and probes call the same operation directly instead of traversing evaluator forwarding methods. The exact ordinary gradient borrows accepted products or streams pair tiles; it does not build exchange/one-index images used only by HVPs. RI gradients use the existing factor-native response kernel, not an AO-pair-by-active-pair adjoint buffer.
The AO-to-CASCI entry in casscf/integrals/active.* uses the same AO response,
active one-electron projection and exact two-electron transform, including the
inactive/nuclear energy. It does not build VB structures or transform virtual
four-index integrals. casscf/ still exposes CASCI, not a complete CASSCF
orbital optimizer.
CMake rejects model/I/O includes inside the integral layer. The standalone
test_integrals links only xmvb_integrals; it checks exact/RI agreement,
directional derivatives, adjoint duality and fixed-adjoint HVPs. test_casci
checks the shared AO preparation against an independently transformed MO
reference with a nontrivial orthonormal frame. No old-path forwarding headers
or namespace aliases remain. Generic matrix-buffer conversion lives in
linalg/storage.hpp; optional per-worker timing lives in parallel/workers.hpp.
C++23 and CMake3.20 or newer are required, with standard extensions disabled
and no -fpermissive. GCC14 is the tested compiler baseline.
CMake must fail rather than silently decay to an older language standard.
Use modern facilities when they clarify ownership or contracts: std::span
borrows contiguous input storage without prescribing its owning container.
Eigen remains the dense physical matrix/vector representation. The dense
LAPACK eigensolver still makes its required writable working copies; a span
does not change LAPACK's overwrite contract.
| ISCF | Report name | CLI backend | Meaning |
|---|---|---|---|
| 7 | TNHVP | nonredundant_truncated_newton |
Truncated Newton with HVPs |
| 8 | P-LBFGS | plbfgs |
Preconditioned L-BFGS, the default |
| 9 | CIAH | ciah |
Co-iterative augmented Hessian |
P-LBFGS was previously called block-LBFGS. Its initial inverse is built from
local orbital-curvature blocks, followed by transported L-BFGS secant updates;
the optimization variables are not partitioned into separate block solves.
The new name describes the algorithm's preconditioning role. This does not
rename BlockInverseBfgs: that separate algebraic operation really performs
a simultaneous block-secant update.
The old raw-coordinate L-BFGS backend, its Moré--Thuente search, and its raw
gradient-only report branches have been deleted. ISCF=5 and the lbfgs CLI
name are rejected; neither silently selects P-LBFGS. Current regression decks
that requested the removed backend explicitly now request ISCF=8.
The production ISCF=9 driver uses CIAH keyframes and an AH Davidson workspace,
so its API, output, trace writer and diagnostics use CIAH. neo/solver.*
remains a distinct norm-extended trust-region solver, used in curvature
diagnostics. It is not an alias for the CIAH driver. ISCF=7/8/9 are unchanged.
Old CLI spellings are removed, not forwarded; historical result
files and manuscript drafts retain their original labels until revised.
- Do not add a
cpp_prefix; C++ is already the language of the repository. - Do not encode obsolete implementations with
legacy,compat, orfallbacknames. Delete retired paths. - Avoid umbrella names such as
application,runtime,manager, orutilswhen a scientific or I/O responsibility can be stated directly. - Prefer a short noun for a data contract and a short operation name for an implementation, using the containing directories to supply context.
Use these local abbreviations consistently in numerical kernels:
| Name | Meaning |
|---|---|
n_bf |
number of AO basis functions |
n_ao |
number of active orbitals |
n_orb |
total number of orbitals |
n_occ |
number of occupied orbitals |
n_inact |
number of inactive orbitals |
n_det |
number of determinants |
n_str |
number of VB structures |
Public data contracts may retain explicit names such as
n_basis_functions and n_active_orbitals. Short forms are for local
expressions whose scope makes the meaning unambiguous. In particular, never use
n_ao for the AO basis dimension; use n_bf so it cannot be confused with the
active-orbital count.
Dense physical vectors and matrices are Eigen objects. std::vector remains
appropriate for ragged topology, discrete indices, packed integral records,
and raw external I/O buffers, but not as an implicit dense-matrix container.