XCFun’s application programming interface¶
The library is written in C++, but can also be directly used in a C or
Fortran project through its application programming interface.
The C interface is exposed described in the api/xcfun.h
, while the
Fortran interface is described in the module file api/xcfun.f90
.
This documentation describes the C API. The Fortran API is written as a wrapper
to the C API and has the same behavior.
Types and type definitions¶
-
struct XCFunctional¶
Exchange-correlation functional.
-
typedef struct xcfun_s xcfun_t¶
Opaque handle to a
XCFunctional
object.Note
This type definition is a workaround to have the opaque
xcfun_t
struct
available to C.
Functions¶
-
const char *xcfun_version()¶
The version of XCFun in use.
- Returns
the version of XCFun
-
const char *xcfun_splash()¶
The XCFun splash screen.
Return a multi-line string describing the library. This functions shows the code attribution and literature citation. It should be called when initializing XCFun in client code, so that your users find the right citation for the library.
- Returns
A
char
array with the XCFun splash screen.
-
const char *xcfun_authors()¶
The XCFun splash screen.
- Returns
A
char
array with the current list of XCFun authors.
-
int xcfun_test()¶
Test XCFun.
Run all internal tests and return the number of failed tests.
- Returns
the number of failed tests.
-
bool xcfun_is_compatible_library()¶
Whether the library is compatible with the header file Checks that the compiled library and header file version match. Host should abort when that is not the case.
Warning
This function should be called before instantiating any XCFunctional object.
-
xcfun_vars xcfun_which_vars(const unsigned int func_type, const unsigned int dens_type, const unsigned int laplacian, const unsigned int kinetic, const unsigned int current, const unsigned int explicit_derivatives)¶
Obtain correct value of
xcfun_vars
enum
.This routine encodes the different options bitwise. Each legitimate combination is then converted to the corresponding enum value.
7
6
5
4
3
2
1
0
0
0
LDA
0
1
GGA
1
0
metaGGA
1
1
Taylor
0
0
\(\rho_{\alpha}\)
0
1
\(\rho\)
1
0
\(\rho_{\alpha}\) and \(\rho_{\beta}\)
1
1
\(\rho\) and \(s\)
0
no laplacian
1
laplacian required
0
no kinetic energy density
1
kinetic energy density required
0
no current density required
1
current density required
0
\(\gamma\)-type partial derivatives
1
explicit partial derivatives
- Parameters
func_type – [in] LDA (0), GGA (1), metaGGA (2), taylor (3)
dens_type – [in] Alpha (A,0), Rho (N,1), Alpha&Beta (A_B,2), Rho&Spin (N_S,3)
laplacian – [in] (0 not required / 1 required)
kinetic – [in] (0 not required / 1 required)
current – [in] (0 not required / 1 required)
explicit_derivatives – [in] (0 not required / 1 required)
- Returns
XC functional variables to use
-
xcfun_mode xcfun_which_mode(const unsigned int mode_type)¶
Obtain correct value of
xcfun_mode
enum
.- Parameters
mode_type – [in] Partial derivatives (1), Potential (2), Contracted (3)
- Returns
The XC functional evaluation mode
-
const char *xcfun_enumerate_parameters(int param)¶
Describe XC functional parameters.
- Parameters
param – [in] the parameter to describe.
param
>= 0.- Returns
description of the given parameter, or
NULL
isparam
is too large.
-
const char *xcfun_enumerate_aliases(int n)¶
Describe XC functional aliases.
- Parameters
n – [in] the alias to describe.
n
>= 0.- Returns
description of the given alias, or
NULL
isn
is too large.
-
const char *xcfun_describe_short(const char *name)¶
Short description of the XC functional.
- Parameters
name – [in]
- Returns
short description of the functional.
-
const char *xcfun_describe_long(const char *name)¶
Long description of the XC functional.
- Parameters
name – [in]
- Returns
long description of the functional.
-
xcfun_t *xcfun_new()¶
Create a new XC functional object.
Create a new functional object. The creation of this object may be rather slow; create an object once for each calculation, not once for each grid point.
- Returns
A
xcfun_t
object.
-
void xcfun_delete(xcfun_t *fun)¶
Delete a XCFun functional.
- Parameters
fun – [inout] the XCFun functional to be deleted
-
int xcfun_set(xcfun_t *fun, const char *name, double value)¶
Set a parameter in the XC functional.
- Parameters
fun – [inout]
name – [in]
value – [in]
- Returns
error code (0 means normal exit)
-
int xcfun_get(const xcfun_t *fun, const char *name, double *value)¶
Get weight of given functional in the current setup.
- Parameters
fun – [in] the functional object
name – [in] functional name to test, aliases not supported
value – [out] weight of functional
- Returns
0
ifname
is a valid functional,-1
if not. Seelist_of_functionals.hpp
for valid functional names.
-
bool xcfun_is_gga(const xcfun_t *fun)¶
Is the XC functional GGA?
- Parameters
fun – [inout]
- Returns
Whether
fun
is a GGA-type functional
-
bool xcfun_is_metagga(const xcfun_t *fun)¶
Is the XC functional GGA?
- Parameters
fun – [inout]
- Returns
Whether
fun
is a metaGGA-type functional
-
int xcfun_eval_setup(xcfun_t *fun, xcfun_vars vars, xcfun_mode mode, int order)¶
Set up XC functional evaluation variables, mode, and order.
- Parameters
fun – [inout] XC functional object
vars – [in] evaluation variables
mode – [in] evaluation mode
order – [in] order of the derivative requested (order=1 is the xc potential)
- Returns
some combination of
XC_E*
if an error occurs, else 0
-
int xcfun_user_eval_setup(xcfun_t *fun, const int order, const unsigned int func_type, const unsigned int dens_type, const unsigned int mode_type, const unsigned int laplacian, const unsigned int kinetic, const unsigned int current, const unsigned int explicit_derivatives)¶
Host program-friendly set up of the XC functional evaluation variables, mode, and order.
- Parameters
fun – [inout] XC functional object
order – [in] order of the derivative requested (order 0 (functional), 1 (potential), 2 (hessian), ….)
func_type – [in] LDA (0), GGA (1), metaGGA (2), taylor (3)
dens_type – [in] Alpha (A,0), Rho (N,1), Alpha&Beta (A_B,2), Rho&Spin (N_S,3)
mode_type – [in] Partial derivatives (1), Potential (2), Contracted (3)
laplacian – [in] (0 not required / 1 required)
kinetic – [in] (0 not required / 1 required)
current – [in] (0 not required / 1 required)
explicit_derivatives – [in] (0 not required / 1 required)
- Returns
some combination of
XC_E*
if an error occurs, else 0
-
int xcfun_input_length(const xcfun_t *fun)¶
Length of the density[] argument to
xcfun_eval
- Parameters
fun – [inout] XC functional object
- Returns
some combination of
XC_E*
if an error occurs, else 0
-
int xcfun_output_length(const xcfun_t *fun)¶
Length of the result[] argument to
xcfun_eval
Note
All derivatives up to order are calculated, not only those of the particular order.
- Parameters
fun – [inout] XC functional object
- Returns
Return the number of output coefficients computed by
xc_eval()
.
-
void xcfun_eval(const xcfun_t *fun, const double density[], double result[])¶
Evaluate the XC functional for given density at a point.
Note
In contracted mode density is of dimension \(2^{\mathrm{order}}*N_{\mathrm{vars}}\)
- Parameters
fun – [inout] XC functional object
density – [in]
result – [inout]
-
void xcfun_eval_vec(const xcfun_t *fun, int nr_points, const double *density, int density_pitch, double *result, int result_pitch)¶
Evaluate the XC functional for given density on a set of points.
Note
In contracted mode density is of dimension \(2^{\mathrm{order}}*N_{\mathrm{vars}}\)
- Parameters
fun – [inout] XC functional object
nr_points – [in] number of points in the evaluation set.
density – [in]
density_pitch – [in]
density[start_of_second_point] - density[start_of_first_point]
result – [inout]
result_pitch – [in]
result[start_of_second_point] - result[start_of_first_point]
Enumerations¶
-
enum xcfun_mode¶
Evaluation mode for functional derivatives.
Values:
-
enumerator XC_MODE_UNSET¶
Need to be zero for default initialized structs
-
enumerator XC_PARTIAL_DERIVATIVES¶
???
-
enumerator XC_POTENTIAL¶
???
-
enumerator XC_CONTRACTED¶
???
-
enumerator XC_NR_MODES¶
???
-
enumerator XC_MODE_UNSET¶
-
enum xcfun_vars¶
Types of variables to define a functional.
The XC energy density and derivatives can be evaluated using a variety of variables and variables combinations. The variables in this
enum
are named as:XC_
prefixTag for density variables.
Tag for gradient variables.
Tag for Laplacian variables.
Tag for kinetic energy density variables.
Tag for current density variables.
XCFun recognizes the following basic variables:
A
, the spin-up electron number density: \(n_{\alpha}\)B
, the spin-down electron number density: \(n_{\beta}\)GAA
, the square magnitude of the spin-up density gradient: \(\sigma_{\alpha \alpha} = \nabla n_\alpha.\nabla n_\alpha\)GAB
, the dot product of the spin-up and spin-down density gradients: \(\sigma_{\alpha \beta} = \nabla n_\alpha.\nabla n_\beta\)GBB
, the square magnitude of the spin-down density gradient: \(\sigma_{\beta \beta} = \nabla n_\beta.\nabla n_\beta\)LAPA
, the Laplacian of the spin-up density: \(\nabla^2 n_{\alpha}\)LAPB
, the Laplacian of the spin-down density: \(\nabla^2 n_{\beta}\)TAUA
, the spin-up Kohn-Sham kinetic energy density: \(\tau_\alpha = \frac{1}{2} \sum_i |\psi_{i \alpha}|^2\)TAUB
, the spin-down Kohn-Sham kinetic energy density: \(\tau_\beta = \frac{1}{2} \sum_i |\psi_{i \beta}|^2\)JPAA
, the spin-up current density: \(\mathbf{j}_{\alpha\alpha}\)JPBB
, the spin-down current density: \(\mathbf{j}_{\beta\beta}\)
The following quantities are also recognized:
N
, the number density: \(n = n_{\alpha} + n_{\beta}\)S
, the spin density: \(s = n_{\alpha} - n_{\beta}\)GNN
, the square magnitude of the density gradient: \(\sigma_{nn} = \nabla n.\nabla n\)GSS
, the dot product of the number and spin density gradients: \(\sigma_{ns} = \nabla n.\nabla s\)GNS
, the square magnitude of the spin density gradient: \(\sigma_{ss} = \nabla s.\nabla s\)LAPN
, the Laplacian of the density: \(\nabla^2 n\)LAPS
, the Laplacian of the spin density: \(\nabla^2 s\)TAUN
, the Kohn-Sham kinetic energy density: \(\tau_n\)TAUS
, the spin Kohn-Sham kinetic energy density: \(\tau_s\)
XC functionals depending on the gradient of the density can furthermore be defined to use the \((x, y, z)\) components of the gradient explicitly.
Values:
-
enumerator XC_VARS_UNSET¶
Not defined
-
enumerator XC_A¶
LDA with \(n_{\alpha}\)
-
enumerator XC_N¶
LDA with \(n\)
-
enumerator XC_A_B¶
LDA with \(n_{\alpha}\) and \(n_{\beta}\)
-
enumerator XC_N_S¶
LDA with \(n\) and \(s\)
-
enumerator XC_A_GAA¶
GGA with grad^2 alpha
-
enumerator XC_N_GNN¶
GGA with grad^2 rho
-
enumerator XC_A_B_GAA_GAB_GBB¶
GGA with grad^2 alpha & beta
-
enumerator XC_N_S_GNN_GNS_GSS¶
GGA with grad^2 rho and spin
-
enumerator XC_A_GAA_LAPA¶
metaGGA with grad^2 alpha laplacian
-
enumerator XC_A_GAA_TAUA¶
metaGGA with grad^2 alpha kinetic
-
enumerator XC_N_GNN_LAPN¶
metaGGA with grad^2 rho laplacian
-
enumerator XC_N_GNN_TAUN¶
metaGGA with grad^2 rho kinetic
-
enumerator XC_A_B_GAA_GAB_GBB_LAPA_LAPB¶
metaGGA with grad^2 alpha & beta laplacian
-
enumerator XC_A_B_GAA_GAB_GBB_TAUA_TAUB¶
metaGGA with grad^2 alpha & beta kinetic
-
enumerator XC_N_S_GNN_GNS_GSS_LAPN_LAPS¶
metaGGA with grad^2 rho and spin laplacian
-
enumerator XC_N_S_GNN_GNS_GSS_TAUN_TAUS¶
metaGGA with grad^2 rho and spin kinetic
-
enumerator XC_A_B_GAA_GAB_GBB_LAPA_LAPB_TAUA_TAUB¶
metaGGA with grad^2 alpha & beta laplacian kinetic
-
enumerator XC_A_B_GAA_GAB_GBB_LAPA_LAPB_TAUA_TAUB_JPAA_JPBB¶
metaGGA with grad^2 alpha & beta laplacian kinetic current
-
enumerator XC_N_S_GNN_GNS_GSS_LAPN_LAPS_TAUN_TAUS¶
metaGGA with grad^2 rho and spin laplacian kinetic
-
enumerator XC_A_AX_AY_AZ¶
GGA with gradient components alpha
-
enumerator XC_A_B_AX_AY_AZ_BX_BY_BZ¶
GGA with gradient components alpha & beta
-
enumerator XC_N_NX_NY_NZ¶
GGA with gradient components rho
-
enumerator XC_N_S_NX_NY_NZ_SX_SY_SZ¶
GGA with gradient components rho and spin
-
enumerator XC_A_AX_AY_AZ_TAUA¶
metaGGA with gradient components alpha
-
enumerator XC_A_B_AX_AY_AZ_BX_BY_BZ_TAUA_TAUB¶
metaGGA with gradient components alpha & beta
-
enumerator XC_N_NX_NY_NZ_TAUN¶
metaGGA with gradient components rho
-
enumerator XC_N_S_NX_NY_NZ_SX_SY_SZ_TAUN_TAUS¶
metaGGA with gradient components rho and spin
-
enumerator XC_A_2ND_TAYLOR¶
2nd order Taylor coefficients of alpha density, 1+3+6=10 numbers, rev gradlex order
-
enumerator XC_A_B_2ND_TAYLOR¶
2nd order Taylor expansion of alpha and beta densities (first alpha, then beta) 20 numbers
-
enumerator XC_N_2ND_TAYLOR¶
2nd order Taylor rho
-
enumerator XC_N_S_2ND_TAYLOR¶
2nd order Taylor rho and spin
-
enumerator XC_NR_VARS¶
Number of variables
Preprocessor definitions and global variables¶
-
XCFUN_API_VERSION¶
Version of the XCFun API
-
XCFUN_MAX_ORDER¶
Maximum differentiation order for XC kernels
-
constexpr auto xcfun::XCFUN_TINY_DENSITY = 1e-14¶
Used for regularizing input
-
constexpr auto xcfun::XC_EORDER = 1¶
Invalid order for given mode and vars
-
constexpr auto xcfun::XC_EVARS = 2¶
Invalid vars for functional type (ie. lda vars for gga)
-
constexpr auto xcfun::XC_EMODE = 4¶
Invalid mode for functional type (ie. potential for mgga)