Electronic ground-state via Density-Functional Theory. More...

#include <dftengine.h>

Collaboration diagram for votca::xtp::DFTEngine:

[legend]

Classes
struct	SpinDensity
struct	CDFTConstraintSpec

Public Member Functions
void	Initialize (tools::Property &options)
	Read DFT, grid, and SCF settings from the user options tree.
void	setLogger (Logger *pLog)
	Attach the logger used for SCF progress and diagnostics.
void	setExternalcharges (std::vector< std::unique_ptr< StaticSite > > *externalsites)
bool	Evaluate (Orbitals &orb)
bool	RunCDFT (Orbitals &orb, HirshfeldPartition::Constraint &constraint)
bool	EvaluateActiveRegion (Orbitals &orb)
bool	EvaluateTruncatedActiveRegion (Orbitals &trunc_orb)
std::string	getDFTBasisName () const
	Return the configured AO basis-set name for the DFT calculation.
bool	IsRestrictedOpenShell () const
Index	NumberOfRestrictedOccupiedOrbitals () const
SpinDensity	BuildSpinDensity (const tools::EigenSystem &MOs) const
ConvergenceAcc::options	BuildConvergenceOptions () const
void	setForceUKSPath (bool force)

Private Member Functions
void	Prepare (Orbitals &orb, Index numofelectrons=-1)
Vxc_Potential< Vxc_Grid >	SetupVxc (const QMMolecule &mol)
Eigen::MatrixXd	OrthogonalizeGuess (const Eigen::MatrixXd &GuessMOs) const
	Orthonormalize an initial MO guess with respect to the AO overlap matrix.
void	PrintMOs (const Eigen::VectorXd &MOEnergies, Log::Level level)
	Print a one-spin list of orbital energies and occupations to the logger.
void	PrintMOsUKS (const Eigen::VectorXd &alpha_energies, const Eigen::VectorXd &beta_energies, Log::Level level) const
	Print separate alpha and beta orbital energies for a UKS calculation.
void	CalcElDipole (const Orbitals &orb) const
	Evaluate and print the electronic dipole moment from the final density.
std::array< Eigen::MatrixXd, 2 >	CalcERIs_EXX (const Eigen::MatrixXd &MOCoeff, const Eigen::MatrixXd &Dmat, double error) const
Eigen::MatrixXd	CalcERIs (const Eigen::MatrixXd &Dmat, double error) const
	Build the Coulomb matrix contribution from the current density matrix.
void	ConfigOrbfile (Orbitals &orb)
	Propagate basis-set, XC, and metadata settings into the orbital container.
void	SetupInvariantMatrices ()
	Precompute AO matrices that remain unchanged throughout the SCF procedure.
Eigen::MatrixXd	McWeenyPurification (Eigen::MatrixXd &Dmat_in, AOOverlap &overlap)
Mat_p_Energy	SetupH0 (const QMMolecule &mol) const
	Assemble the one-electron core Hamiltonian for the current molecule.
Mat_p_Energy	IntegrateExternalMultipoles (const QMMolecule &mol, const std::vector< std::unique_ptr< StaticSite > > &multipoles) const
Mat_p_Energy	IntegrateExternalDensity (const QMMolecule &mol, const Orbitals &extdensity) const
Eigen::MatrixXd	IntegrateExternalField (const QMMolecule &mol) const
	Integrate a homogeneous external electric field into the AO basis.
tools::EigenSystem	IndependentElectronGuess (const Mat_p_Energy &H0) const
	Generate an initial guess by diagonalizing the core Hamiltonian only.
tools::EigenSystem	ModelPotentialGuess (const Mat_p_Energy &H0, const QMMolecule &mol, const Vxc_Potential< Vxc_Grid > &vxcpotential) const
Eigen::MatrixXd	AtomicGuess (const QMMolecule &mol) const
	Build an atomic-density based initial guess in the AO basis.
Eigen::VectorXd	BuildEHTOrbitalEnergies (const QMMolecule &mol) const
	Build orbital energies used in the extended-Hückel starting guess.
Eigen::MatrixXd	BuildEHTHamiltonian (const QMMolecule &mol) const
	Build the extended-Hückel Hamiltonian for the current molecule.
tools::EigenSystem	ExtendedHuckelGuess (const QMMolecule &mol) const
tools::EigenSystem	ExtendedHuckelDFTGuess (const Mat_p_Energy &H0, const QMMolecule &mol, const Vxc_Potential< Vxc_Grid > &vxcpotential) const
Orbitals	BuildDimerGuessFromMonomerFiles (const QMMolecule &dimer_mol) const
Eigen::MatrixXd	RunAtomicDFT_unrestricted (const QMAtom &uniqueAtom, bool use_hunds_rule_occupation=false) const
std::map< std::string, Eigen::MatrixXd >	ComputeHirshfeldReferenceDensities (const QMMolecule &mol) const
HirshfeldPartition::Constraint	BuildCDFTConstraint (const QMMolecule &mol, const CDFTConstraintSpec &spec) const
double	NuclearRepulsion (const QMMolecule &mol) const
	Compute the classical nucleus-nucleus repulsion energy.
double	ExternalRepulsion (const QMMolecule &mol, const std::vector< std::unique_ptr< StaticSite > > &multipoles) const
Eigen::MatrixXd	SphericalAverageShells (const Eigen::MatrixXd &dmat, const AOBasis &dftbasis) const
void	TruncateBasis (Orbitals &orb, std::vector< Index > &activeatoms, Mat_p_Energy &H0, Eigen::MatrixXd InitialActiveDensityMatrix, Eigen::MatrixXd v_embedding, Eigen::MatrixXd InitialInactiveMOs)
void	TruncMOsFullBasis (Orbitals &orb, std::vector< Index > activeatoms, std::vector< Index > numfuncpatom)
Eigen::MatrixXd	InsertZeroCols (Eigen::MatrixXd MOsMatrix, Index startidx, Index numofzerocols)
Eigen::MatrixXd	InsertZeroRows (Eigen::MatrixXd MOsMatrix, Index startidx, Index numofzerorows)
	Insert zero rows into an MO coefficient matrix at the requested position.
bool	EvaluateClosedShell (Orbitals &orb, const Mat_p_Energy &H0, const Vxc_Potential< Vxc_Grid > &vxcpotential)
	Run the restricted closed-shell SCF loop and store the converged result.
bool	EvaluateUKS (Orbitals &orb, const Mat_p_Energy &H0, const Vxc_Potential< Vxc_Grid > &vxcpotential)
void	ComputeAndStoreForces (Orbitals &orb, const Eigen::MatrixXd &Dmat, const Vxc_Potential< Vxc_Grid > &vxcpotential) const
Eigen::MatrixXd	ComputeOverlapPulayGradientUKS (const QMMolecule &mol, const tools::EigenSystem &MOs_alpha, const tools::EigenSystem &MOs_beta) const
Eigen::MatrixXd	ComputeNonXCGradientUKS (const QMMolecule &mol, const UKSConvergenceAcc::SpinDensity &Dspin, const tools::EigenSystem &MOs_alpha, const tools::EigenSystem &MOs_beta) const
void	ComputeAndStoreForcesUKS (Orbitals &orb, const UKSConvergenceAcc::SpinDensity &Dspin, const tools::EigenSystem &MOs_alpha, const tools::EigenSystem &MOs_beta, const Vxc_Potential< Vxc_Grid > &vxcpotential) const

Private Attributes
Logger *	pLog_
std::string	auxbasis_name_
std::string	dftbasis_name_
std::string	ecp_name_
AOBasis	dftbasis_
AOBasis	auxbasis_
ECPAOBasis	ecp_
Index	fock_matrix_reset_
double	screening_eps_
std::string	grid_name_
AOOverlap	dftAOoverlap_
std::string	initial_guess_
std::string	dimer_guess_orbA_name_
std::string	dimer_guess_orbB_name_
Index	numofelectrons_ = 0
Index	max_iter_
ConvergenceAcc::options	conv_opt_
ConvergenceAcc	conv_accelerator_
ERIs	ERIs_
std::vector< std::unique_ptr< StaticSite > > *	externalsites_ = nullptr
double	ScaHFX_
std::string	xc_functional_name_
bool	integrate_ext_density_ = false
std::string	orbfilename_
std::string	gridquality_
std::string	state_
QMMolecule	activemol_
Eigen::Vector3d	extfield_ = Eigen::Vector3d::Zero()
bool	integrate_ext_field_ = false
std::string	active_atoms_as_string_
double	active_threshold_
double	levelshift_
Eigen::MatrixXd	H0_trunc_
Eigen::MatrixXd	InitialActiveDmat_trunc_
Eigen::MatrixXd	v_embedding_trunc_
bool	truncate_
Index	active_electrons_
double	Total_E_full_
double	E_nuc_
double	truncation_threshold_
std::vector< Index >	active_and_border_atoms_
std::vector< Index >	numfuncpatom_
Index	num_alpha_electrons_ = 0
Index	num_beta_electrons_ = 0
Index	num_docc_ = 0
Index	num_socc_alpha_ = 0
Index	spin_ = 1
Index	charge_ = 0
bool	force_uks_path_ = false
bool	compute_forces_ = false
std::vector< HirshfeldPartition::Constraint >	constraints_
Index	max_cdft_iterations_ = 50
double	cdft_population_tolerance_ = 1.e-4
bool	cdft_enabled_ = false
CDFTConstraintSpec	cdft_constraint_spec_

Friends
class	DFTEngineTestAccess

Detailed Description

Electronic ground-state via Density-Functional Theory.

This class assembles the one- and two-electron matrix contributions needed for self-consistent Kohn-Sham calculations in a Gaussian AO basis. The SCF machinery supports restricted closed-shell calculations and unrestricted spin-polarized calculations, while reusing the same integral and numerical XC infrastructure whenever possible.

Definition at line 73 of file dftengine.h.

Member Function Documentation

◆ AtomicGuess()

Eigen::MatrixXd votca::xtp::DFTEngine::AtomicGuess ( const QMMolecule & mol ) const

private

Build an atomic-density based initial guess in the AO basis.

Definition at line 2110 of file dftengine.cc.

◆ BuildCDFTConstraint()

HirshfeldPartition::Constraint votca::xtp::DFTEngine::BuildCDFTConstraint	(	const QMMolecule &	mol,
		const CDFTConstraintSpec &	spec ) const

private

Converts a parsed CDFTConstraintSpec (atom indices + relative target charge, from Initialize()'s own <cdft> options parsing) into a fully-built HirshfeldPartition::Constraint, given the real molecule this calculation is actually running on. Builds the weight matrix as the SUM of BuildWeightMatrix over every atom in spec.atom_indices – Hirshfeld weights are additive across atoms in a fragment (w_fragment(r) = sum_{i in fragment} w_i(r)), so this generalizes correctly to a multi-atom region, not just a single atom. The absolute target_population is computed as (sum of the fragment atoms' own nuclear charges) - spec.target_charge, matching CP2K's own internal (absolute) TARGET convention – only the OPTIONS-file syntax is charge-relative, per the earlier design discussion on this; the underlying Constraint/RunCDFT machinery itself was never changed and still only ever deals in absolute populations.

Definition at line 2173 of file dftengine.cc.

◆ BuildConvergenceOptions()

ConvergenceAcc::options votca::xtp::DFTEngine::BuildConvergenceOptions ( ) const

Assemble SCF acceleration settings consistent with the current spin treatment and occupation model.

◆ BuildDimerGuessFromMonomerFiles()

Orbitals votca::xtp::DFTEngine::BuildDimerGuessFromMonomerFiles ( const QMMolecule & dimer_mol ) const

private

Build a dimer guess (both alpha and beta MOs, genuinely different from each other in general) by loading two independently-converged monomer .orb files (dimer_guess_orbA_name_/dimer_guess_orbB_name_) and combining them via Orbitals::PrepareDimerGuessMixedSpin.

Runs two sanity checks against dimer_mol (this calculation's own, real molecule) before trusting either monomer file at all: (1) element-sequence match – monomer A's own elements, in order, must exactly match dimer_mol's first N_A atoms, and monomer B's must match the remaining atoms; (2) internal-geometry match – every pairwise interatomic distance WITHIN monomer A must match the corresponding pairwise distance within dimer_mol's own first N_A atoms, to a tight numerical tolerance (and likewise for monomer B against the remaining atoms). Deliberately NOT an absolute-position comparison: after being optimized as a standalone monomer and then placed into the dimer, a monomer's atoms are expected to be translated/rotated relative to their own, independent optimization – only the INTERNAL geometry (bond lengths/angles, which no translation or rotation changes) should still match if the supplied file genuinely corresponds to that fragment.

Definition at line 2686 of file dftengine.cc.

◆ BuildEHTHamiltonian()

Eigen::MatrixXd votca::xtp::DFTEngine::BuildEHTHamiltonian ( const QMMolecule & mol ) const

private

Build the extended-Hückel Hamiltonian for the current molecule.

Definition at line 2629 of file dftengine.cc.

◆ BuildEHTOrbitalEnergies()

Eigen::VectorXd votca::xtp::DFTEngine::BuildEHTOrbitalEnergies ( const QMMolecule & mol ) const

private

Build orbital energies used in the extended-Hückel starting guess.

Definition at line 2601 of file dftengine.cc.

◆ BuildSpinDensity()

SpinDensity votca::xtp::DFTEngine::BuildSpinDensity ( const tools::EigenSystem & MOs ) const

Construct alpha and beta density matrices from a shared MO coefficient matrix and the current occupation metadata.

◆ CalcElDipole()

void votca::xtp::DFTEngine::CalcElDipole ( const Orbitals & orb ) const

private

Evaluate and print the electronic dipole moment from the final density.

Definition at line 383 of file dftengine.cc.

◆ CalcERIs()

Eigen::MatrixXd votca::xtp::DFTEngine::CalcERIs	(	const Eigen::MatrixXd &	Dmat,
		double	error ) const

private

Build the Coulomb matrix contribution from the current density matrix.

Definition at line 836 of file dftengine.cc.

◆ CalcERIs_EXX()

std::array< Eigen::MatrixXd, 2 > votca::xtp::DFTEngine::CalcERIs_EXX	(	const Eigen::MatrixXd &	MOCoeff,
		const Eigen::MatrixXd &	Dmat,
		double	error ) const

private

Build Coulomb and exact-exchange matrix contributions from the current MO coefficients and density.

Definition at line 819 of file dftengine.cc.

◆ ComputeAndStoreForces()

void votca::xtp::DFTEngine::ComputeAndStoreForces	(	Orbitals &	orb,
		const Eigen::MatrixXd &	Dmat,
		const Vxc_Potential< Vxc_Grid > &	vxcpotential ) const

private

Assemble the total ground-state nuclear gradient (one-electron [kinetic + nuclear attraction] + overlap "Pulay force" + nuclear repulsion + RI-J Coulomb + RI-K exact exchange [hybrid functionals]

XC, LDA or GGA) from a converged density matrix and store it in the orbital container via Orbitals::setForces(), as the physical force (-dE/dR, matching the convention external tools such as ASE expect from a Calculator's getForces()).

The one-electron term and the overlap Pulay force were initially MISSING entirely – discovered by the first genuine end-to-end SCF+forces test (test_dftengine_forces.cc), since every earlier gradient test in this branch validated individual terms against fixed density matrices without ever checking the complete gradient against a real total SCF energy. The overlap Pulay force (arising because the MO orthonormality constraint C^T S C = I depends on geometry through the moving basis functions, weighted by orbital energies rather than occupation) is a standard part of any Gaussian-basis SCF gradient, distinct from the "PulayGradient" naming used elsewhere in this codebase for the XC-integral basis-function term.

RI-K/hybrid-functional support was added after DFTGradient:: RIKGradient's energy convention was fixed (a self-introduced regression during that work: a plausible-looking hand-algebra "correction" to a half-transformed structure was wrong, caught by directly, numerically simulating ERIs::CalculateEXX_mos's real algorithm before committing to it – the original fully-MO- transformed structure was correct, needing only a missing factor of 2) and then verified via a real C++ finite-difference test against ERIs::CalculateEXX_mos itself, not just a self-consistent formula. Also confirmed (numerically, to machine precision): CalculateEXX_mos's symmetric V^-1/2 RI fitting and RIKGradient's simpler asymmetric V^-1 fitting give IDENTICAL exchange energies (an exact algebraic identity for symmetric positive-definite V), so no matrix square root derivative was ever actually needed.

SCOPE, explicitly checked and logged rather than silently producing a wrong result: only supported when RI is actually in use for the SCF (auxbasis_name_ non-empty – DFTGradient::RIJGradient/RIKGradient only implement the RI path, not conventional 4-center ERIs).

OPT-IN: only called at all if compute_forces_ is true (see its declaration below), settable via <xtpdft><compute_forces>true</compute_forces></xtpdft> in the options tree, defaulting to false. Computing forces adds real, non-trivial cost to every converged SCF, so this is deliberately not silently always-on – added after this was pointed out as an unflagged side effect of the original, unconditional wiring.

Definition at line 421 of file dftengine.cc.

◆ ComputeAndStoreForcesUKS()

void votca::xtp::DFTEngine::ComputeAndStoreForcesUKS	(	Orbitals &	orb,
		const UKSConvergenceAcc::SpinDensity &	Dspin,
		const tools::EigenSystem &	MOs_alpha,
		const tools::EigenSystem &	MOs_beta,
		const Vxc_Potential< Vxc_Grid > &	vxcpotential ) const

private

UKS (open-shell) analog of ComputeAndStoreForces.

STATUS: PARTIAL, deliberately. Four of the five non-XC-adjacent terms generalize cleanly to UKS and are implemented here: nuclear repulsion (unchanged), one-electron [kinetic + nuclear attraction] (uses D_total = Dspin.alpha + Dspin.beta, exactly the same convention RKS's Dmat already uses), the overlap Pulay force (W = W_alpha + W_beta, each WITHOUT the factor of 2 RKS uses, since UKS spin densities are not pre-doubled), and RI-K exact exchange for hybrids (0.5 * ScaHFX_ * [RIKGradient(C_alpha_occ,...) + RIKGradient(C_beta_occ,...)] – the extra factor of 0.5 relative to the naive guess of ScaHFX_*(...) confirmed both algebraically and numerically: ERIs::CalculateEXX_dmat(P) == 0.5 * ERIs::CalculateEXX_mos(C) when P = C*C^T, checked directly rather than assumed, since UKS's exact exchange goes through CalculateEXX_dmat, a different code path than the one RIKGradient/CalculateEXX_mos were validated against).

The XC gradient (PulayGradientUKS + GridWeightGradientUKS, LDA and GGA) is now included too – initially deferred as new derivation work (spin-polarized rho_alpha/rho_beta, and for GGA a genuinely new sigma_alpha-alpha/alpha-beta/beta-beta cross-term structure with no analog in the spin-restricted case), then completed and validated (Python-verified formulas first, then a real C++ finite- difference test against IntegrateVXCSpin – caught and fixed one real transcription bug, a missing factor of 2 in the GGA sigma term's Hessian contraction, found by careful line-by-line comparison against the verified Python once the first real test run showed a partial, non-catastrophic discrepancy). With XC now included, this function DOES call Orbitals::setForces(), same as the RKS ComputeAndStoreForces.

Definition at line 714 of file dftengine.cc.

◆ ComputeHirshfeldReferenceDensities()

std::map< std::string, Eigen::MatrixXd > votca::xtp::DFTEngine::ComputeHirshfeldReferenceDensities ( const QMMolecule & mol ) const

private

Build one isolated-atom reference density per unique element in mol, keyed by element symbol – the promolecular densities Hirshfeld-based CDFT constraints need. Mirrors AtomicGuess's own "find unique elements, run RunAtomicDFT_unrestricted once each, cache by element" structure exactly, but (a) always passes use_hunds_rule_occupation=true (unlike AtomicGuess's own call, which never does), and (b) returns the per-element densities directly rather than assembling them into one combined, molecule-sized AO-basis matrix – Hirshfeld only ever needs each reference density evaluated as a real-space scalar function, using that element's own (small, atom-only) basis re-centered on each real atom's actual position, never embedded into the full molecule's AO basis at all, so there is no molecule-sized object to assemble here in the first place.

Definition at line 2152 of file dftengine.cc.

◆ ComputeNonXCGradientUKS()

Eigen::MatrixXd votca::xtp::DFTEngine::ComputeNonXCGradientUKS	(	const QMMolecule &	mol,
		const UKSConvergenceAcc::SpinDensity &	Dspin,
		const tools::EigenSystem &	MOs_alpha,
		const tools::EigenSystem &	MOs_beta ) const

private

The four non-XC-adjacent gradient terms that generalize cleanly to UKS – see the detailed derivation on ComputeAndStoreForcesUKS below, which calls this and then decides whether/how to report the result (currently: never stores it, since XC is missing). Returns the (natoms x 3) dE/dR gradient directly (NOT negated to the physical force convention – that flip, if/when this becomes part of a complete, storable UKS gradient, belongs at the point of storage, same as the RKS path).

Definition at line 661 of file dftengine.cc.

◆ ComputeOverlapPulayGradientUKS()

Eigen::MatrixXd votca::xtp::DFTEngine::ComputeOverlapPulayGradientUKS	(	const QMMolecule &	mol,
		const tools::EigenSystem &	MOs_alpha,
		const tools::EigenSystem &	MOs_beta ) const

private

UKS overlap Pulay force – W = W_alpha + W_beta, each WITHOUT the factor of 2 RKS uses. Split out as its own method (rather than inlined in ComputeNonXCGradientUKS) because it needs a genuinely DIFFERENT validation strategy than the other four terms: it is NOT checkable against a fixed-C finite difference (confirmed directly by a failed attempt to do exactly that – see git history), since it specifically corrects for C's implicit R-dependence through the orthonormality constraint, valid only at a genuine SCF stationary point. See test_dftengine_private.cc for how this is actually validated instead (reduction to the already-validated RKS formula when alpha==beta).

Definition at line 613 of file dftengine.cc.

◆ ConfigOrbfile()

void votca::xtp::DFTEngine::ConfigOrbfile ( Orbitals & orb )

private

Propagate basis-set, XC, and metadata settings into the orbital container.

Definition at line 2235 of file dftengine.cc.

◆ Evaluate()

bool votca::xtp::DFTEngine::Evaluate ( Orbitals & orb )

Run a full ground-state DFT calculation and store the results in the orbital container.

Definition at line 877 of file dftengine.cc.

◆ EvaluateActiveRegion()

bool votca::xtp::DFTEngine::EvaluateActiveRegion ( Orbitals & orb )

Run an embedded active-region DFT calculation for the supplied orbital container.

Definition at line 63 of file embeddingengine.cc.

◆ EvaluateClosedShell()

bool votca::xtp::DFTEngine::EvaluateClosedShell	(	Orbitals &	orb,
		const Mat_p_Energy &	H0,
		const Vxc_Potential< Vxc_Grid > &	vxcpotential )

private

Run the restricted closed-shell SCF loop and store the converged result.

Definition at line 1099 of file dftengine.cc.

◆ EvaluateTruncatedActiveRegion()

bool votca::xtp::DFTEngine::EvaluateTruncatedActiveRegion ( Orbitals & trunc_orb )

Run the truncated active-region workflow used for reduced embedded calculations.

Definition at line 353 of file embeddingengine.cc.

◆ EvaluateUKS()

bool votca::xtp::DFTEngine::EvaluateUKS	(	Orbitals &	orb,
		const Mat_p_Energy &	H0,
		const Vxc_Potential< Vxc_Grid > &	vxcpotential )

private

Run the unrestricted Kohn-Sham SCF loop and store alpha and beta orbitals separately.

Definition at line 1306 of file dftengine.cc.

◆ ExtendedHuckelDFTGuess()

tools::EigenSystem votca::xtp::DFTEngine::ExtendedHuckelDFTGuess	(	const Mat_p_Energy &	H0,
		const QMMolecule &	mol,
		const Vxc_Potential< Vxc_Grid > &	vxcpotential ) const

private

Generate an extended-Hückel based guess refined with the one-electron DFT Hamiltonian.

Definition at line 2662 of file dftengine.cc.

◆ ExtendedHuckelGuess()

tools::EigenSystem votca::xtp::DFTEngine::ExtendedHuckelGuess ( const QMMolecule & mol ) const

private

Generate an initial guess by diagonalizing the extended-Hückel Hamiltonian.

Definition at line 2649 of file dftengine.cc.

◆ ExternalRepulsion()

double votca::xtp::DFTEngine::ExternalRepulsion	(	const QMMolecule &	mol,
		const std::vector< std::unique_ptr< StaticSite > > &	multipoles ) const

private

Compute the classical interaction energy between nuclei and external multipoles.

Definition at line 2495 of file dftengine.cc.

◆ getDFTBasisName()

std::string votca::xtp::DFTEngine::getDFTBasisName ( ) const

inline

Return the configured AO basis-set name for the DFT calculation.

Definition at line 132 of file dftengine.h.

◆ IndependentElectronGuess()

tools::EigenSystem votca::xtp::DFTEngine::IndependentElectronGuess ( const Mat_p_Energy & H0 ) const

private

Generate an initial guess by diagonalizing the core Hamiltonian only.

Definition at line 845 of file dftengine.cc.

◆ Initialize()

void votca::xtp::DFTEngine::Initialize ( tools::Property & options )

Read DFT, grid, and SCF settings from the user options tree.

Self-consistent Kohn-Sham implementation.

The SCF cycle solves F C = S C eps in a Gaussian AO basis. In the restricted branch a single density matrix is iterated, whereas in the UKS branch separate alpha and beta densities are propagated while sharing the same one-electron Hamiltonian, Coulomb term, and AO overlap matrix.

Relative to the earlier restricted implementation, the UKS extension keeps the spin channels separate only where the equations require it: exchange, spin-resolved XC potentials, occupations, and convergence acceleration.

Definition at line 100 of file dftengine.cc.

◆ InsertZeroCols()

Eigen::MatrixXd votca::xtp::DFTEngine::InsertZeroCols	(	Eigen::MatrixXd	MOsMatrix,
		Index	startidx,
		Index	numofzerocols )

private

Insert zero columns into an MO coefficient matrix at the requested position.

◆ InsertZeroRows()

Eigen::MatrixXd votca::xtp::DFTEngine::InsertZeroRows	(	Eigen::MatrixXd	MOsMatrix,
		Index	startidx,
		Index	numofzerorows )

private

Insert zero rows into an MO coefficient matrix at the requested position.

Definition at line 687 of file embeddingengine.cc.

◆ IntegrateExternalDensity()

Mat_p_Energy votca::xtp::DFTEngine::IntegrateExternalDensity	(	const QMMolecule &	mol,
		const Orbitals &	extdensity ) const

private

Integrate an external electron density represented by another orbital container.

Definition at line 2551 of file dftengine.cc.

◆ IntegrateExternalField()

Eigen::MatrixXd votca::xtp::DFTEngine::IntegrateExternalField ( const QMMolecule & mol ) const

private

Integrate a homogeneous external electric field into the AO basis.

Definition at line 2521 of file dftengine.cc.

◆ IntegrateExternalMultipoles()

Mat_p_Energy votca::xtp::DFTEngine::IntegrateExternalMultipoles	(	const QMMolecule &	mol,
		const std::vector< std::unique_ptr< StaticSite > > &	multipoles ) const

private

Integrate the electrostatic potential generated by external multipoles into the AO basis.

Definition at line 2534 of file dftengine.cc.

◆ IsRestrictedOpenShell()

bool votca::xtp::DFTEngine::IsRestrictedOpenShell ( ) const

inline

Report whether the current electron counts define a spin-polarized reference.

Definition at line 149 of file dftengine.h.

◆ McWeenyPurification()

Eigen::MatrixXd votca::xtp::DFTEngine::McWeenyPurification	(	Eigen::MatrixXd &	Dmat_in,
		AOOverlap &	overlap )

private

Apply McWeeny purification to improve the idempotency of a density-matrix guess.

Definition at line 649 of file embeddingengine.cc.

◆ ModelPotentialGuess()

tools::EigenSystem votca::xtp::DFTEngine::ModelPotentialGuess	(	const Mat_p_Energy &	H0,
		const QMMolecule &	mol,
		const Vxc_Potential< Vxc_Grid > &	vxcpotential ) const

private

Generate an initial guess from a model potential including numerical XC contributions.

Definition at line 856 of file dftengine.cc.

◆ NuclearRepulsion()

double votca::xtp::DFTEngine::NuclearRepulsion ( const QMMolecule & mol ) const

private

Compute the classical nucleus-nucleus repulsion energy.

Definition at line 2448 of file dftengine.cc.

◆ NumberOfRestrictedOccupiedOrbitals()

Index votca::xtp::DFTEngine::NumberOfRestrictedOccupiedOrbitals ( ) const

inline

Return the number of spatial orbitals occupied by at least one electron in a restricted open-shell reference.

Definition at line 155 of file dftengine.h.

◆ OrthogonalizeGuess()

Eigen::MatrixXd votca::xtp::DFTEngine::OrthogonalizeGuess ( const Eigen::MatrixXd & GuessMOs ) const

private

Orthonormalize an initial MO guess with respect to the AO overlap matrix.

Definition at line 2589 of file dftengine.cc.

◆ Prepare()

void votca::xtp::DFTEngine::Prepare	(	Orbitals &	orb,
		Index	numofelectrons = -1 )

private

Initialize basis sets, integral engines, and electron counts before entering the SCF loop.

Definition at line 2306 of file dftengine.cc.

◆ PrintMOs()

void votca::xtp::DFTEngine::PrintMOs	(	const Eigen::VectorXd &	MOEnergies,
		Log::Level	level )

private

Print a one-spin list of orbital energies and occupations to the logger.

Definition at line 303 of file dftengine.cc.

◆ PrintMOsUKS()

void votca::xtp::DFTEngine::PrintMOsUKS	(	const Eigen::VectorXd &	alpha_energies,
		const Eigen::VectorXd &	beta_energies,
		Log::Level	level ) const

private

Print separate alpha and beta orbital energies for a UKS calculation.

Definition at line 323 of file dftengine.cc.

◆ RunAtomicDFT_unrestricted()

Eigen::MatrixXd votca::xtp::DFTEngine::RunAtomicDFT_unrestricted	(	const QMAtom &	uniqueAtom,
		bool	use_hunds_rule_occupation = false ) const

private

Run an unrestricted atomic reference calculation used in open-shell atomic guesses.

use_hunds_rule_occupation (default false, preserving all EXISTING callers' behavior exactly): when true, use a small, explicit Hund's-rule ground-state alpha/beta electron-count table for common main-group (s/p-block) elements, instead of the simpler parity-based split (odd nuclear charge -> one extra alpha electron; even -> alpha == beta) used by default. That default split is wrong for many real ground states – e.g. carbon (true ground state alpha=4,beta=2, a triplet) gets alpha=beta=3 (an artificial singlet) – but this does not matter for a SAD initial-guess starting DENSITY MATRIX SHAPE (AtomicGuess, this function's only existing caller), since the full molecule's own SCF reshapes the density regardless of the isolated reference atom's spin state. It DOES matter for promolecular reference densities used in Hirshfeld-based CDFT constraints, which is what this parameter exists for. Falls back to the default, parity-based split (with a logged warning) for any element not covered by the table – currently d/f-block only, where the ground-state configuration is genuinely ambiguous/functional-dependent rather than a simple, textbook Hund's-rule case; see HundsRuleAlphaBetaElectrons's own comment in dftengine.cc.

Definition at line 1873 of file dftengine.cc.

◆ RunCDFT()

bool votca::xtp::DFTEngine::RunCDFT	(	Orbitals &	orb,
		HirshfeldPartition::Constraint &	constraint )

Run a single, charge-constrained DFT (CDFT) calculation: finds the Lagrange multiplier lambda such that Tr[(P_alpha + P_beta) * constraint.weight_matrix] equals constraint.target_population, then converges the SCF at that lambda – the standard Wu-Van Voorhis outer loop, warm-started (matching CP2K's own documented approach: each new trial's SCF is restarted from the PREVIOUS trial's converged density, not a cold start) via the existing "orbfile" initial-guess mechanism, reusing it exactly as written rather than building new warm-start machinery. Only ever wires through EvaluateUKS (never EvaluateClosedShell) – CDFT charge constraints are built on UKS from the start, per the design discussion that preceded this: a localized extra charge is almost always naturally an open-shell/ radical situation regardless of whether spin constraints are ever added later.

constraint.lambda is used as the initial guess for the bisection search (0.0 is a reasonable default for most systems) and is left holding the converged value on return. Returns false (with constraints_ left populated, holding the last-attempted lambda) if EITHER a root cannot be bracketed at all, OR the outer bisection loop exhausts max_cdft_iterations_ without reaching cdft_population_tolerance_. If any individual INNER SCF call itself fails to converge, this throws std::runtime_error instead (does not return false) – an inner SCF failure means something more fundamental than "the outer loop needs more iterations" is wrong (e.g. a genuinely bad initial guess, or too tight an SCF convergence threshold for this system), and silently returning false would look identical to the ordinary "ran out of outer iterations" case, which it is not.

Definition at line 971 of file dftengine.cc.

◆ setExternalcharges()

void votca::xtp::DFTEngine::setExternalcharges ( std::vector< std::unique_ptr< StaticSite > > * externalsites )

inline

Provide external static sites whose electrostatic potential enters the Hamiltonian.

Definition at line 83 of file dftengine.h.

◆ setForceUKSPath()

void votca::xtp::DFTEngine::setForceUKSPath ( bool force )

inline

Definition at line 168 of file dftengine.h.

◆ setLogger()

void votca::xtp::DFTEngine::setLogger ( Logger * pLog )

inline

Attach the logger used for SCF progress and diagnostics.

Definition at line 79 of file dftengine.h.

◆ SetupH0()

Mat_p_Energy votca::xtp::DFTEngine::SetupH0 ( const QMMolecule & mol ) const

private

Assemble the one-electron core Hamiltonian for the current molecule.

Definition at line 1622 of file dftengine.cc.

◆ SetupInvariantMatrices()

void votca::xtp::DFTEngine::SetupInvariantMatrices ( )

private

Precompute AO matrices that remain unchanged throughout the SCF procedure.

Definition at line 1732 of file dftengine.cc.

◆ SetupVxc()

Vxc_Potential< Vxc_Grid > votca::xtp::DFTEngine::SetupVxc ( const QMMolecule & mol )

private

Build the numerical exchange-correlation integration object for the current molecule.

Definition at line 2427 of file dftengine.cc.

◆ SphericalAverageShells()

Eigen::MatrixXd votca::xtp::DFTEngine::SphericalAverageShells	(	const Eigen::MatrixXd &	dmat,
		const AOBasis &	dftbasis ) const

private

Average density-matrix elements over functions belonging to the same atomic shell.

Definition at line 2464 of file dftengine.cc.

◆ TruncateBasis()

void votca::xtp::DFTEngine::TruncateBasis	(	Orbitals &	orb,
		std::vector< Index > &	activeatoms,
		Mat_p_Energy &	H0,
		Eigen::MatrixXd	InitialActiveDensityMatrix,
		Eigen::MatrixXd	v_embedding,
		Eigen::MatrixXd	InitialInactiveMOs )

private

Project the full-system Hamiltonian and densities onto the selected truncated active basis.

Definition at line 496 of file embeddingengine.cc.

◆ TruncMOsFullBasis()

void votca::xtp::DFTEngine::TruncMOsFullBasis	(	Orbitals &	orb,
		std::vector< Index >	activeatoms,
		std::vector< Index >	numfuncpatom )

private

Expand truncated active-region orbitals back into the full AO basis with zero padding.

Definition at line 670 of file embeddingengine.cc.

◆ DFTEngineTestAccess

friend class DFTEngineTestAccess

friend

Definition at line 171 of file dftengine.h.

Member Data Documentation

◆ active_and_border_atoms_

std::vector<Index> votca::xtp::DFTEngine::active_and_border_atoms_

private

Definition at line 586 of file dftengine.h.

◆ active_atoms_as_string_

std::string votca::xtp::DFTEngine::active_atoms_as_string_

private

Definition at line 573 of file dftengine.h.

◆ active_electrons_

Index votca::xtp::DFTEngine::active_electrons_

private

Definition at line 582 of file dftengine.h.

◆ active_threshold_

double votca::xtp::DFTEngine::active_threshold_

private

Definition at line 574 of file dftengine.h.

◆ activemol_

QMMolecule votca::xtp::DFTEngine::activemol_

private

Initial value:

=

QMMolecule("molecule made of atoms participating in Active region", 1)

votca::xtp::QMMolecule

Definition qmmolecule.h:31

Definition at line 567 of file dftengine.h.

◆ auxbasis_

AOBasis votca::xtp::DFTEngine::auxbasis_

private

Definition at line 524 of file dftengine.h.

◆ auxbasis_name_

std::string votca::xtp::DFTEngine::auxbasis_name_

private

Definition at line 520 of file dftengine.h.

◆ cdft_constraint_spec_

CDFTConstraintSpec votca::xtp::DFTEngine::cdft_constraint_spec_

private

Definition at line 640 of file dftengine.h.

◆ cdft_enabled_

bool votca::xtp::DFTEngine::cdft_enabled_ = false

private

Definition at line 639 of file dftengine.h.

◆ cdft_population_tolerance_

double votca::xtp::DFTEngine::cdft_population_tolerance_ = 1.e-4

private

Definition at line 637 of file dftengine.h.

◆ charge_

Index votca::xtp::DFTEngine::charge_ = 0

private

Definition at line 595 of file dftengine.h.

◆ compute_forces_

bool votca::xtp::DFTEngine::compute_forces_ = false

private

Definition at line 609 of file dftengine.h.

◆ constraints_

std::vector<HirshfeldPartition::Constraint> votca::xtp::DFTEngine::constraints_

private

Definition at line 626 of file dftengine.h.

◆ conv_accelerator_

ConvergenceAcc votca::xtp::DFTEngine::conv_accelerator_

private

Definition at line 550 of file dftengine.h.

◆ conv_opt_

ConvergenceAcc::options votca::xtp::DFTEngine::conv_opt_

private

Definition at line 548 of file dftengine.h.

◆ dftAOoverlap_

AOOverlap votca::xtp::DFTEngine::dftAOoverlap_

private

Definition at line 535 of file dftengine.h.

◆ dftbasis_

AOBasis votca::xtp::DFTEngine::dftbasis_

private

Definition at line 523 of file dftengine.h.

◆ dftbasis_name_

std::string votca::xtp::DFTEngine::dftbasis_name_

private

Definition at line 521 of file dftengine.h.

◆ dimer_guess_orbA_name_

std::string votca::xtp::DFTEngine::dimer_guess_orbA_name_

private

Definition at line 542 of file dftengine.h.

◆ dimer_guess_orbB_name_

std::string votca::xtp::DFTEngine::dimer_guess_orbB_name_

private

Definition at line 543 of file dftengine.h.

◆ E_nuc_

double votca::xtp::DFTEngine::E_nuc_

private

Definition at line 584 of file dftengine.h.

◆ ecp_

ECPAOBasis votca::xtp::DFTEngine::ecp_

private

Definition at line 525 of file dftengine.h.

◆ ecp_name_

std::string votca::xtp::DFTEngine::ecp_name_

private

Definition at line 522 of file dftengine.h.

◆ ERIs_

ERIs votca::xtp::DFTEngine::ERIs_

private

Definition at line 552 of file dftengine.h.

◆ externalsites_

std::vector<std::unique_ptr<StaticSite> >* votca::xtp::DFTEngine::externalsites_ = nullptr

private

Definition at line 555 of file dftengine.h.

◆ extfield_

Eigen::Vector3d votca::xtp::DFTEngine::extfield_ = Eigen::Vector3d::Zero()

private

Definition at line 570 of file dftengine.h.

◆ fock_matrix_reset_

Index votca::xtp::DFTEngine::fock_matrix_reset_

private

Definition at line 527 of file dftengine.h.

◆ force_uks_path_

bool votca::xtp::DFTEngine::force_uks_path_ = false

private

Definition at line 596 of file dftengine.h.

◆ grid_name_

std::string votca::xtp::DFTEngine::grid_name_

private

Definition at line 532 of file dftengine.h.

◆ gridquality_

std::string votca::xtp::DFTEngine::gridquality_

private

Definition at line 564 of file dftengine.h.

◆ H0_trunc_

Eigen::MatrixXd votca::xtp::DFTEngine::H0_trunc_

private

Definition at line 578 of file dftengine.h.

◆ initial_guess_

std::string votca::xtp::DFTEngine::initial_guess_

private

Definition at line 537 of file dftengine.h.

◆ InitialActiveDmat_trunc_

Eigen::MatrixXd votca::xtp::DFTEngine::InitialActiveDmat_trunc_

private

Definition at line 579 of file dftengine.h.

◆ integrate_ext_density_

bool votca::xtp::DFTEngine::integrate_ext_density_ = false

private

Definition at line 561 of file dftengine.h.

◆ integrate_ext_field_

bool votca::xtp::DFTEngine::integrate_ext_field_ = false

private

Definition at line 571 of file dftengine.h.

◆ levelshift_

double votca::xtp::DFTEngine::levelshift_

private

Definition at line 575 of file dftengine.h.

◆ max_cdft_iterations_

Index votca::xtp::DFTEngine::max_cdft_iterations_ = 50

private

Definition at line 636 of file dftengine.h.

◆ max_iter_

Index votca::xtp::DFTEngine::max_iter_

private

Definition at line 547 of file dftengine.h.

◆ num_alpha_electrons_

Index votca::xtp::DFTEngine::num_alpha_electrons_ = 0

private

Definition at line 590 of file dftengine.h.

◆ num_beta_electrons_

Index votca::xtp::DFTEngine::num_beta_electrons_ = 0

private

Definition at line 591 of file dftengine.h.

◆ num_docc_

Index votca::xtp::DFTEngine::num_docc_ = 0

private

Definition at line 592 of file dftengine.h.

◆ num_socc_alpha_

Index votca::xtp::DFTEngine::num_socc_alpha_ = 0

private

Definition at line 593 of file dftengine.h.

◆ numfuncpatom_

std::vector<Index> votca::xtp::DFTEngine::numfuncpatom_

private

Definition at line 587 of file dftengine.h.

◆ numofelectrons_

Index votca::xtp::DFTEngine::numofelectrons_ = 0

private

Definition at line 546 of file dftengine.h.

◆ orbfilename_

std::string votca::xtp::DFTEngine::orbfilename_

private

Definition at line 563 of file dftengine.h.

◆ pLog_

Logger* votca::xtp::DFTEngine::pLog_

private

Definition at line 517 of file dftengine.h.

◆ ScaHFX_

double votca::xtp::DFTEngine::ScaHFX_

private

Definition at line 558 of file dftengine.h.

◆ screening_eps_

double votca::xtp::DFTEngine::screening_eps_

private

Definition at line 529 of file dftengine.h.

◆ spin_

Index votca::xtp::DFTEngine::spin_ = 1

private

Definition at line 594 of file dftengine.h.

◆ state_

std::string votca::xtp::DFTEngine::state_

private

Definition at line 565 of file dftengine.h.

◆ Total_E_full_

double votca::xtp::DFTEngine::Total_E_full_

private

Definition at line 583 of file dftengine.h.

◆ truncate_

bool votca::xtp::DFTEngine::truncate_

private

Definition at line 581 of file dftengine.h.

◆ truncation_threshold_

double votca::xtp::DFTEngine::truncation_threshold_

private

Definition at line 585 of file dftengine.h.

◆ v_embedding_trunc_

Eigen::MatrixXd votca::xtp::DFTEngine::v_embedding_trunc_

private

Definition at line 580 of file dftengine.h.

◆ xc_functional_name_

std::string votca::xtp::DFTEngine::xc_functional_name_

private

Definition at line 559 of file dftengine.h.

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

xtp/include/votca/xtp/dftengine.h
xtp/src/libxtp/dftengine/dftengine.cc
xtp/src/libxtp/dftengine/embeddingengine.cc

Classes

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Function Documentation

◆ AtomicGuess()

◆ BuildCDFTConstraint()

◆ BuildConvergenceOptions()

◆ BuildDimerGuessFromMonomerFiles()

◆ BuildEHTHamiltonian()

◆ BuildEHTOrbitalEnergies()

◆ BuildSpinDensity()

◆ CalcElDipole()

◆ CalcERIs()

◆ CalcERIs_EXX()

◆ ComputeAndStoreForces()

◆ ComputeAndStoreForcesUKS()

◆ ComputeHirshfeldReferenceDensities()

◆ ComputeNonXCGradientUKS()

◆ ComputeOverlapPulayGradientUKS()

◆ ConfigOrbfile()

◆ Evaluate()

◆ EvaluateActiveRegion()

◆ EvaluateClosedShell()

◆ EvaluateTruncatedActiveRegion()

◆ EvaluateUKS()

◆ ExtendedHuckelDFTGuess()

◆ ExtendedHuckelGuess()

◆ ExternalRepulsion()

◆ getDFTBasisName()

◆ IndependentElectronGuess()

◆ Initialize()

◆ InsertZeroCols()

◆ InsertZeroRows()

◆ IntegrateExternalDensity()

◆ IntegrateExternalField()

◆ IntegrateExternalMultipoles()

◆ IsRestrictedOpenShell()

◆ McWeenyPurification()

◆ ModelPotentialGuess()

◆ NuclearRepulsion()

◆ NumberOfRestrictedOccupiedOrbitals()

◆ OrthogonalizeGuess()

◆ Prepare()

◆ PrintMOs()

◆ PrintMOsUKS()

◆ RunAtomicDFT_unrestricted()

◆ RunCDFT()

◆ setExternalcharges()

◆ setForceUKSPath()

◆ setLogger()

◆ SetupH0()

◆ SetupInvariantMatrices()

◆ SetupVxc()

◆ SphericalAverageShells()

◆ TruncateBasis()

◆ TruncMOsFullBasis()

Friends And Related Symbol Documentation

◆ DFTEngineTestAccess

Member Data Documentation

◆ active_and_border_atoms_

◆ active_atoms_as_string_

◆ active_electrons_

◆ active_threshold_

◆ activemol_

◆ auxbasis_

◆ auxbasis_name_

◆ cdft_constraint_spec_

◆ cdft_enabled_

◆ cdft_population_tolerance_

◆ charge_

◆ compute_forces_

◆ constraints_

◆ conv_accelerator_

◆ conv_opt_

◆ dftAOoverlap_

◆ dftbasis_

◆ dftbasis_name_