orbital transformations More...

Functions/Subroutines
pure elemental logical function, public	broyden_history_restart_required (non_descent, forget_history, do_ener)
	Decide whether a non-descent Broyden step invalidates its secant history.
pure elemental logical function, public	cg_history_restart_required (occupation_preconditioned, current_energy, reference_energy)
	Decide whether an unresolved accepted energy change invalidates CG conjugacy.
subroutine, public	ot_mini (qs_ot_env, matrix_hc, matrix_hc_im, matrix_hc_physical, matrix_hc_physical_im, para_env_inter_kp, gradient_only, gradient_prepared)
	...
subroutine, public	ot_mini_prepare_gradient (qs_ot_env, matrix_hc, matrix_hc_im, matrix_hc_physical, matrix_hc_physical_im, para_env_inter_kp)
	Evaluate the current OT derivative without advancing the minimizer.
pure subroutine, public	ot_mermin_response_assess (reference_energy, current_energy, reference_residual, current_residual, predicted_slope, predicted_curvature, position, default_step, predicted_drop, measured_drop, quality, residual_ratio, good)
	Assess a finite-response candidate at its accepted Mermin endpoint.
pure subroutine, public	ot_mermin_secant_curvature (reference_energy, current_energy, predicted_slope, position, curvature, valid)
	Recover the total finite Mermin curvature of an accepted line-search secant.
pure subroutine, public	ot_mermin_response_compare (reference_energy, current_energy, reference_residual, current_residual, predicted_slope, shadow_curvature, position, advantage, residual_ratio, good)
	Compare an endpoint response shadow with the linear accepted-step model.
pure subroutine, public	ot_mermin_response_candidate_preferred (baseline_slope, response_slope, response_curvature, accepted_slope, accepted_curvature, position, baseline_drop, response_drop, relative_gain, preferred)
	Compare response and conventional directions in one accepted Mermin model.
pure logical function, public	ot_mermin_response_probe (available, residual, directions, shadow_good_samples, good_samples, cooldown)
	Select a sparse coupled-response probe from accepted-history evidence.
pure logical function, public	ot_mermin_response_preparation_needed (residual, directions, shadow_good_samples, good_samples, cooldown, shadow_pending)
	Decide whether the next accepted state needs the dense finite Mermin response.
pure logical function, public	ot_mermin_response_shadow_followup (residual, directions, shadow_good_samples, good_samples, cooldown)
	Decide whether a prepared conventional direction needs a shadow at its endpoint.
pure real(kind=dp) function, public	lbfgs_curvature_damping_shift (sy, ss, yy, curvature_tol)
	Returns the smallest shift y <- y + shift*s that meets relative L-BFGS curvature.
pure logical function, public	lbfgs_history_restart_required (current_gradient_norm_sq, previous_gradient_norm_sq)
	Decides whether an L-BFGS history must be discarded after excessive gradient growth.
pure logical function, public	lbfgs_step_restart_required (accepted_step, reference_step)
	Decides whether L-BFGS must recover from a collapsed accepted line-search step.
pure subroutine, public	lbfgs_response_secant_parameters (g_dot_response, response_norm_sq, g_dot_h0_g, h0_g_norm_sq, response_scale, response_weight, valid)
	Normalize and damp an occupation-response secant against the conventional H0 direction.

Detailed Description

orbital transformations

History: None

Author: Joost VandeVondele (09.2002)

Function/Subroutine Documentation

◆ broyden_history_restart_required()

pure elemental logical function, public qs_ot_minimizer::broyden_history_restart_required	(	logical, intent(in)	non_descent,
		logical, intent(in)	forget_history,
		logical, intent(in)	do_ener )

Decide whether a non-descent Broyden step invalidates its secant history.

Parameters

non_descent	whether the proposed Broyden direction is not a descent direction
forget_history	explicit user request to discard an inconsistent history
do_ener	whether the product vector contains Mermin auxiliary-energy variables

Returns: true when the Broyden history has to be restarted

Definition at line 74 of file qs_ot_minimizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cg_history_restart_required()

pure elemental logical function, public qs_ot_minimizer::cg_history_restart_required	(	logical, intent(in)	occupation_preconditioned,
		real(kind=dp), intent(in)	current_energy,
		real(kind=dp), intent(in)	reference_energy )

Decide whether an unresolved accepted energy change invalidates CG conjugacy.

The occupation-preconditioned Mermin direction is a coupled Schur step rather than the action of one fixed positive-definite metric on the physical gradient. Once the accepted free-energy change is below floating-point resolution, its nonlinear conjugacy cannot be calibrated reliably. The current preconditioned descent direction remains valid, but the history contribution is discarded.

Parameters

occupation_preconditioned	whether the product direction uses occupation preconditioning
current_energy	current Mermin free energy
reference_energy	Mermin free energy before the accepted line search

Returns: true when the CG history contribution has to be discarded

Definition at line 93 of file qs_ot_minimizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ot_mini()

subroutine, public qs_ot_minimizer::ot_mini	(	type(qs_ot_type), dimension(:), pointer	qs_ot_env,
		type(dbcsr_p_type), dimension(:), pointer	matrix_hc,
		type(dbcsr_p_type), dimension(:), optional, pointer	matrix_hc_im,
		type(dbcsr_p_type), dimension(:), optional, pointer	matrix_hc_physical,
		type(dbcsr_p_type), dimension(:), optional, pointer	matrix_hc_physical_im,
		type(mp_para_env_type), optional, pointer	para_env_inter_kp,
		logical, intent(in), optional	gradient_only,
		logical, intent(in), optional	gradient_prepared )

...

Parameters

qs_ot_env	...
matrix_hc	...
matrix_hc_im	...
matrix_hc_physical	occupation-weighted derivative used for slopes and convergence
matrix_hc_physical_im	imaginary component of matrix_hc_physical
para_env_inter_kp	communicator between distributed k-point groups
gradient_only	return after evaluating the current OT gradient
gradient_prepared	reuse a gradient evaluated by ot_mini_prepare_gradient

Definition at line 130 of file qs_ot_minimizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ot_mini_prepare_gradient()

subroutine, public qs_ot_minimizer::ot_mini_prepare_gradient	(	type(qs_ot_type), dimension(:), pointer	qs_ot_env,
		type(dbcsr_p_type), dimension(:), pointer	matrix_hc,
		type(dbcsr_p_type), dimension(:), optional, pointer	matrix_hc_im,
		type(dbcsr_p_type), dimension(:), optional, pointer	matrix_hc_physical,
		type(dbcsr_p_type), dimension(:), optional, pointer	matrix_hc_physical_im,
		type(mp_para_env_type), optional, pointer	para_env_inter_kp )

Evaluate the current OT derivative without advancing the minimizer.

Parameters

qs_ot_env	OT channel environments
matrix_hc	real H*C products
matrix_hc_im	imaginary H*C products
matrix_hc_physical	occupation-weighted real H*C products
matrix_hc_physical_im	occupation-weighted imaginary H*C products
para_env_inter_kp	communicator between distributed K-point groups

Definition at line 365 of file qs_ot_minimizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ot_mermin_response_assess()

pure subroutine, public qs_ot_minimizer::ot_mermin_response_assess	(	real(kind=dp), intent(in)	reference_energy,
		real(kind=dp), intent(in)	current_energy,
		real(kind=dp), intent(in)	reference_residual,
		real(kind=dp), intent(in)	current_residual,
		real(kind=dp), intent(in)	predicted_slope,
		real(kind=dp), intent(in)	predicted_curvature,
		real(kind=dp), intent(in)	position,
		real(kind=dp), intent(in)	default_step,
		real(kind=dp), intent(out)	predicted_drop,
		real(kind=dp), intent(out)	measured_drop,
		real(kind=dp), intent(out)	quality,
		real(kind=dp), intent(out)	residual_ratio,
		logical, intent(out)	good )

Assess a finite-response candidate at its accepted Mermin endpoint.

Parameters

reference_energy	Mermin energy at the start of the search
current_energy	Mermin energy at the accepted endpoint
reference_residual	physical residual at the start of the search
current_residual	physical residual at the accepted endpoint
predicted_slope	positive predicted decrease per unit line-search position
predicted_curvature	signed finite-response curvature
position	accepted line-search position
default_step	configured initial line-search position
predicted_drop	finite quadratic-model decrease
measured_drop	measured Mermin decrease
quality	measured over predicted decrease
residual_ratio	endpoint over reference residual
good	whether this is a resolved, useful accepted response sample

Definition at line 412 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ ot_mermin_secant_curvature()

pure subroutine, public qs_ot_minimizer::ot_mermin_secant_curvature	(	real(kind=dp), intent(in)	reference_energy,
		real(kind=dp), intent(in)	current_energy,
		real(kind=dp), intent(in)	predicted_slope,
		real(kind=dp), intent(in)	position,
		real(kind=dp), intent(out)	curvature,
		logical, intent(out)	valid )

Recover the total finite Mermin curvature of an accepted line-search secant.

  For F(alpha)=F(0)-g*alpha+0.5*kappa*alpha**2, the accepted energy difference fixes
  kappa without separating REF, rotation, occupation, and self-consistent Hxc terms.

Parameters

reference_energy	Mermin energy at the start of the accepted search
current_energy	Mermin energy at its accepted endpoint
predicted_slope	positive directional decrease at the search origin
position	accepted line-search position
curvature	recovered total finite curvature
valid	whether a resolved finite curvature was recovered

Definition at line 464 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ ot_mermin_response_compare()

pure subroutine, public qs_ot_minimizer::ot_mermin_response_compare	(	real(kind=dp), intent(in)	reference_energy,
		real(kind=dp), intent(in)	current_energy,
		real(kind=dp), intent(in)	reference_residual,
		real(kind=dp), intent(in)	current_residual,
		real(kind=dp), intent(in)	predicted_slope,
		real(kind=dp), intent(in)	shadow_curvature,
		real(kind=dp), intent(in)	position,
		real(kind=dp), intent(out)	advantage,
		real(kind=dp), intent(out)	residual_ratio,
		logical, intent(out)	good )

Compare an endpoint response shadow with the linear accepted-step model.

Parameters

reference_energy	Mermin energy at the start of the search
current_energy	Mermin energy at the accepted endpoint
reference_residual	physical residual at the start of the search
current_residual	physical residual at the accepted endpoint
predicted_slope	positive reference directional decrease
shadow_curvature	endpoint finite-response curvature along the accepted direction
position	accepted line-search position
advantage	reduction of symmetric prediction error relative to the linear model
residual_ratio	endpoint over reference residual
good	whether the passive response prediction is both better and residual-consistent

Definition at line 500 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ ot_mermin_response_candidate_preferred()

pure subroutine, public qs_ot_minimizer::ot_mermin_response_candidate_preferred	(	real(kind=dp), intent(in)	baseline_slope,
		real(kind=dp), intent(in)	response_slope,
		real(kind=dp), intent(in)	response_curvature,
		real(kind=dp), intent(in)	accepted_slope,
		real(kind=dp), intent(in)	accepted_curvature,
		real(kind=dp), intent(in)	position,
		real(kind=dp), intent(out)	baseline_drop,
		real(kind=dp), intent(out)	response_drop,
		real(kind=dp), intent(out)	relative_gain,
		logical, intent(out)	preferred )

Compare response and conventional directions in one accepted Mermin model.

  The most recent accepted conventional secant supplies the dimensionless local curvature
  ratio kappa/g.  Applying that ratio to the current conventional slope transfers the
  measured line-search model without assuming that the two directions have equal norms.
  Both candidates are then evaluated at the same line-search position.

Parameters

baseline_slope	positive current conventional directional decrease
response_slope	positive current response directional decrease
response_curvature	current finite-response curvature
accepted_slope	positive slope of the preceding accepted conventional search
accepted_curvature	measured total curvature of that accepted search
position	common line-search position used for comparison
baseline_drop	predicted conventional Mermin decrease
response_drop	predicted response Mermin decrease
relative_gain	response improvement relative to the larger predicted decrease
preferred	whether the response model predicts a resolved improvement

Definition at line 557 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ ot_mermin_response_probe()

pure logical function, public qs_ot_minimizer::ot_mermin_response_probe	(	logical, intent(in)	available,
		real(kind=dp), intent(in)	residual,
		integer, intent(in)	directions,
		integer, intent(in)	shadow_good_samples,
		integer, intent(in)	good_samples,
		integer, intent(in)	cooldown )

Select a sparse coupled-response probe from accepted-history evidence.

Parameters

available	whether every local channel has a finite coupled response
residual	current conventional-preconditioned residual
directions	number of accepted directions seen by this response state
shadow_good_samples	passive accepted steps where response improved the prediction
good_samples	consecutive useful active response samples
cooldown	accepted directions remaining after a failed response sample

Returns: whether the next direction should use the coupled response candidate

Definition at line 605 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ ot_mermin_response_preparation_needed()

pure logical function, public qs_ot_minimizer::ot_mermin_response_preparation_needed	(	real(kind=dp), intent(in)	residual,
		integer, intent(in)	directions,
		integer, intent(in)	shadow_good_samples,
		integer, intent(in)	good_samples,
		integer, intent(in)	cooldown,
		logical, intent(in)	shadow_pending )

Decide whether the next accepted state needs the dense finite Mermin response.

  A pending shadow is always completed. Otherwise the response is prepared while collecting
  the initial accepted-step calibration and at the state immediately preceding a sparse
  response-probe window. The relaxed residual bound accounts for using the preceding
  accepted residual before the current norm has been reduced across K-point groups.

Parameters

residual	preceding accepted conventional-preconditioned residual
directions	number of accepted directions already seen
shadow_good_samples	useful passive accepted-step samples
good_samples	useful active response samples
cooldown	accepted directions remaining after a failed active sample
shadow_pending	whether the current endpoint must assess a prepared shadow

Returns: whether to build the dense finite response at the current accepted endpoint

Definition at line 642 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ ot_mermin_response_shadow_followup()

pure logical function, public qs_ot_minimizer::ot_mermin_response_shadow_followup	(	real(kind=dp), intent(in)	residual,
		integer, intent(in)	directions,
		integer, intent(in)	shadow_good_samples,
		integer, intent(in)	good_samples,
		integer, intent(in)	cooldown )

Decide whether a prepared conventional direction needs a shadow at its endpoint.

Parameters

residual	current conventional-preconditioned residual
directions	number of accepted directions including the current one
shadow_good_samples	useful passive accepted-step samples
good_samples	useful active response samples
cooldown	accepted directions remaining after a failed active sample

Returns: whether the next accepted endpoint must assess the current response shadow

Definition at line 678 of file qs_ot_minimizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lbfgs_curvature_damping_shift()

pure real(kind=dp) function, public qs_ot_minimizer::lbfgs_curvature_damping_shift	(	real(kind=dp), intent(in)	sy,
		real(kind=dp), intent(in)	ss,
		real(kind=dp), intent(in)	yy,
		real(kind=dp), intent(in)	curvature_tol )

Returns the smallest shift y <- y + shift*s that meets relative L-BFGS curvature.

Parameters

sy	scalar product s.y
ss	scalar product s.s
yy	scalar product y.y
curvature_tol	requested lower bound for (s.y)/sqrt((s.s)(y.y))

Returns: non-negative finite damping shift, or zero when no valid shift is needed or available

Definition at line 2118 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ lbfgs_history_restart_required()

pure logical function, public qs_ot_minimizer::lbfgs_history_restart_required	(	real(kind=dp), intent(in)	current_gradient_norm_sq,
		real(kind=dp), intent(in)	previous_gradient_norm_sq )

Decides whether an L-BFGS history must be discarded after excessive gradient growth.

Parameters

current_gradient_norm_sq	squared norm at the current accepted point
previous_gradient_norm_sq	squared norm at the preceding accepted point

Returns: true when both norms are finite and the gradient grew by more than a factor of ten

Definition at line 2145 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ lbfgs_step_restart_required()

pure logical function, public qs_ot_minimizer::lbfgs_step_restart_required	(	real(kind=dp), intent(in)	accepted_step,
		real(kind=dp), intent(in)	reference_step )

Decides whether L-BFGS must recover from a collapsed accepted line-search step.

Parameters

accepted_step	step selected by the preceding line search
reference_step	configured initial line-search step

Returns: true for a finite step smaller than one millionth of a valid reference step

Definition at line 2166 of file qs_ot_minimizer.F.

Here is the caller graph for this function:

◆ lbfgs_response_secant_parameters()

pure subroutine, public qs_ot_minimizer::lbfgs_response_secant_parameters	(	real(kind=dp), intent(in)	g_dot_response,
		real(kind=dp), intent(in)	response_norm_sq,
		real(kind=dp), intent(in)	g_dot_h0_g,
		real(kind=dp), intent(in)	h0_g_norm_sq,
		real(kind=dp), intent(out)	response_scale,
		real(kind=dp), intent(out)	response_weight,
		logical, intent(out)	valid )

Normalize and damp an occupation-response secant against the conventional H0 direction.

The response direction is first normalized to the product norm of H0*g. If its directional derivative is smaller than the Powell bound, it is mixed with H0*g until g^T*p >= 0.2*g^T*H0*g. Equal-norm normalization and convex mixing bound the target direction, while the curvature bound keeps the inverse-BFGS completion positive and well conditioned.

Parameters

g_dot_response	scalar product of g and the raw response direction
response_norm_sq	squared product norm of the raw response direction
g_dot_h0_g	scalar product of g and H0*g
h0_g_norm_sq	squared product norm of H0*g
response_scale	scale applied to the raw response direction
response_weight	convex weight of the normalized response direction
valid	true if finite positive input permits a response secant

Definition at line 2193 of file qs_ot_minimizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

Functions/Subroutines

Detailed Description

Function/Subroutine Documentation

◆ broyden_history_restart_required()

◆ cg_history_restart_required()

◆ ot_mini()

◆ ot_mini_prepare_gradient()

◆ ot_mermin_response_assess()

◆ ot_mermin_secant_curvature()

◆ ot_mermin_response_compare()

◆ ot_mermin_response_candidate_preferred()

◆ ot_mermin_response_probe()

◆ ot_mermin_response_preparation_needed()

◆ ot_mermin_response_shadow_followup()

◆ lbfgs_curvature_damping_shift()

◆ lbfgs_history_restart_required()

◆ lbfgs_step_restart_required()

◆ lbfgs_response_secant_parameters()