(git:27c966b)
Loading...
Searching...
No Matches
qs_electrons_charge_mixing Module Reference

Dual integer-electron-endpoint charge mixing for constant-potential MD, built on top of CP2K's stock MIXED force_eval (METHOD MIXED / MIXING_TYPE LINEAR_COMBINATION). Energy, forces and virial are already interpolated by stock force_env_methods.F's mixed_energy_forces using the LAMBDA value read from the input structure at every call; this module (a) pushes the dynamically tracked lambda into that input structure each step, (b) mixes Fermi level / workfunction, which stock MIXED does not touch, and (c) rebuilds a sub_force_env at a new integer CHARGE whenever q(t) drifts outside the currently-built bracket ("boundary crossing"). More...

Functions/Subroutines

subroutine, public qs_electrons_charge_mixing_lambda (electrons, lambda, n_lo, n_hi)
 Given the current electronic coordinate q and the integer span S, compute the bracketing integers N_lo/N_hi and the mixing weight lambda = (q - N_lo)/S.
subroutine, public push_lambda_to_mixed_env (force_env, lambda)
 Push a dynamically computed lambda into the MIXED force_eval's input structure. force_env_methods.F::mixed_energy_forces reads MIXEDLINEARLAMBDA fresh from the input structure every call, so this alone is sufficient to make energy/force/virial mixing track our own extended-variable dynamics with zero changes to stock CP2K.
subroutine, public compute_mixed_workfunction (force_env, axis, wf_min, wf_max, q, span, fermi_level_ev, workfunction_ev, lambda_in)
 Fermi level / workfunction mixing across the two integer-charge endpoints. Stock MIXED only combines energy/force/virial/dipole (mixed_environment_utils.F::mixed_map_forces), so these two quantities – needed every step by our own O-B-A-B-O potentiostat to decide how to move q(t) – are interpolated here, mirroring FFChargeMixTwoSockets._mix_results's fermi/workfunction lines.
subroutine, public charge_mixing_maybe_rebuild (force_env, electrons)
 Check whether q(t) has drifted outside the currently-built [N_lo,N_hi] bracket and, if so, rebuild whichever endpoint(s) are now stale at the new integer electron count. Must be called every step, right after qs_electrons_drift and before push_lambda_to_mixed_env, so LAMBDA is always pushed against a bracket that actually matches the physically-built sub_force_env pair.
subroutine, public charge_mixing_sync_endpoint_state (force_env, electrons)
 Record which integer electron counts the two FORCE_EVAL blocks are ACTUALLY built for, by interrogating them, so that the very first charge_mixing_maybe_rebuild can tell whether the input agrees with q.

Detailed Description

Dual integer-electron-endpoint charge mixing for constant-potential MD, built on top of CP2K's stock MIXED force_eval (METHOD MIXED / MIXING_TYPE LINEAR_COMBINATION). Energy, forces and virial are already interpolated by stock force_env_methods.F's mixed_energy_forces using the LAMBDA value read from the input structure at every call; this module (a) pushes the dynamically tracked lambda into that input structure each step, (b) mixes Fermi level / workfunction, which stock MIXED does not touch, and (c) rebuilds a sub_force_env at a new integer CHARGE whenever q(t) drifts outside the currently-built bracket ("boundary crossing").

Author
Nanchen DONGFANG

Function/Subroutine Documentation

◆ qs_electrons_charge_mixing_lambda()

subroutine, public qs_electrons_charge_mixing::qs_electrons_charge_mixing_lambda ( type(qs_electrons_type), pointer electrons,
real(kind=dp), intent(out) lambda,
integer, intent(out), optional n_lo,
integer, intent(out), optional n_hi )

Given the current electronic coordinate q and the integer span S, compute the bracketing integers N_lo/N_hi and the mixing weight lambda = (q - N_lo)/S.

Parameters
electrons...
lambda...
n_lo...
n_hi...

Definition at line 78 of file qs_electrons_charge_mixing.F.

Here is the caller graph for this function:

◆ push_lambda_to_mixed_env()

subroutine, public qs_electrons_charge_mixing::push_lambda_to_mixed_env ( type(force_env_type), pointer force_env,
real(kind=dp), intent(in) lambda )

Push a dynamically computed lambda into the MIXED force_eval's input structure. force_env_methods.F::mixed_energy_forces reads MIXEDLINEARLAMBDA fresh from the input structure every call, so this alone is sufficient to make energy/force/virial mixing track our own extended-variable dynamics with zero changes to stock CP2K.

IMPORTANT sign convention: CP2K's own mixed_energy_forces computes E = LAMBDA*E(force_eval#1) + (1-LAMBDA)*E(force_eval#2). In our input, force_eval#1 is the N_lo endpoint and force_eval#2 is the N_hi endpoint, but our own lambda argument here uses the opposite (standard interpolation) convention, lambda = (q-N_lo)/S, i.e. lambda=0 at N_lo and lambda=1 at N_hi. So CP2K's LAMBDA must be set to (1-lambda), NOT lambda directly, or the mixing comes out backwards (mostly N_hi when q is near N_lo).

Parameters
force_envthe top-level MIXED force_env (force_envin_use must be use_mixed_force; force_envforce_env_section must contain a MIXED subsection with MIXING_TYPE LINEAR_COMBINATION)
lambdaour convention: 0 at N_lo, 1 at N_hi

Definition at line 123 of file qs_electrons_charge_mixing.F.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ compute_mixed_workfunction()

subroutine, public qs_electrons_charge_mixing::compute_mixed_workfunction ( type(force_env_type), pointer force_env,
integer, intent(in) axis,
real(kind=dp), intent(in) wf_min,
real(kind=dp), intent(in) wf_max,
real(kind=dp), intent(in) q,
integer, intent(in) span,
real(kind=dp), intent(out) fermi_level_ev,
real(kind=dp), intent(out) workfunction_ev,
real(kind=dp), intent(in), optional lambda_in )

Fermi level / workfunction mixing across the two integer-charge endpoints. Stock MIXED only combines energy/force/virial/dipole (mixed_environment_utils.F::mixed_map_forces), so these two quantities – needed every step by our own O-B-A-B-O potentiostat to decide how to move q(t) – are interpolated here, mirroring FFChargeMixTwoSockets._mix_results's fermi/workfunction lines.

Parameters
force_envthe top-level MIXED force_env; force_envsub_force_env(1) and (2) must each be an ordinary QS force_env
axis...
wf_min...
wf_max...
qcurrent electronic coordinate (total electron count)
spancharge_mixing_span (S)
fermi_level_eV...
workfunction_eV...
lambda_inoptional explicit mixing weight; callers pass the value from qs_electrons_charge_mixing_lambda so a FIXED lambda is honoured here too

Definition at line 155 of file qs_electrons_charge_mixing.F.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ charge_mixing_maybe_rebuild()

subroutine, public qs_electrons_charge_mixing::charge_mixing_maybe_rebuild ( type(force_env_type), pointer force_env,
type(qs_electrons_type), pointer electrons )

Check whether q(t) has drifted outside the currently-built [N_lo,N_hi] bracket and, if so, rebuild whichever endpoint(s) are now stale at the new integer electron count. Must be called every step, right after qs_electrons_drift and before push_lambda_to_mixed_env, so LAMBDA is always pushed against a bracket that actually matches the physically-built sub_force_env pair.

Parameters
force_envthe top-level MIXED force_env
electrons...

Definition at line 243 of file qs_electrons_charge_mixing.F.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ charge_mixing_sync_endpoint_state()

subroutine, public qs_electrons_charge_mixing::charge_mixing_sync_endpoint_state ( type(force_env_type), pointer force_env,
type(qs_electrons_type), pointer electrons )

Record which integer electron counts the two FORCE_EVAL blocks are ACTUALLY built for, by interrogating them, so that the very first charge_mixing_maybe_rebuild can tell whether the input agrees with q.

This closes the "startup endpoint mismatch" hole. The port assumes throughout that sub_force_env(1) carries N_lo and sub_force_env(2) carries N_hi – push_lambda_to_mixed_env relies on it, since CP2K evaluates E = LAMBDA*E(1) + (1-LAMBDA)*E(2) and we therefore push LAMBDA = 1 - lambda. Nothing in stock CP2K enforces that ordering: an input whose two blocks are written high-charge-first would mix BACKWARDS, silently, for the whole run, and the only symptom would be a potentiostat that pushes q the wrong way.

Reading the counts back here and letting maybe_rebuild correct them removes the dependence on the order of the input blocks.

Reading rather than blindly forcing a rebuild matters: seeding the tracking with -HUGE(0) would also fix the ordering, but it would force two full qs_init rebuilds at step 0 of every run, including the vast majority whose input is already correct.

Parameters
force_envthe top-level MIXED force_env
electrons...

Definition at line 311 of file qs_electrons_charge_mixing.F.

Here is the call graph for this function:
Here is the caller graph for this function: