xTB接口取数与分子电子性质
运行四个小分子的GFN1/GFN2，读取能量、梯度、电荷、偶极、完整键级和轨道数据，并独立检查梯度。
阅读本篇目录
当你需要在自己的脚本里获取xTB计算结果，可以调用稳定C API，直接读取完整数组。本篇用H₂O、NH₄⁺、OH自由基和H₂，演示xTB6.7.1的静态库接口；资料包已把编译、计算和绘图串起来，不要求先手写C程序。
1. 下载后先运行#
下载完整输入、接口源码和绘图包，进入 xtb-c-api，在已分配CPU作业内执行：
bash run.sh
也可 sbatch job.slurm 提交；CPU分区按56核整节点分配和计费，本例只用一个线程，不使用GPU。脚本使用现有xTB6.7.1头文件和 libxtb.a，通过oneAPI2024.2的icx/ifx编译链接助手程序；Python取数和绘图使用 sisl/0.16.4。
流程是：编译接口助手 → 四个分子分别运行GFN1/GFN2的API与CLI → 水分子做正负位移检查梯度 → 输出CSV、全数组和两张图。每次54个电子单点中包含位移和坐标更新，属于同一套小例流程。
2. 看清结构、单位、电荷和自旋#
cat inputs/water.xyz
cat inputs/water.dat
本例水分子的完整XYZ为：
3
Fixed generic3D rotated teaching geometry
O 0.05291772109030 0.10583544218060 0.15875316327090
H 0.81682432412487 0.28469910273760 -0.38959556953728
H -0.14865865300789 0.94592297669472 0.57088389466498
XYZ坐标是Å；.dat 第一行是原子数、总电荷和未成对电子数，随后每行是原子序数与三维Bohr坐标，供C接口读取。不要把Å坐标不换算就送入API。
| 体系 | 总电荷 | 未成对电子数 |
|---|---|---|
| H₂O | 0 | 0 |
| NH₄⁺ | +1 | 0 |
| OH | 0 | 1 |
| H₂ | 0 | 0 |
OH演示开放壳层占据的输入。这里的未成对电子数与自旋多重度不是同一个整数；也不在本例讨论磁性响应。
颜色和文字来自实际部分电荷，连线按Wiberg键级>0.1绘制，不能直接当作唯一的形式氧化态或整数化学键级。
3. 从终端直接读结果#
head -n 10 results/molecular-properties.csv
cat raw/water-gfn2/cli/wbo
module load sisl/0.16.4
python -B show_results.py
脚本直接读取已算完的水GFN2结果，打印能量、梯度、电荷、偶极、完整Wiberg矩阵和轨道占据，不会重新启动计算。
| 结果 | 单位和含义 |
|---|---|
| 电子总能 | Eh；只在一致方法与配平组分下组合比较 |
| 梯度 | Eh/Bohr；原子受力是负梯度 |
| 部分电荷 | e；分配方案和方法会影响数值 |
| 总偶极 | e·Bohr；1 e·Bohr约为2.54175 Debye |
| 轨道能量 | API为Eh，图中换成eV；分子轨道不是晶体能带 |
| 轨道系数 | 列优先的AO×MO矩阵，需要匹配该方法的基组 |
实际水分子GFN2电子能约 −5.07036944085 Eh。不要用不同分子、不同方法的绝对电子能直接判定哪个“更稳定”。
4. 为什么API矩阵比wbo文件完整#
这版CLI的 wbo 文件只写出键级大于0.1的原子对。水的O–H项约0.9202，而H–H项约0.0004，不会出现在稀疏文件里；未列出不表示这个矩阵元素严格等于零。API返回完整矩阵，适合做后续筛选或自己的图。
总偶极也不能简单由部分电荷乘坐标求和替代。GFN2还包含原子偶极贡献；带电分子在平移t后，总偶极增加Q·t。NH₄⁺的数值必须结合本例坐标原点解释，不能与另一个原点下的结果直接比大小。
5. 独立检查梯度并重画#
module load sisl/0.16.4
python -B verify.py
python -B plot.py
这里用水分子每个坐标的正负0.001 Bohr能量差分核对完整梯度。当前6.7.1 Intel发布包在本例恰好沿坐标轴放置的水构型上，出现过梯度与能量差分不一致；API和CLI彼此一致仍不足以排除该问题。本包使用一般三维方向，同时核对总力矩和刚性旋转关系。遇到类似异常时，应保留原结果，做旋转对照和独立差分，不把更换摆放方向视作任意体系的通用保证。
新方向下最大梯度差分误差约 2×10⁻⁷ Eh/Bohr。换自己的分子时另建目录，准备匹配的电荷、自旋和坐标，重新做必要检查，不能沿用水的固定参考文件。
完整数组在 results/full-fields.npz，本次新图在 plots/，原示例图在 reference-plots/。继续看对象管理与接口范围；接口定义见官方C API文档。