xTB接口对象、轨道与错误处理

本篇面向希望把xTB接到自己程序中的用户。稳定接口围绕四个对象：环境负责输出和错误，分子负责结构、电荷等输入，计算器负责方法与数值设置，结果对象保存能量、梯度和波函数相关数组。

1. 先跑共同的小例#

下载接口源码、固定输入和结果图包，进入 xtb-c-api，在CPU作业内执行：

bash run.sh

本包用现有静态库编译C助手，不要求额外安装Python-xTB绑定。icx编译C，ifx负责链接Fortran库；-nofor-main 用于C主程序，MKL采用顺序库，运行限制为一个线程。完整命令已在脚本里，不需要手动拼长命令。

2. 对象的基本顺序#

核心调用如下；完整可编译源码是包内 api_driver.c，包含逐步错误检查和数组分配。

xtb_TEnvironment env = xtb_newEnvironment();
xtb_TMolecule mol = xtb_newMolecule(
    env, &natoms, numbers, positions_bohr, &charge, &uhf, NULL, NULL);
xtb_TCalculator calc = xtb_newCalculator();
xtb_TResults res = xtb_newResults();
xtb_loadGFN2xTB(env, mol, calc, NULL);
xtb_setAccuracy(env, calc, 0.0001);
xtb_setMaxIter(env, calc, 500);
xtb_setElectronicTemp(env, calc, 300.0);
xtb_singlepoint(env, mol, calc, res);
xtb_getEnergy(env, res, &energy);
xtb_getGradient(env, res, gradient);

本例使用孤立分子，所以晶格和周期标志传NULL。分子的原子数、元素、电荷、未成对电子数等条件改变时，应重新创建相应对象；仅更新坐标可用 xtb_updateMolecule。周期体系、特殊方法和溶剂应分别核对支持范围。

3. 更新坐标时怎样保留上一份结果#

先用 xtb_copyResults 保存副本，再更新原分子坐标并把新计算写入原结果对象。这样可以比较前后结构，而不是让同一个指针被新结果覆盖后丢掉旧状态。本例实际做了水分子坐标小位移和还原，并保留副本中的全部数组。

head -n 18 raw/water-gfn2/api/result.json
cat raw/water-gfn2/api/handled-input-error.json

结果JSON包含 center、updated、restored 和前后副本。后一个文件演示查询尚未计算的结果时如何拿到错误消息；这不是正常计算出的零能量。自己的程序应检查环境状态、读取错误信息并释放不再使用的对象，再按正确输入创建新环境。

xtb_delResults、xtb_delCalculator、xtb_delMolecule 和 xtb_delEnvironment 需要传对象指针的地址，释放后句柄会置空。重复建模或批量调用时，应把对象生命周期写清楚。

4. 轨道数、矩阵顺序和物理含义#

先用 xtb_getNao 获取维数，再分配轨道能量、占据和系数数组。水的GFN1有8个分子轨道、GFN2有6个；不能把一个方法的固定数组长度直接用于另一个方法。

Fortran返回的矩阵按列优先存储，NumPy读取时可用 reshape((nao, nao), order="F")。轨道相位和简并子空间的表示可以改变，不应只凭某个系数正负判断物理是否不同；没有重叠矩阵S时，也不能用CᵀC替代CᵀSC检查正交。

本例导出的孤立分子virial不用于解释周期晶体应力。MO能量图只是当前近似方法的分子轨道结果，不是晶体能带或实验激发谱。

5. 查看完整接口索引与范围#

cat api-symbol-coverage.csv

CSV列出当前开发头中的全部函数，并标注本例实际调用情况。GFN0、GFN-FF、溶剂和外电荷等未在本包运行的分支仍明确单列；符号存在并不等于所有方法组合都可直接套用。xtb_getAPIVersion 返回的是接口ABI版本，也不是xTB发行版号。

module load sisl/0.16.4
python -B verify.py

这一步重读已完成数据，不重新计算电子结构。输入、静态库和头文件条件不同时，请先核对对应版本的官方接口说明与结果对象实现，再迁移到自己的程序。