Exchange–correlation functionals for density-functional theory, written in Rust. This crate is a port of a subset of libxc 7.1.2 and keeps libxc's functional numbers, short names, spin conventions, input ordering and output array layouts, so results can be checked directly against libxc.
It is not a complete translation of libxc (which contains 800+ functionals and ~50 MB of generated code). The infrastructure, however, is complete for the LDA / GGA / meta-GGA families, and adding a functional only requires writing its energy expression — first and second derivatives are obtained by automatic differentiation.
use rsxcs::{Order, Spin, Xc};
let xc = Xc::from_name("gga_x_pbe").unwrap(); // or Xc::new(101).unwrap()
let rho = [0.8, 0.2]; // spin-up, spin-down
let sigma = [0.1, 0.01, 0.05]; // uu, ud, dd
let out = xc
.eval(Spin::Polarized, &rho, Some(&sigma), None, None, Order::Fxc)
.unwrap();
println!("exc = {}", out.exc[0]);
println!("vrho = {:?}", out.vxc);
println!("vsigma = {:?}", out.vsigma);
println!("v2rho2 = {:?}", out.fxc.as_ref().unwrap().v2rho2);| libxc ID | name | family | kind |
|---|---|---|---|
| 1 | lda_x |
LDA | exchange |
| 7 | lda_c_vwn |
LDA | correlation (VWN5) |
| 8 | lda_c_vwn_rpa |
LDA | correlation (VWN-RPA) |
| 9 | lda_c_pz |
LDA | correlation |
| 12 | lda_c_pw |
LDA | correlation (PW92) |
| 13 | lda_c_pw_mod |
LDA | correlation (PW92, modified) |
| 28–31 | lda_c_vwn_1..4 |
LDA | correlation (VWN1–VWN4) |
| 101 | gga_x_pbe |
GGA | exchange |
| 102 | gga_x_pbe_r |
GGA | exchange (revPBE) |
| 106 | gga_x_b88 |
GGA | exchange |
| 109 | gga_x_pw91 |
GGA | exchange |
| 116 | gga_x_pbe_sol |
GGA | exchange |
| 130 | gga_c_pbe |
GGA | correlation |
| 131 | gga_c_lyp |
GGA | correlation |
| 132 | gga_c_p86 |
GGA | correlation |
| 217 | gga_c_p86_ft |
GGA | correlation |
| 202 | mgga_x_tpss |
MGGA | exchange |
| 402 | hyb_gga_xc_b3lyp |
hybrid GGA | exchange–correlation (semilocal part) |
| 406 | hyb_gga_xc_pbeh |
hybrid GGA | exchange–correlation (semilocal part) |
For hybrids, only the semilocal part is returned; the exact-exchange fraction
(cam_alpha: 0.20 for B3LYP, 0.25 for PBE0) has to be added by the host code.
Xc::eval(spin, rho, sigma, lapl, tau, order) follows libxc:
rho:npoints * nspin, spin-resolved densities.sigma:npoints * (1 or 3), with the ordering(uu)or(uu, ud, dd);sigma_udmay be negative, with|sigma_ud| <= (sigma_uu + sigma_dd)/2. Required for GGA and meta-GGA.lapl: accepted for API compatibility. None of the implemented functionals depends on the Laplacian, and the corresponding second derivatives are returned as zeros.tau:npoints * nspin, required for meta-GGA. Use the positive kinetic-energy density (tau = 1/2 sum_i |grad psi_i|^2).order:Exc,VxcorFxc.
Evaluation contains:
| field | size | ordering |
|---|---|---|
exc |
npoints |
energy per particle |
vxc |
npoints * nspin |
(u, d) |
vsigma |
npoints * (1 or 3) |
(uu, ud, dd) |
vtau |
npoints * nspin |
(u, d) |
fxc.v2rho2 |
npoints * (1 or 3) |
(uu, ud, dd) |
fxc.v2rhosigma |
npoints * (1 or 6) |
(u_uu, u_ud, u_dd, d_uu, d_ud, d_dd) |
fxc.v2sigma2 |
npoints * (1 or 6) |
(uu_uu, uu_ud, uu_dd, ud_ud, ud_dd, dd_dd) |
fxc.v2rhotau |
npoints * (1 or 4) |
(u_u, u_d, d_u, d_d) |
fxc.v2sigmatau |
npoints * (1 or 6) |
(uu_u, uu_d, ud_u, ud_d, dd_u, dd_d) |
fxc.v2tau2 |
npoints * (1 or 3) |
(uu, ud, dd) |
fxc.v2rho{lapl}, v2sigma{lapl}, v2lapl* |
zeros | meta-GGA only |
The sigma ordering and the second-derivative orderings match libxc/pylibxc.
Each functional is implemented once as an energy-density expression generic
over a scalar type (src/functional/*.rs). Evaluating it with f64 gives the
energy; evaluating it with Jet<N> (src/scalar.rs) propagates the gradient
and Hessian with respect to the N layout variables by forward-mode automatic
differentiation. The driver then maps those derivatives onto libxc's arrays
(src/eval.rs).
This means:
- there is exactly one implementation of each parametrisation — no separate
hand-written
vxc/fxckernels that can drift out of sync; - adding a functional is a matter of adding its energy expression and an entry
in
src/info.rs; - near zero gradients the automatic differentiation can lose accuracy in the
second derivative (the analytic cancellation is only exact in real
arithmetic), although the energy and
vxcremain well behaved. Grid points withsigma = 0are floored, as in libxc.
tests/data/libxc_7_1_2_reference.txt contains exc, vxc, vsigma,
vtau and all implemented second derivatives computed with libxc 7.1.2 for
four unpolarized and four polarized points per functional. The test suite
compares every value with a relative tolerance of 5e-10:
$ cargo testThe reference file was generated by tools/gen_reference.py; regenerating it
requires a libxc 7.1.2 build and the matching pylibxc sources:
$ cmake -S libxc-7.1.2 -B build -DENABLE_FORTRAN=OFF -DBUILD_TESTING=OFF \
-DENABLE_PYTHON=OFF -DBUILD_SHARED_LIBS=ON
$ cmake --build build -j
$ cp build/libxc.so.15 libxc-7.1.2/pylibxc/
$ ln -sf libxc.so.15 libxc-7.1.2/pylibxc/libxc.so
$ PYTHONPATH=libxc-7.1.2 python3 tools/gen_reference.pyAll listed functionals are covered by the test.
$ cargo run --example grid- Implement its energy density (hartree) as
fn my_f<S: Scalar>(...) -> Sinsrc/functional/{lda,gga,mgga}.rs. - Add a variant to
define_functionals!insrc/info.rswith the libxc number, name, family and kind. - Add the dispatch arm in the corresponding module.
- Optionally regenerate the reference data (see above) and add the name to
FUNCTIONALSintools/gen_reference.py.
The safe crate above implements a curated subset. For all libxc 7.1.2
functionals there is a complete mechanical translation generated with
c2rust in c2rust/:
- all 332 libxc translation units (~53 MB of Rust), including analytic
fxc; c2rust/generate.shreproduces the transpilation from the 7.1.2 release (requires c2rust 0.22.1 +nightly-2023-04-15);c2rust/libxc-wrapperis a small safe wrapper (Xc::new,Xc::from_name,evalfor LDA/GGA/meta-GGA and hybrids);cargo run --example comparechecks the full backend againstrsxcs: the maximum relative difference over all overlapping functionals, spin treatments and derivatives is 3.8e-14.
Why keep both? The hand-written crate is stable, reviewable and easy to extend; the c2rust backend is complete but large, unsafe and pinned to an old nightly. Use the former for the implemented functionals and the latter when you need libxc's full catalogue.
$ ./c2rust/generate.sh
$ cd c2rust/libxc-wrapper && cargo run --example compare- Only the functionals listed above are implemented; the rest of libxc is not (yet) translated.
- No Laplacian-dependent meta-GGAs;
laplis ignored. - No external parameters (e.g. the
alphaoflda_c_xalpha), no range separation, no kinetic-energy functionals, no GGA/MGGA hybrids beyond the two listed. - Exact exchange is not evaluated: hybrids return only their semilocal contribution.
- Meta-GGA input points must satisfy
tau >= tau_W(no Fermi-hole-curvature enforcement is applied). libxc does not enforce it for TPSS either, but the algebraic rearrangements differ in that unphysical regime. - Densities below
1e-15,sigmabelow1e-40andtaubelow1e-20are clamped, mirroring libxc's screening thresholds for these functionals.
Mozilla Public License 2.0, the same license as libxc. The functional formulas and constants are derived from libxc 7.1.2 (Copyright the libxc authors, M. A. L. Marques, S. Lehtola, X. Andrade and contributors).