xcx/
lib.rs

1// Copyright (c) 2026 Jiekang Tian and the xcx authors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! # xcx — exchange–correlation functionals for DFT in pure Rust
5//!
6//! `xcx` evaluates exchange–correlation (XC) functionals: given a density (and,
7//! depending on the functional, its gradient / kinetic energy density), it
8//! returns the XC energy per particle, its first and second derivatives (`vxc`
9//! and `fxc`), together with metadata (family, requirements, exact-exchange
10//! fraction, range-separation, VV10, and PT2 parameters).
11//!
12//! Each functional is written once as a scalar energy expression; all
13//! derivatives are obtained by forward-mode automatic differentiation, so they
14//! are correct by construction. Functional IDs follow
15//! [libxc](https://libxc.gitlab.io/) for drop-in interoperability (verified to
16//! ≤ 1e-10 where the two overlap); functionals unique to xcx — notably the
17//! double-hybrid family — use the xcx-private id namespace (≥ 100000).
18//!
19//! ## Scope fence
20//!
21//! `xcx` maps `(rho, sigma, tau[, lapl]) → energy density + derivatives +
22//! metadata + linear mixing` and nothing else — no grids, atomic-orbital
23//! evaluation, SCF driver, or dispersion. For hybrids and VV10 it exposes the
24//! parameters; it does not compute the exact-exchange or nonlocal integrals.
25//!
26//! The full, semver-stable contract lives in [`docs/api-convention.md`](https://github.com/nmrtist/xcx/blob/main/docs/api-convention.md).
27//!
28//! ## Example
29//!
30//! ```
31//! use xcx::{Functional, FunctionalId, Spin, XcInput};
32//!
33//! // Spin-unpolarized LDA exchange over three grid points.
34//! let f = Functional::new(FunctionalId::LdaX, Spin::Unpolarized)?;
35//! let rho = [0.1_f64, 0.2, 0.3];
36//! let out = f.eval(rho.len(), &XcInput::lda(&rho))?;
37//!
38//! assert_eq!(out.exc.len(), 3); // energy per particle at each point
39//! assert_eq!(out.vrho.len(), 3); // ∂(n·ε_xc)/∂n at each point
40//! # Ok::<(), xcx::XcError>(())
41//! ```
42#![forbid(unsafe_code)]
43#![warn(missing_docs)]
44
45mod error;
46mod families;
47mod func;
48mod functionals;
49mod io;
50mod reduced;
51
52pub use error::XcError;
53pub use func::{
54    CamParams, DispersionModel, DispersionRec, DoubleHybridParams, Family, Functional,
55    FunctionalId, FunctionalInfo, GridRec, HybridInfo, Kind, Rung, Spin, Vv10Params,
56};
57pub use io::{XcInput, XcResult};
xcx/lib.rs

xcx/
lib.rs
