(git:27c966b)
Loading...
Searching...
No Matches
qs_electrons_workfunction.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 Work function and Fermi level readback from the converged SCF, using the planar
10!> average of the Hartree potential over a user-defined region.
11!> \author Nanchen DONGFANG
12! **************************************************************************************************
14 USE ieee_arithmetic, ONLY: ieee_is_finite
16 USE cp_dbcsr_api, ONLY: dbcsr_p_type
17 USE cp_fm_types, ONLY: cp_fm_type
20 USE kinds, ONLY: dp
22 USE physcon, ONLY: bohr
23 USE pw_types, ONLY: pw_r3d_rs_type
28 USE qs_mo_types, ONLY: get_mo_set,&
30#include "./base/base_uses.f90"
31
32 IMPLICIT NONE
33
34 PRIVATE
36
37 REAL(KIND=dp), PARAMETER, PRIVATE :: hartree_to_ev = 27.211386245988_dp
38
39 CHARACTER(len=*), PARAMETER, PRIVATE :: moduleN = 'qs_electrons_workfunction'
40
41CONTAINS
42
43! **************************************************************************************************
44!> \brief Average the Hartree potential over a slab perpendicular to a lattice axis.
45!> \param v_hartree_rspace Hartree potential on the real-space grid
46!> \param para_env parallel environment of the grid
47!> \param axis axis (1=x, 2=y, 3=z) along which the potential is planar-averaged
48!> \param minimum_A lower bound of the averaging slab, Angstrom
49!> \param maximum_A upper bound of the averaging slab, Angstrom
50!> \param v_avg_hartree the averaged potential, Hartree
51! **************************************************************************************************
52 SUBROUTINE planar_hartree_average(v_hartree_rspace, para_env, axis, minimum_A, maximum_A, &
53 v_avg_hartree)
54 TYPE(pw_r3d_rs_type), POINTER :: v_hartree_rspace
55 TYPE(mp_para_env_type), POINTER :: para_env
56 INTEGER, INTENT(IN) :: axis
57 REAL(KIND=dp), INTENT(IN) :: minimum_a, maximum_a
58 REAL(KIND=dp), INTENT(OUT) :: v_avg_hartree
59
60 INTEGER :: grid_index, ix, iy, iz
61 INTEGER, DIMENSION(2, 3) :: bounds_global, bounds_local
62 REAL(KIND=dp) :: cell_hmat(3, 3), coordinate_bohr, cross_product(3), face_norm, height_bohr, &
63 local_count, local_sum, maximum_bohr, minimum_bohr, udvol
64
65 IF (.NOT. ASSOCIATED(para_env)) THEN
66 cpabort("Planar-potential average could not access para_env.")
67 END IF
68 IF (.NOT. ASSOCIATED(v_hartree_rspace)) THEN
69 cpabort("Planar-potential average could not access the Hartree potential grid.")
70 END IF
71 IF (.NOT. ASSOCIATED(v_hartree_rspace%array)) THEN
72 cpabort("Planar-potential average found an unallocated Hartree potential grid.")
73 END IF
74 IF (.NOT. ASSOCIATED(v_hartree_rspace%pw_grid)) THEN
75 cpabort("Planar-potential average found a Hartree potential grid without metadata.")
76 END IF
77 IF (v_hartree_rspace%pw_grid%dvol <= 0.0_dp) THEN
78 cpabort("Planar-potential average found an invalid Hartree potential grid volume.")
79 END IF
80
81 minimum_bohr = minimum_a*bohr
82 maximum_bohr = maximum_a*bohr
83 IF (axis < 1 .OR. axis > 3) THEN
84 cpabort("Planar-potential average received an invalid averaging axis.")
85 END IF
86 IF (maximum_bohr <= minimum_bohr) THEN
87 cpabort("Planar-potential average requires potential_average_max_A > min_A.")
88 END IF
89
90 cell_hmat(:, 1) = v_hartree_rspace%pw_grid%dh(:, 1)* &
91 REAL(v_hartree_rspace%pw_grid%npts(1), KIND=dp)
92 cell_hmat(:, 2) = v_hartree_rspace%pw_grid%dh(:, 2)* &
93 REAL(v_hartree_rspace%pw_grid%npts(2), KIND=dp)
94 cell_hmat(:, 3) = v_hartree_rspace%pw_grid%dh(:, 3)* &
95 REAL(v_hartree_rspace%pw_grid%npts(3), KIND=dp)
96 SELECT CASE (axis)
97 CASE (1)
98 cross_product(1) = cell_hmat(2, 2)*cell_hmat(3, 3) - cell_hmat(3, 2)*cell_hmat(2, 3)
99 cross_product(2) = cell_hmat(3, 2)*cell_hmat(1, 3) - cell_hmat(1, 2)*cell_hmat(3, 3)
100 cross_product(3) = cell_hmat(1, 2)*cell_hmat(2, 3) - cell_hmat(2, 2)*cell_hmat(1, 3)
101 CASE (2)
102 cross_product(1) = cell_hmat(2, 3)*cell_hmat(3, 1) - cell_hmat(3, 3)*cell_hmat(2, 1)
103 cross_product(2) = cell_hmat(3, 3)*cell_hmat(1, 1) - cell_hmat(1, 3)*cell_hmat(3, 1)
104 cross_product(3) = cell_hmat(1, 3)*cell_hmat(2, 1) - cell_hmat(2, 3)*cell_hmat(1, 1)
105 CASE (3)
106 cross_product(1) = cell_hmat(2, 1)*cell_hmat(3, 2) - cell_hmat(3, 1)*cell_hmat(2, 2)
107 cross_product(2) = cell_hmat(3, 1)*cell_hmat(1, 2) - cell_hmat(1, 1)*cell_hmat(3, 2)
108 cross_product(3) = cell_hmat(1, 1)*cell_hmat(2, 2) - cell_hmat(2, 1)*cell_hmat(1, 2)
109 END SELECT
110 face_norm = sqrt(sum(cross_product**2))
111 IF (.NOT. ieee_is_finite(face_norm) .OR. face_norm <= 0.0_dp) THEN
112 cpabort("Planar-potential average found a singular cell face.")
113 END IF
114 height_bohr = v_hartree_rspace%pw_grid%vol/face_norm
115 IF (.NOT. ieee_is_finite(height_bohr) .OR. height_bohr <= 0.0_dp) THEN
116 cpabort("Planar-potential average found an invalid cell height.")
117 END IF
118 IF (minimum_bohr < -1.0e-10_dp .OR. maximum_bohr > height_bohr + 1.0e-10_dp) THEN
119 cpabort("CP2K potential_average_region lies outside the cell")
120 END IF
121
122 udvol = 1.0_dp/v_hartree_rspace%pw_grid%dvol
123 local_sum = 0.0_dp
124 local_count = 0.0_dp
125
126 bounds_global = v_hartree_rspace%pw_grid%bounds
127 bounds_local = v_hartree_rspace%pw_grid%bounds_local
128
129 DO iz = bounds_local(1, 3), bounds_local(2, 3)
130 DO iy = bounds_local(1, 2), bounds_local(2, 2)
131 DO ix = bounds_local(1, 1), bounds_local(2, 1)
132 SELECT CASE (axis)
133 CASE (1)
134 grid_index = ix - bounds_global(1, 1)
135 CASE (2)
136 grid_index = iy - bounds_global(1, 2)
137 CASE (3)
138 grid_index = iz - bounds_global(1, 3)
139 END SELECT
140 coordinate_bohr = real(grid_index, kind=dp)/ &
141 REAL(v_hartree_rspace%pw_grid%npts(axis), KIND=dp)*height_bohr
142 IF (coordinate_bohr >= minimum_bohr .AND. coordinate_bohr <= maximum_bohr) THEN
143 local_sum = local_sum + v_hartree_rspace%array(ix, iy, iz)*udvol
144 local_count = local_count + 1.0_dp
145 END IF
146 END DO
147 END DO
148 END DO
149
150 CALL para_env%sum(local_sum)
151 CALL para_env%sum(local_count)
152 IF (local_count <= 0.0_dp) THEN
153 cpabort("Planar-potential average found no grid points in the requested region.")
154 END IF
155
156 v_avg_hartree = local_sum/local_count
157 END SUBROUTINE planar_hartree_average
158
159! **************************************************************************************************
160!> \brief Compute the work function (vacuum Hartree level minus Fermi level, in eV)
161!> from the planar average of the Hartree potential of this force_env's own
162!> converged SCF and its Fermi level.
163!> \param force_env force_env whose qs_env holds the converged SCF result
164!> \param axis axis (1=x, 2=y, 3=z) along which the potential is planar-averaged
165!> \param minimum_A lower bound of the averaging slab, Angstrom
166!> \param maximum_A upper bound of the averaging slab, Angstrom
167!> \param fermi_level_eV returned Fermi level, eV
168!> \param workfunction_eV returned work function, eV
169! **************************************************************************************************
170 SUBROUTINE qs_electrons_compute_workfunction(force_env, axis, minimum_A, maximum_A, &
171 fermi_level_eV, workfunction_eV)
172 TYPE(force_env_type), POINTER :: force_env
173 INTEGER, INTENT(IN) :: axis
174 REAL(kind=dp), INTENT(IN) :: minimum_a, maximum_a
175 REAL(kind=dp), INTENT(OUT) :: fermi_level_ev, workfunction_ev
176
177 CHARACTER(LEN=*), PARAMETER :: routinen = 'qs_electrons_compute_workfunction'
178
179 INTEGER :: handle, homo, ispin, nmo, nspin
180 REAL(kind=dp) :: fermi_hartree, v_avg_hartree
181 REAL(kind=dp), DIMENSION(:), POINTER :: mo_eigenvalues
182 TYPE(cp_fm_type), POINTER :: mo_coeff
183 TYPE(dbcsr_p_type), DIMENSION(:), POINTER :: matrix_ks
184 TYPE(dft_control_type), POINTER :: dft_control
185 TYPE(mo_set_type), DIMENSION(:), POINTER :: mos
186 TYPE(mp_para_env_type), POINTER :: para_env
187 TYPE(pw_r3d_rs_type), POINTER :: v_hartree_rspace
188 TYPE(qs_energy_type), POINTER :: energy
189 TYPE(qs_environment_type), POINTER :: qs_env
190
191 CALL timeset(routinen, handle)
192
193 IF (axis < 1 .OR. axis > 3) THEN
194 cpabort("workfunction axis must be x, y, or z.")
195 END IF
196 IF (maximum_a <= minimum_a) THEN
197 cpabort("workfunction region requires maximum_A > minimum_A.")
198 END IF
199
200 NULLIFY (qs_env)
201 CALL force_env_get(force_env, qs_env=qs_env)
202 IF (.NOT. ASSOCIATED(qs_env)) THEN
203 cpabort("workfunction update requires a QS force environment.")
204 END IF
205
206 NULLIFY (energy, mos, dft_control, matrix_ks, mo_coeff, mo_eigenvalues, para_env, &
207 v_hartree_rspace)
208 CALL get_qs_env(qs_env, energy=energy, mos=mos, dft_control=dft_control, matrix_ks=matrix_ks, &
209 para_env=para_env, v_hartree_rspace=v_hartree_rspace)
210 IF (.NOT. ASSOCIATED(energy)) THEN
211 cpabort("workfunction update could not access QS energy data.")
212 END IF
213
214 ! Tier 1: standard diagonalization sets energy%efermi directly.
215 fermi_hartree = energy%efermi
216 IF (fermi_hartree == 0.0_dp) THEN
217 ! Tier 2: fall back to the average MO chemical potential (e.g. smearing).
218 IF (.NOT. ASSOCIATED(mos)) THEN
219 cpabort("Fermi level unset; no MO data available.")
220 END IF
221 IF (SIZE(mos) <= 0) cpabort("MO array is empty.")
222 nspin = SIZE(mos)
223 fermi_hartree = 0.0_dp
224 DO ispin = 1, nspin
225 IF (.NOT. ieee_is_finite(mos(ispin)%mu)) THEN
226 cpabort("MO chemical potential not finite.")
227 END IF
228 fermi_hartree = fermi_hartree + mos(ispin)%mu
229 END DO
230 fermi_hartree = fermi_hartree/real(nspin, kind=dp)
231 END IF
232
233 IF (abs(fermi_hartree) <= 10.0_dp*epsilon(fermi_hartree)) THEN
234 ! Tier 3: OT does not populate mo_set%mu or energy%efermi. Compute the
235 ! occupied-subspace Ritz eigenvalues from the converged KS matrix and use
236 ! the HOMO as the zero-temperature electronic chemical potential.
237 ! Open shell: the chemical potential is the HIGHER of the two spin
238 ! HOMOs (the level an electron leaves first), not their mean, which
239 ! sits between them and biases e_F whenever the channels differ.
240 IF (.NOT. ASSOCIATED(mos) .OR. .NOT. ASSOCIATED(matrix_ks)) THEN
241 cpabort("OT fallback needs MO and KS-matrix data.")
242 END IF
243 IF (SIZE(matrix_ks) < SIZE(mos)) THEN
244 cpabort("OT fallback found too few KS matrices.")
245 END IF
246 IF (ASSOCIATED(dft_control)) THEN
247 IF (dft_control%do_admm) THEN
248 cpabort("OT fallback does not support ADMM.")
249 END IF
250 END IF
251 nspin = SIZE(mos)
252 fermi_hartree = -huge(0.0_dp)
253 DO ispin = 1, nspin
254 NULLIFY (mo_coeff, mo_eigenvalues)
255 homo = 0
256 nmo = 0
257 CALL get_mo_set(mos(ispin), mo_coeff=mo_coeff, &
258 eigenvalues=mo_eigenvalues, homo=homo, nmo=nmo)
259 IF (.NOT. ASSOCIATED(mo_coeff) .OR. .NOT. ASSOCIATED(mo_eigenvalues)) THEN
260 cpabort("OT fallback could not access orbitals.")
261 END IF
262 IF (homo <= 0 .OR. homo > nmo .OR. homo > SIZE(mo_eigenvalues)) THEN
263 cpabort("OT fallback found an invalid HOMO index.")
264 END IF
265 CALL calculate_subspace_eigenvalues(orbitals=mo_coeff, &
266 ks_matrix=matrix_ks(ispin)%matrix, &
267 evals_arg=mo_eigenvalues, &
268 do_rotation=.false.)
269 IF (.NOT. ieee_is_finite(mo_eigenvalues(homo))) THEN
270 cpabort("OT HOMO energy not finite.")
271 END IF
272 fermi_hartree = max(fermi_hartree, mo_eigenvalues(homo))
273 END DO
274 END IF
275
276 IF (.NOT. ieee_is_finite(fermi_hartree)) THEN
277 cpabort("Fermi level not finite.")
278 END IF
279 IF (abs(fermi_hartree) <= 10.0_dp*epsilon(fermi_hartree)) THEN
280 cpabort("Fermi level unset after OT fallback.")
281 END IF
282 fermi_level_ev = fermi_hartree*hartree_to_ev
283
284 ! The average is taken from this force_env's own Hartree potential, so that the two
285 ! endpoints of a charge-mixing run each contribute their own vacuum level.
286 CALL planar_hartree_average(v_hartree_rspace, para_env, axis, minimum_a, maximum_a, &
287 v_avg_hartree)
288 workfunction_ev = v_avg_hartree*hartree_to_ev - fermi_level_ev
289
290 CALL timestop(handle)
291
293
Defines control structures, which contain the parameters and the settings for the DFT-based calculati...
represent a full matrix distributed on many processors
Definition cp_fm_types.F:15
Interface for the force calculations.
recursive subroutine, public force_env_get(force_env, in_use, fist_env, qs_env, meta_env, fp_env, subsys, para_env, potential_energy, additional_potential, kinetic_energy, harmonic_shell, kinetic_shell, cell, sub_force_env, qmmm_env, qmmmx_env, eip_env, pwdft_env, globenv, input, force_env_section, method_name_id, root_section, mixed_env, nnp_env, embed_env, ipi_env)
returns various attributes about the force environment
Defines the basic variable types.
Definition kinds.F:23
integer, parameter, public dp
Definition kinds.F:34
Interface to the message passing library MPI.
Definition of physical constants:
Definition physcon.F:68
real(kind=dp), parameter, public bohr
Definition physcon.F:147
Work function and Fermi level readback from the converged SCF, using the planar average of the Hartre...
subroutine, public qs_electrons_compute_workfunction(force_env, axis, minimum_a, maximum_a, fermi_level_ev, workfunction_ev)
Compute the work function (vacuum Hartree level minus Fermi level, in eV) from the planar average of ...
subroutine, public get_qs_env(qs_env, atomic_kind_set, qs_kind_set, cell, super_cell, cell_ref, use_ref_cell, kpoints, dft_control, mos, sab_orb, sab_all, qmmm, qmmm_periodic, mimic, sac_ae, sac_ppl, sac_lri, sap_ppnl, sab_vdw, sab_scp, sap_oce, sab_lrc, sab_se, sab_xtbe, sab_tbe, sab_core, sab_xb, sab_xtb_pp, sab_xtb_nonbond, sab_almo, sab_kp, sab_kp_nosym, sab_cneo, particle_set, energy, force, matrix_h, matrix_h_im, matrix_ks, matrix_ks_im, matrix_vxc, run_rtp, rtp, matrix_h_kp, matrix_h_im_kp, matrix_ks_kp, matrix_ks_im_kp, matrix_vxc_kp, kinetic_kp, matrix_s_kp, matrix_w_kp, matrix_s_ri_aux_kp, matrix_s, matrix_s_ri_aux, matrix_w, matrix_p_mp2, matrix_p_mp2_admm, matrix_vhxc, rho, rho_xc, pw_env, ewald_env, ewald_pw, active_space, mpools, input, para_env, blacs_env, scf_control, rel_control, kinetic, qs_charges, vppl, xcint_weights, rho_core, rho_nlcc, rho_nlcc_g, ks_env, ks_qmmm_env, wf_history, scf_env, local_particles, local_molecules, distribution_2d, dbcsr_dist, molecule_kind_set, molecule_set, subsys, cp_subsys, oce, local_rho_set, rho_atom_set, task_list, task_list_soft, rho0_atom_set, rho0_mpole, rhoz_set, rhoz_cneo_set, ecoul_1c, rho0_s_rs, rho0_s_gs, rhoz_cneo_s_rs, rhoz_cneo_s_gs, do_kpoints, has_unit_metric, requires_mo_derivs, mo_derivs, mo_loc_history, nkind, natom, nelectron_total, nelectron_spin, efield, neighbor_list_id, linres_control, xas_env, virial, cp_ddapc_env, cp_ddapc_ewald, outer_scf_history, outer_scf_ihistory, x_data, et_coupling, dftb_potential, results, se_taper, se_store_int_env, se_nddo_mpole, se_nonbond_env, admm_env, lri_env, lri_density, exstate_env, ec_env, harris_env, dispersion_env, gcp_env, vee, rho_external, external_vxc, mask, mp2_env, bs_env, kg_env, wanniercentres, atprop, ls_scf_env, do_transport, transport_env, v_hartree_rspace, s_mstruct_changed, rho_changed, potential_changed, forces_up_to_date, mscfg_env, almo_scf_env, gradient_history, variable_history, embed_pot, spin_embed_pot, polar_env, mos_last_converged, eeq, rhs, do_rixs, tb_tblite)
Get the QUICKSTEP environment.
collects routines that perform operations directly related to MOs
Definition and initialisation of the mo data type.
Definition qs_mo_types.F:22
subroutine, public get_mo_set(mo_set, maxocc, homo, lfomo, nao, nelectron, n_el_f, nmo, eigenvalues, occupation_numbers, mo_coeff, mo_coeff_b, uniform_occupation, kts, mu, flexible_electron_count, cmo_coeff)
Get the components of a MO set data structure.
represent a full matrix
wrapper to abstract the force evaluation of the various methods
stores all the informations relevant to an mpi environment