(git:27c966b)
Loading...
Searching...
No Matches
qs_electrons_types.F
Go to the documentation of this file.
1!--------------------------------------------------------------------------------------------------!
2! CP2K: A general program to perform molecular dynamics simulations !
3! Copyright 2000-2026 CP2K developers group <https://cp2k.org> !
4! !
5! SPDX-License-Identifier: GPL-2.0-or-later !
6!--------------------------------------------------------------------------------------------------!
7
8! **************************************************************************************************
9!> \brief State of the fictitious electronic degree of freedom (electron number q, its
10!> momentum, potentiostat and charge-mixing settings) used in constant-potential MD.
11!> \author Nanchen DONGFANG
12! **************************************************************************************************
14 USE kinds, ONLY: dp
15 USE parallel_rng_types, ONLY: gaussian,&
18#include "./base/base_uses.f90"
19
20 IMPLICIT NONE
21
22 PRIVATE
23 PUBLIC :: qs_electrons_type, &
26
28 REAL(kind=dp) :: q = 0.0_dp ! electronic coordinate (total electron number)
29 REAL(kind=dp) :: p = 0.0_dp ! conjugate momentum
30 REAL(kind=dp) :: mass = 1.0_dp ! fictitious electronic mass
31 REAL(kind=dp) :: neutral_electrons = 0.0_dp
32 REAL(kind=dp) :: target_workfunction = 0.0_dp
33 REAL(kind=dp) :: target_fermi_level = 0.0_dp ! eV, used when control_fermi is TRUE
34 ! Control mode. FALSE = work-function
35 ! control (drive Phi -> TARGET_WORKFUNCTION), TRUE = Fermi-level control
36 ! (drive e_F -> TARGET_FERMI_LEVEL). The two are NOT equivalent: they differ
37 ! by the vacuum level, and d(V_vac)/dq is not zero for a charged slab.
38 LOGICAL :: control_fermi = .false.
39 ! Frozen mixing weight. When lambda_is_fixed is TRUE the mixing weight is
40 ! held at lambda_fixed, q(t) is NOT propagated, and no endpoint is ever
41 ! rebuilt: the run becomes ordinary MD on a fixed linear combination of the
42 ! two integer-charge endpoints. Diagnostic use -- it isolates the mixing
43 ! from the potentiostat, so a run with LAMBDA set contains no
44 ! constant-potential dynamics at all.
45 REAL(kind=dp) :: lambda_fixed = 0.0_dp
46 LOGICAL :: lambda_is_fixed = .false.
47 ! Boundary-crossing policy. FALSE = tear down and re-run qs_init on the
48 ! stale endpoint. TRUE = mutate the existing endpoint's electron count
49 ! in place, never re-entering qs_init.
50 LOGICAL :: charge_mixing_inplace = .false.
51 ! Report-only mode, selected by "&ELECTRONS 0" (section present, parameter
52 ! false). The .cpcont file is written for an ordinary MD run -- in
53 ! particular the Fermi level and work function are computed and logged
54 ! every step -- but q is never propagated: no kick, no drift, no
55 ! potentiostat, no charge mixing, no endpoint rebuilds. q stays at the
56 ! system's actual electron count for the whole run and
57 ! target_workfunction is 0, so the Legendre term vanishes and
58 ! Grand_canonical_potential reduces to E_pot.
59 LOGICAL :: report_only = .false.
60 REAL(kind=dp) :: tau_potentiostat = 0.0_dp ! relaxation time, plain number in femtoseconds
61 REAL(kind=dp) :: temp_potentiostat = 0.0_dp
62 REAL(kind=dp) :: thermostat_energy = 0.0_dp ! accumulated heat exchanged, for conserved-quantity bookkeeping
63 REAL(kind=dp) :: current_workfunction = 0.0_dp
64 REAL(kind=dp) :: current_fermi_level_ev = 0.0_dp
65 INTEGER :: potential_average_axis = 3
66 INTEGER :: cpcont_unit = -1
67 REAL(kind=dp) :: potential_average_min = 0.0_dp
68 REAL(kind=dp) :: potential_average_max = 0.0_dp
69 INTEGER :: charge_mixing_span = 1 ! S: N_lo=S*floor(q/S), N_hi=N_lo+S
70 INTEGER :: charge_mixing_current_n_lo = -huge(0)
71 INTEGER :: charge_mixing_current_n_hi = -huge(0)
72 LOGICAL :: charge_mixing_enabled = .false.
73 TYPE(rng_stream_type) :: gaussian_rng_stream = rng_stream_type()
74 END TYPE qs_electrons_type
75
76 CHARACTER(len=*), PARAMETER, PRIVATE :: modulen = 'qs_electrons_types'
77
78CONTAINS
79
80! **************************************************************************************************
81!> \brief Initialize the electronic coordinate/potentiostat state for constant-potential MD.
82!> \param electrons ...
83!> \param q_init ...
84!> \param p_init ...
85!> \param mass ...
86!> \param neutral_electrons ...
87!> \param target_workfunction ...
88!> \param tau_potentiostat relaxation time, a plain number in femtoseconds (converted to
89!> "number of thermostat calls" inside qs_electrons_thermostat_step)
90!> \param temp_potentiostat ...
91!> \param potential_average_axis axis (1=x, 2=y, 3=z) for the planar potential average
92!> \param potential_average_min lower bound of the averaging slab, Angstrom
93!> \param potential_average_max upper bound of the averaging slab, Angstrom
94!> \param charge_mixing_span S: endpoint separation in electrons; presence of this
95!> argument is what enables charge mixing
96!> \param target_fermi_level target Fermi level in eV (absolute, on CP2K's internal scale)
97!> \param control_fermi TRUE for Fermi-level control, FALSE for work-function control
98!> \param lambda_fixed frozen mixing weight, honoured only when lambda_is_fixed
99!> \param lambda_is_fixed TRUE when LAMBDA was given: q is not propagated
100!> \param charge_mixing_inplace TRUE to mutate an endpoint's electron count in place
101!> rather than re-running qs_init on it
102!> \param report_only ...
103! **************************************************************************************************
104 SUBROUTINE qs_electrons_init(electrons, q_init, p_init, mass, neutral_electrons, &
105 target_workfunction, tau_potentiostat, temp_potentiostat, &
106 potential_average_axis, potential_average_min, potential_average_max, &
107 charge_mixing_span, target_fermi_level, control_fermi, &
108 lambda_fixed, lambda_is_fixed, charge_mixing_inplace, &
109 report_only)
110 TYPE(qs_electrons_type), POINTER :: electrons
111 REAL(kind=dp), INTENT(IN) :: q_init, p_init, mass, neutral_electrons, &
112 target_workfunction, tau_potentiostat, &
113 temp_potentiostat
114 INTEGER, INTENT(IN) :: potential_average_axis
115 REAL(kind=dp), INTENT(IN) :: potential_average_min, &
116 potential_average_max
117 INTEGER, INTENT(IN), OPTIONAL :: charge_mixing_span
118 REAL(kind=dp), INTENT(IN), OPTIONAL :: target_fermi_level
119 LOGICAL, INTENT(IN), OPTIONAL :: control_fermi
120 REAL(kind=dp), INTENT(IN), OPTIONAL :: lambda_fixed
121 LOGICAL, INTENT(IN), OPTIONAL :: lambda_is_fixed, charge_mixing_inplace, &
122 report_only
123
124 cpassert(.NOT. ASSOCIATED(electrons))
125 ALLOCATE (electrons)
126 electrons%q = q_init
127 electrons%p = p_init
128 electrons%mass = mass
129 electrons%neutral_electrons = neutral_electrons
130 electrons%target_workfunction = target_workfunction
131 IF (PRESENT(target_fermi_level)) electrons%target_fermi_level = target_fermi_level
132 IF (PRESENT(control_fermi)) electrons%control_fermi = control_fermi
133 IF (PRESENT(lambda_fixed)) electrons%lambda_fixed = lambda_fixed
134 IF (PRESENT(lambda_is_fixed)) electrons%lambda_is_fixed = lambda_is_fixed
135 IF (PRESENT(charge_mixing_inplace)) electrons%charge_mixing_inplace = charge_mixing_inplace
136 IF (PRESENT(report_only)) electrons%report_only = report_only
137 electrons%tau_potentiostat = tau_potentiostat
138 electrons%temp_potentiostat = temp_potentiostat
139 electrons%thermostat_energy = 0.0_dp
140 electrons%potential_average_axis = potential_average_axis
141 electrons%potential_average_min = potential_average_min
142 electrons%potential_average_max = potential_average_max
143 ! Initialise the Gaussian random-number stream used by the CSVR potentiostat.
144 ! This MUST be done explicitly, exactly as csvr_thermo_create does for the
145 ! ionic thermostats. Left at its default initialisation the component has
146 ! distribution_type = UNIFORM and bg = cg = ig = 0, and rn32() then returns
147 ! the constant m1*norm = 0.99999999976716947 on every call without ever
148 ! advancing its state. The linear noise term in rescaling_factor,
149 ! 2*rr*SQRT(kk*sigma/ndeg*(1-factor)*factor),
150 ! consequently stops averaging to zero and the thermostat turns into a
151 ! systematic energy source for the electronic degree of freedom.
152 electrons%gaussian_rng_stream = rng_stream_type( &
153 ! rng_name_length is 40 -- keep this string shorter
154 name="Wiener process for e-potentiostat", &
155 distribution_type=gaussian, &
156 extended_precision=.true., &
157 seed=next_rng_seed())
158
159 IF (PRESENT(charge_mixing_span)) THEN
160 electrons%charge_mixing_span = charge_mixing_span
161 electrons%charge_mixing_enabled = .true.
162 ! Left at the -HUGE(0) sentinel on purpose. These record which
163 ! endpoints the two FORCE_EVAL blocks are ACTUALLY built for, which is
164 ! not knowable here -- md_run calls charge_mixing_sync_endpoint_state
165 ! to read it back off the sub_force_envs before the first force
166 ! evaluation. Seeding them from q_init instead (the original code)
167 ! ASSERTED that the input already agreed, so the first
168 ! charge_mixing_maybe_rebuild saw no divergence and never corrected
169 ! anything: an input whose two blocks were written high-charge-first
170 ! mixed backwards, silently, for the entire run.
171 END IF
172
173 END SUBROUTINE qs_electrons_init
174
175! **************************************************************************************************
176!> \brief Release the electronic state.
177!> \param electrons ...
178! **************************************************************************************************
179 SUBROUTINE qs_electrons_dealloc(electrons)
180 TYPE(qs_electrons_type), POINTER :: electrons
181
182 IF (ASSOCIATED(electrons)) DEALLOCATE (electrons)
183
184 END SUBROUTINE qs_electrons_dealloc
185
186END MODULE qs_electrons_types
Defines the basic variable types.
Definition kinds.F:23
integer, parameter, public dp
Definition kinds.F:34
Parallel (pseudo)random number generator (RNG) for multiple streams and substreams of random numbers.
real(kind=dp) function, dimension(3, 2), public next_rng_seed(seed)
Get the seed for the next RNG stream w.r.t. a given seed.
integer, parameter, public gaussian
State of the fictitious electronic degree of freedom (electron number q, its momentum,...
subroutine, public qs_electrons_dealloc(electrons)
Release the electronic state.
subroutine, public qs_electrons_init(electrons, q_init, p_init, mass, neutral_electrons, target_workfunction, tau_potentiostat, temp_potentiostat, potential_average_axis, potential_average_min, potential_average_max, charge_mixing_span, target_fermi_level, control_fermi, lambda_fixed, lambda_is_fixed, charge_mixing_inplace, report_only)
Initialize the electronic coordinate/potentiostat state for constant-potential MD.