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.
- Return
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.
- Return
A
char
array with the XCFun splash screen.
The XCFun splash screen.
- Return
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.
- Return
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.
- Return
XC functional variables to use
- Parameters
[in] func_type
: LDA (0), GGA (1), metaGGA (2), taylor (3)[in] dens_type
: Alpha (A,0), Rho (N,1), Alpha&Beta (A_B,2), Rho&Spin (N_S,3)[in] laplacian
: (0 not required / 1 required)[in] kinetic
: (0 not required / 1 required)[in] current
: (0 not required / 1 required)[in] explicit_derivatives
: (0 not required / 1 required)
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
-
xcfun_mode
xcfun_which_mode
(const unsigned int mode_type)¶ Obtain correct value of
xcfun_mode
enum
.- Return
The XC functional evaluation mode
- Parameters
[in] mode_type
: Partial derivatives (1), Potential (2), Contracted (3)
-
const char *
xcfun_enumerate_parameters
(int param)¶ Describe XC functional parameters.
- Return
description of the given parameter, or
NULL
isparam
is too large.- Parameters
[in] param
: the parameter to describe.param
>= 0.
-
const char *
xcfun_enumerate_aliases
(int n)¶ Describe XC functional aliases.
- Return
description of the given alias, or
NULL
isn
is too large.- Parameters
[in] n
: the alias to describe.n
>= 0.
-
const char *
xcfun_describe_short
(const char *name)¶ Short description of the XC functional.
- Return
short description of the functional.
- Parameters
[in] name
:
-
const char *
xcfun_describe_long
(const char *name)¶ Long description of the XC functional.
- Return
long description of the functional.
- Parameters
[in] name
:
-
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.
- Return
A
xcfun_t
object.
-
void
xcfun_delete
(xcfun_t *fun)¶ Delete a XCFun functional.
- Parameters
[inout] fun
: the XCFun functional to be deleted
-
int
xcfun_set
(xcfun_t *fun, const char *name, double value)¶ Set a parameter in the XC functional.
- Return
error code (0 means normal exit)
- Parameters
[inout] fun
:[in] name
:[in] value
:
-
int
xcfun_get
(const xcfun_t *fun, const char *name, double *value)¶ Get weight of given functional in the current setup.
- Return
0
ifname
is a valid functional,-1
if not. Seelist_of_functionals.hpp
for valid functional names.- Parameters
[in] fun
: the functional object[in] name
: functional name to test, aliases not supported[out] value
: weight of functional
-
bool
xcfun_is_gga
(const xcfun_t *fun)¶ Is the XC functional GGA?
- Return
Whether
fun
is a GGA-type functional- Parameters
[inout] fun
:
-
bool
xcfun_is_metagga
(const xcfun_t *fun)¶ Is the XC functional GGA?
- Return
Whether
fun
is a metaGGA-type functional- Parameters
[inout] fun
:
-
int
xcfun_eval_setup
(xcfun_t *fun, xcfun_vars vars, xcfun_mode mode, int order)¶ Set up XC functional evaluation variables, mode, and order.
- Return
some combination of
XC_E*
if an error occurs, else 0- Parameters
[inout] fun
: XC functional object[in] vars
: evaluation variables[in] mode
: evaluation mode[in] order
: order of the derivative requested (order=1 is the xc potential)
-
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.
- Return
some combination of
XC_E*
if an error occurs, else 0- Parameters
[inout] fun
: XC functional object[in] order
: order of the derivative requested (order 0 (functional), 1 (potential), 2 (hessian), ….)[in] func_type
: LDA (0), GGA (1), metaGGA (2), taylor (3)[in] dens_type
: Alpha (A,0), Rho (N,1), Alpha&Beta (A_B,2), Rho&Spin (N_S,3)[in] mode_type
: Partial derivatives (1), Potential (2), Contracted (3)[in] laplacian
: (0 not required / 1 required)[in] kinetic
: (0 not required / 1 required)[in] current
: (0 not required / 1 required)[in] explicit_derivatives
: (0 not required / 1 required)
-
int
xcfun_input_length
(const xcfun_t *fun)¶ Length of the density[] argument to
xcfun_eval
- Return
some combination of
XC_E*
if an error occurs, else 0- Parameters
[inout] fun
: XC functional object
-
int
xcfun_output_length
(const xcfun_t *fun)¶ Length of the result[] argument to
xcfun_eval
- Return
Return the number of output coefficients computed by
xc_eval()
.- Note
All derivatives up to order are calculated, not only those of the particular order.
- Parameters
[inout] fun
: XC functional object
-
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
[inout] fun
: XC functional object[in] density
:[inout] result
:
-
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
[inout] fun
: XC functional object[in] nr_points
: number of points in the evaluation set.[in] density
:[in] density_pitch
:density[start_of_second_point] - density[start_of_first_point]
[inout] result
:[in] result_pitch
: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
-
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)