Self-consistent reaction-field (SCRF) primitives shared between the HF/DFT-side occ::solvent::COSMO driver and the xTB-side CPCM-X / SMD implicit-solvation models. More...

Classes
struct	MultipoleKernel
	Geometric factors of the atom-centred multipole expansion evaluated at a displacement d = r_cavity − R_atom: More...
struct	MultipoleDamping
	Short-range damping of the dipole and quadrupole kernels, f_n(d) = 1/(1 + 6·(rco/d)^kdmp_n), applied to t1 with n = 3 and to t2 with n = 5. More...
struct	CosmoResponse
	Pre-solved CPCM/COSMO response operator on a cavity, driven by atom- centred point-charge sources. More...
struct	CavityGeometry
	A cavity whose points ride rigidly on their owner atoms, for derivatives beyond the frozen-cavity gradient. More...

Functions
Mat	build_cosmo_A (const Mat3N &cavity_points, const Vec &cavity_areas)
	Build the dense COSMO A matrix on a discretised cavity: A(i, j) = 1/\|r_i − r_j\|, off-diagonal A(i, i) = 1.07·√(4π/S_i) ≈ 3.793051240937804 / √S_i cavity_points is 3 × ncav (Bohr), cavity_areas is ncav (Bohr²).
Mat	build_atom_cavity_coulomb (const Mat3N &cavity_points, const Mat3N &atom_positions)
	Build the atom↔cavity Coulomb operator B(i, a) = 1/\|r_i − R_a\|.
MultipoleKernel	multipole_kernel (const Vec3 &d, MultipoleDamping damping={})
Vec3	multipole_kernel_gradient (const Vec3 &d, double q, const Vec3 &mu, const double *theta, MultipoleDamping damping={})
	∂φ/∂d for one atom's moments, the gradient counterpart of multipole_kernel.
CosmoResponse	build_cosmo_response (const Mat3N &atom_positions_bohr, const Mat3N &cavity_points, const Vec &cavity_areas, double epsilon, double x)
	Build the pre-solved response.
Mat3N	cosmo_gradient_frozen (const Mat3N &atom_positions_bohr, const Mat3N &cavity_points, const Vec &cavity_areas, const IVec &cavity_atom_index, const Vec &atom_charges, const Vec &sigma, double f_epsilon, const Vec &atom_radii_bohr=Vec(), double smoothing_width_bohr=0.0, const Mat3N &atom_dipoles=Mat3N(), const Mat &atom_quadrupoles=Mat(), const Vec &damping_rco_bohr=Vec(), double kdmp3=3.0, double kdmp5=4.0)
	Frozen-cavity analytical gradient of the polarisation energy with respect to atomic positions:
Mat	cavity_log_weight_gradient (const CavityGeometry &cavity)
	∂ ln w_k / ∂x (M x 3N); zero for a boolean cavity.
Mat	cavity_log_weight_hessian (const CavityGeometry &cavity, const Vec &c)
	Σ_k c_k ∂² ln w_k / ∂x∂y (3N x 3N); zero for a boolean cavity.
Mat	cosmo_A_derivative_product (const CavityGeometry &cavity, const Mat &dlnw, const Vec &sigma)
	(∂A/∂x) σ (M x 3N): the point-pair Coulomb terms plus, on a smooth cavity, the diagonal ∂A_kk/∂x = −½ A_kk ∂ ln w_k/∂x.
Mat	cosmo_A_second_derivative (const CavityGeometry &cavity, const Mat &dlnw, const Vec &sigma)
	σᵀ (∂²A/∂x∂y) σ (3N x 3N), using ∂²A_kk = A_kk (¼ g gᵀ − ½ ∂² ln w_k) with g = ∂ ln w_k on the diagonal.
Mat	atom_cavity_potential_derivatives (const CavityGeometry &cavity, const Vec &atom_charges)
	∂φ_k/∂x (M x 3N) for the potential φ_k = Σ_a Z_a / \|r_k − R_a\| of atom-centred point charges Z at the cavity points.
Mat	atom_cavity_potential_hessian (const CavityGeometry &cavity, const Vec &atom_charges, const Vec &sigma)
	Σ_k σ_k ∂²φ_k/∂x∂y (3N x 3N) for the same potential.

Detailed Description

Self-consistent reaction-field (SCRF) primitives shared between the HF/DFT-side occ::solvent::COSMO driver and the xTB-side CPCM-X / SMD implicit-solvation models.

The intent is that this module owns the COSMO / CPCM math (cavity A matrix, atom↔cavity B operator, pre-solved response, frozen-cavity analytical gradient) while higher-level wrappers in occ::solvent and occ::xtb (and the forthcoming occ::scrf::ReactionFieldEngine) glue this kernel to the rest of their pipeline (cavity build, parameter lookup, energy accounting, gradient flow).

Everything here is parameterised on raw Eigen arrays so the library depends only on occ_core — no dependency on occ_solvent or any particular cavity representation.

Function Documentation

◆ atom_cavity_potential_derivatives()

Mat occ::scrf::detail::atom_cavity_potential_derivatives	(	const CavityGeometry &	cavity,
		const Vec &	atom_charges )

∂φ_k/∂x (M x 3N) for the potential φ_k = Σ_a Z_a / |r_k − R_a| of atom-centred point charges Z at the cavity points.

◆ atom_cavity_potential_hessian()

Mat occ::scrf::detail::atom_cavity_potential_hessian	(	const CavityGeometry &	cavity,
		const Vec &	atom_charges,
		const Vec &	sigma )

Σ_k σ_k ∂²φ_k/∂x∂y (3N x 3N) for the same potential.

◆ build_atom_cavity_coulomb()

Mat occ::scrf::detail::build_atom_cavity_coulomb	(	const Mat3N &	cavity_points,
		const Mat3N &	atom_positions )

Build the atom↔cavity Coulomb operator B(i, a) = 1/|r_i − R_a|.

Useful when the source potential at each cavity point is being driven by point-like atomic charges (e.g. xTB Mulliken charges): φ_i = (B · q_atom)_i cavity_points is 3 × ncav, atom_positions is 3 × natom (both Bohr).

◆ build_cosmo_A()

Mat occ::scrf::detail::build_cosmo_A	(	const Mat3N &	cavity_points,
		const Vec &	cavity_areas )

Build the dense COSMO A matrix on a discretised cavity: A(i, j) = 1/|r_i − r_j|, off-diagonal A(i, i) = 1.07·√(4π/S_i) ≈ 3.793051240937804 / √S_i cavity_points is 3 × ncav (Bohr), cavity_areas is ncav (Bohr²).

◆ build_cosmo_response()

CosmoResponse occ::scrf::detail::build_cosmo_response	(	const Mat3N &	atom_positions_bohr,
		const Mat3N &	cavity_points,
		const Vec &	cavity_areas,
		double	epsilon,
		double	x )

Build the pre-solved response.

epsilon is the solvent relative permittivity; x selects the f(ε) convention in f(ε) = (ε−1)/(ε+x): x = 0 is the CPCM ideal-conductor convention, x = 0.5 is Klamt COSMO. Empty cavity (cavity_points.cols() == 0) returns zero-sized matrices.

◆ cavity_log_weight_gradient()

Mat occ::scrf::detail::cavity_log_weight_gradient ( const CavityGeometry & cavity )

∂ ln w_k / ∂x (M x 3N); zero for a boolean cavity.

Areas follow as ∂a_k/∂x = a_k ∂ ln w_k/∂x.

◆ cavity_log_weight_hessian()

Mat occ::scrf::detail::cavity_log_weight_hessian	(	const CavityGeometry &	cavity,
		const Vec &	c )

Σ_k c_k ∂² ln w_k / ∂x∂y (3N x 3N); zero for a boolean cavity.

◆ cosmo_A_derivative_product()

Mat occ::scrf::detail::cosmo_A_derivative_product	(	const CavityGeometry &	cavity,
		const Mat &	dlnw,
		const Vec &	sigma )

(∂A/∂x) σ (M x 3N): the point-pair Coulomb terms plus, on a smooth cavity, the diagonal ∂A_kk/∂x = −½ A_kk ∂ ln w_k/∂x.

dlnw is cavity_log_weight_gradient(cavity).

◆ cosmo_A_second_derivative()

Mat occ::scrf::detail::cosmo_A_second_derivative	(	const CavityGeometry &	cavity,
		const Mat &	dlnw,
		const Vec &	sigma )

σᵀ (∂²A/∂x∂y) σ (3N x 3N), using ∂²A_kk = A_kk (¼ g gᵀ − ½ ∂² ln w_k) with g = ∂ ln w_k on the diagonal.

◆ cosmo_gradient_frozen()

Mat3N occ::scrf::detail::cosmo_gradient_frozen	(	const Mat3N &	atom_positions_bohr,
		const Mat3N &	cavity_points,
		const Vec &	cavity_areas,
		const IVec &	cavity_atom_index,
		const Vec &	atom_charges,
		const Vec &	sigma,
		double	f_epsilon,
		const Vec &	atom_radii_bohr = Vec(),
		double	smoothing_width_bohr = 0.0,
		const Mat3N &	atom_dipoles = Mat3N(),
		const Mat &	atom_quadrupoles = Mat(),
		const Vec &	damping_rco_bohr = Vec(),
		double	kdmp3 = 3.0,
		double	kdmp5 = 4.0 )

nodiscard

Frozen-cavity analytical gradient of the polarisation energy with respect to atomic positions:

∂E_es/∂R_c = − Σ_{i: a_i=c} σ_i · g_i

q_c · h_c
(1/f(ε)) · Σ_{i: a_i=c} σ_i · t_i
diagonal-A term (smooth cavity only — see below)

g_i = Σ_a q_a · (r_i − R_a) / |r_i − R_a|³ (field at cavity i from q) t_i = −Σ_{j≠i} σ_j · (r_i − r_j) / |r_i − r_j|³ (field at cavity i from σ) h_c = Σ_i σ_i · (r_i − R_c) / |r_i − R_c|³ (field at atom c from σ)

With a boolean cavity (smoothing_width = 0), per-element areas are geometry-independent and ∂A_ii/∂R = 0. With a smooth cavity, each per- element area depends smoothly on every other atom's position through the erf-based smoothstep weight, giving

∂A_ii/∂R_c = −½ A_ii · ∂ln(weight_i)/∂R_c ∂ln(weight_i)/∂R_c = Σ_{k ≠ a_i} (s'/s)|d_ik · ∂d_ik/∂R_c

where s(d) = ½(1 + erf((d − t_k)/w)), t_k = r_k. Pass atom_radii_bohr and smoothing_width_bohr > 0 to enable this term; leave smoothing_width_bohr = 0 to skip it (boolean-cavity default).

Returns 3 × N_atoms in Hartree/Bohr.

atom_dipoles (3 × N) and atom_quadrupoles (6 × N, multipole_kernel layout) extend the source from point charges to the full atom-centred expansion; pass them empty for the charge-only field. They enter through g and h only — the σ-on-σ and diagonal-A terms see the cavity, not the source, and are unchanged.

◆ multipole_kernel()

MultipoleKernel occ::scrf::detail::multipole_kernel	(	const Vec3 &	d,
		MultipoleDamping	damping = {} )

◆ multipole_kernel_gradient()

Vec3 occ::scrf::detail::multipole_kernel_gradient	(	const Vec3 &	d,
		double	q,
		const Vec3 &	mu,
		const double *	theta,
		MultipoleDamping	damping = {} )

∂φ/∂d for one atom's moments, the gradient counterpart of multipole_kernel.

theta points at six contiguous quadrupole components in the same layout, or is null for a charge-and-dipole source.

Classes

Functions