TEXT   11

# peqm

Guest on 19th May 2022 03:24:04 PM

1. :orphan:
2.
3. .. index:: *PEQM
4. .. _*PEQM:
5.
6. ======
7. \*PEQM
8. ======
9.
10. Polarizable embedding model
11.
12. This input section controls calculations using the polarizable embedding (PE) model.
13. In DIRAC it is possible to include the effects from a structured environment on a core
14. molecular system using the polarizable embedding (PE) model. The current implemen-
15. tation is a layered QM/MM-type embedding model capable of using advanced potentials
16. that include an electrostatic component as well as an induction (polarization) component.
17. The effects of the environment are included through effective operators that contain an em-
18. bedding potential, which is a representation of the environment, thereby directly affecting
19. the molecular properties of the core system. The wave function of the core system is opti-
20. mized while taking into account the explicit electrostatic interactions and induction effects
21. from the environment in a fully self-consistent manner. The electrostatic and induction
22. components are modeled using Cartesian multipole moments and anisotropic dipole-dipole
23. polarizabilities, respectively. The electrostatic part models the permanent charge distribu-
24. tion of the environment and will polarize the core system, while the induction part also
25. allows polarization of the environment. The environment response is included in the effec-
26. tive operator as induced dipoles, which arise due to the electric fields from the electrons and
27. nuclei in the core system as well as from the environment itself. It is therefore necessary
28. to recalculate the induced dipoles according to the changes in the electron density of the
29. core system as they occur in a wave function optimization. Furthermore, since the induced
30. dipoles are coupled through the electric fields, it is necessary to solve a set of coupled linear
31. equations. This can be done using either an iterative or a direct solver. This also means
32. that we include many-body effects of the total system.
33.
34. The multipoles and polarizabilities can be obtained in many different ways. It is
35. possible to use the molecular properties, however, usually distributed/localized properties
36. are used because of the better convergence of the multipole expansion. These are typically
37. centered on all atomic sites in the environment (and sometimes also bond-midpoints), how-
38. ever, the implementation is general in this sense so they can be placed anywhere in space.
39. Currently, the PE library supports multipole moments up to fifth order and anisotropic
40. dipole-dipole polarizabilities are supported. For multipoles up to and including third order
41. (octopoles) the trace will be removed if present. Note, that the fourth and fifth order multi-
42. pole moments are expected to be traceless. In case polarizabilities are included it might be
43. necessary to use an exclusion list to ensure that only relevant sites can polarize each other.
44. The format of the POTENTIAL.INP file is demonstrated below.
45.
46. Keywords
47. ========
48.
49. .. index:: .POTENTIAL
50. .. _PEQM_.POTENTIAL:
51.
52. .POTENTIAL
53. ----------
54.
55. This option can be used to specify a non-default name of the POTENTIAL.INP in-
56. put file that contains the embedding potential parameters, e.g.::
57.
58.    .POTENT
59.    peqm.pot
60.
61. The default name is POTENTIAL.INP.
62.
63. .. index:: .DIRECT
64. .. _PEQM_.DIRECT:
65.
66. .DIRECT
67. -------
68.
69. Use the direct solver to determine the induced dipole moments. It will explicitly build
70. a classical response matrix of size :math:3S(3S + 1)/2, where :math:S is the number of polarizable
71. sites and is therefore only recommendable for smaller molecular systems. Note that
72. this solver is not parallelized. The default is to use the iterative solver
73.
74. .. index:: .ITERATIVE
75. .. _PEQM_.ITERATIVE:
76.
77. .ITERATIVE
78. ----------
79.
80. Use the iterative solver to determine the induced dipole moments. This is the
81. default. The convergence threshold defaults to :math:1.0\cdot 10^{-8}>\sum^S_{s=1}|\mu^{(k)}_s-\mu^{(k-1)}_s|, where :math:k is the
82. current iteration, but can also be provided with this option::
83.
84.   READ (LUCMD, *) THRITER (optional)
85.
86. .. index:: .BORDER
87. .. _PEQM_.BORDER:
88.
89. .BORDER
90. -------
91.
92. Controls the handling of the border between the core molecular system and its en-
93. vironment described by the embedding potential.::
94.
95.    1) READ (LUCMD, *) BORDER_TYPE, RMIN, AUORAA
96.    2) READ (LUCMD, *) BORDER_TYPE, REDIST_ORDER, RMIN, AUORAA, NREDIST
97.
98. There are two mutually exclusive schemes:
99.    1) BORDER_TYPE = REMOVE
100.    2) BORDER_TYPE = REDIST
101.
102. The first option will remove all multipoles and polarizabilities that are within the given distance "RMIN" from any atom in the core molecular system. The "AUORAA" variable specifies
103. whether the distance threshold is given in ångström ("AA") or bohr ("AU"). The second
104. option will redistribute parameters that are within the given threshold "RMIN" from any
105. atom in the core system to nearest sites in the environment. The order of multipoles
106. up to which will be redistributed is determined by the "REDIST_ORDER" variable, e.g.
107. "REDIST_ORDER = 1" means that only charges will be redistributed and all other pa-
108. rameters removed, "REDIST_ORDER = 2" means charges and dipoles are redistributed
109. and so on. The sign of "REDIST_ORDER" specifies if the polarizabilities are redistributed.
110. Positive means that the polarizabilities are removed and negative means redistributed.
111. The number of sites that parameters on a given site are redistributed to is determined
112. by the "NREDIST" variable which can be between 1 and 3. The default is to redistribute
113. charges within 2.2 bohr to its nearest site and removing all other parameters.
114.
115. .. index:: .DAMP INDUCED
116. .. _PEQM_.DAMP INDUCED:
117.
118. .DAMP INDUCED
119. -------------
120.
121. Damp the electric fields from induced dipole moments using Thole’s exponential damp-
122. ing scheme.::
123.
124.   READ (LUCMD, *) IND_DAMP (optional)
125.
126. The default damping coefficient is the standard 2.1304.
127.
128. .. index:: .DAMP MULTIPOLE
129. .. _PEQM_.DAMP MULTIPOLE:
130.
131. .DAMP MULTIPOLE
132. ---------------
133.
134. Damp the electric fields from permanent multipole moments using Thole’s expo-
135. nential damping scheme.::
136.
137.   READ (LUCMD, *) MUL_DAMP (optional)
138.
139. This option requires polarizabilities on all sites with permanent multipole moments. The default damping coefficient is the standard 2.1304.
140.
141. .. index:: .DAMP CORE
142. .. _PEQM_.DAMP CORE:
143.
144. .DAMP CORE
145. ----------
146.
147. Damp the electric fields from the electrons and nuclei in the core region based on
148. Thole’s exponential damping scheme::
149.
150.    READ (LUCMD, *) CORE_DAMP (optional)
152.    DO I = 1, NALPHAS
154.    END DO
155.
156. The damping coefficient is optional unless isotropic polarizabilities are present. The default damping coefficient is the standard 2.1304. Standard polarizabilities from :cite:vanduijnen1998
157. have been implemented and will be used if none are given as input. However, only H, C, N, O, F, S, Cl, Br and I are available.
158.
159. .. index:: .GSPOL
160. .. _PEQM_.GSPOL:
161.
162. .GSPOL
163. ------
164.
165. Activate the ground-state polarization approximation, i.e. freeze the embedding po-
166. tential according to the ground-state density. This means that the polarizable envi-
167. ronment is self-consistently relaxed during the optimization of the ground-state den-
168. sity/wave function of the core molecular system and then kept frozen in any following
169. response calculations
170.
171. .. index:: .NOMB
172. .. _PEQM_.NOMB:
173.
174. .NOMB
175. -----
176.
177. Remove many-body effects in the environment. This is done by deactivating interac-
178. tions between inducible dipole moments.
179.
180. .. index:: .RESTART
181. .. _PEQM_.RESTART:
182.
183. .RESTART
184. --------
185.
186. Use any existing files to restart calculation.
187.
188. .. index:: .CUBE
189. .. _PEQM_.CUBE:
190.
191. .CUBE
192. -----
193.
194. Create cube file for the core molecular system containing the electrostatic potential due
195. to the final converged polarizable embedding potential.::
196.
197.    1) READ (LUCMD, *) STD_GRID
198.    2) READ (LUCMD, *) OPTION
199.    2) IF (OPTION == ’GRID’) THEN
200.    2)    READ (LUCMD, *) XSIZE, XGRID, YSIZE, YGRID, ZSIZE, ZGRID
201.    2) END IF
202.    IF (OPTION == ’FIELD’) THEN
203.       FIELD = .TRUE.
204.    END IF
205.
206. The grid density can be spec-
207. ified either using 1) standard grids (COARSE (3 points/bohr), MEDIUM (6 points/bohr)
208. or FINE (12 points/bohr) and in all cases 8.0 bohr are added in each direction) or
209. 2) the GRID option which gives full control of the cube size and density, and requires
210. an additional input line specifying the extent added (in bohr) in each direction and
211. density (in points/bohr). The default grid density is MEDIUM and default cube size
212. is the extent of the molecule plus 8.0 bohr in plus and minus each Cartesian coordi-
213. nate. If the FIELD option is given then also three cube files containing the Cartesian
214. components of the electric field from the embedding potential will be created.
215.
216. .. index:: .ISOPOL
217. .. _PEQM_.ISOPOL:
218.
219. .ISOPOL
220. -------
221.
222. Converts all anisotropic polarizabilities into isotropic polarizabilities.
223.
224. .. index:: .ZEROPOL
225. .. _PEQM_.ZEROPOL:
226.
227. .ZEROPOL
228. --------
229.
230. Remove all polarizabilities
231.
232. .. index:: .ZEROMUL
233. .. _PEQM_.ZEROMUL:
234.
235. .ZEROMUL
236. --------
237.
238. Remove all multipoles of order ZEROMUL_ORDER and up.::
239.
240.    READ (LUCMD, *) ZEROMUL_ORDER (optional)
241.
242. Remove all multipoles of order ZEROMUL_ORDER and up. The default is to remove all
243. dipoles and higher-order multipoles (i.e. ZEROMUL_ORDER = 1).
244.
245. .. index:: .VERBOSE
246. .. _PEQM_.VERBOSE:
247.
248. .VERBOSE
249. --------
250.
251. Verbose output. Currently this will print the final converged induced dipole moments.
252.
253. .. index:: .DEBUG
254. .. _PEQM_.DEBUG:
255.
256. .DEBUG
257. ------
258.
259. Debug output. Prints the total electric field and the induced dipole moments in each
260. iteration. WARNING: for large systems this will produce very large output files.
261.
262.
263.
264. The potential input format
265. ==========================
266.
267. The POTENTIAL.INP file is split into three sections: @COORDINATES, @MULTIPOLES and
268. @POLARIZABILITIES. The format is perhaps best illustrated using an example:
269.
270. .. literalinclude:: ../tutorials/polarizable_embedding/3_h2o.pot
271.
272. @COORDINATES
273. ------------
274.
275. The coordinates section follows the standard XYZ file format so that the environment can
276. be easily visualized using standard programs. The first line in gives the total number of
277. sites in the environment and the second line specifies whether the coordinates are given in
278. ångström (AA) or bohr (AU). The rest of the coordinates section is a list of the sites in the
279. environment where each line contains the element symbol and x-, y- and z-coordinates of
280. a site. If a site is not located on an atom, e.g. if it is a bond-midpoint, then the element
281. symbol should be specified as X. The listing also gives an implicit numbering of the sites,
282. so that the first line is site number one, the second line is site number two and so on. This
283. numbering is important and used in the following sections.
284.
285. @MULTIPOLES
286. -----------
287. The multipoles section is subdivided into the orders of the multipoles, i.e. ORDER 0
288. for monopoles/charges, ORDER 1 for dipoles and so on. For each order there is a number
289. specifying the number of multipoles of that specific order. Note, that this number does
290. not have to be equal to the total number of sites. This is followed by a list of multipoles
291. where each line gives the multipole of a site. The lines begin with a number that specifies
292. which site the multipole is placed. Only the symmetry-independent Cartesian multipoles
293. (given in a.u.) should be provided using an ordering such that the components are stepped
294. from the right, e.g. xx xy xz yy yz zz or xxx xxy xxz xyy xyz xzz yyy yyz yzz zzz.
295. Note, that the multipoles should in general be traceless, however, for multipoles up to and
296. including octopoles (i.e. ORDER 3) the trace is removed if present. Furthermore, the current
297. implementation is limited to fifth order multipoles.
298.
299. @POLARIZABILITIES
300. -----------------
301.
302. The polarizabilities section is also subdivided into orders, i.e. ORDER 1 1 for dipole-dipole
303. polarizabilities, which is the only type supported in the current release. The format is the
304. same as for multipoles, i.e. first line contains number of polarizabilities which is followed by
305. a list of the polarizabilities using the same ordering as the multipoles. The polarizabilities
306. should also be given in a.u. In addition, there is also the exclusion lists (EXCLISTS section).
307. Here the first line gives the number of lists (i.e. the number of lines) and the length of the
308. exclusion lists (i.e. the number of entries per line). The exclusion lists specify the polar-
309. ization rules. There is a list attached to each polarizable site that specifies which sites are
310. not allowed to polarize it, e.g. 1 2 3 4 5 means that site number 1 cannot be polarized by
311. si