Overview

Methods

XMVB provides an ab initio computing platform for various VB approaches, including classical VB methods, such as VBSCF, BOVB, VBCI, VBPT2, modern VB methods, such as SCVB and GVB, and molecular orbitals based VB method, BLW. Combined with solvation models, it can perform VBPCM, VBEFP, and VBSMD to account for solvent effects. Incorporating XMVB with KS-DFT code, it can be applied to hybrid DFVB calculation. In this manual, only a brief introduction to classical VB methods is provided. Please read the following references for details:

Articles:

Book Chapters:

The VBSCF method

The wave function of Valence Bond Self Consistent Field (VBSCF) method is the linear combination of VB structures, as shown below.

\[\Psi = \sum_{K}C_K\Phi_K\]

In VBSCF method, All VB structures share the same set of VB orbitals, and both sets of the structure coefficients and VB orbitals are optimized simultaneously to minimize the total energy. This is comparable to the MCSCF method in the MO theory. VBSCF method takes care of the static electron correlation and gives equivalent results to the MO-based CASSCF calculations. It should be noted that the dynamic electron correlation is not accounted for in the VBSCF method. In XMVB, VBSCF method is the default method, thus this keyword can be ignored.

VB Methods including Dynamic Correlation

The VBSCF result includes only static correlation energy, which makes VBSCF results not accurate enough for quantitative researches. The purpose of post-VBSCF methods is to take dynamic correlation into account as much as possible to get accurate enough results. There are several post-VBSCF methods developed so far and will be introduced in this section. It is strongly recommended to perform post-VBSCF calculations with initial guesses from a pre-proceeded VBSCF calculation. As to VBCI and VBPT2, this is enforced.

The BOVB method

The orbitals of Breathing Orbital Valence Bond (BOVB) method are also optimized by SCF procedure, as VBSCF does. The difference between VBSCF and BOVB methods is that BOVB provides an extra degree of freedom during orbital optimization. In BOVB method, each VB structure has its own set of orbitals and are optimized independently

\[\Psi^{\textrm{VBSCF}} = C_1\left( \vert \phi_a\overline{\phi_b} \vert - \vert \phi_b\overline{\phi_a} \vert \right) + C_2\vert \phi_a\overline{\phi_a} \vert + C_3 \vert \phi_b\overline{\phi_b} \vert\]

\[\Psi^{\textrm{BOVB}} = B_1\left( \vert \phi_a\overline{\phi_b} \vert - \vert \phi_b\overline{\phi_a} \vert \right) + B_2\vert \phi'_a\overline{\phi'_a} \vert + C_3 \vert \phi'_b\overline{\phi'_b} \vert\]

Thus, the orbitals adopt themselves to the instantaneous field of the VB structures, rather than to the mean field of all the structures in VBSCF. This degree of freedom makes the orbitals in BOVB “breathing” in different structures, introduces dynamic correlation, and thereby improves considerably the accuracy of VB computations.

The VBCI method

The VBCI method is based on localized VB orbitals. In this method VB orbitals are divided to several blocks (occupied and virtual orbitals). Excited VB structures are generated by replacing occupied VB orbitals with virtual orbitals that are localized on the same block. The wave function of VBCI is the linear combination of all reference and excited VB structures

\[\Psi^{\textrm{VBCI}} = \sum_K\sum_iC_{Ki}\Phi^i_K\]

where $\Phi^i_K$is CI structure coming from VBSCF structure K, including reference and excited structures, and the coefficients ${C_{Ki}}$ are obtained by solving the secular equation. The VBCI weight can be given either with equation

\[W_K = C_K\sum_LC_LM_{KL}\]

which gives weights of all CI structures, or in a more compact way as

\[W_K = \sum_iW_{Ki}\]

where $W_K$ is the contracted weights of reference structure K, including weights of all CI structures coming from structure K.

Allowing for different excitations for different electronic shells, currently the VBCI method consists of the following calculation levels:

VBCI(S,S): only single excitations are involved in either active electron or inactive electron. In brief, this is a VBCIS procedure.
VBCI(D,S): the active shell is treated by single and double excitations, whereas the inactive shell by single excitations only. Also included in this level are double excitations which consist of a single excitation from each shell.
VBCI(D,D): single and double excitations are involved for both active and inactive electrons, in short, VBCISD.

The VBPT2 Method

Another post-VBSCF method is Valence Bond second-order Perturbation Theory (VBPT2) method. The wave function of VBPT2 can be separated into 2 parts as

\[\Psi^{\textrm{VBPT2}} = \Psi^0 + \Psi^1\]

where VBSCF wave function is taken as the zeroth-order wave function $\Psi^0$, and the first-order part is the combination of singly and doubly excited wave functions

\[\Psi^1 = \sum_{R\in V^{SD}}C^1_R\Phi_R\]

To enhance the efficiency of VBPT2, the virtual orbitals are delocalized and orthogonal to the occupied space, and the excitations include all virtual orbitals. In this manner, the excited structures in VBPT2 don’t belong to any fundamental structure, and the matrix elements can be calculated easily with Coulson-Slater rules.

Installation

Both distributions of XMVB are currently available for LINUX platform. 1.5GB RAM is required. Followings are the instructions for installation. Note that the source code will NEVER be released to the users. Only compiled object file or executable files are available for users.

Module distribution

Tip

This is an installation guidance for GAMESS-XMVB,whose functions are not provided on the XACS cloud computing platform.

To build the module distribution, the user may need a library file libgamess-xmvb.a which can be found in the package they obtained. The user may also need to prepare LIBCINT library file libcint.a which is needed for some functions in XMVB. After that, copy these two library files to object directory in GAMESS-US. The user also need to make the following modifications to linke XMVB into GAMESS-US package. We assume that the user will run GAMESS-XMVB with AMD-64 Linux, which corresponds to linux64 architecture of GAMESS-US, and the target is sockets. All operation is proceeded in the root directory of GAMESS-US.

Open ddi/compddi and modify

if($COMM == sockets) then
    set DDI_COMM = '-DDDI_SOC'
endif

to

if($COMM == sockets) then
    set DDI_COMM = '-DDDI_SOC -mcmodel=large'
endif

then run

cd ddi && ./compddi

to recompile DDI.

Open comp, find the entry for linux64, then modify
```
set EXTRAOPT=" "
```
to
```
set EXTRAOPT="-mcmodel=large"
```
in the branch of gfortran, then run
```
./compall
```
to recompile all modules.
Open lked, modify
```
set XMVB=false
```
to
```
set XMVB=true
```
to activate linking XMVB, then modify
```
set VBOBJ='xmvb.o'
```
to
```
set VBOBJ='libgamess-xmvb.a libcint.a /path/to/lapack /path/to/blas'
```
where /path/to/lapack is the location (absolute path) of LAPACK library file, and /path/to/blas is the location of BLAS library file. If MKL is used for GAMESS-US, LAPACK and BLAS library files may be omitted.
Open lked, find the entry for linux64, then modify
```
set LDOPTS=' '
```
to
```
set LDOPTS='-fopenmp -mcmodel=large'
```
in the branch of gfortran, then run
```
./lked gamess xmvb
```
to start linking. After that, an executable file gamess.xmvb.x including the whole capability of XMVB will be generated.
Before running GAMESS-XMVB, don’t forget to append a line
```
setenv  VBINP $USERSCR/$JOB.xmi
```
in the file gms-files.csh. The varialbe $USERSCR can be replaced with other values such as $SCR which is defined in rungms.

Stand-alone distribution

The stand-alone distribution is released as a package of compiled executable files. To install the stand-alone distribution, the users should:

Unpack the compressed tar file by using the following command,
tar xvfz xmvb.tar.gz
Once the file is unpacked successfully, a new directory xmvb/ will be created.
Set the VBDIR environment variable to the location of XMVB package and append xmvb/ to your $PATH. The variable VBDIR is essential for PPD algorithm and utility PREINT.

Running a job

A typical XMVB job consists of the following two steps:

Prepare the integrals of primitive basis functions and the MO orbitals of the system. An input file including molecular information and basis set information is needed. Files “1e.tem”, “2e.tem” and “orb.mo” will be generated after this step.
Run XMVB calculation. A file with extension name “.xmi”(XMI file, see section Input ) is needed here.

The programs, utilities and files needed in these 2 steps differ in different distributions. The details are shown below.

For module distribution

The two steps of an XMVB job in module distribution are done in one shot with command

rungms job [VERNO] [1]

after all files are prepared.

Step 1 is done in GAMESS program with a GAMESS input file including line

$CONTRL VBTYP=XMVB $END

XMVB calculation will be proceeded automatically following the completion of step 1.

Tip

By default, XMVB guess and input files will not be copied into the $SCR directory, which is the real directory where GAMESS- US is doing the calculation. Please copy these files into your $SCR directory BEFORE the calculation. Otherwise an error may occur.
After the calculation, the integral files and XMVB outputs will also be left in $SCR. Integral files may be used for XMVB calculations with stand-alone XMVB program. Please remember to get them if you need them later for stand-alone XMVB.

For stand-alone distribution

With stand-alone distribution used, step 1 is done with program PREINT. After obtaining the integral, create an input file file.xmi for your job (for details, see section manual/input). Then run the XMVB job by typing command

xmvb file.xmi

Then an output file with name file.xmo will be obtained. For use XMVB in parallelization, see below.

Parallelization in stand-alone XMVB

MPI and OpenMP are two popular protocols for parallelization. MPI will create a bunch of processes and the data is synchronized by message-passing, and is useful for multi-node parallelization in distributed systems, e.g. clusters. OpenMP creates a bunch of lightweight threads under a process and is useful for parallelization in single node. The MPI+OpenMP strategy may take the advantages of both protocols to provide a highly-efficient parallelization with multiple nodes. With $N_\textrm{MPI}$ MPI processes and $N_\textrm{OMP}$ OpenMP threads for each process, the total number of CPU cores consumed for a parallel job $N_\textrm{CPU}$ is

\[N_\textrm{CPU} = N_\textrm{MPI} * N_\textrm{OMP}\]

Currently such strategy is supported only by stand-alone XMVB. To use MPI in XMVB, the user may have MPICH installed in the computer. The version of MPICH to compile XMVB is 3.3.2.

MPI parallelization

To run XMVB with MPI parallelization, the user need to type the command

mpirun -np N xmvb file.xmi

to start a computation with N processes. For more information about running parallel computation with MPICH, please refer to the MPICH documentation.

OpenMP parallelization

The OpenMP parallelization does not need to change the command of running XMVB jobs, as shown in 3.2. The number of CPU cores for the parallelization can be controlled by setting the variable OMP_NUM_THREADS

export OMP NUM THREADS=N

if you just need a certain number N of CPUs for your job. If the variable is abesent, OpenMP parallelizes the XMVB computation with ALL processors in your computer.

For large systems, OpenMP parallelzation may proceed a strange “segmentation fault”. This is because the stack size of threads is not large enough. This can be avoided by setting the stack size to a certain number to avoid this error. In OpenMP parallelization, the stack size of master and slave threads are set in different ways. The stack size of master thread is set by command ulimit as shown

ulimit -s stack_size

The default stack size is 8192. Setting a larger value or simply

ulimit -s unlimited

The stack size of slave threads are controlled by environment variable $OMP_STACKSIZE. Following command will set the stack size of each slave threads to 1GB

export OMP_STACKSIZE=1G

Utilities

Tip

This utilities in this section is not provided on the XACS cloud computing platform.

Viewing VB orbitals: Moldendat

Viewing VB orbitals is available. To do that, you need to run a utility, called “moldendat”:

moldendat.exe MOfile vbdat [denfile] >&vbfile

where MOfile is an output file of Gaussian or GAMESS-US, or formatted Gaussian checkpoint file (.fchk); vbdat is a XMVB xdat file; if .fchk file is inputted, an optional XMVB density file with extension “.den” is also supported. The program will produce an NEW output file (vbfile) with the same format as input MO files, with which you can view VB orbitals with MOLDEN or MacMolPlt (for GAMESS-US only) packages.

Preparing integrals: PREINT

This utility is developed to prepare integrals and MO orbitals for XMVB. To run PREINT, simply type the command as following:

preint input >&output

where input is the input file (see below) and output is the user-defined output file. A typical input file for F2 molecule is shown below:

hf cc-pVTZ libcint spher
0 1
F 0.000000 0.000000 0.000000
F 0.000000 0.000000 1.400000

Here keyword libcint means the integrals will be generated by external library LIBCINT and spher means spherical integrals will be generated. Both keywords are optional. Currently “spher” can only be used with “libcint”.

The program provides three files for standalone XMVB jobs:

x1e.int containing 1-e integrals and MO orbitals
x2e.int storing 2-e integrals
INFO storing basis function information and coordinate of the molecule

The Basis sets and elements supported by current PREINT are:

STO-2G H-Ca,Sr
STO-3G H-Xe
STO-6G H-Kr
3-21G H-Cs
3-21G* H-Ar
3-21++G H-Ca
3-21++G* H-Ar
4-31G H-Cl
6-31G H-Zn
6-31G* H-Kr
6-31G** H-Zn
6-31+G H-Ca
6-31+G* H-Ca
6-31+G** H-Ca
6-31++G H-Ca
6-31++G* H-Ca
6-31++G** H-Ca
6-311G H-Ca,Ga-Kr,I
6-311G* H-Ca,Ga-Kr,I
6-311G** H-Ca,Ga-Kr,I
6-311+G H-Ca
6-311+G* H-Ca
6-311+G** H-Ca
6-311+G(2d,p) H-Ca
6-311++G H-Ca
6-311++G* H-Ca
6-311++G** H-Ca
6-311++G(2d,2p) H-Ca
cc-pVDZ H-Kr
cc-pVTZ H-Ca
aug-cc-pVDZ H-Kr
cc-pCVDZ H-Ca
cc-pCVTZ H-Ca
aug-cc-pCVDZ H-Ar
aug-cc-pCVTZ H-Ar
DZP H-Ba,La,Hf-Rn
TZP H-Ca

PREINT can also proceed DFT calculations. Currently supported DFT functionals are:

Exchange functionals: Slater, B88.
Correlation functionals: VWN1, VWN5, LYP.
Exchange-correlation functionals: SVWN1, SVWN5, BLYP.
Hybrid functionals: BHHLYP, B3LYP

More functionals will be implemented and supported in the future. All functionals support R-, U-, and RO-type calculations. To enable DFT calculations, just replace “hf” in the exmaple with functional names, for instance

ub3lyp cc-pVTZ libcint spher
0 1
F 0.000000 0.000000 0.000000
F 0.000000 0.000000 1.400000

Cartesian to spheric integral transformation: 6D25D

This utility transforms integrals from cartesian type to spheric (harmonic) type. Currently the utility supports D and F transformation only and not available for higher basis functions.

To run the utility, typing the command as following:

6d25d.exe [-if gau/gms/lib] [-of gau/std]

where option “-if” defines the sequential of cartesian F functions. Argument “gau” means the sequential in Gaussian and PREINT, “gms” means the sequential in GAMESS-US. Option and “lib” means the sequential by LIBCINT; -of” defines the output format of spheric F basis functions. Argument “gau” means the spheric F functions used in Gaussian package and “std” means standard spheric F function, which is different from the definition in Gaussian. By default, 6d25d will use Gaussian type for both input and output format.

After running 6d25d, the original cartesian integral files x1e.int, x2e.int and INFO will be overwritten by the spheric integrals. Make a backup of your cartesian integral files if you need them later.

Use NBOs as XMVB initial guess: NBOPREP

This utility read the NBOs obtianed from a previous GAMESS/Gaussian calculation, and transfer them to the XMVB readable formats so that user may use them as initial guess in later XMVB calculations with keyword GUESS=NBO.

The user need to run a GAMESS/Gaussian calculations with keyword

$NBO PLOT $END

to get files with name FILE.36 and FILE.37 which stores NBOs and PNBOs. Then run NBOPREP as following:

nboprep.exe outfile [NBO/PNBO]

where “outfile” refers to the output file of GAMESS/Gaussian program, and “NBO/PNBO” tells the program which kind of NBOs should be prepared for later XMVB calculation. The user may be able to use keyword GUESS=NBO by copying file “orb.nbo” generated by NBOPREP to the directory where the XMVB job will be proceeded.

Generate cube file for XMVB computation: vbcubegen

This utility generates cube grid file to visualize VB orbitals with other programs. It supports module distribution or stand-alone XMVB with keyword INT=CALC or INT=LIBCINT since basis function information is essential for generating grids. The syntax of this utility is

vbcubegen.exe xmofile

where xmofile refers to the XMO output file of the XMVB computation. After that, a cube grid file with the same file name as the xmo file will be generated, with which the user may visualize VB orbitals with programs such as GaussView, Multiwfn etc.