occ
Loading...
Searching...
No Matches
Public Member Functions | List of all members
occ::xtb::XtbSolvationModel Class Referenceabstract

Abstract interface for an implicit-solvent contribution to a GFN-xTB SCC. More...

#include <solvation_interface.h>

Inheritance diagram for occ::xtb::XtbSolvationModel:
[legend]

Public Member Functions

virtual ~XtbSolvationModel ()=default
 
virtual void initialize (const Mat3N &positions_bohr, const IVec &atomic_numbers)=0
 
virtual void update (const Vec &atomic_charges)=0
 
virtual void update (const Vec &atomic_charges, const Mat3N &, const Mat &)
 Update from the atomic charges together with the CAMM atomic dipoles (3 × N) and traceless quadrupoles (6 × N, CammMoments::qp layout), so the anisotropic part of the density polarises the continuum too.
 
virtual void set_multipole_damping (const Vec &, double, double)
 Hand the model the solute's own short-range damping radii for the atom→cavity dipole and quadrupole kernels, so a multipolar reaction field treats the CAMM moments the way the rest of the method does.
 
virtual const Vec & atom_potential () const =0
 
virtual const Mat3N & dipole_potential () const
 Conjugates of the atomic dipoles and quadrupoles at the last update: ∂E_solv/∂μ (3 × N) and ∂E_solv/∂Θ (6 × N, same layout as the input).
 
virtual const Mat & quadrupole_potential () const
 
virtual const Vec & damping_radius_gradient () const
 ∂E_solv/∂R_co per atom, for damping radii that depend on the geometry.
 
virtual double energy () const =0
 
virtual std::string name () const =0
 
virtual std::optional< SolvationSurfaces > surfaces () const
 Optional per-element decomposition of the latest solvation contribution.
 
virtual Mat3N gradient () const
 Analytical gradient of the solvation energy with respect to atomic positions (Hartree/Bohr, 3 × N_atoms).
 

Detailed Description

Abstract interface for an implicit-solvent contribution to a GFN-xTB SCC.

Concrete models (CPCM-X in Phase 7B, SMD in Phase 7C) implement an atom-resolved potential shift folded into the per-shell isotropic V plus a scalar energy term added to the SCC breakdown. The contract is:

  1. initialize(positions, Z) is called once at the top of an SCC, after the engine has built its geometry caches. The model sizes its internal buffers and (re)builds the cavity here.
  2. update(atom_charges) is called at the start of every SCC iteration with the input-iter atomic Mulliken charges (length = N_atoms). The model solves its surface response and caches energy + potential.
  3. atom_potential() returns the cached per-atom V_solv (Hartree), length = N_atoms. The engine adds V_solv[atom_of(s)] to the per-shell iso V before forming H.
  4. energy() returns the cached scalar contribution to scc_energy, Hartree, evaluated against the same atom_charges passed to update().

NullSolvationModel below is a no-op implementation used as a gate during Phase 7A — it must not perturb gas-phase numbers.

Constructor & Destructor Documentation

◆ ~XtbSolvationModel()

virtual occ::xtb::XtbSolvationModel::~XtbSolvationModel ( )
virtualdefault

Member Function Documentation

◆ atom_potential()

virtual const Vec & occ::xtb::XtbSolvationModel::atom_potential ( ) const
pure virtual

Implemented in occ::xtb::CpcmXSolvationModel, occ::xtb::SmdSolvationModel, and occ::xtb::NullSolvationModel.

◆ damping_radius_gradient()

virtual const Vec & occ::xtb::XtbSolvationModel::damping_radius_gradient ( ) const
inlinevirtual

∂E_solv/∂R_co per atom, for damping radii that depend on the geometry.

The caller closes the chain through its own ∂R_co/∂CN and ∂CN/∂R. Empty when the model applies no damping.

Reimplemented in occ::xtb::SmdSolvationModel.

◆ dipole_potential()

virtual const Mat3N & occ::xtb::XtbSolvationModel::dipole_potential ( ) const
inlinevirtual

Conjugates of the atomic dipoles and quadrupoles at the last update: ∂E_solv/∂μ (3 × N) and ∂E_solv/∂Θ (6 × N, same layout as the input).

The SCC folds these into its anisotropic potentials so the reaction field reaches the Fock matrix through the multipole channels as well as the charge one. Both are empty unless the model took the multipole update.

Reimplemented in occ::xtb::SmdSolvationModel.

◆ energy()

virtual double occ::xtb::XtbSolvationModel::energy ( ) const
pure virtual

Implemented in occ::xtb::CpcmXSolvationModel, occ::xtb::SmdSolvationModel, and occ::xtb::NullSolvationModel.

◆ gradient()

virtual Mat3N occ::xtb::XtbSolvationModel::gradient ( ) const
inlinevirtual

Analytical gradient of the solvation energy with respect to atomic positions (Hartree/Bohr, 3 × N_atoms).

Frozen-cavity convention — the cavity points move rigidly with their parent atoms and per-element areas are constant. Concrete models override; the default returns an empty matrix so callers can detect "no gradient available" without surprise.

Reimplemented in occ::xtb::CpcmXSolvationModel, and occ::xtb::SmdSolvationModel.

◆ initialize()

virtual void occ::xtb::XtbSolvationModel::initialize ( const Mat3N &  positions_bohr,
const IVec &  atomic_numbers 
)
pure virtual

Implemented in occ::xtb::NullSolvationModel, occ::xtb::CpcmXSolvationModel, and occ::xtb::SmdSolvationModel.

◆ name()

virtual std::string occ::xtb::XtbSolvationModel::name ( ) const
pure virtual

Implemented in occ::xtb::CpcmXSolvationModel, occ::xtb::SmdSolvationModel, and occ::xtb::NullSolvationModel.

◆ quadrupole_potential()

virtual const Mat & occ::xtb::XtbSolvationModel::quadrupole_potential ( ) const
inlinevirtual

Reimplemented in occ::xtb::SmdSolvationModel.

◆ set_multipole_damping()

virtual void occ::xtb::XtbSolvationModel::set_multipole_damping ( const Vec &  ,
double  ,
double   
)
inlinevirtual

Hand the model the solute's own short-range damping radii for the atom→cavity dipole and quadrupole kernels, so a multipolar reaction field treats the CAMM moments the way the rest of the method does.

Called once per geometry, before the first update. The default ignores them.

Reimplemented in occ::xtb::SmdSolvationModel.

◆ surfaces()

virtual std::optional< SolvationSurfaces > occ::xtb::XtbSolvationModel::surfaces ( ) const
inlinevirtual

Optional per-element decomposition of the latest solvation contribution.

Concrete models (CPCM-X, SMD) override; the default returns std::nullopt. Reflects the state at the most recent update(q).

Reimplemented in occ::xtb::CpcmXSolvationModel, and occ::xtb::SmdSolvationModel.

◆ update() [1/2]

virtual void occ::xtb::XtbSolvationModel::update ( const Vec &  atomic_charges)
pure virtual

Implemented in occ::xtb::NullSolvationModel, occ::xtb::CpcmXSolvationModel, occ::xtb::SmdSolvationModel, occ::xtb::CpcmXSolvationModel, and occ::xtb::NullSolvationModel.

◆ update() [2/2]

virtual void occ::xtb::XtbSolvationModel::update ( const Vec &  atomic_charges,
const Mat3N &  ,
const Mat &   
)
inlinevirtual

Update from the atomic charges together with the CAMM atomic dipoles (3 × N) and traceless quadrupoles (6 × N, CammMoments::qp layout), so the anisotropic part of the density polarises the continuum too.

The default drops them, which leaves charge-only models unchanged.

Reimplemented in occ::xtb::CpcmXSolvationModel, occ::xtb::NullSolvationModel, and occ::xtb::SmdSolvationModel.

The documentation for this class was generated from the following file: