libbeef接口实操：交换、关联与导数
libbeef 0.1.3实际编译运行：C接口、导数、随机种子与VASP集合核对。
阅读本篇目录
适合什么需求#
普通VASP用户可先看BEEF计算流程。本篇适合需要理解接口或把libbeef接入自己程序的用户。我们实际编译运行了libbeef 0.1.3的C调用例，检查交换、局域关联、能量导数、自旋分支和集合生成。这个小程序计算给定电子密度上的泛函值，不是完整材料DFT计算；非局域vdW项需要由调用它的电子结构程序处理。
运行完整例子#
下载解压后，在已分配的一个CPU核上运行：
bash run.sh
cat api.log
cat spin.log
脚本使用已安装的VASP 5.4.4 BEEF模块提供Intel oneAPI 2023.2、ICC/ifort 2021.10和MKL环境，GPUMDkit 1.5.8模块提供Python与绘图依赖。没有重新安装或修改公共库。
关键编译命令：
module purge
module load vasp/5.4.4-8173m-beef gpumdkit/1.5.8
export OMP_NUM_THREADS=1 MKL_NUM_THREADS=1
icc beef_api.c \
/public/software/vasp/libbeef/0.1.3/oneapi-2023.2-icc/8173m/lib/libbeef.a \
-qmkl -lm -o beef_api
./beef_api
运行时也要保留MKL环境。不要编译后立刻module purge，否则动态加载MKL可能失败。当前安装前缀不提供公共头文件，示例中的函数声明依据该版本源码；升级版本后应重新核对ABI。
密度与梯度分别是什么#
本例使用原子单位。r为电子密度ρ，单位bohr⁻³；g是σ=|∇ρ|²，而不是|∇ρ|。交换和局域关联接口的e为每体积能量，单位Ha/bohr³；不是每电子能量。
返回的dr是对ρ的导数；返回的dg是(∂e/∂|∇ρ|)/|∇ρ|，等于2∂e/∂σ。有限差分时必须保留这个因子2。测试取20个正密度点，σ=0.03ρ²；计算ρ导数时保持σ不变，计算σ导数时保持ρ不变。零密度和零梯度的极限处理不属于本例覆盖范围。
最小调用形式：
extern void beefx_(double*, double*, double*, double*, double*, int*);
extern void beefsetmode_(int*);
int mode = -1, addlda = 1;
double rho = 0.1, sigma = 0.0003, e, drho, dgrad;
beefsetmode_(&mode);
beefx_(&rho, &sigma, &e, &drho, &dgrad, &addlda);
addlda=1包含相应LDA基线，0用于调用程序已经单独处理LDA的情况。本例分别检查两种设置，不应把二者当作同一种绝对能量直接比较。
哪些入口做了实际调用#
| 接口 | 本例操作与文件 |
|---|---|
| beef_set_type_ | 选择该版本支持的类型0，即BEEF-vdW |
| beefsetmode_ | 默认−1、PBE关联−2、LDA关联−3、关闭分支−4、0至29阶交换基函数；modes.csv |
| beefx_ / beefxpot_ | 交换能及导数，对照仅能量入口；derivatives.csv |
| beeflocalcorr_ / beeflocalcorrpot_ | 局域关联能及导数；derivatives.csv |
| beeflocalcorrspin_ / beeflocalcorrpotspin_ | 自旋极化ζ从−0.8至0.8，两种LDA设置和多个模式；spin.csv |
| beefrandinit_ / beefrandinitdef_ | 自定义及默认随机种子 |
| beefensemble_ | 32个基展开贡献生成2000成员；另与实际VASP输出核对 |
自旋导数通过独立变化ρ↑或ρ↓核对，同时更新总密度与ζ=(ρ↑−ρ↓)/ρ。与直接固定ζ改变总密度不是同一种导数。
实际结果与图#
max_derivative_error 1.22055547891e-08
seed_repeat_error 0
max_spin_derivative_error 1.49837642294e-11
上述误差是本例采样点的绝对数值差；没有证明任意密度、所有平台和极限输入都满足同样精度。synthetic_ensemble.csv使用人为构造的32维向量演示接口重复性，不能解释为某种材料的能量。真实材料输出的复现见随机种子与VASP集合核对。
调用时的边界#
该版本使用全局模式和随机状态，示例采用串行调用。不要在多个线程里无保护地交错修改模式和种子。交换基函数索引限0至29，类型使用0；不要假定超范围参数会替你完成安全校验。直接调用接口也不会替代VASP中的自洽迭代、非局域关联或结构优化。