
6 Input Descriptions


VB2000 is designed to balance the flexibility of controls and the
convenience of usability. Most of the controls and options needed are
automated as defaults, which in most cases work well. This automation
reduces the input to a minimum. On the other hand, many controls can be
customized and will overwrite the defaults with explicit input, thus
providing the maximum flexibility. One should also understand that VB2000
is not designed as a black box. Input backed by chemical knowledge is
essential to obtain insights into interesting chemical systems. VB2000 is
designed to provide convenient controls to convert sophisticated theory
into practice so as to test, verify and refine theoretical ideas about the
nature of chemical bonds. This chapter illustrates how to specify different
kinds of calculations in the input files.



6.1 General considerations


The controls in the program are divided into three Levels, as follows.


      Level 1: Defaults.

When controls are not set explicitly, the defaults take effects
automatically, being preset according the the type of calculation.


      Level 2: Global controls.

Most of the default settings can be overwritten by providing explicit
inputs. There are two kinds of the global controls: (1) controls that
concern the optimization of the total wave functions (including the number
of subgroups, number of macro iterations, etc.); (2) controls that relate
to a specific method. All groups treated by the same method can be dealt
with using the same method-specific global controls. A global control can
be either a key word  or a dollar '$' flag string.


      Level 3: Controls for individual groups.

The optimization of the group wave function of any specific group can be
controlled directly by a level 3 control. The general expression of a level
3 control is as follows:

      $##CONTROL-NAME
      CONTROL-CONTENT

The control consists of two parts, i.e. the control flag and the control-
content. The control flag always starts with a dollar ('$') sign, followed
by a two-digit number and the name of the control (no space in between). We
use upper-case letters for all control names. The two digit number (here
represented by ##) is the number of the group that the control is applied
to. The number starts from 01 up to 99.  In most common cases, the first
group is a Hartree-Fock group, and the second one a VB group.  The control
content can be either empty or a multiple line input.


6.2 Basic controls and the input of a molecule

The input for a calculation starts with ‘#!’ (in order to distinguish it
from ‘#’ used in the  Gaussian package) and followed by basic controls and
molecule specification as shown below:

#! METHOD/BASIS_SET [OPTIONS]
      [Blank]
Title or comments (can be multiple lines)
      [Blank]
Charge, Multiplicity
Atomic#1, X1, Y1, Z1
Atomic#2, X2, Y2, Z2
……
      [Blank]
[Other controls]



The first input can be continued and terminated by a blank line. Multiple
lines of comments can be inserted before providing the numbers of charge
and multiplicity.  The  comments are also terminated with a blank line. For
each atom, the atomic number and its Cartesian coordinates should be
provided. All these numbers can be given in free format. The atom input is
also terminated by a blank line. After the atomic input, additional
controls can be provided in the input. All these controls are described in
the following sections.

6.2.1 Method

In the above, METHOD can be any of the key words explained below.

      HF
If the METHOD is set to HF, then Hartree-Fock method will be used for the
whole molecule. This is essentially a regular molecular orbital
calculation.

      VB(m)
VB method will be used for a group of m electrons. By default, only one VB
structure will be included in the calculation. One can explicitly specify
multiple VB structures by using an additional control flag $##VBSTR (see
section 6.4.3)
      SCVB(m)
Spin-Coupled  method is used for a set of m electrons in m orbitals. All
linear independent spin-configuration of m electrons in m orbitals are
included in an automatic way. Therefore, there is not essential difference
between SCVB(m) and VB(m) with multiple VB structures. SCVB(m) provides a
convenient shortcut for a special multiple-VB structure calculation that a
user don't have to write all linear independent spin configurations
explicitly.

      SC(m,n)
We can ask ourselves: what would be the most natural way to extend Spin-
Coupled method to systems where the number of electrons is not equal to the
number of orbitals? In VB2000, we define it as the all spin-coupled states
from all possible electron-orbital configurations which have the maximum
number of occupied orbitals. For instance, in the case of SC(m,m), there
only one such a configuration, that is all orbitals are occupied with one
electron on each, and all spin-coupled states are from the spin-coupling
schemes from this configuration. Thus SC(m,m) = SCVB(m). An essential
advantage of SC method is that the wave function and optimized orbitals are
independent of the way to choose the Lewis structures of the SC space,
therefore, the results is not biased to any personal preference.

One can make special use of SC(m,n) when m=2n, i.e. all orbitals are double-
occupied. In this case, SC option turns into non-orthogonal Hartree-Fock
method. In VB2000, we use this trick to do non-orthogonal localized Hartree-
Fock molecular orbital calculations. Even though for regular VB calculation
the maximum number of electrons in each VB group is currently limited to
16, the non-orthogonal Hartree-Fock MO calculations does not have such a
limitation. The limitation for the number of non-orthognal molecular
orbitals comes from the limit of total number of basis functions which can
be handled by the program and the computational time. It should be noted
that the non orthogonal Hartree-Fock MO computation is much more expensive
than the regular Hartree-Fock method.


      CASVB(m,n)
Complete Active Space VB (CASVB) is used for a set of m electrons in n
orbitals. It is mathematically equal to a CASSCF(m,n) method, i.e. the wave
functions produced by the two methods have the same energy and properties.
The CASVB method has some unique advantages that the orbitals in CASVB wave
functions are nonorthogonal and can be maximally localized.

      GPF(ng)
This an old way to specify a multi-group VB calculation, where ng is the
number of electron groups including the Hartree-Fock core. Additional
controls are required for this method. This notation will become obsolete
in the future release. The most convenient way to specify a multiple-group
VB calculation is by the dot notation which is described in the next
section.

      Dot (•) notation
The dot notation has been introduced since version 1.8 for specifying a
multi-group VB calculation. This notation is a more convenient and
intuitive than the GPF notation.  For example, VB(8)·CASVB(6,6)·VB(8)
specify a 3 VB group calculation. One should note that if the molecule is a
open-shell system, then the last VB group must include the open-shell
electrons. Only one VB group can have unpaired spins.


6.2.2 Basis set

BASIS_SET is the name of basis set, which can be any one of the following:

      STO-3G
      STO-4G
      STO-6G
      D95 (Dunning/Huzinaga full double-zeta)
      MIDIX (Minnesota MIDI! basis set)
      3-21G
      3-21G*
      6-31G
      6-31G*
      6-31+G*
      6-31G**
      6-31++G**
      cc-pVDZ
      AUG-cc-pVDZ
      TZVP
      GEN (general basis set provided by user with a basis set file)

The first 15 are built-in basis sets. GEN is a flag for a user defined
basis set: when specified, the program will expect additional input (after
the atomic input) as follows.

      &basis_set_file

where basis_set_file is the file name of the user-defined basis set, which
should be put in the directory BASET. You can also provide the basis set
file with the full path if the file is not in the BASET directory, for
instance,

      &/usr/people/jli/VB20000/GEN/basis_set_file


This file should be prepared in the appropriate format (see the format used
for the standard basis set files in BASET).


6.2.3 Options


[OPTIONS] are key words that control the overall calculation.

      PRINTALL
With this option, a lot more messages will be printed during the
computation. For example, the initial VB orbitals, Mulliken population of
LMOs and VBSCF iterations

      RESTART
This option is originally designed for restarting a computation which is
terminated premature. However, we find a more useful usage of RESTART is to
read VB orbitals from a different calculation as the initial VB orbitals
for a new calculation. A typical scenario of such a usage is generating the
initial VB orbitals for a bond breaking process. In the dissociation limit,
the Hartree-Fock calculation breaks down, and therefore the LMOs based on
Hartree-Fock molecular orbitals becomes less meaningful. As a consequence,
the method for generating initial VB orbitals from LMOs becomes
problematic. The RESTART option can be used to solve the problem: do a VB
calculation of the molecule at the normal bonding geometry, and then do
same type VB calculation at the bond breaking geometry using the RESTART
option. Also see the $RESTARTFILE control.  A VB restart file of a molecule
can be even used for another VB calculation of the same molecule but with
different number of electrons and geometry. Also see $RESTARTMAPPING for
more details.

      CIONLY
This option disable VB orbital optimization during the VBSCF iteration.
With this option, a multi-structure VB calculation becomes essentially a
VBCI. However, this option does not disable VB orbital optimization
completely. The overall wave function optimization involved the in-group
optimization (VBSCF) and rigid rotation for group-group optimization. The
CIONLY option has no effects on the rigid rotation. To disable rigid
rotation, you need use the keyword: NOROT.

      NOROT
There are situations that one needs to disable the rigid rotation between
groups. The keyword NOROT is designed for this purpose. However, both
CIONLY and NOROT does not disable the optimization of Hartree-Fock
orbitals. To disable the Hartree-Fock orbital optimization, the following
keyword is required.

      FROZEN
Freeze all orbitals in the Hartree-Fock group

      UNITS=BOHR
This keyword is required if the unit of the the 3D coordinates is Bohr. The
default unit is Å

      SPDEN
This keyword is required for the computation of spin density of open shell
system. For close shell systems, this keyword has no effects. In the
current implementation, the spin density calculation can be significantly
slow down  for VB groups with more than 12 electrons.

      DIIS
This option can be used to stabilize the VBSCF iteration based on Direct
Inversion of the Iterative Subspace (DIIS) method. The Newton-Raphson (NR)
method implemented in VB2000 usually has very good performance for orbital
optimization. However, there are cases that the VBSCF iteration becomes
unstable. The DIIS option can stabilize the pure NR iteration. It is quite
useful for BOVB type of calculations where multiple structures are included
and different orbitals sets are used for different structures. We have also
found that the DIIS option helps to maintain symmetry.

      SPHER
This option is used to enforce the use of spherical harmonics basis sets.
GAMESS and the stand-alone VB2000 use Cartesian functions for basis sets
internally. Some basis sets, such as cc-pVnZ, are officially defined as
spherical harmonics. To avoid confusion as well as to keep consistency from
one program to another, it is required to stick to the same definition for
these basis sets. GAMESS enforces the use of spherical harmonics basis set
by the option ISPHER=1.   In VB2000, the SPHER keyword is used for the same
purpose.

      TEST
This option is usually used to check the LMOs before doing a complete VB
calculation. With this option, the program does the Hartree-Fock molecular
orbital calculation, orbital localization and then stops. By checking the
order and the characteristics of the LMOs one can decide whether it is
necessary to use more controls or not  to adjust the LMO assignment.



6.3 Group function control flags


$GENCTL

This is the main control for group function specification. The input format
is as follows:

      $GENCTL
      (MELE(i),i=1,NG)
      (METHOD(i),i=1,NG)

Where NG is the number of electrons groups (including the Hartree-Fock
group). MELE(i) is the number of electrons of group i , and METHOD(i) is
the method for obtaining wave function of group i. The following values of
method are possible:

      1 for HF
      2 for VB (may contain multiple VB structures)
      3 for SCVB
      4 for CASVB

$GENCTL is usually combined with the key work GPF(n) in the input. If
GPF(n) is specified and the control flag $GENCTL is missing, then the
molecule is treated with (n-1) GVB pairs. Please note that by default, the
first electron group is a Hartree-Fock group. Therefore, if a system is
divided into n groups, only n-1 groups are expected to be treated with VB
methods. If no specification is provided for the n-1 groups, then they are
assumed to be GVB pairs.


$GRPDIM

This flag specifies the dimension of the subspace for each electron group.
The format of this control is as follows:

      $GRPDIM
      (NDIM(i),i=1,NG)

where NDIM(i) is the dimension of the basis for group i. In most cases, the
default values for all groups will be generated automatically by the
program. For instance, with a (close shell) Hartree-Fock group, the
dimension should be equal to  half the total number of the  electrons in
the Hartree-Fock group. If the explicit input number is different from
that, an assertion error will be detected and the computation will be
aborted.



$VBGA (or $VBGROUPASSIGNMENT)

Two $ flags are introduced for this option: $VBGROUPASSIGNMENT or  a short
notation as $VBGA. This option provides an intuitive electron group
assignment for valence electrons. The following example shows how the
control is applied.

Example 6.1. VB calculation of H2O with two C-H bonds.

#! VB(4)/D95 PRINTALL

TEST H2O

0 1
8   .000000   .000000   .000000
1   .801842   .000000   .555582
1  -.801842   .000000   .555582

 $VBGA
 1-2 => 2
 1-3 => 2

 $02VBORB
 1-2
 1-3

In this example, the $VBGA input has two entries. The first one, 1-2 => 2,
means that the  electrons of the σ bond LMO between atom 1 and 2 are
assigned to (=>) electron group 2 (here group 2 is the VB group). The
second entry means that the σ bond between atom 1 and 3 is assigned to
group 2.  One should note that for such a simple molecule, the $VBGA and
$02VBORB inputs can be omitted, and the LMO groups assignment and VBOs are
generated automatically. The next example shows how to explicitly specify
the group assignment and how to generate VBOs. For multiple bonds, for
instance the triple bond in C2H2, one can assign all the three bonds to the
same electron group with one entry as follows:

Example 6.2. VB calculation of the triple bond in  C2H2

#! VB(6)/D95

TEST C2H2 TRIPLE BOND (SIGMA+PI)

0 1
6   .000000   .000000   .610009
6   .000000   .000000  -.610009
1   .000000   .000000  1.690006
1   .000000   .000000 -1.690006

 $VBGA
 1#2 => 2
the $VBGA input is equivalent to the following:


      $VBGA
      1-2(1) => 2
      1-2(2) => 2
      1-2(3) => 2

The first entry means the first (σ) bond is assigned to group 2. The second
entry means that the second (i.e. the first π bond) is assigned to group 2.
The last entry assigns the third  bond (the second π bond ) to group 2.

$LMOGRPMODIFY

The $VBGA (or $VBGROUPASSIGNMENT) control is based on the automatic LMO
classification, which assigns each LMO as a bonding orbital between two
atoms or a lone pair (including the inner core ) orbital on an atom.
However, there are cases where such an automatic LMO assignment does not
work well. For instance in the multi-center bonds and some conjugated
systems, the LMOs are not necessary localized on one or two atoms.
Therefore the $VBGA logic does not apply for such LMOs. To deal with cases
of this kind, a less intuitive but more flexible control has been
implemented in VB2000. This control explicitly assigns each LMO to a
specific electron group. The general control format is as follows:

      $LMOGRPMODIFY
      NLMO
      N1, G1
      N2, G2
      ......

Where NLMO is the number of LMOs, followed by NLMO pairs of integers (Ni,
Gi). Ni  is the LMO index, and Gi is the electron group that the Ni-th LMO
belongs to.


$MACROITER

The default maximum number of macro iterations is 12. If this default
number needs to be changed, then $MACROITER flag can be used as follows:

      $MACROITER
      MITER

where MITER is the new number of macro iterations.


$ECONV

The default energy threshold for the total energy of a molecule is 10-6
a.u. This can also be overwritten by this control flag as follows:

      $ECONV
      n

and the new energy threshold will be 10-n a.u.

$ROTATION

The optimization of a molecule wave function expressed as a generalized
product function involves the optimization of each group function within
its corresponding subspace and the Jacobi rotations between the basis
functions of different groups. By default, only one rotation is performed
for each pair during each macro iteration. However, this can be changed by
using this control flag:

      $ROTATION
      nRot

where nRot is the number of Jacobi rotations for each macro iteration. The
default value is 1. In some cases, by increasing this number (say 2-5), the
macro iteration can be made more stable. However, a large value of nRot
also means a much more expensive computation.


$NOTROT

There are some cases where we need to disable the Jacobi rotation for basis
functions of two groups, such as the σ and π groups in a conjugated system.
This can be done in the following way:

      $NOTROT
      NR
      NA1,NB1
      NA2,NB2
      .....
Where NR is the number of group pairs to be disabled, and followed by the
NR pairs. The first pair is group NA1 and group NB1, and so on. This option
may make the program more efficient and converge faster. To give an
example, benzene can be divided into two electron groups, the σ-electron
group and the π-electron group. A set of virtual orbitals can be used to
define a third group, containing no electrons. The optimization of the
system wave function involves the inter-group rotations of the subspaces of
all groups. Clearly, however, the rotation between σ and π orbitals should
be avoided for benzene; and this can be achieved by turning off the inter-
group rotation between the σ and π groups. This option is used whenever a
molecule has such kind of symmetry, thus avoiding inter-group rotations
that would break the symmetry. For more details, please check the example
inputs.


$FULLHESS

The Jacobi rotation involves the evaluation of a Hessian matrix, which is
usually an expensive procedure. To improve the efficiency, our experience
shows where only evaluating the block diagonal Hessian matrix elements can
be as good as the full Hessian matrix in most cases. Therefore, by default,
only block diagonal matrix elements are evaluated, and any matrix elements
involving rotations of more than two groups are ignored. However, there are
cases that the full evaluation of Hessian matrix is essential, especially
for systems with unusual bonding, as in chemical reactions. To enable the
full Hessian evaluation, just put the above control flag in the input.

6.3.10 $DAMPROT

Occasionally, one may see the macro iteration becomes unstable. This may
happen for BOVB type calculations. If the total energy of the wave function
oscillates, then a damping factor for rigid rotation will most likely solve
the problem. The damping factor d should be in the range (0 < d < 1.0). A
small factor means a strong damping effect, and can also significantly slow
down convergence. A good starting point is 0.5. For instance, you can add
the following control parameter in the input:

      $DAMPROT
      0.5


6.4 VB Orbital optimization controls

$VBSCF

This is a global SCF control for VB groups. The general formation of the
input is as follows:

      $VBSCF
      EPS, MaxIter

Where EPS is the threshold for the maximum change of orbital coefficients
of VB orbitals, and MaxIter is the maximum number of VBSCF iterations. This
control applies to all VB groups, unless the specific values are specified
for a particular VB group. The default values of EPS and MaxIter are 0.0001
and 15, respectively. Also see the next control for a specific VB group.
$##VBSCF

This control is very similar to the above control, but it applies only to a
specific group as denoted by the number. The general format of this control
is:

      $##VBSCF
      EPS, MaxIter

Where ## is a two digit number of a group index. The default values are
specified by $VBSCF.


$##VBSTR

This control is used for VB structure specification of a group. The general
format of this control is:

      $##VBSTR
      NSTR
      N1 1 N1 2 ...... N1 N
      N2 1 N2 2 ...... N2 N
      ......
      Ni 1 Ni 2 ...... Ni  N
      ......
      NNSTR 1 NNSTR 2 ...... NNSTR N

NSTR is the number of VB structures for a VB group, N is the number of
electrons in this VB group. Each line specifies a VB structure, Each
structure is specified by a set of orbital indexes. In VB2000, the
following convention is used for the pairing pattern of each VB structure:
If the total spin of the electrons of the current group is S, and the
number of electrons is N, then there are (N-2S)/2 pairs, and 2S unpaired
electrons. The pairing pattern of the first structure can be interpreted in
the following way:

      N1 1 – N1 2
      N1 3 – N1 4
      ..........
      N1 N-2S-1 – N1 N-2S
      N1 N-2S+1
      N1 N-2S+2
      .........
      N1 N

Note: The indexes of orbitals in the symbolic VB structure specification
refer to the index of the orbitals of the group. For instance, if an index
is 1, it refers to the first orbital in this group. Here the double sharp
(##) stands for a two digit number. For instance, $02VBSTR stands for the
VB structure of group 2. Note: the program expects a two-digit number even
it is less than 10.

Let's consider an example.  The two Kekule structures and three Dewar
structures of benzene can be represented as:

The 5 VB structures can be given as follows:

  $02VBSTR
  5
  1 2 3 4 5 6
  2 3 4 5 6 1
  1 4 2 3 5 6
  2 5 3 4 1 6
  3 6 1 2 4 5

The first two are Kekule structures, and the last 3 are Dewar structures.



$HESSCONST

This control is used to increase the stability of VB orbital optimization
by adding a constant to Hessian diagonal elements. The formation of this
input is:

      $HESSCONST
      D

where D is a constant, suggested value is 0.1 A larger value can make the
iteration more stable, but also slow down the convergence. For difficult
cases,  one can try is to divide the computation into multiple restart
runs, and watch carefully the convergence behavior by using PRINTALL
option. Once the convergence becomes stable but slow, one can reduce the
constant D, or even set it to zero to speed up the convergence.



$BRILLMASK

This control is used for VB orbital optimization under strict localization
constraints. This control specify a set of orbital pairs that are not
allowed to be mixed during orbital optimization. Generally, only orbitals
on the same atom are allowed to be mixed during orbital optimization. The
resulting VB orbitals are strictly localized. To make this working, the
initial VB orbitals must be strictly localized. One can  start from a set
of AOs as initial VB orbitals, and then each VB orbital is optimized within
the basis functions of the atom what the initial VBO belongs to. The
general format of this control is as follows:

      $BRILLMASK
      M
      NA1, NB1
      NA2, NB2
      ......
      NAM, NBM
Where M  is the number of orbital pairs that the orbital mixing between the
two is be avoided. For instance, orbital NAi does not have any contribution
from orbital NBi during orbital optimization.


$##LENHANCE

This is a localization enhancement control. For some applications, the
strict localization is a too strong constraint imposed on the orbital
optimization and can lead to much higher energy of wave functions than that
from free optimization. It is also technically cumbersome to set up the
calculation and can only be applied in very limited systems. Therefore a
more flexible and general way to obtain localization enhanced VB orbitals
is needed. In VB2000 2.0, a new algorithm is implemented.  In this new
algorithm, a penalty function of delocalization of a set of VB orbitals is
added to the total energy of the VB wavefunction. The delocalization of a
VB orbital is defined as the Mulliken population of the VB orbital on atoms
which are  not in the localization target of the orbital. The VB
wavefunction is optimzed by minimize the following objective function:

      [pic]

where [pic]is the delocalization penalty of VB orbital  [pic]defined as
follows:

      [pic]

[pic] is the overlap matrix of basis functions, [pic] is the VB orbital
localized on atom [pic] (or a set of atoms [pic]),  and[pic] is the
delocalization overlap matrix defined as follows:

      [pic]

i.e. the delocalization overlap matrix  [pic] is from the original overlap
matrix [pic] by setting the rows and columns of basis functions of [pic] to
zero.

Such a penalty can be scaled by a weighting parameter. The general format
of this control is as follows:

      $##LENHANCE
      M
      VBO1, N1 , A1 ,A,2, ... AN1
      VBO2, N2 , B1, B2, .... BN2
      .......


where M is the number of VBOs to be localized. By default, the
delocalization penalty weight W is set to 0.1, and can be modified by
$DPWEIGHT input (see the next section). The following lines specify how
each VBO will be localized. For instance, for VBO1,  it is localized on N1
atoms for the atom list A1 ,A,2, ... AN1. There are M lines to specify the
localization of M orbitals.

This control for obtaining more localized VB orbitals has the following
advantages.
    • It is very general. It does not require and special orientation of a
      molecule and pre-classification of atomic basis functions.
    • It is very flexible. The penalty weight control how much localization
      is needed. By setting a very large weight, the optimized VB orbitals
      are close to the strictly localization. We recommend 0.1 as a starting
      point. It is also recommended that  the same weight is used for a
      comparison study of a number of molecules. One can also use the total
      energy change and the delocalization coefficients to make good
      judgment for a reasonable weight.
    • The input is intuitive and relatively easy to set up. One only needs
      to specify which atoms a VB orbital should be localized on. Such a
      control does not need the details of the basis set used in the
      calculation.
    • By increasing the delocalization penalty weight to an extremely large
      value, say 106, one can get strictly localized VB orbitals. See the
      example input: TESTINP/h2bovb.inp. However, one should note that it
      this is possible to get strictly localized VB orbitals for only one VB
      group, unless the multiple VB groups are separated by molecule
      symmetry (such as σ-π systems). Due to strong orthogonality
      constraints, it is generally impossible to keep orthogonality between
      groups and strict localization of orbitals at the same time.



$DPWEIGHT

This controls the delocalization penalty weight for localization enhanced
VB orbital optimization. The format is as follows:

      $DPWEIGHT
      W

where W is the delocalization penalty weight defined in the previous
section. Without this input, the default value is 0.1 for localization
enhancement option.




$CMAXCUT

This controls the Hessian matrix evaluation of VBSCF iterations. If the
maximum coefficient change is less than the threshold specified by
$CMAXCUT, then the Hessian matrix of previous iteration is used instead of
recomputed. This is especially important for VB groups with more than 10
electrons. However, if the region described by the VB wave function is non-
classical (i.e. the Lewis structures are non-classical), one should use a
more accurate Hessian by using a smaller threshold. To force full Hessian
matrix evaluation for each iteration, one can set the threshold as 0.0. The
default value is 0.025.


$NOLOCVBO

By default, the maximum VBO localization will be performed at the last
macro iteration of a CASVB calculation. This is designed to eliminate the
intrinsic invariance of VBOs of CASVB space.  In most cases, the CASVB
calculation leads to well localized AO-like VBOs even without maximum
localization. However, one can turn off the maximum localization of CASVB
by adding the above control flag in the input. No extra data is needed for
this control.
6.5 Initial VB orbital generation


$##VBORB

This control flag provides a very flexible and intuitive way to specify a
set of initial VB orbitals for a specific group. The ##  is a two digit
number of the group index. The general format of this control is as
follows:

      $##VBORB
      VBO-Specification-1
      VBO-Specification-2
      ......

Each VBO specification line specifies one or more VB orbitals, several
lines can be used and the control is ended with a blank line. Each VBO
specification can take one of the following forms:

      a) NA->NB
      b) NA-NB
      c) NA:(n)
      d) NA^(n)
      e) NA=NB
      f) NA#NB
      g) Expression

Where NA and NB are atom indexes. NA->NB stands for a sigma orbital on atom
NA pointing to atom NB. NA-NB stands for two orbitals forming a single bond
between atom NA and NB. NA:(n) stands for the n-th lone pair on atom NA.
NA^(n) stands for the n-th π orbital on atom NA. NA=NB and NA#NB stands for
4 and 6 orbitals for double and triple bonds, respectively. For more
details, please go to Chapter 7. The last case stands for general
expression for initial VB orbitals. See more details in the following
section.


6.5.2 General expression

The most general way to specify an initial VB orbital is to express it in a
 linear combination of atomic orbitals. VB2000 version 2.1 provides a
simple and intuitive way for this purpose. The general expression of an
orbital is shown as follows:

      $##VBORB
      c1 AO n1 + c2 AO n2  + ...  ci AO ni + ...
      ......
where ci is a coefficient for atomic orbital ni , denoted as AO ni.
Generally speaking, there is no limitation for the number of terms in the
expression, however, in practice, all expression must fit into one line for
each VB orbital. A good example can be found in
TESTINP/StressTest/h2cc6.inp:

 $01VBORB
 0.05 AO 1 +0.1 AO 2  +0.22 AO 3  +0.40 AO 4  +0.30 AO 5 +0.07 AO 18
 0.05 AO 76 +0.1 AO 77 +0.22 AO 78 +0.40 AO 79 +0.30 AO 80 -0.07 AO 93
 ....

The order of the terms is not important. A possible scenario of using such
expressions is that one already has a good initial guess of VB orbitals
using whatever methods, and want to use this guess as an input. Since the
expression is limited one orbital per line, you have to truncate the
expression to only a few terms with the largest coefficients.


$##PIVBO

Even though the control flag $##VBORB can be used to specify a set of π
orbitals, a more convenient way to specify a set of π orbitals is the PIVBO
flag. The general format is as follows:

      $##PIVBO
      nOrbitals
      n1, n2, n3 ....

where ## stands for a two digit number of the group index, nOrbitals is the
number of π orbitals, and n1,n2.. are the atom indexes on which the π
orbitals are located. It is assumed that the atoms specified in this
control form a conjugated plane (or approximately plane), and the orbital
orientation of each π orbital  is perpendicular to the plane of the atom
and its connected conjugate atoms.


$LMODISTORTION

This control specifies the distortion constant for splitting bonding LMOs.
The general input format is as follows:

      $LMODISTORTION
      SplitPara

Here SplitPara a splitting parameter (range 1.0 – 0.0, and the default
value 1.0 gives the maximum split). Assume a bonding LMO localized between
atom A and B, can be expressed as following


      [pic]

Where CA1, CA2 ... are the orbital coefficients on atom A and CB1, CB2 ...
on atom B. With the default value, the LMO can be split into two VBOs, one
is localized on atom A and the other on atom B as follows:-

      [pic]

and

      [pic]

Experiences show that the default value works fine in almost all cases. A
small value of the splitting parameter means that the two generated VB
orbitals are very close. A zero value means two VB orbitals are identical,
and it may cause the VBSCF unstable.

$WRITEGUESS

This control specifies a file name for writing an initial guess of the
orbitals into a file. The input format is:


      $WRITEGUESS
      FileName

where FileName is the file name for the generated initial guess of VB
orbitals. The file has the following format:


      Nbasis, Norbitals
      ((orbital(i,j),i=1,Nbasis), j=1,Norbitals)

where the first two integers are the number of basis functions and the
number of orbitals, respectively, orbital(i,j) are AO coefficients of
orbitals. The file is in free text format, and can be manually edited. The
file can be read for the initial guess by VB2000. This can be useful in
that one can modify some of the VBOs manually, and restart the computation
by reading the file for the initial orbitals by using another control flag
$READGUESS.  Note: all occupied orbitals (including both HF orbitals and VB
orbitals)  are exported.


$READGUESS

This control can be considered as a complementary of $WRITEGUESS.  It
controls the initial guess to be created from a disk file generated by a
previous computation with control $WRITEGUESS.  Input format:

      $READGUESS
      FileName

Here FileName is the file name of the initial guess of the orbitals. The
file is a free format text file. Even though the automatically generated
initial orbitals are normally quite robust, there are some cases where user-
defined orbitals may be required. This option provides a convenient way of
loading the initial guess, which may have been generated in an independent
program, or even created manually.

$RESTARTFILE

Each VB2000 calculation will generate a binary restart file, which stores
all necessary information for a restart calculation. The file contains the
1D density matrix for each electron group and the VB orbitals. This can be
useful in case of a not fully converged computation to start a new
computation for the same molecule based on a previous computation. If the
the key word “RESTART” is specified in the input, then the program is
expecting a restart file, and by default this restart file is the input
file name with extension .V84. To restart the computation from a different
file, one needs the control flag to specify the restart file in the
following way:

      $RESTARTFILE
      RestartFileName

Please note that the restart file can be used as a way to provide initial
VB orbitals for a different calculation of the same molecule but with a
different geometry and even different electrons and methods.


$RESTARTMAPPING

The restart file not only allows a user to restart a computation with the
same electron group partitioning, Version 1.8 also allows a restart of a
computation with different electron group partitioning. To make this to
work, another control, which tells how to correlate the electron group
partitioning of a previous computation and the current one, is needed. The
control is $RESTARTMAPPING.  Two or more VB groups in a previous
calculation can be combined into one VB group in the second calculation,
and the LMOs in a Hartree-Fock group can be re-assigned to a VB group in
the second calculation. The general format is as following:

      $RESTARTMAPPING
      NHFG(i),(i=1.... NHFX)
      NGP(j),(j=1 .... NGPX)

where NHFX is the number of HF orbitals of previous calculation, and NGPX
is the number of groups of previous calculation. NHFG(i) is the group
assignment of the i-th HF orbital of previous calculation, and NGP(J) is
the group assignment of the j-th group of the previous calculation. Please
note that if NGP(1) is Hartree-Fock group, then all of these orbital
assignments are controlled by NHFG(I).

This can be explained by a two-step calculation on ClO2. The first step is
a GPF(3) calculation, with one Hartree-Fock group and two VB groups:


Example 6.3. Group function description of σ-π system of  ClO2

#! GPF(3)/D95 PRINTALL

TEST ClO2

0 2
17  .000000   .000000   .37
8   .0       1.260000  -.39
8   .0      -1.260000  -.39

  $GENCTL
  24,4,5
  1, 2,4

  $GRPDIM
  12,4,3

  $LMOGRPMODIFY
  17
  1,1
  2,1
  3,1
  4,1
  5,1
  6,1
  7,1
  8,1
  9,1
  10,1
  11,3
  12,1
  13,1
  14,3
  15,3
  16,2
  17,2

  $03VBORB
  1:(2)
  2:(3)
  3:(3)

  $02VBORB
  1->2
  2->1
  1->3
  3->1


Group 2 has 4 electrons in 4 VB orbitals, corresponding to the two Cl-O
bonds. Group 3 has 5 electrons in 3 VBOs. Each O has three LPs. The first
LP on O is opposite to the Cl-O bond, the second LP is perpendicular to the
Cl-O bond and in the O-Cl-O plane, and the third LP is perpendicular to the
O-Cl-O plane (also see the rules in Chapter 7). For group 3, the CASVB
method (method No. 4) is used in order to keep the localization of VBOs as
tight as possible. It is usually more efficient and more stable to divide a
system into a number of subsystems.

In the next step, we want to perform a VB calculation by combining groups 2
and 3 of the previous calculation into one VB group with two more LPs from
the two oxygen atoms. To do this, one needs to specify explicitly how to
map the VB groups and LMOs of the  previous calculation into the groups of
a new calculation. This can be controlled by  $RESTARTMAPPING:

Example 6.4.  Restart calculation for σ-π system of  ClO2

#! VB(13)/D95 RESTART CIONLY PRINTALL

TEST ClO2

0 2
17  .000000   .000000   .37
8   .0       1.260000  -.39
8   .0      -1.260000  -.39


  $GENCTL
  20,13
  1, 2

  $GRPDIM
  10,9

  $02VBSTR
  9
  1 1 2 2 3 4 5 6 8 8 9 9 7
  1 1 2 2 3 4 5 6 7 7 8 8 9
  1 1 2 2 3 4 5 6 7 7 9 9 8
  1 1 2 6 3 4 5 5 8 8 9 9 7
  2 2 1 4 5 6 3 3 8 8 9 9 7
  1 1 2 6 3 4 5 5 7 7 8 8 9
  2 2 1 4 5 6 3 3 7 7 9 9 8
  1 4 2 6 3 3 5 5 8 8 9 9 7
  1 2 4 6 3 3 5 5 8 8 9 9 7

  $RESTARTMAPPING
  1,1,1,1,1,1,1,1,1,1,2,2
  1,2,2

  $MACROITERATION
  1

The first line specifies the new group assignment of the 12 LMOs of the
Hartree-Fock group of the previous calculation. The first 10 still belong
to group 1 (i.e. the H-F group), and the last two are assigned to group 2
(i.e. the VB group). The second line is the group-wise assignment. Thus
group 1 of the previous calculation is still assigned to the new group 1
(modified by the first line specification), and groups 2 and 3 are combined
into the new group 2. A question is: how can we know that the orbital 11
and 12 of the first line are the ones we want to included in the VB group (
the second group)?  The orbitals 11 and 12 in the final printout of the
previous calculation are identified to be the second LPs of the two oxygens
by comparing the similarity of the starting LPs and the resulting LPs.






$AOGROUP

Even though the optimal system wave function can be obtained from a
reasonably good  initial guess, there are cases where a classification of
atomic orbitals can be helpful. A typical situation is the σ-π separation
in a conjugated system. In such a case, the system can be divided into a σ
group and a π group, and one may wish to avoid σ-π mixing during the
optimization. To achieve this goal, a control is used to assign atomic
orbitals into different groups, and group functions are then optimized
within their corresponding subspaces. The input format is as follows:

      $AOGROUP
      NAO
      NA1, NA2, ...... NANAO
      GA1, GA2, ...... GANAO

where NAO is the number of atomic orbitals to be classified. The next line
is the atomic orbital indexes, and following the atomic indexes are the
group indexes GA of their corresponding atomic orbitals.  With this
control, the pure atomic orbitals are used as the initial orbitals for the
group wave function.



6.6 Control for a chemical reaction



$REACTION

This control is used to specify the energy profile calculation along a
chemical reaction path. It is assumed that the reaction path has been
obtained, or a reasonable guess has been made. The general input format is
shown as follows:

      $REACTION
      IPOINT, NGEOM, NATOMS
      GEOM1
      atomic#1   x11   y11  z11
      atomic#2   x12   y12  z12
      ......
      atomic#n   x1n   y1n  z1n
      GEOM2
      atomic#1   x21   y21  z21
      atomic#2   x22   y22  z22
      .....
      atomic#n   x2n   y2n  z2n
      .....

where NGEOM is the number of geometries of the reacting system along the
reaction path, and NATOMS is the number of atoms in the reacting system.
The atomic numbers are the nuclear numbers of atoms, x, y and z are the
coordinates of atoms. IPOINT is the number of geometric interpolation
points between each two consecutive structures along the reaction path. In
a typical calculation, three geometries are used, include the geometries of
reactants, the transition state, and the products.



6.7 Advanced controls

$##ROOT

The number of the CI root for an excited state. In most cases, the ground
state is calculated, thus this input can be omitted.  The general format of
this control is:

      $##ROOT
      NROOT

Where ## stands for the two digit number of an electron group,  NROOT is
the number of the CI root for an excited state, in ascending order. For
instance, if NROOT is 2, the first excited state of group ## will be
optimized. This is only meaningful when the electron group is described
with multiple structure VB wave function (for instance, a CASVB wave
function).

This method only works well for the case where the excited state and the
group state have different symmetry (i.e. symmetry vs. anti-symmetry) so
that the excited state and the group state are always orthogonal,
otherwise, the excited state may collapse into the ground state during the
optimization.


$##STRSYMM

This control specifies the symmetry constraints on VB structure
coefficients. The general format of the control is:

      $##SYMSYMM
      NP
      IA1, F1, IB1
      IA2, F2, IB2
      .........

where NP is the number of constraints, followed by the NP entries of the
constraint specification. Each line specifies a symmetry related equality
constraint as following:

      IAi        Index of structure coefficient
      Fi         The symmetry factor, which can be either 1 or -1.
      IBi        Index of structure coefficient symmetrically related to IA
Assume the structure coefficients are denoted as CSTR(i), where i is the
index of the structure, then the constraint is

      [pic]



$MEMORY

This control is used to specify the size of dynamically allocated memory
for the calculation. Following this $ flag is the memory size in double-
precision. For instance,

      $MEMORY
      10000000

The control will allow the program to allocate 10 MW memory during the
computation. This is very necessary for the integral transformation of
large basis sets where a large memory will speed up the transformation,
otherwise the program will switch to the disk file mode for the integral
transformation, and this will significantly increase the elapsed time of
the computation. One can tell from the output  file of a computation if the
integral transformation is in the disk mode or not. If the disk mode is
used, the output file also tells how much more memory is needed for the in-
core integral transformation. The default size of the scratch memory is
6.5MW

Please note that the $MEMORY flag is ignored in GAMESS-VB2000 and the
memory   is controlled by GAMESS memory management in GAMESS $SYSTEM block.

$VBOLIBGEN

This control is used for generating a VBO library for a new basis set;
therefore, it may require a number of trial and error attempts. The general
strategy of building a VBO library is to choose a set of simple molecules
containing different types of bonds and atoms, and perform simple VB
calculations which do not rely on a VBO library, and then store the VB
orbitals from the calculation. The general format of the control is:

      $VBOLIBGEN
      VBO-NAME
      NA NB
      NVBO
      VX VY VZ

where VBO-NAME is a string for the VBO name, and NA and NB are the two
atoms defining the VBO orientation. The VBO is located on atom NA and
pointing to atom NB. NVBO is the orbital index of the VBO in the output
from the VB calculation. For lone pairs or π VBOs, NB is zero, and the
orientation of the VBO is defined by a vector with components (VX, VY and
VZ). Usually case, one does not know the VBO index before the calculation.
Therefore, for creating a new VBO record, one has to do two calculations.
Once the first calculation is done, one needs to inspect the VBOs in the
final output, and find out the VBO index, then add the $VBOLIBGEN control
with the correct VBO index. If NB is not zero, the VBO orientation is
defined by the vector from atom NA atom NB, and the vector line is not
required. Multiple VBO records can be created under this control. One can
repeat the above inputs for each VBO record without any lines in between
and the input ends with a blank line.

The VBO-label consists of two parts: a prefix and an extension. The search
for a VBO in a library file is by the prefix, and the same VBOs for
different basis sets are stored in different VBO library files. Each VBO
library file is a collection of VBOs of the same basis set. Currently, the
following VBO-Label prefixes are supported:

      σ Orbitals

      $SIGMA-H-
      $SIGMA-LI
      $SIGMA-BE
      $SIGMA-B-
      $SIGMA-N-
      $SIGMA-O-
      $SIGMA-F-
      $SIGMA-NA
      $SIGMA-MG
      $SIGMA-AL
      $SIGMA-SI
      $SIGMA-P-
      $SIGMA-S-
      $SIGMA-CL
      $SIGMA-BR
      $SIGMA-I-


      π Orbitals

      $PI-H-IN-HH
      $PI-LI-IN-LIH
      $PI-BE-IN-H2BE
      $PI-B-IN-BH3
      $PI-C-IN-C2H4
      $PI-N-IN-CH2NH
      $PI-O-IN-CH2O
      $PI-F-IN-HF
      $PI-NA-IN-NAH
      $PI-MG-IN-MGH2
      $PI-AL-IN-ALH3
      $PI-SI-IN-SIH3
      $PI-P-IN-PH3
      $PI-S-IN-CH2S
      $PI-CL-IN-HCL
      $PI-BR-IN-HBR
      $PI-I-IN-HI
      $PI-N-IN-PYRROLE
      $PI-O-IN-FURAN
      $PI-S-IN-THIOPHENE

      Lone Pairs

      $LP1-N-
      $LP1-O-
      $LP2-O-
      $LP1-F-
      $LP2-F-
      $LP1-P-
      $LP1-S-
      $LP2-S-
      $LP1-CL
      $LP2-CL
      $LP1-BR
      $LP2-BR
      $LP1-I-
      $LP2-I-


To initialize a VBO by using a VBO library, the program searches for the
exact match first. If no exact match can be found, then it looks for the
most the similar one. For each VBO library, the minimal VBO entries are
those for H, C, O and S for 1-3 period elements. The molecules and the
utility scripts for creating the minimal VBO library files are released in
this package in the subdirectory VBOLIBMOL.


6.7.5 Controls for canonicalization of LMOs

The VBO library is used in two ways: the canonicalization of LMOs and the
generation of initial VB orbitals. If the library file exists, then one can
use canonicalization option for triple bonds and atoms with multiple lone
pairs so that the triple bond LMOs and lone pairs have the standard
orientation. To enable canonicalization, you can use the following control
flags.

      $CANONLP

      $CANONPI

The first one is used for the canonicalization of  lone pairs, and the
second one is for the two π LMOs of a triple bond. For a triple bond such
as that in C2H2,  the MO localization procedure does not guarantee the
resulting two π LMOs are in the standard orientations.


$PRINTHS

If you need VB matrix elements, you can add control flag $PRINTHS in the
input. With this control appearing in the input, both overlap and
Hamiltonian matrix elements of VB structures will be printed. However, this
option only prints matrix elements with for decimal points. You need modify
the code if you wish to get higher precision numbers.



6.8 Visualization of VB orbitals and molecules

Since version 1.8, we have introduced a number of routines to prepare data
for a number of molecular visualization programs. In some cases there are
quite different procedures in the three different programs - the stand-
alone VB2000, the G98 version and the
GAMESS(US) version. This is particularly true where the basis set has to be
obtained and output. The options for visualization are as follows.


$MOLPLT

This option is for the GAMESS(US) graphics programs. The data created by
this option can be used to display the molecule in an X window or to create
an image in a postscript file for printing. In all three programs,
inclusion of the keyword:-

      $MOLPLT

in the VB input data will create a file with the '.mol' extension to the
jobname. In GAMESS(US), the MOLPLT data can be appended to the PUNCH file
(jobname.dat) by adding 'MOLPLT=.TRUE.' to the $CONTRL group. The inclusion
of '$MOLPLT' in the VB data, overrides this so the MOLPLT data is only in
the jobname.mol file. In GAMESS(US) you might want to add a line in rungms
to move this file from the scratch directory to your current working
directory. In G98 also, the file is written to the scratch directory.


$PLTORB

This option is also for the GAMESS(US) graphics programs. The data created
by this option is used to display individual orbitals as contour plots in a
specified plane. It requires two input files - jobname.orb and jobname.vec.
In the GAMESS version, these can be created very easily. Adding
'PLTORB=.TRUE. to the $CONTRL group puts the jobname.orb data appended to
the PUNCH file (jobname.dat). jobname.orb can then be created by retrieving
that data. The jobname.vec file is created from the VB code by the keyword:-


      $PLTORB

in the VB data. It contains the coefficients of the VB orbitals in the
format that will be familiar to anyone who has used the PUNCH file and the
MOREAD keyword in the $GUESS group in Gamess(US). The jobname.orb file does
require some editing to add the plane for printing the orbitals and so on,
but these are flagged in the file created by the Gamess code.

In the stand-alone and G98 versions, both a jobname.vec and a jobname.orb
file are created. As in the GAMESS case, the jobname.orb file needs some
editing. In fact they need slightly more editing than in the GAMESS case.
In the latter the number of bonds and the bond specification are created
automatically. In the stand-alone and G98 versions, they have to be edited
in. To use the pltorb program, you will need the manual, which is
'pltorb.man' in the gamess/graphics directory (NB, this is not a man page;
it is a straight text file).

$CUBE

Orbitals can be displayed from a standard Gaussian cube file, a format that
can be read by several visualization programs, including VMD and Molekel.

The data block:-

      $CUBE
      M
      (N(i),i=1,M)
      Title
      NP

will produce M output files, called jobname-{N(i)}.cube. M is the number of
orbitals to be created and N(i) is an array of the orbital numbers. E.g.

      $CUBE
      3
      15 16 17
      Molecule X
      64

will generate 3 files, called jobname-015.cube, jobname-016.cube and
jobname-017.cube containing the cube data for the VB orbitals, 15, 16 and
17. NP is the number of grid points in each Cartesian coordinates. NP has a
maximum of 100 and defaults to 80 if given as 0.

Note that cube files generated by Gaussian itself contain many orbitals,
but not all visualization codes can read them. Some can only read one
orbital, so VB orbitals are created in separate cube files. Note also that
the current code is not very efficient and can be slow. Do not create cube
files unless you really need them. The $CUBE directive can be used in all
three versions of VB2000.

$GRID

The grid files can be generated in very similar way as above. The input is
almost identical except the flag $CUBE is replace by $GRID. The grid files
generated as .grd as the file extension. The grid files can be visualized
by DS Visualizer, which is free from Accelrys.  One can generate both cube
and grid files by using a shortcut as follows:

      $CUBE$GRID
      M
      (N(i),i=1,M)
      Title
      NP


$XYZFILE

To create an XYZ file for the molecule one can use the above directive in
the input. A file with file name jobname.xyz will be created. The xyz file
can be read by many visualization packages, such as VMD:

      VMD (Visual Molecular Dynamics) http://www.ks.uiuc.edu/Research/vmd/.


VMD is a freely available and  very powerful toolkit for visualization and
analysis of molecular dynamics (MD) simulation data. Although it was
initially developed with focus on MD, the newer versions contain many
features that make it a very attractive choice for visualizing results of
VB2000. One can find the tutorial of VMD at

  http://www.theochem.ruhr-uni-bochum.de/~axel.kohlmeyer/cpmd-
vmd/index.html



Here is are few tips for how to use VMD for displaying a VB orbital:

   1. Load the molecule (.xyz file) into the UI.
   2. Add the cube file of the molecule orbital to the molecule.
   3. Use the Graphics-> Representations menu from the VMD main Windows and
      choose Volume as the coloring method and isosurface as the drawing
      method. You'll just have to choose the appropriate isovalue for the
      the orbital you want to see.  You can also make orbital transparent.

One can also use another free software Molekel http://www.cscs.ch/molekel/
to display a Gaussian cube file. Molekel accepts the so-called .mkl file
for molecule structure. You may need to use of the directive:-


$MOLEKEL

The directive in the VB data block generates a file called jobname.mkl (in
the GAMESS and G98 cases in the scratch area). This is the molecule input
file for Molekel.



