interface class to simple-dftd3, Grimme's D3 empirical dispersion correction More...

#include <dispersion.h>

Collaboration diagram for madness::DispersionCorrection:

[legend]

Public Member Functions
	DispersionCorrection ()=default
	default ctor – inactive, energy() is 0.0 and gradient() is all zeros

	DispersionCorrection (const std::string &spec, const std::string &xc_line, const std::string &functional, const bool atm)
	construct from the `dft` input group

bool	active () const
	true if a correction is actually being applied

std::string	description () const
	short human-readable tag, e.g. "D3(BJ)/pbe0" – "none" if inactive

double	energy (World &world, const Molecule &mol) const
	the dispersion energy in Hartree; 0.0 if inactive

Tensor< double >	gradient (World &world, const Molecule &mol) const
	d E_disp / d R in Hartree/bohr, length 3natom, laid out [3atom + axis]

Tensor< double >	hessian (World &world, const Molecule &mol) const
	d^2 E_disp / dR_i dR_j in Hartree/bohr^2, (3natom, 3natom)

void	print_citation (World &world) const
	print the method and its primary references; a no-op if inactive

void	reject (const char *engine) const
	same, for an already-constructed correction

Static Public Member Functions
static bool	available ()
	true if this build can compute a correction at all

static std::string	library_version ()
	linked simple-dftd3 version as "major.minor.patch", or "" if unavailable

static void	reject (const std::string &spec, const char *engine)
	throw if `spec` asks for a correction, naming the engine that cannot apply it

Private Types
enum	Damping { none , rational , zero }

Private Member Functions
void	compute (World &world, const Molecule &mol) const
	evaluate on rank 0 and broadcast; fills the cache below

void	evaluate (const std::vector< int > &numbers, const Tensor< double > &coords, double &e, Tensor< double > &g) const

Static Private Member Functions
static std::vector< int >	atomic_numbers (const Molecule &mol)
	the atomic numbers, ordered to match Molecule::get_all_coords()

Private Attributes
bool	atm = false
	include the three-body ATM term

bool	cache_valid = false

Tensor< double >	cached_coords

double	cached_energy = 0.0

Tensor< double >	cached_gradient

bool	citation_printed = false

Damping	damping = none

std::string	method
	the method name handed to simple-dftd3's parameter tables

Detailed Description

interface class to simple-dftd3, Grimme's D3 empirical dispersion correction

The D3 correction is a closed-form function of the nuclear coordinates alone: it touches neither the density nor the Fock matrix, so it enters a calculation as one additive number in the total energy and one additive tensor in the nuclear gradient.

References

S. Grimme, J. Antony, S. Ehrlich, H. Krieg, J. Chem. Phys. 132, 154104 (2010), doi:10.1063/1.3382344 [the D3 model]
S. Grimme, S. Ehrlich, L. Goerigk, J. Comput. Chem. 32, 1456 (2011), doi:10.1002/jcc.21759 [BJ damping]
implementation: https://github.com/dftd3/simple-dftd3

Requires MADNESS to be configured against simple-dftd3 (-DENABLE_DFTD3=ON, the default, plus a discoverable install); a default constructed object is inactive and returns zeros, but asking for an actual correction in a build without the library throws.

Member Enumeration Documentation

◆ Damping

enum madness::DispersionCorrection::Damping

private

Enumerator
none
rational
zero

Constructor & Destructor Documentation

◆ DispersionCorrection() [1/2]

madness::DispersionCorrection::DispersionCorrection ( )

default

default ctor – inactive, energy() is 0.0 and gradient() is all zeros

◆ DispersionCorrection() [2/2]

madness::DispersionCorrection::DispersionCorrection	(	const std::string &	spec,
		const std::string &	xc_line,
		const std::string &	functional,
		const bool	atm
	)

construct from the dft input group

Parameters

[in]	spec	"none", "d3bj" or "d3zero" (the `dispersion` keyword)
[in]	xc_line	the `xc` input line; its first token is the fallback source for the damping parameter set
[in]	functional	explicit functional name (the `dispersion_functional` keyword); empty means derive it from `xc_line`
[in]	atm	include the three-body Axilrod-Teller-Muto term

References atm, damping, madness::error(), MADNESS_EXCEPTION, method, none, madness::nonlinear_vector_solver(), param, madness::print(), rational, and zero.

Member Function Documentation

◆ active()

bool madness::DispersionCorrection::active ( ) const

inline

true if a correction is actually being applied

References damping, and none.

Referenced by madness::SCF::solve().

◆ atomic_numbers()

std::vector< int > madness::DispersionCorrection::atomic_numbers ( const Molecule & mol )

staticprivate

the atomic numbers, ordered to match Molecule::get_all_coords()

the atomic numbers, in the order simple-dftd3 expects the coordinates

References madness::Molecule::get_atomic_number(), madness::Molecule::natom(), and madness::nonlinear_vector_solver().

Referenced by compute(), and hessian().

◆ available()

bool madness::DispersionCorrection::available ( )

static

true if this build can compute a correction at all

Referenced by main().

◆ compute()

void madness::DispersionCorrection::compute	(	World &	world,
		const Molecule &	mol
	)		const

private

evaluate on rank 0 and broadcast; fills the cache below

References atomic_numbers(), madness::WorldGopInterface::broadcast(), cache_valid, cached_coords, cached_energy, cached_gradient, madness::copy(), e(), evaluate(), madness::g, madness::Molecule::get_all_coords(), madness::World::gop, madness::Molecule::natom(), madness::nonlinear_vector_solver(), madness::World::rank(), and madness::BaseTensor::size().

Referenced by energy(), and gradient().

◆ description()

std::string madness::DispersionCorrection::description ( ) const

short human-readable tag, e.g. "D3(BJ)/pbe0" – "none" if inactive

References atm, d, damping, method, none, and rational.

Referenced by print_citation(), and reject().

◆ energy()

double madness::DispersionCorrection::energy	(	World &	world,
		const Molecule &	mol
	)		const

the dispersion energy in Hartree; 0.0 if inactive

References cached_energy, compute(), damping, and none.

Referenced by madness::SCF::solve().

◆ evaluate()

void madness::DispersionCorrection::evaluate	(	const std::vector< int > &	numbers,
		const Tensor< double > &	coords,
		double &	e,
		Tensor< double > &	g
	)		const

private

one library call: energy and gradient for a geometry. Rank-local and uncached, so the finite differences in hessian() neither communicate per displacement nor evict the cache.

References atm, damping, e(), madness::error(), madness::g, MADNESS_EXCEPTION, method, madness::nonlinear_vector_solver(), param, madness::Tensor< T >::ptr(), rational, and sigma.

Referenced by compute(), and hessian().

◆ gradient()

Tensor< double > madness::DispersionCorrection::gradient	(	World &	world,
		const Molecule &	mol
	)		const

d E_disp / d R in Hartree/bohr, length 3*natom, laid out [3*atom + axis]

Same layout as SCF::derivatives and NemoBase::compute_gradient, so the result can be added to those tensors directly. All zeros if inactive.

References cached_gradient, compute(), madness::copy(), damping, madness::Molecule::natom(), and none.

Referenced by madness::SCF::derivatives().

◆ hessian()

Tensor< double > madness::DispersionCorrection::hessian	(	World &	world,
		const Molecule &	mol
	)		const

d^2 E_disp / dR_i dR_j in Hartree/bohr^2, (3*natom, 3*natom)

Same [3*atom + axis] index convention as gradient(), so the result can be added straight to Nemo::hessian's matrix. All zeros if inactive.

Central differences of the analytic gradient. simple-dftd3 grew an analytic Hessian (dftd3_get_dispersion_hessian) only in its 1.6 API, which no release carries yet; differencing costs 6*natom library calls of a few microseconds each and lands ~1e-9 Ha/bohr^2 from the exact result, orders of magnitude below the error of the electronic Hessian it joins.

References atomic_numbers(), madness::WorldGopInterface::broadcast(), madness::copy(), damping, e(), evaluate(), madness::Molecule::get_all_coords(), madness::World::gop, h(), madness::Molecule::natom(), none, madness::nonlinear_vector_solver(), madness::World::rank(), and x0.

◆ library_version()

std::string madness::DispersionCorrection::library_version ( )

static

linked simple-dftd3 version as "major.minor.patch", or "" if unavailable

References madness::nonlinear_vector_solver(), and v.

Referenced by main(), and print_citation().

◆ print_citation()

void madness::DispersionCorrection::print_citation ( World & world ) const

print the method and its primary references; a no-op if inactive

Prints at most once per object, so callers on a path that repeats per geometry step (Nemo::value) need no guard of their own.

References citation_printed, damping, description(), library_version(), none, madness::nonlinear_vector_solver(), madness::print(), madness::World::rank(), and rational.

Referenced by main().

◆ reject() [1/2]

void madness::DispersionCorrection::reject ( const char * engine ) const

inline

same, for an already-constructed correction

References description(), madness::nonlinear_vector_solver(), and reject().

Referenced by reject().

◆ reject() [2/2]

void madness::DispersionCorrection::reject	(	const std::string &	spec,
		const char *	engine
	)

static

throw if spec asks for a correction, naming the engine that cannot apply it

For engines whose energy expression has no dispersion term. Silently dropping the correction would report an uncorrected energy as the answer to a deck that asked for a corrected one. A no-op for "none"/"", so call sites need no guard of their own.

Takes the raw dispersion keyword because not every such engine owns an SCF to ask – Znemo carries a bare CalculationParameters.

References MADNESS_EXCEPTION, madness::nonlinear_vector_solver(), and madness::print().

Referenced by test_bad_input(), and madness::Znemo::value().

Member Data Documentation

◆ atm

bool madness::DispersionCorrection::atm = false

private

include the three-body ATM term

Referenced by DispersionCorrection(), description(), and evaluate().

◆ cache_valid

bool madness::DispersionCorrection::cache_valid = false

mutableprivate

Referenced by compute().

◆ cached_coords

Tensor<double> madness::DispersionCorrection::cached_coords

mutableprivate

memoized result – SCF::solve asks once per iteration for a quantity that only changes when the optimizer moves the nuclei

Referenced by compute().

◆ cached_energy

double madness::DispersionCorrection::cached_energy = 0.0

mutableprivate

Referenced by compute(), and energy().

◆ cached_gradient

Tensor<double> madness::DispersionCorrection::cached_gradient

mutableprivate

Referenced by compute(), and gradient().

◆ citation_printed

bool madness::DispersionCorrection::citation_printed = false

mutableprivate

Referenced by print_citation().

◆ damping

Damping madness::DispersionCorrection::damping = none

private

Referenced by DispersionCorrection(), active(), description(), energy(), evaluate(), gradient(), hessian(), and print_citation().

◆ method

std::string madness::DispersionCorrection::method

private

the method name handed to simple-dftd3's parameter tables

Referenced by DispersionCorrection(), description(), and evaluate().

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

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ Damping

Constructor & Destructor Documentation

◆ DispersionCorrection() [1/2]

◆ DispersionCorrection() [2/2]

Member Function Documentation

◆ active()

◆ atomic_numbers()

◆ available()

◆ compute()

◆ description()

◆ energy()

◆ evaluate()

◆ gradient()

◆ hessian()

◆ library_version()

◆ print_citation()

◆ reject() [1/2]

◆ reject() [2/2]

Member Data Documentation

◆ atm

◆ cache_valid

◆ cached_coords

◆ cached_energy

◆ cached_gradient

◆ citation_printed

◆ damping

◆ method