GFN-xTB的编译与API使用

2019年10月1日前后，Grimme课题组将GFN-xTB源代码推到了Github上面。这样友好的举动，无疑增加了用户使用GFN-xTB的热情。GFN-xTB源代码能成为一个很好的教材，我们也可以把它整合到一些已有的程序中，它不再是黑箱。GFN-xTB是近一年以来的热门计算软件，在网上可以找到很多教程，这里不予赘述。一句话概括，GFN-xTB能很快、比精准地完成结构优化、频率计算。本文着重于讲怎么从源代码编译GFN-xTB，以及使用它的API。

1. GFN-xTB的编译（有网络）

GFN-xTB的代码量不大，编译很简单，就是编译的需求有点特殊。

必须用Intel (Compiler 17.0.7)及以上版本才可以编译通过。
meson+ninja这种小众的自动build方案（区别于Cmake等）。

我在编译时候，发现gcc无法编译通过，这一点官方也明确说了，开发者明确表示近期不打算兼容gcc。同时，我发现低版本的Intel编译器（13版）无法通过。必须去官网取得较新版本的Intel编译器，学生用户可以用带edu的信箱申请免费版本。

meson是Python系的一个程序构建软件。安装可以参考

https://mesonbuild.com/Quick-guide.html

在联网环境，如果你有一套好的Python环境，可以直接,

pip3 install --user meson

依赖的ninja也跟着装好了。到这里，我们可以开始编译了，按照Github上的介绍，执行如下代码：

export FC=ifort CC=icc CXX=icpc
meson setup build_intel --optimization=2
ninja -C build_intel test

GFN-xTB 会被快速编译、测试完。编译好的可执行文件、库文件(libxtb.so,libxtb.a)在build_intel目录下。

2. API的使用

GFN-xTB 明确支持作为一个库连接在别的程序上，作为一个计算引擎。与市面上一些人写的脚本不同，GFN-xTB能连接在别的程序上，通过一个接口就可以走内存的方式进行计算，这样我们就有了更多的操作余地。GFN-xTB针对不同计算提供了不同的接口。可是，暂时没有一套详尽的API说明去介绍它们，我们需要通过阅读源代码学习API接口的用法，也欢迎大家补充。我们以gfn2_calculation这个接口为例进行介绍。

gfn2_calculation这个接口在calculator.f90中，顾名思义，它进行的是gfn2计算。

subroutine gfn2_calculation(iunit,env,opt,mol,gfn,pcem,wfn,hl_gap,energy,gradient)

iunit: fortran 文件的Unit号，指定输出到指定文件中。
env: 与操作系统环境有关的,例如当前目录、hostname、等。通过tb_environment定义。
opt: 调控计算的参数，例如是不是算梯度、最大迭代次数..。
mol: 存着与分子有关的信息，原子类型、原子坐标等..。
gfn: xTB的半经验计算参数。
pcem: 环境电荷，这个在QM/MM计算有用。
wfn: 与计算波函数有关。
hl_gap: HOMO− LUMO Gap（返回值）
energy: 体系能量（返回值）
gradient:梯度（返回值）

这些需要传递的数据，基本都是Derived Data Types，通过Type定义的数据组。怎么使用，需要看对应的module。在下一节中，我将举例讲述怎么使用接口。

3. 举例

我写了一个简单的测试主程序程序，主程序叫两个xTB提供的接口test_gfn2_scc与test_gfn2_api。为了确保xTB在一次计算结束后彻底释放了内存，每个接口被调用两次（不彻底释放，会导致报错以及内存溢出）。

program test
   call test_gfn2_scc
   call test_gfn2_scc
   call test_gfn2_api
   call test_gfn2_api
end program test

这些subroutine,

subroutine test_gfn2_scc
subroutine test_gfn2_api

是从xTB自带的test文件中拷过来的，我把一些没用的代码剔除掉，这样xTB就以API形式接入主程序了。

编译的时候，把libxtb.a拷到主函数所在的文件下，记住xtb库函数所在的位置。我们可以通过以下方式编译：

ifort -I/home/***/Software/xtb-source/xtb/build_intel/xtb@sta  -c gfn2.f90
ifort gfn2.o libxtb.a -debug -CB -traceback -Wl,--no-undefined -Wl,--as-needed -Wl,--start-group libxtb.a -static -lmkl_intel_lp 64 -lmkl_intel_thread -lmkl_core -liomp5 -lpthread -i8 -lm -ldl -pthread

产生二进制可执行文件a.out，运行即可。这部分接口测试我已经分享：

https://github.com/chenxin199261/xtb-API

在这里面可以找到具体变量如何定义。