#include <uks_convergenceacc.h>

Collaboration diagram for votca::xtp::UKSConvergenceAcc:

[legend]

Classes
struct	SpinDensity
struct	SpinFock

Public Types
using	options = ConvergenceAcc::options
using	KSmode = ConvergenceAcc::KSmode
using	CoupledFockBuilder

Public Member Functions
void	Configure (const options &opt_alpha, const options &opt_beta)
void	setLogger (Logger *log)
void	setOverlap (AOOverlap &S, double etol)
void	setCoupledFockBuilder (const CoupledFockBuilder &builder)
SpinDensity	DensityMatrix (const tools::EigenSystem &MOs_alpha, const tools::EigenSystem &MOs_beta) const
SpinDensity	Iterate (const SpinDensity &dmat, SpinFock &H, tools::EigenSystem &MOs_alpha, tools::EigenSystem &MOs_beta, double totE)
tools::EigenSystem	SolveFockmatrix (const Eigen::MatrixXd &H) const
Eigen::MatrixXd	UnflattenRotation (const Eigen::VectorXd &v_ov, Index nao, Index nocclevels) const
std::pair< Eigen::MatrixXd, Eigen::MatrixXd >	UnflattenCoupledRotation (const Eigen::VectorXd &v, Index nao_alpha, Index nocclevels_alpha, Index nao_beta, Index nocclevels_beta) const
Eigen::VectorXd	BuildCoupledSigmaVector (const Eigen::VectorXd &v, const Eigen::MatrixXd &C_alpha, Index nocclevels_alpha, const Eigen::MatrixXd &C_beta, Index nocclevels_beta, const CoupledFockBuilder &coupled_fock_builder, double finite_diff_step=1e-3) const
std::pair< Eigen::MatrixXd, Eigen::MatrixXd >	CoupledAugmentedHessianStep (const Eigen::MatrixXd &H_AO_alpha, const tools::EigenSystem &MOs_alpha, Index nocclevels_alpha, const Eigen::MatrixXd &H_AO_beta, const tools::EigenSystem &MOs_beta, Index nocclevels_beta, const CoupledFockBuilder &coupled_fock_builder, double trust_radius, double &predicted_energy_change) const
bool	isConverged () const
double	getDIIsError () const
double	getDeltaE () const
bool	getUseMixing () const

Private Member Functions
Eigen::MatrixXd	DensityMatrixGroundState_unres (const Eigen::MatrixXd &MOs, Index nocclevels) const
void	Levelshift (Eigen::MatrixXd &H, const Eigen::MatrixXd &MOs_old, const options &opt, Index nocclevels) const
Eigen::MatrixXd	BuildErrorMatrix (const Eigen::MatrixXd &dmat, const Eigen::MatrixXd &H) const
double	CombinedError (const Eigen::MatrixXd &err_alpha, const Eigen::MatrixXd &err_beta) const
Eigen::MatrixXd	DirectMinimizationRotation (const Eigen::MatrixXd &H_AO, const tools::EigenSystem &MOs, Index nocclevels, double &predicted_energy_change) const

Private Attributes
options	opt_alpha_
options	opt_beta_
AOOverlap *	S_ = nullptr
Logger *	log_ = nullptr
Eigen::MatrixXd	Sminusahalf
CoupledFockBuilder	coupled_fock_builder_
Index	nocclevels_alpha_ = 0
Index	nocclevels_beta_ = 0
std::vector< Eigen::MatrixXd >	mathist_alpha_
std::vector< Eigen::MatrixXd >	mathist_beta_
std::vector< Eigen::MatrixXd >	dmatHist_alpha_
std::vector< Eigen::MatrixXd >	dmatHist_beta_
std::vector< double >	totE_
DIIS	diis_
ADIIS	adiis_
double	diiserror_ = 1.0
double	maxerror_ = -1.0
Index	maxerrorindex_ = 0
bool	usedmixing_ = true
Index	consecutive_adiis_failures_ = 0
std::vector< double >	diiserror_history_
Index	total_iteration_count_ = 0
bool	direct_min_pending_ = false
double	direct_min_pre_energy_ = 0.0
double	direct_min_predicted_change_ = 0.0
Eigen::MatrixXd	direct_min_pre_MOs_alpha_
Eigen::MatrixXd	direct_min_pre_MOs_beta_
Eigen::VectorXd	direct_min_pre_MOs_alpha_energies_
Eigen::VectorXd	direct_min_pre_MOs_beta_energies_
double	trust_radius_current_ = 0.2
bool	direct_min_floor_hit_ = false

Static Private Attributes
static constexpr Index	kMaxConsecutiveADIISFailures = 5
static constexpr Index	kTrailingWindowSize = 10
static constexpr Index	kAutoStartIteration = 50
static constexpr double	kMeanRatioTolerance = 1.125
static constexpr double	kMinTrustRadius = 3e-3

Detailed Description

Definition at line 42 of file uks_convergenceacc.h.

Member Typedef Documentation

◆ CoupledFockBuilder

using votca::xtp::UKSConvergenceAcc::CoupledFockBuilder

Initial value:

 
std::function<SpinFock(const Eigen::MatrixXd& ,
                       const Eigen::MatrixXd& )>

Given BOTH new spin densities together, returns BOTH new AO Fock matrices together (H0 + Coulomb + exchange + XC, for each channel). Closer to VOTCA's own native Fock-build structure: Vxc_Potential::IntegrateVXCSpin already computes vxc_alpha and vxc_beta together from both densities in one call. Used by CoupledAugmentedHessianStep/BuildCoupledSigmaVector to capture the genuine alpha-beta coupling (through the shared Coulomb potential and the XC kernel's cross-spin terms) that treating the two channels independently would discard – see the conversation this grew out of: a direct, controlled comparison against ORCA on an identical geometry showed ORCA's own, fully-coupled TRAH converging where an earlier, decoupled implementation here did not. Injected from DFTEngine (setCoupledFockBuilder below) since the actual integral/XC machinery (CalcERIs/CalcERIs_EXX, Vxc_Potential::IntegrateVXCSpin) lives there, not in this class – matching the same pointer-injection pattern already used for S_/log_.

Definition at line 76 of file uks_convergenceacc.h.

◆ KSmode

using votca::xtp::UKSConvergenceAcc::KSmode = ConvergenceAcc::KSmode

Definition at line 45 of file uks_convergenceacc.h.

◆ options

using votca::xtp::UKSConvergenceAcc::options = ConvergenceAcc::options

Definition at line 44 of file uks_convergenceacc.h.

Member Function Documentation

◆ BuildCoupledSigmaVector()

Eigen::VectorXd votca::xtp::UKSConvergenceAcc::BuildCoupledSigmaVector	(	const Eigen::VectorXd &	v,
		const Eigen::MatrixXd &	C_alpha,
		Index	nocclevels_alpha,
		const Eigen::MatrixXd &	C_beta,
		Index	nocclevels_beta,
		const CoupledFockBuilder &	coupled_fock_builder,
		double	finite_diff_step = 1e-3 ) const

Coupled analogue of BuildSigmaVector: rotates BOTH spin channels SIMULTANEOUSLY by +-a small step (unlike BuildSigmaVector, which rotates one channel while holding the other fixed), builds BOTH new densities together, and calls coupled_fock_builder ONCE per perturbation to get BOTH new Fock matrices together – capturing the genuine alpha-beta coupling (through the shared Coulomb potential and the XC kernel's cross-spin terms) that BuildSigmaVector's own, deliberately decoupled treatment discards. Returns the combined sigma vector (alpha's own block first, beta's immediately after, matching v's own layout). Central difference, for the identical reason BuildSigmaVector itself uses one (see that function's own header comment).

Definition at line 100 of file uks_convergenceacc.cc.

◆ BuildErrorMatrix()

Eigen::MatrixXd votca::xtp::UKSConvergenceAcc::BuildErrorMatrix	(	const Eigen::MatrixXd &	dmat,
		const Eigen::MatrixXd &	H ) const

private

Definition at line 521 of file uks_convergenceacc.cc.

◆ CombinedError()

double votca::xtp::UKSConvergenceAcc::CombinedError	(	const Eigen::MatrixXd &	err_alpha,
		const Eigen::MatrixXd &	err_beta ) const

private

Definition at line 527 of file uks_convergenceacc.cc.

◆ Configure()

void votca::xtp::UKSConvergenceAcc::Configure	(	const options &	opt_alpha,
		const options &	opt_beta )

Definition at line 28 of file uks_convergenceacc.cc.

◆ CoupledAugmentedHessianStep()

std::pair< Eigen::MatrixXd, Eigen::MatrixXd > votca::xtp::UKSConvergenceAcc::CoupledAugmentedHessianStep	(	const Eigen::MatrixXd &	H_AO_alpha,
		const tools::EigenSystem &	MOs_alpha,
		Index	nocclevels_alpha,
		const Eigen::MatrixXd &	H_AO_beta,
		const tools::EigenSystem &	MOs_beta,
		Index	nocclevels_beta,
		const CoupledFockBuilder &	coupled_fock_builder,
		double	trust_radius,
		double &	predicted_energy_change ) const

Solves ONE augmented-Hessian eigenvalue problem over the COMBINED (alpha+beta) rotation space, rather than treating the two spin channels independently – see this class's own CoupledFockBuilder comment for the full motivation. Returns BOTH new MO coefficient matrices together, since a single, coupled step inherently produces both simultaneously. predicted_energy_change (output): the ONE, combined quadratic model's own predicted energy change for this step – Iterate's own Fletcher accept/reject logic uses this directly.

Definition at line 324 of file uks_convergenceacc.cc.

◆ DensityMatrix()

UKSConvergenceAcc::SpinDensity votca::xtp::UKSConvergenceAcc::DensityMatrix	(	const tools::EigenSystem &	MOs_alpha,
		const tools::EigenSystem &	MOs_beta ) const

Definition at line 490 of file uks_convergenceacc.cc.

◆ DensityMatrixGroundState_unres()

Eigen::MatrixXd votca::xtp::UKSConvergenceAcc::DensityMatrixGroundState_unres	(	const Eigen::MatrixXd &	MOs,
		Index	nocclevels ) const

private

Definition at line 481 of file uks_convergenceacc.cc.

◆ DirectMinimizationRotation()

Eigen::MatrixXd votca::xtp::UKSConvergenceAcc::DirectMinimizationRotation	(	const Eigen::MatrixXd &	H_AO,
		const tools::EigenSystem &	MOs,
		Index	nocclevels,
		double &	predicted_energy_change ) const

private

Approximate ARH-style direct energy minimization step: builds new MO coefficients directly via an orbital rotation (occ-virt block only, since occ-occ/virt-virt rotations leave the density matrix unchanged), using the orbital gradient (the occ-virt block of the MO-basis Fock matrix, which vanishes exactly at self-consistency) and an approximate, diagonal Hessian (orbital energy differences – the same cheap approximation used as the starting point for most quasi-Newton SCF methods, e.g. SOSCF's own initial Hessian guess). The step is trust-radius bounded, and the resulting (only approximately unitary) rotation is re-orthonormalized via the same Lowdin approach as OrthogonalizeGuess. See the design discussion this grew out of for the full reasoning: this is a deliberately simplified relative of the ARH/TRAH family of direct-minimization SCF methods (confirmed directly, on this exact system, to resolve an ADIIS/DIIS convergence failure that ORCA's own auto-TRAH fallback also had to invoke), not a full implementation of either. predicted_energy_change (output): the quadratic model's own predicted E_new - E_old, Sum_ia[g_ia*kappa_ia + 0.5*h_ia*kappa_ia^2] using the SAME (possibly per-element- and trust-radius-clamped) kappa actually applied – needed by Iterate's own Fletcher-style accept/reject logic (see its own header comment) to compute the ratio r = E_actual_change / E_predicted_change once the actual, post-step energy becomes available (on the NEXT Iterate() call, once the caller has built a new Fock matrix from this step's own density and passed its energy back in).

STATUS: superseded by CoupledAugmentedHessianStep below whenever a coupled Fock-builder callback has been injected (i.e. DFTEngine has wired up setCoupledFockBuilder) – kept as the fallback for any caller that has not done so (e.g. DFTEngine::RunAtomicDFT_unrestricted), and because CoupledAugmentedHessianStep itself still uses this same diagonal approximation as the Davidson preconditioner, exactly as the TRAH paper's own Sec. II B describes doing.

Definition at line 182 of file uks_convergenceacc.cc.

◆ getDeltaE()

double votca::xtp::UKSConvergenceAcc::getDeltaE ( ) const

Definition at line 967 of file uks_convergenceacc.cc.

◆ getDIIsError()

double votca::xtp::UKSConvergenceAcc::getDIIsError ( ) const

inline

Definition at line 154 of file uks_convergenceacc.h.

◆ getUseMixing()

bool votca::xtp::UKSConvergenceAcc::getUseMixing ( ) const

inline

Definition at line 156 of file uks_convergenceacc.h.

◆ isConverged()

bool votca::xtp::UKSConvergenceAcc::isConverged ( ) const

Definition at line 974 of file uks_convergenceacc.cc.

◆ Iterate()

UKSConvergenceAcc::SpinDensity votca::xtp::UKSConvergenceAcc::Iterate	(	const SpinDensity &	dmat,
		SpinFock &	H,
		tools::EigenSystem &	MOs_alpha,
		tools::EigenSystem &	MOs_beta,
		double	totE )

Definition at line 533 of file uks_convergenceacc.cc.

◆ Levelshift()

void votca::xtp::UKSConvergenceAcc::Levelshift	(	Eigen::MatrixXd &	H,
		const Eigen::MatrixXd &	MOs_old,
		const options &	opt,
		Index	nocclevels ) const

private

Definition at line 501 of file uks_convergenceacc.cc.

◆ setCoupledFockBuilder()

void votca::xtp::UKSConvergenceAcc::setCoupledFockBuilder ( const CoupledFockBuilder & builder )

inline

Definition at line 83 of file uks_convergenceacc.h.

◆ setLogger()

void votca::xtp::UKSConvergenceAcc::setLogger ( Logger * log )

Definition at line 41 of file uks_convergenceacc.cc.

◆ setOverlap()

void votca::xtp::UKSConvergenceAcc::setOverlap	(	AOOverlap &	S,
		double	etol )

Definition at line 43 of file uks_convergenceacc.cc.

◆ SolveFockmatrix()

tools::EigenSystem votca::xtp::UKSConvergenceAcc::SolveFockmatrix ( const Eigen::MatrixXd & H ) const

Definition at line 54 of file uks_convergenceacc.cc.

◆ UnflattenCoupledRotation()

std::pair< Eigen::MatrixXd, Eigen::MatrixXd > votca::xtp::UKSConvergenceAcc::UnflattenCoupledRotation	(	const Eigen::VectorXd &	v,
		Index	nao_alpha,
		Index	nocclevels_alpha,
		Index	nao_beta,
		Index	nocclevels_beta ) const

Coupled analogue of UnflattenRotation: splits ONE combined vector v (size n_ov_alpha + n_ov_beta – alpha's own occ-virt block first, beta's own immediately after) into TWO separate antisymmetric rotation matrices, kappa_alpha (nao_alpha x nao_alpha) and kappa_beta (nao_beta x nao_beta). Public for the same reason as UnflattenRotation itself.

Definition at line 85 of file uks_convergenceacc.cc.

◆ UnflattenRotation()

Eigen::MatrixXd votca::xtp::UKSConvergenceAcc::UnflattenRotation	(	const Eigen::VectorXd &	v_ov,
		Index	nao,
		Index	nocclevels ) const

One column of the Davidson trial-vector matrix V, containing [v0; v_ov] (the scalar augmented component and the flattened occ-virt rotation-space vector), mapped back to a full nao x nao antisymmetric matrix (occ-virt/virt-occ blocks only, matching DirectMinimizationRotation's own convention) – needed to actually apply a trial rotation direction when building the finite-difference sigma vector. Public so it can be exercised directly by unit tests (see test_uks_convergenceacc.cc), given how cheaply this pure, self-contained math can be checked in isolation compared to the SCF machinery that otherwise relies on it.

Definition at line 70 of file uks_convergenceacc.cc.

Member Data Documentation

◆ adiis_

ADIIS votca::xtp::UKSConvergenceAcc::adiis_

private

Definition at line 228 of file uks_convergenceacc.h.

◆ consecutive_adiis_failures_

Index votca::xtp::UKSConvergenceAcc::consecutive_adiis_failures_ = 0

private

Definition at line 242 of file uks_convergenceacc.h.

◆ coupled_fock_builder_

CoupledFockBuilder votca::xtp::UKSConvergenceAcc::coupled_fock_builder_

private

Definition at line 216 of file uks_convergenceacc.h.

◆ diis_

DIIS votca::xtp::UKSConvergenceAcc::diis_

private

Definition at line 227 of file uks_convergenceacc.h.

◆ diiserror_

double votca::xtp::UKSConvergenceAcc::diiserror_ = 1.0

private

Definition at line 230 of file uks_convergenceacc.h.

◆ diiserror_history_

std::vector<double> votca::xtp::UKSConvergenceAcc::diiserror_history_

private

Definition at line 261 of file uks_convergenceacc.h.

◆ direct_min_floor_hit_

bool votca::xtp::UKSConvergenceAcc::direct_min_floor_hit_ = false

private

Definition at line 305 of file uks_convergenceacc.h.

◆ direct_min_pending_

bool votca::xtp::UKSConvergenceAcc::direct_min_pending_ = false

private

Definition at line 278 of file uks_convergenceacc.h.

◆ direct_min_pre_energy_

double votca::xtp::UKSConvergenceAcc::direct_min_pre_energy_ = 0.0

private

Definition at line 279 of file uks_convergenceacc.h.

◆ direct_min_pre_MOs_alpha_

Eigen::MatrixXd votca::xtp::UKSConvergenceAcc::direct_min_pre_MOs_alpha_

private

Definition at line 281 of file uks_convergenceacc.h.

◆ direct_min_pre_MOs_alpha_energies_

Eigen::VectorXd votca::xtp::UKSConvergenceAcc::direct_min_pre_MOs_alpha_energies_

private

Definition at line 283 of file uks_convergenceacc.h.

◆ direct_min_pre_MOs_beta_

Eigen::MatrixXd votca::xtp::UKSConvergenceAcc::direct_min_pre_MOs_beta_

private

Definition at line 282 of file uks_convergenceacc.h.

◆ direct_min_pre_MOs_beta_energies_

Eigen::VectorXd votca::xtp::UKSConvergenceAcc::direct_min_pre_MOs_beta_energies_

private

Definition at line 284 of file uks_convergenceacc.h.

◆ direct_min_predicted_change_

double votca::xtp::UKSConvergenceAcc::direct_min_predicted_change_ = 0.0

private

Definition at line 280 of file uks_convergenceacc.h.

◆ dmatHist_alpha_

std::vector<Eigen::MatrixXd> votca::xtp::UKSConvergenceAcc::dmatHist_alpha_

private

Definition at line 223 of file uks_convergenceacc.h.

◆ dmatHist_beta_

std::vector<Eigen::MatrixXd> votca::xtp::UKSConvergenceAcc::dmatHist_beta_

private

Definition at line 224 of file uks_convergenceacc.h.

◆ kAutoStartIteration

Index votca::xtp::UKSConvergenceAcc::kAutoStartIteration = 50

staticconstexprprivate

Definition at line 264 of file uks_convergenceacc.h.

◆ kMaxConsecutiveADIISFailures

Index votca::xtp::UKSConvergenceAcc::kMaxConsecutiveADIISFailures = 5

staticconstexprprivate

Definition at line 243 of file uks_convergenceacc.h.

◆ kMeanRatioTolerance

double votca::xtp::UKSConvergenceAcc::kMeanRatioTolerance = 1.125

staticconstexprprivate

Definition at line 265 of file uks_convergenceacc.h.

◆ kMinTrustRadius

double votca::xtp::UKSConvergenceAcc::kMinTrustRadius = 3e-3

staticconstexprprivate

Definition at line 316 of file uks_convergenceacc.h.

◆ kTrailingWindowSize

Index votca::xtp::UKSConvergenceAcc::kTrailingWindowSize = 10

staticconstexprprivate

Definition at line 263 of file uks_convergenceacc.h.

◆ log_

Logger* votca::xtp::UKSConvergenceAcc::log_ = nullptr

private

Definition at line 213 of file uks_convergenceacc.h.

◆ mathist_alpha_

std::vector<Eigen::MatrixXd> votca::xtp::UKSConvergenceAcc::mathist_alpha_

private

Definition at line 221 of file uks_convergenceacc.h.

◆ mathist_beta_

std::vector<Eigen::MatrixXd> votca::xtp::UKSConvergenceAcc::mathist_beta_

private

Definition at line 222 of file uks_convergenceacc.h.

◆ maxerror_

double votca::xtp::UKSConvergenceAcc::maxerror_ = -1.0

private

Definition at line 231 of file uks_convergenceacc.h.

◆ maxerrorindex_

Index votca::xtp::UKSConvergenceAcc::maxerrorindex_ = 0

private

Definition at line 232 of file uks_convergenceacc.h.

◆ nocclevels_alpha_

Index votca::xtp::UKSConvergenceAcc::nocclevels_alpha_ = 0

private

Definition at line 218 of file uks_convergenceacc.h.

◆ nocclevels_beta_

Index votca::xtp::UKSConvergenceAcc::nocclevels_beta_ = 0

private

Definition at line 219 of file uks_convergenceacc.h.

◆ opt_alpha_

options votca::xtp::UKSConvergenceAcc::opt_alpha_

private

Definition at line 209 of file uks_convergenceacc.h.

◆ opt_beta_

options votca::xtp::UKSConvergenceAcc::opt_beta_

private

Definition at line 210 of file uks_convergenceacc.h.

◆ S_

AOOverlap* votca::xtp::UKSConvergenceAcc::S_ = nullptr

private

Definition at line 212 of file uks_convergenceacc.h.

◆ Sminusahalf

Eigen::MatrixXd votca::xtp::UKSConvergenceAcc::Sminusahalf

private

Definition at line 214 of file uks_convergenceacc.h.

◆ total_iteration_count_

Index votca::xtp::UKSConvergenceAcc::total_iteration_count_ = 0

private

Definition at line 262 of file uks_convergenceacc.h.

◆ totE_

std::vector<double> votca::xtp::UKSConvergenceAcc::totE_

private

Definition at line 225 of file uks_convergenceacc.h.

◆ trust_radius_current_

double votca::xtp::UKSConvergenceAcc::trust_radius_current_ = 0.2

private

Definition at line 285 of file uks_convergenceacc.h.

◆ usedmixing_

bool votca::xtp::UKSConvergenceAcc::usedmixing_ = true

private

Definition at line 233 of file uks_convergenceacc.h.

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

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

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

◆ CoupledFockBuilder

◆ KSmode

◆ options

Member Function Documentation

◆ BuildCoupledSigmaVector()

◆ BuildErrorMatrix()

◆ CombinedError()

◆ Configure()

◆ CoupledAugmentedHessianStep()

◆ DensityMatrix()

◆ DensityMatrixGroundState_unres()

◆ DirectMinimizationRotation()

◆ getDeltaE()

◆ getDIIsError()

◆ getUseMixing()

◆ isConverged()

◆ Iterate()

◆ Levelshift()

◆ setCoupledFockBuilder()

◆ setLogger()

◆ setOverlap()

◆ SolveFockmatrix()

◆ UnflattenCoupledRotation()

◆ UnflattenRotation()

Member Data Documentation

◆ adiis_

◆ consecutive_adiis_failures_

◆ coupled_fock_builder_

◆ diis_

◆ diiserror_

◆ diiserror_history_

◆ direct_min_floor_hit_

◆ direct_min_pending_

◆ direct_min_pre_energy_

◆ direct_min_pre_MOs_alpha_

◆ direct_min_pre_MOs_alpha_energies_

◆ direct_min_pre_MOs_beta_

◆ direct_min_pre_MOs_beta_energies_

◆ direct_min_predicted_change_

◆ dmatHist_alpha_

◆ dmatHist_beta_

◆ kAutoStartIteration

◆ kMaxConsecutiveADIISFailures

◆ kMeanRatioTolerance

◆ kMinTrustRadius

◆ kTrailingWindowSize

◆ log_

◆ mathist_alpha_

◆ mathist_beta_

◆ maxerror_

◆ maxerrorindex_

◆ nocclevels_alpha_

◆ nocclevels_beta_

◆ opt_alpha_

◆ opt_beta_

◆ S_

◆ Sminusahalf

◆ total_iteration_count_

◆ totE_

◆ trust_radius_current_

◆ usedmixing_