Interface to the DFT library `Libxc`¹

Libxc is a collection of exchange correlation and kinetic energy functionals for density-functional theory. Libxc supports a variety of functionals, including LDA, GGA, and meta-GGA (mGGA). LDAs, GGAs, and meta-GGAs rely on local information in the sense that the value of the density functional part of the energy density at a given position is determined solely by the density, density gradient, kinetic energy density, and/or density laplacian. Libxc is meant to accurately evaluate this energy density and its derivatives. More details can be found on its documentation page, including a complete list of available functionals.

Empirical dispersion corrections are not part of Libxc itself. However, TeraChem can add DFT-D corrections (e.g., D3) on top of a Libxc functional when requested via dftd (see below). When dftd d3-* is requested, TeraChem tries to match parameters from simple-dftd3; if no parameters are matched, dispersion will be turned off.

Important: Deprecated Keywords

Warning: The keywords hfx and c_ex for controlling HF exchange fractions are ignored when libxc is used. Please use explicit HF exchange components (hf_x_sr, hf_x_lr, hf_x_fr) within the libxc keyword instead. Using the deprecated keywords will display a warning message for backward compatibility.

Summary of `libxc`-related keywords

Keyword	Type	Default	Description
`libxc`	string(s)	N/A	A comma-separated list of functional names from a library of exchange-correlation functionals, Libxc, e.g. `xc_gga_x_b88,xc_gga_c_lyp`. Can also include explicit HF exchange components: `hf_x_sr` (short-range), `hf_x_lr` (long-range), `hf_x_fr` (full-range). If specified, DFT calculation will be performed with Libxc functional(s) and the `method` keyword will be ignored. Restricted or unrestricted KS can be specified by adding `r` or `u` as a prefix in front of the first functional. Restricted KS is the default.
`libxc_fractions`	float(s)	N/A	A comma-separated list of weighting factors for each specified Libxc functionals, assigned with the same order; assumed to be 1 if unspecified.
`libxc_set_cam_beta_with_pcm`	bool	no	Only useful if used with a range-separated functional with the Coulomb attenuating method (CAM) and the polarizable continuum model (PCM). CAM range correction takes the form of \(\frac{1}{r} = \frac{1-[\alpha+\beta\text{erf}(\omega r)]}{r} + \frac{\alpha+\beta\text{erf}(\omega r)}{r}\). If switched on, set the \(\beta\) parameter of functional according to \(\alpha+\beta=\frac{1}{\epsilon}\), where \(\alpha\) is the contribution of short-range Hartree-Fock exchange and \(\epsilon\) is the relative dielectric constant used in the PCM model.
`dftd`	string	no	Empirical dispersion correction. Supported values include `no` (default), `d3-bj`, `d3-zero`, `d3-zerom`, and `d2`. When a Libxc functional is used and a D3 variant is requested, parameters are first matched from `simple-dftd3` (unless `dftd_load_params no`), then (if needed) a fallback to hardcoded parameters is attempted; if no parameters are found, dispersion is turned off.
`dftd_atm`	bool or int	no	Whether to include the 3-body ATM term for D3. Can also be an integer (only meaningful for `gfn2xtb` \(=5\)).
`dftd_load_params`	bool	yes (Libxc)	Whether to try loading D3 parameters from `simple-dftd3` before falling back to hardcoded parameters. The default is `yes` for Libxc functionals.

Double-hybrid DFT (bDH family)

TeraChem supports a small set of common double-hybrid DFT functionals (bDH family, related to B2PLYP) with THC-MP2 and THC-SOS-MP2. Currently, this feature depends on thcbox, dftbox, and libxc (and thcfitbox is optional but preferred).

When dh yes is enabled: - dh_xc selects the double-hybrid functional and will override any libxc ... selection. - dh_pt2 selects the PT2 correlation model (mp2 or sos-mp2) and will override thc_method. - c_os / c_ss separately scale opposite-spin and same-spin components of the THC-MP2 correlation energy (SCS-THC-MP2).

Example: Double-hybrid with SCS-THC-MP2

libxc          blyp # will be overridden if `dh_xc` is specified
...
dh             yes
dh_xc          b2plyp # name of the dh functional
dh_pt2         mp2 # or sos-mp2
c_os           0.27 # scaling coefficient for the opposite-spin component
c_ss           0.27 # scaling coefficient for the same-spin component
...
thc_method     mp2 # will be overridden if `dh_pt2` is specified

Dispersion corrections for Libxc functionals

When a Libxc functional is used, D3 dispersion corrections can be requested via dftd. By default, TeraChem tries to match the functional signature with simple-dftd3 and, if successful, loads parameters from that package. Otherwise, it tries pre-existing hardcoded values (this is always the case when dftd d2 is requested). If no parameters are matched, dispersion is turned off.

Example: D3 with a Libxc functional

libxc             wb97xd3
dftd              d3-zero # no (default), d3-bj, d3-zero, d2, d3-zerom
dftd_atm          yes # yes, no (default); can also be an integer, but only meaningful for gfn2xtb (=5)
dftd_load_params  no # whether to try `simple-dftd3`'s parameters first; default is `yes` for Libxc functionals

Example input scripts

Custom list of functional components

There should be no whitespace between commas and functional signatures.
Only one hybrid and/or range-separated exchange can be specified to ensure unique fractions of full-range and long-range HF exchange and \(\omega\) parameter.

...
dftbox yes
dftgrid 1
libxc xc_lda_x,xc_gga_x_b88,xc_gga_c_lyp,xc_lda_c_vwn_rpa
libxc_fractions 0.08,0.72,0.81,0.19

Explicit HF exchange components (new approach)

The new approach allows explicit specification of HF exchange components using hf_x_sr, hf_x_lr, and hf_x_fr:

...
dftbox yes
dftgrid 1
libxc hf_x_sr,hf_x_lr,xc_gga_x_b88,xc_gga_c_lyp
libxc_fractions 0.5,0.5,0.5,1.0

Alternatively, you can use hf_x_fr which effectively combines short-range and long-range contributions:

...
dftbox yes
dftgrid 1
libxc hf_x_fr,xc_gga_x_b88,xc_gga_c_lyp
libxc_fractions 0.5,0.5,1.0

TeraChem input parameters that control the contribution of exact HF exchange with libxc turned on

Figure 1: TeraChem input parameters (when libxc is turned on) that control the contribution of exact HF exchange

Common names

Common names for some commonly used functionals can be used instead of the full Libxc functional signature.

...
dftbox yes
dftgrid 1
libxc blyp

A full list of supported common names are given below.

Rung 1: LDAs

Common name	Libxc functional signature(s)
`svwn`	`lda_x,lda_c_vwn_rpa`
`spw92`	`lda_x,lda_c_rpw92`

Rung 2: GGAs

Common name	Libxc functional signature(s)
`blyp`	`gga_x_b88,gga_c_lyp`
`pbe`	`gga_x_pbe,gga_c_pbe`
`revpbe`	`gga_x_pbe_r,gga_c_pbe`
`bp86`	`gga_x_b88,gga_c_p86`

Rung 3: meta-GGAs

Common name	Libxc functional signature(s)
`b97mv`	`mgga_xc_b97m_v`
`tpss`	`mgga_x_tpss,mgga_c_tpss`
`m06l`	`mgga_x_m06_l,mgga_c_m06_l`
`revm06l`	`mgga_x_revm06_l,mgga_c_revm06_l`
`scan`	`mgga_x_scan,mgga_c_scan`
`r2scan`	`mgga_x_r2scan,mgga_c_r2scan`

Rung 4: hybrid GGAs

Common name	Libxc functional signature(s)
`b3lyp`	`hyb_gga_xc_b3lyp`
`b3lyp1`	`hyb_gga_xc_b3lyp`
`b3lyp3`	`hyb_gga_xc_b3lyp3`
`b3lyp5`	`hyb_gga_xc_b3lyp5`
`pbe0`	`hyb_gga_xc_pbeh`
`pbeh`	`hyb_gga_xc_pbeh`
`b97`	`hyb_gga_xc_b97`
`b97d`	`gga_xc_b97_d`
`bhandhlyp`	`hyb_gga_xc_bhandhlyp`
`hflyp`	`hyb_gga_xc_hflyp`
`pbe50`	`hyb_gga_xc_pbe50`
`wb97xv`	`hyb_gga_xc_wb97x_v`
`wb97xd`	`hyb_gga_xc_wb97x_d`
`wb97xd3`	`hyb_gga_xc_wb97x_d3`
`wb97`	`hyb_gga_xc_wb97`
`wb97x`	`hyb_gga_xc_wb97x`
`wpbe`	`hyb_gga_xc_lrc_wpbe`
`wpbeh`	`hyb_gga_xc_lrc_wpbeh`
`camb3lyp`	`hyb_gga_xc_cam_b3lyp`
`hse06`	`hyb_gga_xc_hse06`

Rung 4: hybrid meta-GGAs

Common name	Libxc functional signature(s)
`wb97mv`	`hyb_mgga_xc_wb97m_v`
`tpssh`	`hyb_mgga_xc_tpssh`
`m06`	`mgga_x_m06,mgga_c_m06`
`m062x`	`mgga_x_m06_2x,mgga_c_m06_2x`
`scan0`	`mgga_x_scan0,mgga_c_scan`
`mn15`	`hyb_mgga_x_mn15,mgga_c_mn15`
`r2scan0`	`hyb_mgga_xc_r2scan0`

Other supported aliases

Common name	Libxc functional signature(s)
`mubop`	`hyb_gga_xc_lc_bop`

Rung 5: double-hybrids (via `dh_xc`, not `libxc`)

Common name	Double-hybrid functional name (`dh_xc`)
`b2plyp`	`b2plyp`
`mpw2plyp`	`mpw2plyp`
`pbe0dh`	`pbe0dh`
`pbeqidh`	`pbeqidh`
`pbe02`	`pbe02`
`b2gpplyp`	`b2gpplyp`
`ls1dhpbe`	`ls1dhpbe`
`dsdpbep86`	`dsdpbep86`
`dsdpbep86d3`	`dsdpbep86d3`
`revdsdpbep86d3`	`revdsdpbep86d3`
`dsdpbepbed3`	`dsdpbepbed3`
`dsdblypd3`	`dsdblypd3`
`dsdpbeb95d3`	`dsdpbeb95d3`

Details about custom parameters for the TeraChem developers

In TeraChem, the full-range (FR) exact HF exchange energy is calculated with the operator \(1/r_{12}\) and the long-range (LR) one is calculated with the operator \(\text{erf}{(\omega r_{12})}/r_{12}\). The short-range (SR) counterpart is not explicitly calculated, but is realized from the relation that FR is the sum of LR and SR.

Note: The preferred approach is now to use explicit HF exchange components (hf_x_sr, hf_x_lr, hf_x_fr) in the libxc keyword rather than the deprecated keywords below.

Keyword	Type	Default	Description
`hfx`	float	Following the selected DFT functional	[DISABLED] Fraction of FR exact HF exchange (Figure 2, Left); should be avoided when a custom `c_ex` is specified. Use explicit HF exchange components in `libxc` instead.
`c_ex`	float	Following the selected DFT functional	[DISABLED] Fraction of SR exact HF exchange (Figure 2, Right). Use explicit HF exchange components in `libxc` instead.
`rc_w`	float	Following the selected DFT functional	Range correction scaling parameter \(\omega\) required by DFT functionals with a fraction of exact long range exchange operator

TeraChem input parameters that control the contribution of exact HF exchange with libxc turned off

Figure 2: TeraChem input parameters (when libxc is turned off) that control the contribution of exact HF exchange

However, Libxc uses a different convention when defining the contributions of each part of the exact HF exchange energy. For easier future development, the relation between them is shown in Figure 3. In TeraChem's language: - r12K->fr = fraction of long-range HF (1) = fraction of short-range HF (3) - r12K->lr = fraction of long-range HF (2) - Effective fraction of long-range HF = (1) + (2) - Effective fraction of short-range HF = r12K->fr = (3)

In Libxc's language: - cam_alpha = same as r12K->fr = fraction of long-range HF (a) = fraction of short-range HF (b) - cam_beta = fraction of short-range HF (c) - Effective fraction of long-range HF = (a) - Effective fraction of short-range HF = r12K->fr + (c) = (b) + (c)

Figure 3: TeraChem and Libxc Parameter Meanings

Lehtola, S.; Steigemann, C.; Oliveira, M. J. T.; Marques, M. A. L. Recent Developments in Libxc — A Comprehensive Library of Functionals for Density Functional Theory. SoftwareX 2018, 7, 1–5. https://doi.org/10.1016/j.softx.2017.11.002. ↩

Interface to the DFT library Libxc1