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.

const char *xcfun_authors()

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 is param 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 is n 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 if name is a valid functional, -1 if not. See list_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 = 0

Need to be zero for default initialized structs

enumerator XC_PARTIAL_DERIVATIVES

???

enumerator XC_POTENTIAL

???

enumerator XC_CONTRACTED

???

enumerator XC_NR_MODES

???

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_ prefix

  • Tag 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 = -1

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)