autoVB 使用文档

1. 简介

autoVB 是一个能从分子结构自动进行 XMVB 计算的自动化工具。它能自动调用 Gaussian 跑 NBO 计算、选择活性空间、提供初猜，并自动生成 XMVB 输入文件进行最终的计算，目前版本为 0.1.4-dev。如果你对价键理论还不了解，可以查看 XMVB 中文教程。

1.1 环境变量配置

在运行 autoVB 之前，请确保下列可执行文件能被找到：Gaussian 可执行文件、formchk 与 xmvb。如果使用 guess=gvb，还需要能找到 MOKIT 的 automr 与 GAMESS 的 rungms。常见的配置方法如下：

# 指定 Gaussian 可执行程序的完整路径（可为可执行文件或其所在目录）
export GAUSS_EXE=/share/apps/gaussian/g16/g16
# 将 XMVB 和 formchk 所在目录加入 PATH（示例路径，请根据实际安装位置修改）
export PATH=/share/apps/xmvb/latest/bin:$PATH
export PATH=/share/apps/gaussian/16/formchk:$PATH
# guess=gvb 时需要 MOKIT automr 与 GAMESS rungms
export PATH=/share/apps/mokit/bin:$PATH
export GMS=/share/apps/gamess/rungms

将配置写入 ~/.bashrc 或 ~/.profile（或 ~/.zshrc）以保持长期可用：

echo 'export GAUSS_EXE=/share/apps/gaussian/g16/g16' >> ~/.bashrc
echo 'export PATH=/share/apps/xmvb/latest/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

提示：autoVB 中的 find_executable_in_env 与 find_tool 会优先查找环境变量或 PATH 中的可执行文件。若已设置 GAUSS_EXE，请确保其指向正确的可执行路径；否则请将 g16/formchk/xmvb 添加到 PATH。

2 输入文件

2.1 输入文件示例

输入文件格式包括两种类型，默认类型与 Gaussian .gjf 格式高度相似：

%mem=4GB
%nprocshared=4
#p vbscf(4,4)/cc-pVDZ

autovb{}

0 1
C   -3.329219900   2.091826940   0.000000000
H   -2.839967430   1.120094350  -0.000000040
H   -4.414989510   2.089928580   0.000000000
C   -2.624068780   3.231943550   0.000000010
H   -3.149818500   4.187367240   0.000000030
C   -1.168018280   3.297558130   0.000000020
H   -0.642289190   2.342122530   0.000000040
C   -0.462840870   4.437656730  -0.000000010
H   -0.952055180   5.409407090  -0.000000040
H    0.622929910   4.439514340  -0.000000010

另一种输入文件格式与 XMVB .xmi 文件格式类似，你可以将输入文件后缀名改为 .xmi 以使用该类型，如果后缀名不正确，autoVB 也将会自动检查你是否使用了该格式。具体格式参见 XMVB 文档：

C4H6
$ctrl
vbscf
nao=4
nae=4
basis=cc-pvdz
$end

$actorb
1
4
6
8
$end

$geo
C   -3.329219900   2.091826940   0.000000000
H   -2.839967430   1.120094350  -0.000000040
H   -4.414989510   2.089928580   0.000000000
C   -2.624068780   3.231943550   0.000000010
H   -3.149818500   4.187367240   0.000000030
C   -1.168018280   3.297558130   0.000000020
H   -0.642289190   2.342122530   0.000000040
C   -0.462840870   4.437656730  -0.000000010
H   -0.952055180   5.409407090  -0.000000040
H    0.622929910   4.439514340  -0.000000010
$end

2.2 控制命令行 (`#` 所在行)

命令行的格式需要是 # 方法(nae,nao)/基组 或 # 方法/基组，如果采用 .xmi 格式则是在 $ctrl 块内填写参数。

2.2.1 方法

目前支持的计算方法包括 vbscf，vbpt2，lam-dfvb，blw, tbvbscf。blw方法没有活性空间选择相关选项。

2.2.2 显式指定活性空间

你可以直接在方法名后面使用括号显式地声明活性电子数和活性轨道数。例如：vbscf(4,4)。如果不指定，autoVB会自动确定活性空间。这会覆盖下方在 autovb{} 中的设置！

2.2.3 基组

计算使用的基组，支持任何在 Gaussian 和 XMVB 中都支持的基组。

2.2.4 结构优化

opt参数，暂未实现

2.3 标题行控制参数

在输入文件部分的标题行位置，你可以写入类似 autovb{...} 的语法来精准控制价键计算。注意，如果已在 # 命令行设置了 nae / nao 的值，此处的设置会被覆盖。

2.3.1 活性空间选择相关参数

自动选择活性空间时，autoVB 会先读取 Gaussian NBO 结果中的轨道类型、占据数和原子连接关系，然后按以下优先级确定活性轨道：

如果给出 aoa，按指定原子搜索相关 NBO 轨道；如果给出 aoa_bond，按指定原子对搜索相关成键轨道。
如果给出 aoi，直接使用指定的 NBO 轨道编号。
如果只给出 nae / nao，程序会在占据轨道中按 NBO 占据数从低到高挑选 NBO 轨道。
如果给出 threshold，程序会先选择占据数满足 1 < occ <= threshold 的对应轨道。
如果以上参数都未给出，则使用默认规则：选择低占据的 BD 轨道、满足 BD 低占据且对应 BD* 有一定占据的成键/反键对，以及低占据的 LP 轨道。默认阈值为 BD < 1.96、BD < 1.99 且 BD* > 0.06、LP < 1.96；若设置了 nolp，则跳过 LP 轨道。

默认规则会根据选出的电子数和轨道数自动收紧阈值，尽量避免生成过大的活性空间；如果仍然过大，程序会给出警告，建议手动指定 aoa、aoi 或 nae / nao。

2.3.1.1 nae=n

显式指定活性电子数。如果不指定，autoVB 会自动根据 NBO 占据数选定活性空间。

2.3.1.2 nao=n

显式指定活性轨道数。如果不指定，autoVB 会自动根据 NBO 占据数选定活性空间。

2.3.1.3 aoa=(n1, n2, ...)

活性轨道原子序列（Active Orbital Atom）。指定活性空间所在涉及的原子的索引。比如 aoa=(1,2,3,4) 会自动搜索1-4号原子的 NBO 轨道作为活性轨道。原子编号从 1 开始，范围在 [1, 分子总原子数] 的整数之间。对于 .xmi 格式的输入文件，该参数将使用 $actorb 部分的数据，格式见输入文件示例。

2.3.1.4 aoi=(n1, n2, ...)

活性轨道的索引编号（Active Orbital Indices）。直接指定活性空间所使用的 NBO 轨道索引（从1开始）。比如 aoi=(1,2,3,4) 会将 1-4号 NBO 轨道作为活性轨道。

2.3.1.5 threshold=n

根据 NBO 占据数挑选活性轨道的阈值。程序基于 NBO 占据数自动挑选活性空间。必须大于等于 1。

2.3.1.6 rethre=n

按照修正占据数进行筛选，修正占据数是 NBO 的成键-反键对占据数修正为加和为2的占据数。

2.3.1.7 active_order=n

决定如何重新排列活性轨道的顺序，默认值是 rumer，如果设置了 aoa 参数，则默认值是 aoa。它有如下选项： aoa：按照用户给定的aoa顺序排序。 rumer：按照选择的活性空间原子在分子中的拓扑顺序排序，会尽量避免交叉。 seq：按照数字从大到小排序。 none：不进行排序。

2.3.1.8 aoa_bond=(n1, n2, ...)

成键活性轨道原子序列。指定活性空间所在涉及的原子的索引。比如 aoa_old=(1,2, 3,4) 表示原子1和2成键，3和4成键，将会选取1与2的键和3与4的键为活性空间。如果输入奇数个索引，则最后一个原子索引将会被识别为孤对电子。原子编号从 1 开始，范围在 [1, 分子总原子数] 的整数之间。注意如果期望的活性空间中有超过1对孤对电子，它将无法正常工作（因它会认为两个原子成键），因此不推荐使用该选项。

2.3.1.9 bond_first

aoa 参数的子选项，开启该选项后会优先搜索成键轨道而非孤对电子。如果你期望的活性空间内没有占据数较低的孤对电子时可开启它。

2.3.1.10 nolp

不选择孤对电子，支持 aoa 参数和无参数的默认方式挑选轨道。它和 bond_first 参数的区别是 nolp 会强制忽略孤对电子，而 bond_first 在没有可用的成键轨道时依然会选择孤对电子。

2.3.2 NBO 计算相关参数

2.3.2.1 nbo=n

使用的 NBO 轨道计算方法，默认为 hf，使用不同的方法可能会获得不同的活性空间大小和初猜。因未经验证，不建议修改为 hf 和常见 DFT 泛函（如 B3LYP）以外的方法。

2.3.2.2 nbo_file=n

读取已经计算完成的 NBO 文件，n 为带后缀的文件名，需要该文件和输入文件在同一工作目录下。这会从 .fch 文件中读取分子信息，从 .out 文件中读取 NBO 输出信息，从 .37 文件中读取 NBO 轨道，从 .36 文件中读取 PNBO 轨道。此时 autoVB 将不进行 NBO 计算。注意：autoVB 暂时会忽略 NBO 输出文件中的坐标，而是使用 autoVB 输入文件中给出的坐标，所以请确保 NBO 计算使用的坐标与 autoVB 输入文件中给出的坐标一致。

2.3.3 XMVB 计算相关参数

2.3.3.1 str=n/stru=n

配置 XMVB 将要在计算中生成的价键结构类型，可选值包括 "full", "cov", "ion(a,b,c)", "ion(a-b)"。默认值为 "full"，具体含义参见 XMVB 文档。

2.3.3.2 int=n/inte=n

配置 XMVB 计算积分的方式。可选值包括 libcint, ri, cosx。默认值为 libcint，具体含义参见 XMVB 文档。

2.3.3.3 iscf=n

配置 XMVB 轨道优化的方式。可选值包括 2, 5, 6。默认值为 5，具体含义参见 XMVB 文档。

2.3.3.4 sort

是否按照结构系数排序价键结构。

2.3.3.5 guess=n

生成的 XMVB 使用的初猜以及如何挑选活性空间的设置，可选项包括 nbo，pnbo，gvb。默认值为 nbo。 nbo：使用 NBO 轨道作为初猜和挑选活性空间的依据。 pnbo：使用 NBO 轨道作为挑选活性空间的依据，使用 PNBO 轨道作为初猜。PNBO 轨道是非正交且严格定域的。 gvb：使用 GVB 轨道作为初猜和挑选活性空间的依据。

2.3.3.6 atom_slice

对分子轨道作单原子截断（将指定原子外的基函数清零），以生成定域的初猜。一般来说，XMVB 会自动进行截断，所以不需要使用此功能。

2.3.3.7 novb

不进行 XMVB 计算，只生成输入文件。当环境中没有可用的 XMVB 或希望手动修改生成的输入文件时推荐使用该选项。

2.3.3.8 nogvb

不进行 GVB 计算，读取 MOKIT 的计算输出。

2.3.4 绘图相关

2.3.4.1 draw_xmo

调用 draw_xmo 工具，对 .xmo 文件进行解析，生成分子价键结构 .svg 图像文件。画出的分子构型仅供参考，可能存在错误。

2.3.4.2 draw_rumer

使用 Rumer 规则选择的活性空间原子在分子中的拓扑顺序排序时，生成分子 .svg 图像文件。

2.3.5 其他参数

2.3.5.1 debug

调试模式，会打印更多输出。

3 脚本提交方法

配置好环境变量后，你可以直接在终端中传入输入文件运行：

autovb <input-file>

如果需要同时指定内存和并行核心数（覆盖文件内 %mem 与 %nprocshared），可以追加参数：

autovb <input-file> --mem 8GB --nproc 8

注意：不要在登录节点运行计算，请将命令写入作业脚本（SLURM/PBS 等）提交。examples 目录下包含 example_slurm.sh，你可以根据本地软件路径调整并提交：

sbatch example_slurm.sh <input-file>

FilesExpand file tree

UserGuide.md

Latest commit

History