vibe-qc/Documentation

Unified molecular solvation

The user selects cosmo, cosmo-rs or moist. The electronic method supplies its density and Hamiltonian coupling. The environment owns the cavity, solvent model and environment energy. Existing solvent= and cosmors= inputs remain supported.

Contract and energy convention

All host quantities use atomic units and the spin-summed real AO density D = D_alpha + D_beta. An environment evaluation returns its energy E_env[D] and the complete derivative V_env = dE_env/dD. A method that solves in H_core + V_env reports

E_total = E_method_with_external_operator - Tr(D V_env) + E_env[D]

The trace removes the external operator exactly once. Half-charge formulas are confined to stationary linear PCM implementations. They do not apply to arbitrary pressure, nonlinear or density-dependent cavity components. MOIST’s potential adjoint need not equal its apparent surface charge.

The common lifecycle is geometry update, density update, cavity build, energy evaluation, response evaluation and host contraction. Reuse a geometric cavity at fixed nuclei; rebuild a density-dependent cavity at every new density. Cache keys include geometry, basis, density, model, cavity and numerical settings. Unknown requests or response items raise. Finite values, shapes, spin convention and symmetry are checked at the boundary. Changing grid size invalidates every grid-bound operator.

COSMO-RS adds a thermodynamic layer over a protocol-matched conductor surface, with its existing experimental status and parameterization checks. Delta G_solv, standard states, temperature and sigma-potential provenance remain distinct from electronic total and polarization energies. The selector must not make these different observables interchangeable.

Host capabilities

The host interface is independent of the electronic method. Its capabilities cover potential and spatial derivatives (point and Gaussian kernels), density and spatial derivatives, Gaussian pressure moments, nuclear derivatives and a density-response action. Native vibe-qc integrals and AO evaluators perform these operations; no production PySCF import is allowed. The independent MOIST PySCF host is a test oracle only.

Support is declared separately for energy, self-consistent first derivative, nuclear gradient, Hessian and excited-state response. Supporting a cavity or an SCF Fock derivative does not imply any of the latter capabilities. In particular, MOIST’s first-derivative response is not a TDDFT response kernel. Molecular cavities are not a periodic electrostatic model.

For nonvariational post-SCF methods, distinguish a frozen SCF reference field, evaluation on a correlated one-particle density and a relaxed, state-specific environment. Only the last includes the relevant Lagrangian and density response. Active-space solvers must add the operator to their one-electron Hamiltonian and retain the same energy subtraction. MSINDO retains its multipole provider and native COSMO path.

Implementation sequence and acceptance

Stage	Issue	Deliverable and acceptance
SOLV-01	#872	Backend selection, environment protocol, trace correction and backward-compatible dispatch; route and derivative checks
SOLV-02	#873	MOIST request/response host, optional dependency and cavity invalidation; independent dE/dD checks, unknown-item refusal and matched host references
SOLV-03	#874	RHF/UHF/RKS/UKS SCF and workflow integration; density/operator convergence, complete gradients, rigid-motion checks and vq reference calculations
SOLV-04	#875	Correlated, active-space and semiempirical adapters with explicit coupling levels; method-specific numerical acceptance
SOLV-05	#876	Primary literature/SI and comparison protocol; converged matched calculations before paper claims
SOLV-06	#877	Manual, executable tutorials, citations and packaging; documented capability matrix agrees with tested behavior

Develop and land coherent stages without development CI. Scientific issues remain open until their applicable acceptance is recorded. Record source commit, native runtime, MOIST version, complete input and reference identity with the measured numerical verdict. Operational records live outside the product checkout. New capabilities do not invalidate unrelated completed checks or require another source-review gate.

Literature and comparison design

Start with MOIST’s upstream docs/_static/references.bib, docs/reference/coupling.rst and its Python reference host. The software record is doi:10.5281/zenodo.23473416. Read the primary equations and SI for COSMO (10.1039/P29930000799), CPCM (10.1002/jcc.10189), IEF-PCM (10.1063/1.474659), smooth Gaussian discretization (10.1063/1.3511297), COSMO-RS (10.1021/jp980017s) and Direct COSMO-RS (10.1021/jp511158y). Acquire DROP (10.26434/chemrxiv.15003893/v2), isodensity-DROP (10.26434/chemrxiv.15007095/v1), non-static radii (10.1002/jcc.70099), and the upstream references for D-PCM, SS(V)PE, LPB, SLIC, nonlocal PCM, PV and GOSTSHYP. Verify preprint versions and publication replacements through the library intake.

Separate host correctness, cavity convergence, continuum-model differences and thermodynamic prediction. Small neutral molecules, OH, ammonium and acetate exercise spin and charge. Hydrogen-bonded dimers, conformers and solvent-dependent reactions probe applications after numerical qualification. Pressure and excitation examples require their own qualified derivatives. Use primary benchmark geometries and experimental conventions, with predeclared subsets and no parameter tuning on the test set. Match basis, geometry, ECP, dielectric, cavity/radii, convergence and standard state. ORCA and CRYSTAL comparisons apply only where the physical models match; MOIST’s independent host helps isolate host-coupling errors.

The paper should describe and attribute the integration and comparison, without claiming MOIST’s existing algorithms as new. Journal selection and benchmark results remain research tasks, not implementation acceptance gates.