1 /*
2  Copyright (C) 2006-2007 M.A.L. Marques
3 
4  This Source Code Form is subject to the terms of the Mozilla Public
5  License, v. 2.0. If a copy of the MPL was not distributed with this
6  file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 */
8 
9 #ifndef _XC_H
10 #define _XC_H
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 #include <xc_version.h>
17 #include <stddef.h>
18 
19 #define XC_UNPOLARIZED          1
20 #define XC_POLARIZED            2
21 
22 #define XC_NON_RELATIVISTIC     0
23 #define XC_RELATIVISTIC         1
24 
25 #define XC_EXCHANGE             0
26 #define XC_CORRELATION          1
27 #define XC_EXCHANGE_CORRELATION 2
28 #define XC_KINETIC              3
29 
30 #define XC_FAMILY_UNKNOWN      -1
31 #define XC_FAMILY_LDA           1
32 #define XC_FAMILY_GGA           2
33 #define XC_FAMILY_MGGA          4
34 #define XC_FAMILY_LCA           8
35 #define XC_FAMILY_OEP          16
36 #define XC_FAMILY_HYB_GGA      32
37 #define XC_FAMILY_HYB_MGGA     64
38 #define XC_FAMILY_HYB_LDA     128
39 
40 /* flags that can be used in info.flags. Don't reorder these since it
41    will break the ABI of the library. */
42 #define XC_FLAGS_HAVE_EXC         (1 <<  0) /*     1 */
43 #define XC_FLAGS_HAVE_VXC         (1 <<  1) /*     2 */
44 #define XC_FLAGS_HAVE_FXC         (1 <<  2) /*     4 */
45 #define XC_FLAGS_HAVE_KXC         (1 <<  3) /*     8 */
46 #define XC_FLAGS_HAVE_LXC         (1 <<  4) /*    16 */
47 #define XC_FLAGS_1D               (1 <<  5) /*    32 */
48 #define XC_FLAGS_2D               (1 <<  6) /*    64 */
49 #define XC_FLAGS_3D               (1 <<  7) /*   128 */
50 /* range separation via error function (usual case) */
51 #define XC_FLAGS_HYB_CAM          (1 <<  8) /*   256 */
52 /* range separation via Yukawa function (rare) */
53 #define XC_FLAGS_HYB_CAMY         (1 <<  9) /*   512 */
54 #define XC_FLAGS_VV10             (1 << 10) /*  1024 */
55 /* range separation via error function i.e. same as XC_FLAGS_HYB_CAM; deprecated */
56 #define XC_FLAGS_HYB_LC           (1 << 11) /*  2048 */
57 /* range separation via Yukawa function i.e. same as XC_FLAGS_HYB_CAMY; deprecated */
58 #define XC_FLAGS_HYB_LCY          (1 << 12) /*  4096 */
59 #define XC_FLAGS_STABLE           (1 << 13) /*  8192 */
60 /* functionals marked with the development flag may have significant problems in the implementation */
61 #define XC_FLAGS_DEVELOPMENT      (1 << 14) /* 16384 */
62 #define XC_FLAGS_NEEDS_LAPLACIAN  (1 << 15) /* 32768 */
63 
64   /* This is the case for most functionals in libxc */
65 #define XC_FLAGS_HAVE_ALL         (XC_FLAGS_HAVE_EXC | XC_FLAGS_HAVE_VXC | \
66                                    XC_FLAGS_HAVE_FXC | XC_FLAGS_HAVE_KXC | \
67                                    XC_FLAGS_HAVE_LXC)
68 
69   /* This magic value means use default parameter */
70 #define XC_EXT_PARAMS_DEFAULT   -999998888
71 
72 #define XC_TAU_EXPLICIT         0
73 #define XC_TAU_EXPANSION        1
74 
75 #define XC_MAX_REFERENCES       5
76 
77 /* This are the derivatives that a functional returns */
78 #define XC_NOARG
79 #define LDA_OUT_PARAMS_NO_EXC(P_)                                          \
80   P_ vrho, P_ v2rho2, P_ v3rho3, P_ v4rho4
81 
82 #define GGA_OUT_PARAMS_NO_EXC(P_)                                          \
83   P_ vrho, P_ vsigma,                                                      \
84   P_ v2rho2, P_ v2rhosigma, P_ v2sigma2,                                   \
85   P_ v3rho3, P_ v3rho2sigma, P_ v3rhosigma2, P_ v3sigma3,                  \
86   P_ v4rho4, P_ v4rho3sigma, P_ v4rho2sigma2, P_ v4rhosigma3, P_ v4sigma4  \
87 
88 /* This are the derivatives of a mgga
89        1st order:  4
90        2nd order: 10
91        3rd order: 20
92        4th order: 35
93  */
94 #define MGGA_OUT_PARAMS_NO_EXC(P_)                                         \
95   P_ vrho, P_ vsigma, P_ vlapl, P_ vtau,                                   \
96   P_ v2rho2, P_ v2rhosigma, P_ v2rholapl, P_ v2rhotau, P_ v2sigma2,        \
97   P_ v2sigmalapl, P_ v2sigmatau, P_ v2lapl2, P_ v2lapltau,  P_ v2tau2,     \
98   P_ v3rho3, P_ v3rho2sigma, P_ v3rho2lapl, P_ v3rho2tau, P_ v3rhosigma2,  \
99   P_ v3rhosigmalapl, P_ v3rhosigmatau, P_ v3rholapl2, P_ v3rholapltau,     \
100   P_ v3rhotau2, P_ v3sigma3, P_ v3sigma2lapl, P_ v3sigma2tau,              \
101   P_ v3sigmalapl2, P_ v3sigmalapltau, P_ v3sigmatau2, P_ v3lapl3,          \
102   P_ v3lapl2tau, P_ v3lapltau2, P_ v3tau3,                                 \
103   P_ v4rho4, P_ v4rho3sigma, P_ v4rho3lapl, P_ v4rho3tau, P_ v4rho2sigma2, \
104   P_ v4rho2sigmalapl, P_ v4rho2sigmatau, P_ v4rho2lapl2, P_ v4rho2lapltau, \
105   P_ v4rho2tau2, P_ v4rhosigma3, P_ v4rhosigma2lapl, P_ v4rhosigma2tau,    \
106   P_ v4rhosigmalapl2, P_ v4rhosigmalapltau, P_ v4rhosigmatau2,             \
107   P_ v4rholapl3, P_ v4rholapl2tau, P_ v4rholapltau2, P_ v4rhotau3,         \
108   P_ v4sigma4, P_ v4sigma3lapl, P_ v4sigma3tau, P_ v4sigma2lapl2,          \
109   P_ v4sigma2lapltau, P_ v4sigma2tau2, P_ v4sigmalapl3, P_ v4sigmalapl2tau,\
110   P_ v4sigmalapltau2, P_ v4sigmatau3, P_ v4lapl4, P_ v4lapl3tau,           \
111   P_ v4lapl2tau2, P_ v4lapltau3, P_ v4tau4
112 
113 
114 void xc_version(int *major, int *minor, int *micro);
115 const char *xc_version_string();
116 
117 struct xc_func_type;
118 
119 typedef struct{
120   const char *ref, *doi, *bibtex;
121 } func_reference_type;
122 
123 char const *xc_func_reference_get_ref(const func_reference_type *reference);
124 char const *xc_func_reference_get_doi(const func_reference_type *reference);
125 char const *xc_func_reference_get_bibtex(const func_reference_type *reference);
126 
127 typedef struct{
128   int n; /* Number of parameters */
129 
130   const char **names; /* ATTENTION: if name starts with a _ it is an *internal* parameter,
131                         changing the value effectively changes the functional! */
132   const char **descriptions; /* long description of the parameters */
133   const double *values; /* default values of the parameters */
134 
135   void (*set)(struct xc_func_type *p, const double *ext_params);
136 } func_params_type;
137 
138 typedef struct{
139   int   number;   /* identifier number */
140   int   kind;     /* XC_EXCHANGE, XC_CORRELATION, XC_EXCHANGE_CORRELATION, XC_KINETIC */
141 
142   const char *name;     /* name of the functional, e.g. "PBE" */
143   int   family;   /* type of the functional, e.g. XC_FAMILY_GGA */
144   func_reference_type *refs[XC_MAX_REFERENCES];  /* index of the references */
145 
146   int   flags;    /* see above for a list of possible flags */
147 
148   double dens_threshold;
149 
150   /* this allows to have external parameters in the functional */
151   func_params_type ext_params;
152 
153   void (*init)(struct xc_func_type *p);
154   void (*end) (struct xc_func_type *p);
155   void (*lda) (const struct xc_func_type *p, size_t np,
156                const double *rho,
157                double *zk, LDA_OUT_PARAMS_NO_EXC(double *));
158   void (*gga) (const struct xc_func_type *p, size_t np,
159                const double *rho, const double *sigma,
160                double *zk, GGA_OUT_PARAMS_NO_EXC(double *));
161   void (*mgga)(const struct xc_func_type *p, size_t np,
162                const double *rho, const double *sigma, const double *lapl_rho, const double *tau,
163                double *zk, MGGA_OUT_PARAMS_NO_EXC(double *));
164 } xc_func_info_type;
165 
166 /* for API compability with older versions of libxc */
167 #define XC(func) xc_ ## func
168 
169 int xc_func_info_get_number(const xc_func_info_type *info);
170 int xc_func_info_get_kind(const xc_func_info_type *info);
171 char const *xc_func_info_get_name(const xc_func_info_type *info);
172 int xc_func_info_get_family(const xc_func_info_type *info);
173 int xc_func_info_get_flags(const xc_func_info_type *info);
174 const func_reference_type *xc_func_info_get_references(const xc_func_info_type *info, int number);
175 
176 int xc_func_info_get_n_ext_params(const xc_func_info_type *info);
177 char const *xc_func_info_get_ext_params_name(const xc_func_info_type *p, int number);
178 char const *xc_func_info_get_ext_params_description(const xc_func_info_type *info, int number);
179 double xc_func_info_get_ext_params_default_value(const xc_func_info_type *info, int number);
180 
181 struct xc_dimensions{
182   int rho, sigma, lapl, tau;       /* spin dimensions of the arrays */
183   int zk;
184 
185   int MGGA_OUT_PARAMS_NO_EXC(XC_NOARG);
186 };
187 
188 typedef struct xc_dimensions xc_dimensions;
189 
190 struct xc_func_type{
191   const xc_func_info_type *info;       /* all the information concerning this functional */
192   int nspin;                           /* XC_UNPOLARIZED or XC_POLARIZED  */
193 
194   int n_func_aux;                      /* how many auxiliary functions we need */
195   struct xc_func_type **func_aux;      /* most GGAs are based on a LDA or other GGAs  */
196   double *mix_coef;                    /* coefficients for the mixing */
197 
198   /**
199      Parameters for range-separated hybrids
200      cam_omega: the range separation constant
201      cam_alpha: fraction of full Hartree-Fock exchange, used both for
202                 usual hybrids as well as range-separated ones
203      cam_beta:  fraction of short-range only(!) exchange in
204                 range-separated hybrids
205 
206      N.B. Different conventions for alpha and beta can be found in
207      literature. In the convention used in libxc, at short range the
208      fraction of exact exchange is cam_alpha+cam_beta, while at long
209      range it is cam_alpha.
210   */
211   double cam_omega, cam_alpha, cam_beta;
212 
213   double nlc_b;                /* Non-local correlation, b parameter */
214   double nlc_C;                /* Non-local correlation, C parameter */
215 
216   xc_dimensions dim;           /* the dimensions of all input and output arrays */
217 
218   void *params;                /* this allows us to fix parameters in the functional */
219   double dens_threshold;
220 };
221 
222 typedef struct xc_func_type xc_func_type;
223 
224 /* functionals */
225 int   xc_functional_get_number(const char *name);
226 char *xc_functional_get_name(int number);
227 int   xc_family_from_id(int id, int *family, int *number);
228 int   xc_number_of_functionals();
229 int   xc_maximum_name_length();
230 void  xc_available_functional_numbers(int *list);
231 void  xc_available_functional_names(char **list);
232 
233 xc_func_type *xc_func_alloc();
234 int   xc_func_init(xc_func_type *p, int functional, int nspin);
235 void  xc_func_end(xc_func_type *p);
236 void  xc_func_free(xc_func_type *p);
237 const xc_func_info_type *xc_func_get_info(const xc_func_type *p);
238 void  xc_func_set_dens_threshold(xc_func_type *p, double dens_threshold);
239 void  xc_func_set_ext_params(xc_func_type *p, double *ext_params);
240 void  xc_func_set_ext_params_name(xc_func_type *p, const char *name, double par);
241 
242 #include "xc_funcs.h"
243 #include "xc_funcs_removed.h"
244 
245 void xc_lda (const xc_func_type *p, size_t np, const double *rho,
246             double *zk, LDA_OUT_PARAMS_NO_EXC(double *));
247 void xc_gga (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
248              double *zk, GGA_OUT_PARAMS_NO_EXC(double *));
249 void xc_mgga(const xc_func_type *p, size_t np,
250              const double *rho, const double *sigma, const double *lapl_rho, const double *tau,
251              double *zk, MGGA_OUT_PARAMS_NO_EXC(double *));
252 
253 void xc_lda_exc (const xc_func_type *p, size_t np, const double *rho, double *zk);
254 void xc_gga_exc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
255 		 double *zk);
256 void xc_mgga_exc(const xc_func_type *p, size_t np,
257      const double *rho, const double *sigma, const double *lapl, const double *tau,
258      double *zk);
259 
260 #ifndef XC_DONT_COMPILE_VXC
261 void xc_lda_exc_vxc (const xc_func_type *p, size_t np, const double *rho, double *zk, double *vrho);
262 void xc_gga_exc_vxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
263 		 double *zk, double *vrho, double *vsigma);
264 void xc_mgga_exc_vxc(const xc_func_type *p, size_t np,
265      const double *rho, const double *sigma, const double *lapl, const double *tau,
266      double *zk, double *vrho, double *vsigma, double *vlapl, double *vtau);
267 
268 void xc_lda_vxc (const xc_func_type *p, size_t np, const double *rho, double *vrho);
269 void xc_gga_vxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
270 		 double *vrho, double *vsigma);
271 void xc_mgga_vxc(const xc_func_type *p, size_t np,
272      const double *rho, const double *sigma, const double *lapl, const double *tau,
273      double *vrho, double *vsigma, double *vlapl, double *vtau);
274 
275 #ifndef XC_DONT_COMPILE_FXC
276 void xc_lda_exc_vxc_fxc (const xc_func_type *p, size_t np, const double *rho, double *zk, double *vrho, double *v2rho2);
277 void xc_gga_exc_vxc_fxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
278                          double *zk, double *vrho, double *vsigma, double *v2rho2, double *v2rhosigma, double *v2sigma2);
279 void xc_mgga_exc_vxc_fxc(const xc_func_type *p, size_t np,
280                          const double *rho, const double *sigma, const double *lapl, const double *tau,
281                          double *zk, double *vrho, double *vsigma, double *vlapl, double *vtau,
282                          double *v2rho2, double *v2rhosigma, double *v2rholapl, double *v2rhotau,
283                          double *v2sigma2, double *v2sigmalapl, double *v2sigmatau, double *v2lapl2,
284                          double *v2lapltau, double *v2tau2);
285 
286 void xc_lda_vxc_fxc (const xc_func_type *p, size_t np, const double *rho, double *vrho, double *v2rho2);
287 void xc_gga_vxc_fxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
288                          double *vrho, double *vsigma, double *v2rho2, double *v2rhosigma, double *v2sigma2);
289 void xc_mgga_vxc_fxc(const xc_func_type *p, size_t np,
290                          const double *rho, const double *sigma, const double *lapl, const double *tau,
291                          double *vrho, double *vsigma, double *vlapl, double *vtau,
292                          double *v2rho2, double *v2rhosigma, double *v2rholapl, double *v2rhotau,
293                          double *v2sigma2, double *v2sigmalapl, double *v2sigmatau, double *v2lapl2,
294                          double *v2lapltau, double *v2tau2);
295 
296 void xc_lda_fxc (const xc_func_type *p, size_t np, const double *rho, double *v2rho2);
297 void xc_gga_fxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
298 		 double *v2rho2, double *v2rhosigma, double *v2sigma2);
299 void xc_mgga_fxc(const xc_func_type *p, size_t np,
300      const double *rho, const double *sigma, const double *lapl, const double *tau,
301      double *v2rho2, double *v2rhosigma, double *v2rholapl, double *v2rhotau,
302      double *v2sigma2, double *v2sigmalapl, double *v2sigmatau, double *v2lapl2,
303      double *v2lapltau, double *v2tau2);
304 
305 #ifndef XC_DONT_COMPILE_KXC
306 void xc_lda_exc_vxc_fxc_kxc (const xc_func_type *p, size_t np, const double *rho, double *zk, double *vrho, double *v2rho2, double *v3rho3);
307 void xc_gga_exc_vxc_fxc_kxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
308                              double *zk, double *vrho, double *vsigma, double *v2rho2, double *v2rhosigma, double *v2sigma2,
309                              double *v3rho3, double *v3rho2sigma, double *v3rhosigma2, double *v3sigma3);
310 void xc_mgga_exc_vxc_fxc_kxc(const xc_func_type *p, size_t np,
311                              const double *rho, const double *sigma, const double *lapl, const double *tau,
312                              double *zk, double *vrho, double *vsigma, double *vlapl, double *vtau,
313                              double *v2rho2, double *v2rhosigma, double *v2rholapl, double *v2rhotau,
314                              double *v2sigma2, double *v2sigmalapl, double *v2sigmatau, double *v2lapl2,
315                              double *v2lapltau, double *v2tau2,
316                              double *v3rho3, double *v3rho2sigma, double *v3rho2lapl, double *v3rho2tau,
317                              double *v3rhosigma2, double *v3rhosigmalapl, double *v3rhosigmatau,
318                              double *v3rholapl2, double *v3rholapltau, double *v3rhotau2, double *v3sigma3,
319                              double *v3sigma2lapl, double *v3sigma2tau, double *v3sigmalapl2, double *v3sigmalapltau,
320                              double *v3sigmatau2, double *v3lapl3, double *v3lapl2tau, double *v3lapltau2,
321                              double *v3tau3);
322 
323 void xc_lda_vxc_fxc_kxc (const xc_func_type *p, size_t np, const double *rho, double *vrho, double *v2rho2, double *v3rho3);
324 void xc_gga_vxc_fxc_kxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
325                              double *vrho, double *vsigma, double *v2rho2, double *v2rhosigma, double *v2sigma2,
326                              double *v3rho3, double *v3rho2sigma, double *v3rhosigma2, double *v3sigma3);
327 void xc_mgga_vxc_fxc_kxc(const xc_func_type *p, size_t np,
328                              const double *rho, const double *sigma, const double *lapl, const double *tau,
329                              double *vrho, double *vsigma, double *vlapl, double *vtau,
330                              double *v2rho2, double *v2rhosigma, double *v2rholapl, double *v2rhotau,
331                              double *v2sigma2, double *v2sigmalapl, double *v2sigmatau, double *v2lapl2,
332                              double *v2lapltau, double *v2tau2,
333                              double *v3rho3, double *v3rho2sigma, double *v3rho2lapl, double *v3rho2tau,
334                              double *v3rhosigma2, double *v3rhosigmalapl, double *v3rhosigmatau,
335                              double *v3rholapl2, double *v3rholapltau, double *v3rhotau2, double *v3sigma3,
336                              double *v3sigma2lapl, double *v3sigma2tau, double *v3sigmalapl2, double *v3sigmalapltau,
337                              double *v3sigmatau2, double *v3lapl3, double *v3lapl2tau, double *v3lapltau2,
338                              double *v3tau3);
339 
340 void xc_lda_kxc (const xc_func_type *p, size_t np, const double *rho, double *v3rho3);
341 void xc_gga_kxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
342 		 double *v3rho3, double *v3rho2sigma, double *v3rhosigma2, double *v3sigma3);
343 void xc_mgga_kxc(const xc_func_type *p, size_t np,
344      const double *rho, const double *sigma, const double *lapl, const double *tau,
345      double *v3rho3, double *v3rho2sigma, double *v3rho2lapl, double *v3rho2tau,
346      double *v3rhosigma2, double *v3rhosigmalapl, double *v3rhosigmatau,
347      double *v3rholapl2, double *v3rholapltau, double *v3rhotau2, double *v3sigma3,
348      double *v3sigma2lapl, double *v3sigma2tau, double *v3sigmalapl2, double *v3sigmalapltau,
349      double *v3sigmatau2, double *v3lapl3, double *v3lapl2tau, double *v3lapltau2,
350      double *v3tau3);
351 
352 #ifndef XC_DONT_COMPILE_LXC
353 void xc_lda_lxc (const xc_func_type *p, size_t np, const double *rho, double *v4rho4);
354 void xc_gga_lxc (const xc_func_type *p, size_t np, const double *rho, const double *sigma,
355      double *v4rho4,  double *v4rho3sigma,  double *v4rho2sigma2,  double *v4rhosigma3,
356      double *v4sigma4);
357 void xc_mgga_lxc(const xc_func_type *p, size_t np,
358      const double *rho, const double *sigma, const double *lapl, const double *tau,
359      double *v4rho4, double *v4rho3sigma, double *v4rho3lapl, double *v4rho3tau, double *v4rho2sigma2,
360      double *v4rho2sigmalapl, double *v4rho2sigmatau, double *v4rho2lapl2, double *v4rho2lapltau,
361      double *v4rho2tau2, double *v4rhosigma3, double *v4rhosigma2lapl, double *v4rhosigma2tau,
362      double *v4rhosigmalapl2, double *v4rhosigmalapltau, double *v4rhosigmatau2,
363      double *v4rholapl3, double *v4rholapl2tau, double *v4rholapltau2, double *v4rhotau3,
364      double *v4sigma4, double *v4sigma3lapl, double *v4sigma3tau, double *v4sigma2lapl2,
365      double *v4sigma2lapltau, double *v4sigma2tau2, double *v4sigmalapl3, double *v4sigmalapl2tau,
366      double *v4sigmalapltau2, double *v4sigmatau3, double *v4lapl4, double *v4lapl3tau,
367      double *v4lapl2tau2, double *v4lapltau3, double *v4tau4);
368 #endif
369 #endif
370 #endif
371 #endif
372 
373 /* Calculate asymptotic value of the AK13 potential */
374 double xc_gga_ak13_get_asymptotic (double homo);
375 /* Calculate asymptotic value of the AK13 potential with customized parameter values */
376 double xc_gga_ak13_pars_get_asymptotic (double homo, const double *ext_params);
377 
378 /* the meta-GGAs */
379 
380 double xc_hyb_exx_coef(const xc_func_type *p);
381 void xc_hyb_cam_coef(const xc_func_type *p, double *omega, double *alpha, double *beta);
382 void xc_nlc_coef(const xc_func_type *p, double *nlc_b, double *nlc_C);
383 
384 #ifdef __cplusplus
385 }
386 #endif
387 
388 #endif
389