Debian Codegraph @

GUI/PWgui/doc/pwdocs/user_guide/node12.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3 <!--Converted with LaTeX2HTML 2019.2 (Released June 5, 2019) -->
4 <HTML lang="EN">
5 <HEAD>
6 <TITLE>2.5 Libxc library</TITLE>
7 <META NAME="description" CONTENT="2.5 Libxc library">
8 <META NAME="keywords" CONTENT="user_guide">
9 <META NAME="resource-type" CONTENT="document">
10 <META NAME="distribution" CONTENT="global">
11
12 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
13 <META NAME="viewport" CONTENT="width=device-width, initial-scale=1.0">
14 <META NAME="Generator" CONTENT="LaTeX2HTML v2019.2">
15
16 <LINK REL="STYLESHEET" HREF="user_guide.css">
17
18 <LINK REL="next" HREF="node13.html">
19 <LINK REL="previous" HREF="node11.html">
20 <LINK REL="next" HREF="node13.html">
21 </HEAD>
22
23 <BODY >
24 <!--Navigation Panel-->
25 <A
26 HREF="node13.html">
27 <IMG WIDTH="37" HEIGHT="24" ALT="next" SRC="next.png"></A>
28 <A
29 HREF="node7.html">
30 <IMG WIDTH="26" HEIGHT="24" ALT="up" SRC="up.png"></A>
31 <A
32 HREF="node11.html">
33 <IMG WIDTH="63" HEIGHT="24" ALT="previous" SRC="prev.png"></A>
34 <A ID="tex2html174"
35 HREF="node1.html">
36 <IMG WIDTH="65" HEIGHT="24" ALT="contents" SRC="contents.png"></A>
37 <BR>
38 <B> Next:</B> <A
39 HREF="node13.html">2.6 Compilation</A>
40 <B> Up:</B> <A
41 HREF="node7.html">2 Installation</A>
42 <B> Previous:</B> <A
43 HREF="node11.html">2.4 Libraries</A>
44 <B> <A ID="tex2html175"
45 HREF="node1.html">Contents</A></B>
46 <BR>
47 <BR>
48 <!--End of Navigation Panel-->
49 <!--Table of Child-Links-->
50 <A ID="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
51
52 <UL>
53 <LI><A ID="tex2html176"
54 HREF="node12.html#SECTION00035100000000000000">2.5.1 Linking in Q<SMALL>UANTUM </SMALL>ESPRESSO</A>
55 <UL>
56 <LI><A ID="tex2html177"
57 HREF="node12.html#SECTION00035110000000000000">2.5.1.1 Note for version 5.0.0:</A>
58 </UL>
59 <BR>
60 <LI><A ID="tex2html178"
61 HREF="node12.html#SECTION00035200000000000000">2.5.2 Usage</A>
62 <LI><A ID="tex2html179"
63 HREF="node12.html#SECTION00035300000000000000">2.5.3 Differences between Libxc and internal functionals</A>
64 <LI><A ID="tex2html180"
65 HREF="node12.html#SECTION00035400000000000000">2.5.4 Special cases</A>
66 <UL>
67 <LI><A ID="tex2html181"
68 HREF="node12.html#SECTION00035410000000000000">2.5.4.1 External parameters.</A>
69 <LI><A ID="tex2html182"
70 HREF="node12.html#SECTION00035420000000000000">2.5.4.2 Hybrid functionals.</A>
71 <LI><A ID="tex2html183"
72 HREF="node12.html#SECTION00035430000000000000">2.5.4.3 Functionals with partial output.</A>
73 <LI><A ID="tex2html184"
74 HREF="node12.html#SECTION00035440000000000000">2.5.4.4 Other functionals.</A>
75 </UL>
76 <BR>
77 <LI><A ID="tex2html185"
78 HREF="node12.html#SECTION00035500000000000000">2.5.5 XC test</A>
79 </UL>
80 <!--End of Table of Child-Links-->
81 <HR>
82
83 <H2><A ID="SECTION00035000000000000000">
84 2.5 Libxc library</A>
85 </H2>
86
87 <P>
88 Q<SMALL>UANTUM </SMALL>ESPRESSO is compatible with <TT>libxc</TT> version 4.3.0 or later (compatibility with older versions is not guaranteed).
89 <BR>
90 The <TT>libxc</TT> functionals are available for LDA, GGA and metaGGA, however, not all of them are straightforwardly usable. Some of them may depend on specific external parameters and some others may provide as output the energy or the potential, but not both. Therefore some attention has to be paid when using <TT>libxc</TT>. Warning messages should appear in the output when particular cases whose correct operation in Q<SMALL>UANTUM </SMALL>ESPRESSO is not guaranteed are chosen.
91
92 <P>
93
94 <H3><A ID="SECTION00035100000000000000">
95 2.5.1 Linking in Q<SMALL>UANTUM </SMALL>ESPRESSO</A>
96 </H3>
97 Once installed <TT>libxc</TT>, the linking with Q<SMALL>UANTUM </SMALL>ESPRESSO can be enabled directly through the configuration script by adding the two switches <TT>&ndash;with-libxc</TT> and <TT>&ndash;with-libxc-prefix</TT>, e.g.:
98 <PRE>
99 ./configure --with-libxc --with-libxc-prefix='/path/to/libxc/'
100 </PRE>
101 By adding the first switch only an automatic search for the libxc folder will be attempted, but its success is not guaranteed. It is always preferable to specify the second switch too. Optionally, a third switch can be added, namely <TT>&ndash;with-libxc-include='/path/to/libxc/include'</TT>, which specifies the path to the Fortran headers (usually it is not necessary).
102
103 <P>
104 Alternatively, the link to <TT>libxc</TT> can be activated after the configuration of Q<SMALL>UANTUM </SMALL>ESPRESSO by modifying the <TT>make.inc</TT> file in the main folder in this way:
105
106 <UL>
107 <LI>add <TT>-D__LIBXC</TT> to <TT>DFLAGS</TT>
108 </LI>
109 <LI>add <TT>-I/path/to/libxc/include/</TT> to <TT>IFLAGS</TT>
110 </LI>
111 <LI>set <TT>LD_LIBS=-L/path/to/libxc/lib/ -lxcf90 -lxc</TT>
112 </LI>
113 </UL>
114 Then Q<SMALL>UANTUM </SMALL>ESPRESSO can be compiled as usual. If the version of <TT>libxc</TT> is older than 5.0.0, the last point must be replaced by:
115
116 <UL>
117 <LI>set <TT>LD_LIBS=-L/path/to/libxc/lib/ -lxcf03 -lxc</TT>
118 </LI>
119 </UL>
120 <H4><A ID="SECTION00035110000000000000">
121 2.5.1.1 Note for version 5.0.0:</A>
122 </H4> the <TT>f03</TT> interfaces are no longer available in <TT>libxc</TT> 5.0.0. They have been reintroduced in the current develop version. Version 5.0.0 is still usable, but, before compiling Q<SMALL>UANTUM </SMALL>ESPRESSO, a string replacement is necessary, namely `<TT>xc_f03</TT>' must be repalced with `<TT>xc_f90</TT>' everywhere in the following files: <TT>funct.f90</TT>, <TT>xc_lda_lsda_drivers.f90</TT>, <TT>xc_gga_drivers.f90</TT>, <TT>xc_mgga_drivers.f90</TT>, <TT>dmxc_drivers.f90</TT> and <TT>dgcxc_drivers.f90</TT> in <TT>Modules</TT> folder and <TT>xctest_qe_libxc.f90</TT> in <TT>PP/src</TT> folder.
123
124 <P>
125
126 <H3><A ID="SECTION00035200000000000000">
127 2.5.2 Usage</A>
128 </H3>
129 In order to use <TT>libxc</TT> functionals, you must enforce them from input by including the <TT>input_dft</TT> string in the <TT>system</TT> namelist. For example, to use the <TT>libxc</TT> version of the PBE functionals (both exchange and correlation):
130 <PRE>
131 input_dft = `gga_x_pbe gga_c_pbe'
132 </PRE>
133 Capital or lowercase is not relevant, neither the separation between one name and the other. The complete list of <TT>libxc</TT> functionals is available at:
134 <PRE>
135 https://www.tddft.org/programs/libxc/functionals/
136 </PRE>
137 Combinations of Q<SMALL>UANTUM </SMALL>ESPRESSO and <TT>libxc</TT> functionals are allowed in <TT>PW</TT>, but some attention has to be paid to their reciprocal compatibility (see section below). In these cases, again, the functionals must be enforced from input. For example, the exchange term of PBE in Q<SMALL>UANTUM </SMALL>ESPRESSO together with the correlation term of PBE in <TT>libxc</TT> is obtained by putting:
138 <PRE>
139 input_dft = `sla pbe gga_c_pbe'
140 </PRE>
141 Note that when using GGA functionals of Q<SMALL>UANTUM </SMALL>ESPRESSO you must always specify the LDA term too, while it is not the case for the <TT>libxc</TT> ones.
142 <BR>
143 Outside <TT>PW</TT> (<TT>PHonon</TT>, <TT>PP</TT>, etc.), <TT>libxc</TT> functionals are still usable, but in these cases it is highly recommended to avoid combinations of QE and <TT>libxc</TT> functionals together, since, at present, they may lead to some issues in the dft detection.
144
145 <H3><A ID="SECTION00035300000000000000">
146 2.5.3 Differences between Libxc and internal functionals</A>
147 </H3>
148 There are some differences between Q<SMALL>UANTUM </SMALL>ESPRESSO functionals and <TT>libxc</TT> ones. In Q<SMALL>UANTUM </SMALL>ESPRESSO the LDA and the GGA terms are separated and must be specified independently. In <TT>libxc</TT> the GGA functionals already include the LDA part (Slater exchange and Perdew&amp;Wang correlation in most of the cases with the exception, for example, of Lee Yang Parr functionals).
149 <BR>
150 The <TT>libxc</TT> metaGGA functionals may or may not need the LDA and GGA terms, depending on the cases, therefore a good check of the chosen functionals is recommended before doing expensive runs.
151 <BR>
152 Some functionals in <TT>libxc</TT> incorporate the exchange part and the correlation one into one term only (e.g. the ones that include the `<TT>_xc</TT>' label in their name). In these cases the whole functional is formally treated as `exchange only' by Q<SMALL>UANTUM </SMALL>ESPRESSO. This does not imply any loss of information.
153
154 <H3><A ID="SECTION00035400000000000000">
155 2.5.4 Special cases</A>
156 </H3>
157 A number of <TT>libxc</TT> functional routines need extra information on input and/or provide only partial information on output (e.g. the energy or the potential only). In these cases the use of such functionals may not be straightforward and, depending on the cases, may require some work on the Q<SMALL>UANTUM </SMALL>ESPRESSO source code.
158
159 <H4><A ID="SECTION00035410000000000000">
160 2.5.4.1 External parameters.</A>
161 </H4>
162 Several functionals in <TT>libxc</TT> depend on one or more external parameters. Some of these can be recovered inside Q<SMALL>UANTUM </SMALL>ESPRESSO, some others are not directly available. In all these cases a direct intervention on the Q<SMALL>UANTUM </SMALL>ESPRESSO source code is necessary in order to be able to properly use such functionals.
163 <BR>
164 The <TT>libxc</TT> routine <TT>xc_f03_func_set_ext_params</TT> allows to set the value of the external parameters, which are contained in a single array. A trace for the usage of this routine is present, among the comments, in the XC-drivers of Q<SMALL>UANTUM </SMALL>ESPRESSO (in <TT>Modules</TT> folder: <TT>xc_lda_lsda_drivers.f90</TT>, <TT>xc_gga_drivers.f90</TT>, etc.).
165 <BR>
166 Without setting the external parameters inside the code, their default value will be assumed. This could lead to results different from the expectations.
167 To get the default values, the <TT>xc_f03_func_info_get_ext_params_default_value</TT> routine is available in <TT>libxc</TT>. For more details we refer to the official documentation of <TT>libxc</TT>.
168 <BR>
169 In any case, when external parameters are needed by the chosen functionals, a warning message will appear in the output of Q<SMALL>UANTUM </SMALL>ESPRESSO.
170
171 <H4><A ID="SECTION00035420000000000000">
172 2.5.4.2 Hybrid functionals.</A>
173 </H4> The hybrid functionals of <TT>libxc</TT> are allowed, but, as in the previous case, their correct operation is not guaranteed by default. It is important to ensure that the <TT>exx_fraction</TT> in Q<SMALL>UANTUM </SMALL>ESPRESSO assumes the desired value when the XC routines are called. To do this you need to act on the external parameters of the functionals, as explained previously. Moreover it is important to ensure that the starting value of the variable <TT>exx_fraction</TT> in Q<SMALL>UANTUM </SMALL>ESPRESSO , which is set in the <TT>matching_libxc</TT> routine in <TT>Modules/funct.f90</TT>, is the desired one (<TT>exx_fraction</TT> may not always coincide with the <TT>exx_coef</TT> of <TT>libxc</TT>).
174
175 <H4><A ID="SECTION00035430000000000000">
176 2.5.4.3 Functionals with partial output.</A>
177 </H4>
178 A few <TT>libxc</TT> functional routines provides the energy and some others the potential only, but not both of them. At present, Q<SMALL>UANTUM </SMALL>ESPRESSO, assumes that both the energy and the potential are provided when a XC-functional routine is called, therefore, in order to use these functionals, some modifications on the code will be necessary.
179
180 <H4><A ID="SECTION00035440000000000000">
181 2.5.4.4 Other functionals.</A>
182 </H4> Besides exchange (<TT>_x</TT>), correlation (<TT>_c</TT>) and exchange plus correlation (<TT>_xc</TT>), a fourth kind of functionals is available in <TT>libxc</TT>, the kinetic functionals (<TT>_k</TT>). At present, they are not usable in Q<SMALL>UANTUM </SMALL>ESPRESSO.
183
184 <H3><A ID="SECTION00035500000000000000">
185 2.5.5 XC test</A>
186 </H3>
187 A simple testing program, <TT>xctest_qe_libxc.f90</TT>, for the XC part of Q<SMALL>UANTUM </SMALL>ESPRESSO is available in the <TT>PP/src</TT> folder.
188 <BR>
189 The program tests the output (energies and potentials) of the XC-driver routines by comparing the results obtained with the Q<SMALL>UANTUM </SMALL>ESPRESSO internal library of XC functionals with those obtained with the <TT>libxc</TT> library.
190 <BR>
191 It also tests the XC-derivative part (mainly used in PHonon) by comparing the QE derivative of the XC potential (for LDA and GGA) with the <TT>libxc</TT> one.
192
193 <P>
194 <HR>
195 <!--Navigation Panel-->
196 <A
197 HREF="node13.html">
198 <IMG WIDTH="37" HEIGHT="24" ALT="next" SRC="next.png"></A>
199 <A
200 HREF="node7.html">
201 <IMG WIDTH="26" HEIGHT="24" ALT="up" SRC="up.png"></A>
202 <A
203 HREF="node11.html">
204 <IMG WIDTH="63" HEIGHT="24" ALT="previous" SRC="prev.png"></A>
205 <A ID="tex2html174"
206 HREF="node1.html">
207 <IMG WIDTH="65" HEIGHT="24" ALT="contents" SRC="contents.png"></A>
208 <BR>
209 <B> Next:</B> <A
210 HREF="node13.html">2.6 Compilation</A>
211 <B> Up:</B> <A
212 HREF="node7.html">2 Installation</A>
213 <B> Previous:</B> <A
214 HREF="node11.html">2.4 Libraries</A>
215 <B> <A ID="tex2html175"
216 HREF="node1.html">Contents</A></B>
217 <!--End of Navigation Panel-->
218
219 </BODY>
220 </HTML>