libxc_functionals

This module deals with libxc kinetic, exchange and correlation functionals. It implements the evaluation of libxc functionals to take a coefficient vector as input and return the energy and gradient/potential vector. Also contains related utility functions.

For classical functionals, it relies on the libxc library and pyscf interface for the calculation of those quantities. The classical functionals \(E_{xc}[\rho]\) are evaluated on a spatial grid with the electron density \(\rho(r)\) and its derivatives as input. The libxc library then provides the energy density \(\epsilon_{xc}(r)\) and the \(E_{xc}\) energy is then given by:

\[E_{xc}[\rho] = \int \epsilon_{xc}(r) \rho(r) \mathrm{d} r\]

Additionally, for the minimization of the energy the gradient of the energy functional is needed. This is given by:

\[\nabla_p E_{xc}[\rho] = \underbrace{\int \frac{\delta E_{xc}[\rho]}{\delta \rho(r)} \nabla_p \rho(r) \mathrm{d}r}_{\nabla_p E_{LDA}} + \underbrace{\int \frac{\delta E_{xc}[\rho]}{\delta \sigma(r)} \nabla_p \sigma(r) \mathrm{d}r}_{\nabla_p E_{GGA}}\]

with \(\nabla_p E_{LDA}\) given by:

\[(\nabla_p E_{LDA})_\mu = \int v_\rho (r) \omega_\mu(r) \mathrm{d}r\]

where \(\nabla_p E_{GGA}\) can then be rewritten as:

\[\begin{split}(\nabla_p E_{GGA})_\mu =& \sum_\nu 2 p_\nu \underbrace{\int v_\sigma(r) \nabla\omega_\mu(r)\nabla\omega_\nu(r)\mathrm{d}r}_{(v_\sigma)_{\mu,\nu}}\\ \nabla_p E_{GGA} =& 2\mathbf{v_\sigma} \mathbf{p}\end{split}\]

_check_ao_dimensions_wrt_derivatives(ao: ndarray, max_derivative_order: int)

Check the dimensions of the atomic orbital coefficients (ao) with respect to the specified maximum derivative order.

Parameters:

• ao (np.ndarray) – Atomic orbital coefficients.

• max_derivative_order (int) – The maximum derivative order used in calculations.

Raises:

• AssertionError – If the dimensions of the atomic orbital coefficients are not consistent with the specified maximum derivative order.

• ValueError – If the dimensionality of the atomic orbital coefficients is neither 2 nor 3.

_get_energy_and_functional_derivatives(libxc_key: str, rho: ndarray, grid: Grids)

Calculates the energy and functional derivatives of the given functional.

The xc energy functional value is given by \(\int \epsilon_{xc} \rho(r) dr\).

Parameters:

• libxc_key – libxc style key for the functional.

• rho – Shape of ((,N)) for electron density (and derivatives); where N is the number of grids. rho (,N) are ordered as (den, grad_x, grad_y, grad_z, laplacian, tau) where grad_x = d/dx den, laplacian = nabla^2 den, tau = 1/2(nabla f)^2.

• grid – Integration grid for functionals.

Returns:

The energy functional value and the functional derivatives with respect to (rho, sigma, laplacian, tau). See libxc documentation for more details.

Return type:

tuple

_xc_type_to_deriv(code: str)

Gets the required derivative of a libxc_code.

uses pyscf.dft.libxc functions to get the functional types.

Parameters:

code – libxc style code

Raises:

NotImplementedError – if the functional is neither LDA, GGA nor metaGGA

check_kxc_implementation(code: str | Callable) → None

Checks whether the XC or kinetic functional is implemented in the OFDFT framework.

Certain functionals are not available in an OFDFT framework. Hybrid functionals are impossible as exact exchange is not available. Furthermore, meta-GGA functionals using KS kinetic energy density are also unavailable.

Parameters:

code – libxc_code or callable

Raises:

• NotImplementedError – If libxc_codes contains a hybrid functional

• NotImplementedError – If libxc_codes contains a nlc functional

• NotImplementedError – If libxc_codes contains a meta-GGA functional

• NotImplementedError – If libxc_codes is a Callable

• TypeError – If an element in libxc_codes is neither str nor callable

eval_libxc_functionals(coeffs: ndarray, functionals: str | list[str], grid: ndarray | None, ao: ndarray | None, max_derivative: int | None = None) → tuple[float | list[float], ndarray]

Evaluate libxc functionals.

Parameters:

• coeffs – Coefficients used in the functional calculation.

• functionals (list[str]) – A list of strings representing libxc functionals.

• ao (np.ndarray or None) – Atomic orbital values on the grid. Set to None if not applicable.

• grid (np.ndarray or None) – Spatial grid for the calculation. Set to None if not applicable.

• max_derivative (int) – The maximum derivative order used in calculations. Will be calculated if not given.

Returns:

Tuple of energies and the sum of the gradients. If only one functional is given, the energies are returned as a float, otherwise as a list of floats.

nr_rks(ni, mol, grids, xc_code, dms, hermi=1, max_memory=2000)

Calculate RKS XC functional on given meshgrids for a set of density matrices. Adapted from pyscf to only compute the energy and not the gradient.

Parameters:

• ni – an instance of NumInt

• mol – an instance of Mole

• grids – an instance of Grids grids.coords and grids.weights are needed for coordinates and weights of meshgrids.

• xc_code – str XC functional description. See parse_xc() of pyscf/dft/libxc.py for more details.

• dms – 2D array or a list of 2D arrays Density matrix or multiple density matrices

• hermi – int Input density matrices symmetric or not. It also indicates whether the potential matrices in return are symmetric or not.

• max_memory – int or float The maximum size of cache to use (in MB).

Returns:

the XC functional value.

Return type:

excsum

required_derivative(libxc_codes: list[str | Callable] | str | Callable) → int

Gets the highest required derivatives for the given functionals.

LDA functionals require no derivatives. GGAs require first derivatives, some meta-GGAs also require the laplacian.

Parameters:

libxc_codes – libxc functional codes or callables (Not Implemented yet)

Returns:

highest required derivatives

Raises:

• NotImplementedError – Callable are not yet Implemented

• TypeError – if libxc_codes contains neither str nor Callable

requires_grid(functionals: list[str | Callable])

Check if any of the given functionals require a spatial grid for calculation.

Parameters:

functionals (List[str or Callable]) – A list of functionals, where each element can be either a string representing a libxc functional or a callable ML functional.

Returns:

True if at least one functional requires a spatial grid, False otherwise.

Return type:

bool

translate_check_xc(kxc_code: str | Callable)

Translates (if applicable) a kxc_code to libxc, check its implementation.

Parameters:

kxc_code – the kinetic or xc energy functional

Returns:

translated energy functional

Raises:

• NotImplementedError – If kxc_code contains a hybrid functional

• NotImplementedError – If kxc_code contains a nlc functional

• NotImplementedError – If kxc_code contains a meta-GGA functional

• NotImplementedError – If kxc_code is a Callable

• TypeError – If an element in kxc_code is neither str nor callable

translate_xc_code(code: str) → str

Translates some standard XC Functional names into their libxc codes.

Parameters:

code – XC Functional name (such as BLYP, PBE, …)

Returns:

libxc code if translation is available, else the input code