The Direct CI Program

Revision: 1.21 Date: 1996/11/12 14:16:44


Table of Contents


 
                                  PREFACE
                                  _______
 
    This  manual  describes  the ATMOL Direct CI program, as implemented on
the Cyber-205 at UMRCC. This  document  is  one  in  a  series  of  twelve,
supporting the ATMOL packages on the Cyber-205.
 
 
                               ATMOL MANUALS
                               _____________
 
 
                          1.   Introduction.
                          2.   Allocator.
                          3.   Gaussian Integrals.
                          4.   Gaussian Library.
                          5.   SCF.
                          6.   APSG.
                          7.   Transformation.
                          8.   Direct CI.
                          9.   Mulliken Analysis.
                         10.   Graphical Analysis.
                         11.   Property.
                         12.   Service.
 
 
                             TABLE OF CONTENTS
                             _________________
 
 
    1.   Introduction.                                               1
    2.   The CNTRL Directive.                                        2
    3.   The TITLE Directive.                                        3
    4.   The THRESH Directive.                                       3
    5.   The MAXCYC Directive.                                       3
    6.   The SHIFT Directive.                                        4
    7.   The ALTERNAT Directive.                                     4
    8.   The DIAGMODE Directive.                                     4
    9.   The PRINTVAR Directive.                                     5
   10.   The TRIAL Directive.                                        5
   11.   The VPRINT Directive.                                       6
   12.   The SPIN Directive.                                         6
   13.   The PSORT Directive.                                        7
   14.   The SORT Directive.                                         7
   15.   The FFILE Directive.                                        7
   16.   The NATORB Directive.                                       8
   17.   The ONELEC Directive.                                       8
   18.   The SYMMETRY Directive.                                     9
   19.   The SYMDET Directive.                                      10
   20.   The REORDER Directive.                                     10
   21.   The EXCIT Directive.                                       12
   22.   The CONF Directive.                                        14
   23.   The REFGEN Directive.                                      15
   24.   The SCREEN Directive.                                      17
   25.   The RESTRICT Directive.                                    17
   26.   The PRCONF Directive.                                      18
   27.   The * Directive.                                           18
   28.   The CEPA Directive.                                        18
   29.   The ENTER Directive.                                       19
   30.   The RESTORE Directive.                                     19
   31.   Spin Functions.                                            19
   32.   Error Monitoring.                                          21
   33.   Specimen Jobs.                                             23
   34.   References.                                                26
 
 
 
 

Introduction


The ATMOL Direct-CI program is a general multi-reference singles and doubles configuration interaction (CI) program. The method (direct or integral driven) used in the package is described in [1]. To invoke the Direct-CI program on the Cyber-205 at UMRCC, use the following JCL:
 
        PATTACH,ATMOL.
        DIRECT.

In default the program will request 3 large pages of main memory, although this can be increased by use of one of the pre-directives LPAGE or MEMORY [2]. For optimal running the main memory allocation should be at least 3 times longer than the number of configuration state functions (CSFs) in the CI expansion. The program will tolerate the allocation of less memory, but at the cost of increased disc input/output, and higher overall job cost. The default memory allocation will usually handle CI expansions of up to 50,000 CSFs, and we recommend that at least 6 large pages of memory be allocated for larger cases. If the PSORT or SORT directives are used to increase the blocking factor of the PSORTFILE or SORTFILE respectively (see below), we recommend the use of 6 large pages of memory even for small cases.

Data input and printed output are on FORTRAN streams 5 and 6 respectively. There is normally no need to mention these streams in the JCL.

The following datasets will be used by the program, and should be mentioned in the JCL, in REQUEST, ATTACH, MFLINK or GETFEP commands:

PSORTFILE: A dataset normally assigned using the VSOS local file name (LFN) PSORT will be used as a scratchfile in a pre-sort of the transformed molecular integrals. The VSOS LFN for the PSORTFILE can be altered with the PSORT directive (see below). The space requirement of the PSORTFILE are about 1.5 times that of the FINAL MAINFILE of transformed 2-electron integrals produced by the transformation program [3].

SORTFILE: A dataset normally assigned with the VSOS LFN SORT will be used as a scratchfile in a post-sort of the transformed molecular integrals. The VSOS LFN for the SORTFILE can be altered with the SORT directive (see below). The maximum space requirements of the SORTFILE are about twice that of the FINAL MAINFILE of transformed 2-electron integrals produced by the transformation program [3], although this will be much reduced in high symmetry, by an inverse factor approaching the order of the point group involved.

FINAL MAINFILE: Transformed 2-electron integrals over the molecular orbitals (MOs) will be read from this file. The user may direct that this dataset be read from any ATMOL file except ED7 or MT7 by means of the FFILE directive (see below). The default is to use ED6.

DUMPFILE: The file used by the transformation program [3] for the output of 1-electron integrals over the MOs may be assigned as any ATMOL file except ED7 or MT7 with the ONELEC directive (see below). The program may also output space and spin natural orbitals (NOs) of the CI wavefunction to this file if so desired (see the NATORB directive below). In the absence of a ONELEC directive the DUMPFILE will be assumed to reside on ED3.

CI-VECTOR FILE: The ATMOL file ED7 is used to accomodate the partial Hamiltonian matrix elements. ED7 is also used to store the update vectors created by the Davidson diagonalization procedure [4]. Twice the CI expansion length will be added at each iterative cycle. The EMIN, VMIN and LOCK directives (see below) may be used to reduce the maximum size of the Davidson sub-space, thus limiting the ultimate size of ED7, possibly at the expense of an inferior rate of convergence. If it is thought possible that the diagonalization procedure may not converge in one job, ED7 must be retained to allow for restarts.

OVERFLOW FILE: During the construction of the partial matrix elements a scratchfile allocated as ATMOL file MT7 may be required. This is particularly likely to occur if a large number of reference CSFs are specified, while its likelyhood is decreased if a large main memory allocation is used. MT7 is usually of the order 1000 to 4000 blocks long if it is required.

All pre-directives [2] are applicable and should be presented before the program specific directives described below.


The Program Directives


The CNTRL Directive
 
    We strongly recommend that the CNTRL directive be presented  first.  It
is read to TEXT,NELEC,NINT,NEXT in format (A,3I).
 
    TEXT    should be set to the character string CNTRL.
 
    NELEC   specifies the number of electrons in the CI calculation. Notice
that any inner shell electrons frozen out with the FROZEN directive of  the
transformation program [3] should not be included.
 
    NINT    specifies  the  number  of  internal MOs. These will be used to
construct reference CSFs. If a MO is not occupied in any reference  CSF  it
should  not  ordinarily  be  classified  as internal, unless high levels of
internal excitation are  contemplated  (see  EXCIT  directive  below).  The
internal  MOs  normally  correspond  to  that  set  capable  of producing a
qualitatively correct wavefunction. Notice that NINT*2 must be greater than
or equal to NELEC.
 
    NEXT    specifies  the  number  of  external  MOs.  Such  MOs  will  be
unoccupied in all reference CSF. Single and  double  excitations  from  the
internal  to  the  external  MOs  cause  the latter to contribute to the CI
expansion.
 
    Notice that NINT+NEXT must be less than  or  equal  to  the  number  of
active  MOs  as  specified to the transformation program [3]. If less than,
then some active MOs will not take part in the CI, and in the absence of  a
REORDER  directive  (see  below),  these will be the highest indexed active
MOs.
 
    The remainder of the directives may be presented in any order, with the
exception  of  RESTORE  or  ENTER,  one of which must come last. In several
cases directives are inter-related and care should be taken when presenting
them,  since  the  order  in  which the directives are presented is in such
cases often significant; this is particularly the case for the EXCIT,  CONF
and REFGEN directives. Not all directives will be required in the same job.
 

The TITLE Directive
 
    Allows  the  user  to  define  an  80  character title for the run, and
extends over two lines. The first line consists  of  the  character  string
TITLE in the first data field, the second line the user defined title.
 
    example:
 
      TITLE
      PROPANE   DIRECT-CI
 

The THRESH Directive
 
    This directive is read to TEXT,C,K in format (A,F,I).
 
    TEXT    should be set to the character string THRESH.
 
    C,K     The diagonalization is converged to a threshold (T)  such  that
T=C/(10**K).  If  K  is  not  set, it will be given the value 0. The lowest
value to which T may be set is 1E-8, and this minimum will be  selected  if
the  user  attempts  to  set a smaller T value. The THRESH directive may be
omitted, when T will be set to 3E-4.
 
    example:
 
      THRESH 2 5
 
      THRESH 2E-5
 
      THRESH 0.00002
 
    are equivalent, causing T to be set to 2E-5.
 

The MAXCYC Directive
 
    This directive is read to TEXT,MAXC in format (A,I).
 
    TEXT    should be set to the character string MAXCYC.
 
    MAXC    specifies the maximum number of iterative cycles to be  carried
out by the Davidson [4] diagonalizer.
 
    The  directive  may  omitted, when MAXC will take the default value 50.
The program currently does not monitor time remaining for the  job,  so  in
large  cases  which  are  not  expected  to converge in one run, the MAXCYC
directive provides a means of ensuring  that  the  program  will  not  fail
'TIME-UP',  giving  the  user  the opportunity to ensure the safety of ED7,
which will be required in a restart job.
 

The SHIFT Directive
 
    This directive is read to TEXT,SHIF in format (A,F).
 
    TEXT    should be set to the character string SHIFT.
 
    SHIF    should be set to the value of the  level  shifter  for  the  CI
diagonalization  phase.  If  the  SHIFT  directive  is omitted, the default
SHIF=0.0 will be taken.
 
    For ground states small values (between 0.0 and 0.2) provide an optimal
rate  of  convergence, and usually there is little point in using the SHIFT
directive. For excited states, the rate of  convergence  may  sometimes  be
markedly   improved  by  using  a  SHIF  value  of  between  0.3  and  0.5,
particularly if the ALTERNAT directive (see below) is used.
 

The ALTERNAT Directive
 
    This directive consists of one line which should contain the  character
string ALTERNAT in the first data field. If presented, the directive causes
the sign of the SHIF parameter  (see  the  SHIFT  directive  above)  to  be
altered  at  each  iterative  cycle of the CI diagonalization, and this may
improve the convergence rate for excited states. We do not recommend use of
ALTERNAT except in cases where severe convergence problems are encountered.
 

The EMIN, VMIN and LOCK Directives

These directives are read to TEXT,NDAVID in format (2A,I).

TEXT
should be set to one of the character strings EMIN, VMIN or LOCK. EMIN causes the program to unconditionally minimize the total energy, and is normally the best option for ground states. VMIN causes the program to minimize the variance (sum of squares of residuals in the secular problem), and is usually the best option if convergence to an excited state is required. LOCK causes the program to seek a solution to the CI problem looking most like the trial wavefunction (see TRIAL directive below), according to the method of [5], and is therefore another way of trying to converge onto an excited state.

NDAVID
specifies the maximum size of the sub-space to be used in the Davidson [4] diagonalization procedure. If omitted, the default NDAVID=40 will be taken. It may be necessary to use a smaller sub-space in order to limit the size of ED7, as explained above. The largest possible sub-space is 40; attempts to set NDAVID larger than 40 will cause the program to use this maximum.
These directives may be omitted, when the defaults ATEXT=EMIN and NDAVID=40 will be taken.
 
    example:
 
      VMIN 40
 
      VMIN
are all equivalent, causing the variance minimization option to be selected, with a maximum sub-space of 40.


The TRIAL Directive

This directive may be used to define the trial CI wavefunction as a linear combination of CSFs. There are 2 ways to do this.

1) Enter specify the coefficients of the CSFs in the input file.

In this case the first line should only contain the literal string
    TRIAL
There may be up to 20 lines following this directive initiator, each being read to ICSF,CCSF in format (I,F).
ICSF
should be set to the index of a CSF in the CI wavefunction. Normally, such an index will only be known after running the program once, so that the configuration generator output can be studied. The user should understand the order in which the program generates spin states belonging to the same space occupancy pattern (see below) before using this directive, particularly where CSFs involving large numbers of singly occupied MOs are involved.
CCSF
should be set to the coefficient of the CSF in the trial wavefunction. The trial wavefunction will be a linear combination of the indicated CSFs with coefficients given by the CCSF parameters.
    example:
 
      TRIAL
      1  0.5
      2 -0.5
The trial wafunction will consist of a linear combination of the first and second CSF in the CI expansion, with coefficients 0.5 and -0.5 respectively. It will be subsequently normalized by the program.

2) Select a subspace of CSFs and compute the eigenvector of the matrix corresponding to the subspace.

In this case the syntax is:
    TEXT TEXTA SUBDIR [ SUBDIR [ .. ] ]
where
TEXT
Should be the literal string "TRIAL".
TEXTA
Should be the literal string "DIAG".
SUBDIR
This is a subdirective. Each subdirective consists of a literal string eventually followed by an integer. The supported subdirectives are
"SELECT" NCSF
Specifying SELECT followed by an integer NCSF will cause the program to select the NCSF configuration state functions with the lowest energies to build the trial vector. The maximum number for NCSF is 200. If a value exceeding this maximum is supplied then the maximum value will be used. The subdirectives SELECT, FIRST, REF and VAC are mutually exclusive.
"FIRST" NCSF
Specifying FIRST followed by an integer NCSF will cause the program to the NCSF configuration state functions that are the first in order. These CSFs are then used to build the trial vector. The maximum number for NCSF is 200. If a value exceeding this maximum is supplied then the maximum value will be used. The subdirectives SELECT, FIRST, REF and VAC are mutually exclusive.
"REF"
Specifying REF will cause the program to select the reference space to build the trial vector. The subdirectives SELECT, FIRST, REF and VAC are mutually exclusive.
"VAC"
Specifying VAC will cause the program to select the vacuum space to build the trial vector. The subdirectives SELECT, FIRST, REF and VAC are mutually exclusive.
"STATE" ISTATE
Supplying STATE followed by the integer ISTATE specifies which eigenvector from the subspace matrix should be used. The default value is 1 which means the eigenvector with the lowest eigenvalue will be selected for the trial vector.
"PRINT"
Supplying PRINT will increase the printing level. This means that the trial vector generator will produce a more detailed output. This subdirective may be used more than ones, resulting in ever higher printing levels.
    example:

      TRIAL DIAG SELECT 25
This will cause the program to select the 25 CSFs with the lowest eigenvalues. The matrix in this basis is solved for the eigenvector to obtain the trial vector.

Default:

The TRIAL directive may be omitted, when the trial wavefunction will be taken to be the first CSF in the CI list multiplied by a CCSF factor of 1.0.
The DIIS Directive

The DIIS directive turns on the diis acceleration of the 2*2 Davidson diagonalisation [9]. The syntax of this directive is:

     DIIS CRITERION NITERATIONS [ IFIX ENERGY ]
where
DIIS
This is a literal string
CRITERION
This is a floating point value. The tester in the Davidson diagonalisation should be less than this criterion to allow the diis acceleration to start.
NITERATIONS
This is an integer value. The iteration number should exceed this value to allow the diis acceleration to start.
IFIX
This is a non-zero integer value. It indicates that the energy to calculate the residuum with should be fixed to ENERGY.
ENERGY
This is a floating point value. It specifies the energy that will be used in calculating the residuum vector in the diis process.
Note that the diis process starts only if both the tester and the number of iterations satisfy CRITERION and NITERATIONS.


The JACDAV Directive

The JACDAV directive sets the controls of the Jacobi-Davidson preconditioning method. The syntax of this directive is

     JACDAV SUBDIR [ SUBDIR [ .. ] ]
where
JACDAV
This is the literal string "JACDAV".
SUBDIR
This is a subdirective. Each subdirective consists of a literal string eventually followed by an integer, real, or string argument. The supported directives are
"OFF"
This is a literal string, it switches the Jacobi-Davidson preconditioner off. By default the preconditioner is switched on, unless VMIN was selected. In the latter case Jacobi-Davidson is switched off by default.
"ON"
This is a literal string, that switches the Jacobi-Davidson preconditioner on. This is the default, unless VMIN was selected.
"SHIFT" "DYNAMIC" / RSHIFT
This subdirective sets the level shifter for the preconditioner. Here SHIFT is a literal string that is followed either by the literal string DYNAMIC or a real value for RSHIFT. If a real value RSHIFT is supplied then that value will be used for the level shifter. If the string DYNAMIC is supplied the level shifter will be automatically adjusted to force convergence. The latter is the default
"THRESH" RTHRSH
This subdirective sets the convergence threshold for the preconditioner. Here THRESH is a literal string and RTHRSH is a real value. By default the threshold is set to half the CI threshold at time of calling JACDAV.
"MAXCYC" IMAXC
This subdirective sets the maximum number of cycles for the preconditioner. Here MAXCYC is a literal string and IMAXC is an integer value. By default IMAXC is set to 100.
"SELECT" "REF" / "VAC" / IMAXS
This subdirective is a literal string followed the literal string REF, the literal string VAC or an integer IMAXS. Specifying REF subjects the reference space to the Jacobi-Davidson preconditioner, VAC selects the vacuum space. If IMAXS is specified then the Jacobi-Davidson preconditioner will work on the first IMAXS CSFs.
By default the vacuum space will be selected, unless the dimension of the total CI space is less than 150 times the dimension of the vacuum space. In the latter case the reference space will be selected.
"PRINT"
This subdirective controls the output level of the preconditioner. Here PRINT is a literal string. Every time this string is supplied the output level is increased, causing the preconditioner to generate a more detailed output. By default the printing is off.
NOTE: Because the default threshold is determined from the CI threshold at time of calling JACDAV interchanging the order of the THRESH directive and the JACDAV directive may lead to different convergence behaviour.


The CHECKD Directive

Entering the CHECKD directive specifies that the energy and the variance of the wavefunction should be recalculated upon convergence of the Davidson diagonalisation. This directive may be used when high accuracy is required.

The syntax of the directive is:

     CHECKD [ ICRIT ]
where "CHECKD" is a literal string. ICRIT specifies the criterion after which the check should be performed according to the expression
    criterion = 0.1d0 ** ICRIT
If the CHECKD directive is omitted then the criterion is set to 0.9d-06. Otherwise, if ICRIT is omitted then the criterion is set to 1.0d0 which means that in practise the check will be performed always.


The MEMDAV Directive

The Davidson diagonalisation method builds a subspace in which it searches for the optimal approximation of the eigenvector. The vectors that form the basis of this subspace have to be stored as well as the vectors that are obtained by multiplying the basis vectors with the Hamiltonian matrix. These vectors may be stored either on disc or in core memory.

The MEMDAV directive provides a means to specify the amount of core memory that should be used to store the subspace vectors. The directive has the following syntax:

     MEMDAV MEMSIZE
where "MEMDAV" is a literal string and MEMSIZE is an integer specifying the required amount of memory in words (real*8).

If the MEMDAV directive is not entered MEMSIZE will be set to 2 Mword. The Davidson diagonalisation routine may be forced to store the vectors on disc by setting MEMSIZE to 0.


The OUTSTORE Directive

The OUTSTORE directive forces the matrix-vector multiplicator that is central to the direct-CI procedure to operate in "outstore" mode. This means that the integral information the multiplicator uses will be kept on disc as much as possible, thus saving as much memory as possible. This may be useful in large calculations where memory limitations cause problems.

The directive has syntax:

By default the program will attempt to operate in "instore" mode.


The VPRINT Directive
 
    This directive is  read  to  TEXT,NPR,TPR,ATEXT,BTEXT,CTEXT  in  format
(A,I,F,3A), and is used to control printing of the CI wavefunction.
 
    TEXT    should be set to the character string VPRINT.
 
    NPR     specifies the maximum number of CI coefficients to be printed.
 
    TPR     CI coefficients less than TPR in absolute magnitude will not be
printed.
 
    ATEXT,BTEXT,CTEXT may each be set to one of the character strings  VAC,
N-1,  or N-2. If VAC is specified, CI coefficients of all the vacuum states
(those with no electrons  in  the  external  MO  space)  will  be  printed,
irrespective of the values of NPR and TPR. Similarly the parameters N-1 and
N-2 control printing of those  CSFs  with  one  or  two  electrons  in  the
external space respectively.
 
    This  directive  may be omitted, when the defaults NPR=100 and TPR=1E-7
will be taken.
 
    example:
 
      VPRINT 50 0.02 VAC
 
    will  cause  all  vacuum  state  coefficients  to   be   printed.   All
coefficients  greater  in  absolute  magnitude  than  0.02 will be printed,
unless there are more than 50 of these, in which case only the  largest  50
will be printed.
 

The SPIN Directive
 
    This directive is read to TEXT,NSPIN in format (A,I).
 
    TEXT    should be set to the character string SPIN.
 
    NSPIN   is  used to specify the spin degeneracy of the CI wavefunction,
using  the  values  1,2,3  etc  for  singlet,doublet,triplet   etc   states
respectively.  It  is  also  possible  to  use one of the character strings
SINGLET, DOUBLET, TRIPLET, QUARTET,  QUINTET,  SEXTET,  SEPTET,  OCTET  and
NONET to specify NSPIN.
 
    The SPIN directive may be omitted, when the program will set NSPIN to 1
or 2 if NELEC is even or odd respectively.
 
    example:
 
      SPIN 4
 
      SPIN QUARTET
 
    are equivalent; the wavefuction will be four-fold spin degenerate.
 

The PSORT Directive
 
    The PSORT directive is read to TEXT,KSIZE,ATEXT in format (A,I,A).
 
    TEXT    should be set to the character string PSORT.
 
    KSIZE   specifies the blocking factor (in units of ATMOL blocks) to  be
used in data transfers involving the PSORTFILE. The maximum blocking factor
is 24 (12K words), and if the user specifies greater than this, the program
adjusts  the  value  back  to  the  maximum. If insufficient main memory is
allocated to allow successful use of a given blocking  factor,  the  latter
will  be  reduced  to  the  maximum  compatible  with the given main memory
allocation. The larger the blocking factor, the more efficiently  will  the
pre-sort  phase  of  the program operate. It is recommended that at least 6
large pages of memory be allocated if the maximum blocking factor is to  be
used.
 
    ATEXT   may  be  used  to  specify  the  VSOS  LFN of the PSORTFILE; if
omitted, the program will assume the LFN is PSORT.
 
    The PSORT directive may be omitted,  when  the  defaults  KSIZE=12  and
ATEXT=PSORT will be taken.
 

The SORT Directive
 
    The SORT directive is read to TEXT,KSIZE,ATEXT in format (A,I,A).
 
    TEXT    should be set to the character string SORT.
 
    KSIZE   specifies  the blocking factor (in units of ATMOL blocks) to be
used in data transfers involving the SORTFILE. The maximum blocking  factor
is 24 (12K words), and if the user specifies greater than this, the program
adjusts the value back to the  maximum.  If  insufficient  main  memory  is
allocated  to  allow  successful use of a given blocking factor, the latter
will be reduced to the  maximum  compatible  with  the  given  main  memory
allocation.  The  larger the blocking factor, the more efficiently will the
post-sort phase of the program operate. It is recommended that at  least  6
large  pages of memory be allocated if the maximum blocking factor is to be
used.
 
    ATEXT   may be used to  specify  the  VSOS  LFN  of  the  SORTFILE;  if
omitted, the program will assume the LFN is SORT.
 
    The  SORT  directive  may  be  omitted,  when the defaults KSIZE=12 and
ATEXT=SORT will be taken.
 

The FFILE Directive
 
    This directive is used to define the location of the FINAL MAINFILE  of
transformed  2-electron  integrals. The syntax has been described elsewhere
[3].
 
    example:
 
      FFILE
      ED2
      1
      0
 
    Valid ATMOL file names are ED0  to  ED6  and  MT0  to  MT6.  The  FFILE
directive may be omitted, when the FINAL MAINFILE will be assumed to reside
on ED6, commencing at block  1  and  terminating  with  an  ENDFILE  block.
Omission is equivalent to:
 
      FFILE
      ED6
      1
      0
 

The NATORB Directive
 
    The NATORB directive  is  read  to  TEXT,KSPACE,KSPIN,ATEXT  in  format
(A,2I,A).
 
    TEXT    should be set to the character string NATORB.
 
    KSPACE   is  an  integer  (between  0 and 190 inclusive) specifying the
section number of the DUMPFILE where the space NOs are  to  be  placed.  If
KSPACE=0, space NOs will not be routed to the DUMPFILE.
 
    KSPIN   is  an  integer  (between  0  and 190 inclusive) specifying the
section number of the DUMPFILE where the spin NOs  are  to  be  placed.  If
KSPIN=0,  spin NOs will not be routed to the DUMPFILE. Notice that spin NOs
will not be produced for singlet wavefunctions (see SPIN  directive  above)
because they have an occupation number of zero in this case.
 
    ATEXT   may  be set to the character string PRINT, when the NOs will be
printed. If ATEXT is omitted, the NOs will not be sent to the lineprinter.
 
    example:
 
      NATORB 12 14 PRINT
 
 
    The space and spin NOs are output to sections 12 and 14 respectively of
the DUMPFILE, and routed to the lineprinter.
 

The ONELEC Directive
 
    The ONELEC directive allows the user to specify  the  location  of  the
DUMPFILE  and  the  transformed  1-electron integrals placed thereon by the
transformation program [3], and is read to TEXT,DDNAM,IBLK,ISECT in  format
(2A,2I).
 
    TEXT    should be set to the character string ONELEC.
 
    DDNAM   specifies the ATMOL file name assigned to the  DUMPFILE.  Valid
names are ED0 to ED6 and MT0 to MT6.
 
    IBLK    specifies the starting block of the DUMPFILE.
 
    ISECT   specifies  the  section  number  of  the transformed 1-electron
integrals on the DUMPFILE. If ISECT is omitted, the transformed  1-electron
integrals  will  be  assumed  to  be  in  section 198, which is the default
section number used by the transformation program [3].
 
    The ONELEC directive may  be  omitted,  when  the  defaults  DDNAM=ED3,
IBLK=1 and ISECT=198 will be taken.
 

The SYMMETRY Directive
 
    This directive is used to give the symmetry point group and irreducible
representation (irrep) of the required CI vector. The first  data  line  is
read to TEXT,TPOINT,TIRREP in format (3A).
 
    TEXT    should be set to the character string SYMMETRY.
 
    TPOINT  should  be  set to the required point group. Valid point groups
are C1,CS,CI,C2,D2,C2V,C2H and D2H. TPOINT should be set to  one  of  these
character strings.
 
    TIRREP  may  be set to the irrep of the CI wavefunction, as required by
the user. If TIRREP is not set, the program will  user  the  irrep  of  the
first  reference CSF (see the CONF directive below). The order and names of
the irreps are as outlined in standard group theory, as shown below.
 
                            POINT GROUP
                            ___________
 
           C1    CS    CI    C2    D2    C2V    C2H    D2H
           _______________________________________________
           A     A'    AG    A     A     A1     AG     AG
       I         A''   AU    B     B1    A2     BG     B1G
       R                           B2    B1     AU     B2G
       R                           B3    B2     BU     B3G
       E                                               AU
       P                                               B1U
                                                       B2U
                                                       B3U
 
    Note that the double prime appearing in the A'' irrep of the  CS  point
group  should  be typed as two single 'quotes', not as the single character
'double quote'. The point group and irrep names should be typed exactly  as
shown, with upper case letters.
 
    After  the  first line follows one line for each irrep, each being read
to NIRO,NERO in format (2I).
 
    NIRO    specifies the number of internal MOs of a given irrep.
 
    NERO    specifies the number of external MOs of a given irrep.
 
    Note that these lines must be in the order of irreps indicated  in  the
table, and that the sum of the NIRO and NERO parameters must equal the NINT
and NEXT parameters respectively, see the CNTRL directive above.
 
 
    example:
 
      SYMMETRY C2V A1
      2 6
      0 1
      1 3
      1 2
 
    The  molecule  has  the  point  group C2V and the required irrep of the
wavefunction is A1. There are to be 2,0,1 and 1 internal  MOs  of  A1,A2,B1
and  B2 irrep respectively, and 6,1,3 and 2 external MOs of A1,A2,B1 and B2
irrep respectively. Note that if there are no internal and external MOs  of
a  given  irrep,  the user must indicate this explicitly. The above example
but wihout the A2 MOs would look like:
 
      SYMMETRY C2V A1
      2 6
      0 0
      1 3
      1 2
 
    If the SYMMETRY and SYMDET (see below) directives are both omitted, the
program will take the point group to be C1. If the SYMDET directive is used
the SYMMETRY directive must be omitted, and vice-versa.
 

The SYMDET Directive
 
    This directive provides a more automatic way of specifying the symmetry
data. The syntax is

    SYMDET [ TPOINT TIRREP ] [ TIRREP1 [ TIRREP2 [ ... ] ] ] [ CRIT ICRIT ]

    SYMDET   is a literal string (it invokes the directive).

    TPOINT   is a text string that specifies the point group of the molecule. 
If this subdirective is not specified SYMDET will try to determine the point
group automatically. If specified the TPOINT should be set to one of 
C1, CS, CI, C2, D2, C2V, C2H and D2H. 

    TIRREP   is a text string that specifies the irreducible representation 
(irrep) of the CI wavefunction. The order and names of the irreps are as 
outlined in standard group theory, as shown at the SYMMETRY directive.
Alternatively, TIRREP may be set to the literal string REF. In this case
the program will use the irrep of the first reference CSF. Normally
it is preferable to set TIRREP to REF, and this parameter should only be 
changed if the program has been run once on the problem, so that the user 
knows the group multiplication table generated by the program, and also 
understands to which irreps the labels correspond.

    TIRREP1, TIRREP2, ....   are text strings specifying the names of the
few representations on the integral file. If these are not specified the
program will automatically assign names to the representations. However, 
as the SYMDET directive does not use the molecular geometry but assigns 
names according to the properties of the integrals, these names may look a 
bit strange.

    CRIT ICRIT   is the literal string CRIT followed by the integer value
ICRIT. The integer ICRIT specifies the accuracy in the symmetry determination.
Molecular integrals of absolute magnitude less than 10**(-ICRIT) will be
ignored. By default ICRIT is set to 5.

    examples:

      SYMDET C2V REF A1 B1 CRIT 5

      SYMDET CRIT 9

      SYMDET D2H REF CRIT 10

 

The REORDER Directive
 
    This  directive  is  used  to renumber the internal and external MOs so
that they are in the order required if the SYMMETRY directive  (see  above)
is used. This ordering is such that:
 
    (a) The internal MOs must come before the  external  MOs.  This  is  an
absolute  requirement,  irrespective  of  whether  the  SYMMETRY  or SYMDET
directives are used.
 
    (b) The internal MOs must be ordered according to increasing  irrep  if
the SYMMETRY directive is used. Similarly for the external MOs.
 
    The  first  data  line  should  be set to the character string REORDER.
Subsequent lines should define NINT+NEXT integers, these defining  the  MOs
in  the  order required. The maximum value of these integers is the size of
the active MO space as defined to the transformation program [3].
 
    example:
 
    Consider the example quoted under the SYMMETRY directive,  and  suppose
the  symmetry  assignments  of  the  active  MOs used in the transformation
program [3] were as follows:
 
      INTERNAL A1:   1  3
               B1:   4
               B2:   2
      EXTERNAL A1:   5  6  7 10 11 16
               A2:  12
               B1:   8 13 14
               B2:   9 15
 
    an appropriate REORDER directive would look like:
 
      REORDER
      1 3 4 2
      5 6 7 10 11 16 12 8 13 14 9 15
 
    The REORDER directive can span as many lines as  required,so  that  the
above sequence can be presented as:
 
      REORDER
      1 3
      4
      2
      5 6 7 10 11 16
      12
      8 13 14
      9 15
 
    The character string TO may be used to string  together  a  consecutive
sequence of MO numbers. Thus our example can also be presented as:
 
 
      REORDER
      1 3
      4
      2
      5 TO 7 10 11 16
      12
      8 13 14
      9 15
 
    Note that any active MOs defined during integral transformation but not
present in the REORDER list will not take part in the CI calculation. It is
also possible to use the ACTIVE directive of the transformation program [3]
to obtain the desired ordering of the MOs.
 

The EXCIT Directive
 
    This  directive  is used to define the excitation pattern allowed for a
set of reference CSFs defined with the  CONF  directive  (see  below).  The
EXCIT  directive  may be used more than once in the data input to allow the
user to specify different excitation patterns for different reference CSFs,
and  normally  consists of a single dataline, in which the first data field
should contain the character string EXCIT.
 
    The second data field may also be read in A  format,  and  if  so  used
should  be  set  to  one  of the character strings OCTAL or BINARY. If this
second A format field is omitted, the program takes OCTAL as default.
 
    Subsequent data fields are read in I-format, and should contain  either
octal  numbers (valid range 0 to 7) or binary numbers (valid range 0 to 1),
according to the character string contained in the second data  field.  The
octal  or  binary  integers  may  be  continued  onto  subsequent  lines if
neccessary.
 
    We now explain the significance of these integers if OCTAL  input  mode
is selected.
 
    The  first  octal integer specifies the external excitation pattern for
the reference CSFs, (where no internal excitations have been applied). This
octal number should be translated into a binary format, such that:
 
       OCTAL NUMBER           BINARY NUMBER
       ____________           _____________
            0         =       0     0     0
            1         =       0     0     1
            2         =       0     1     0
            3         =       0     1     1
            4         =       1     0     0
            5         =       1     0     1
            6         =       1     1     0
            7         =       1     1     1
 
    The  left-most  binary  integer  defines  a double external excitation,
where two electrons are promoted from the internal to the  external  space.
If  it  is  0  or  1  the process is forbidden or allowed respectively. The
middle binary integer defines the single external  excitation  process.  If
this is set to 1, the process is allowed,  if  it  is  0,  single  external
excitations  are  forbidden. The right-most binary integer corresponds to a
no external excitation process, the reference CSFs being left as they  are.
If  set to 0 or 1 the reference CSFs will be eliminated from or retained in
the final list of CSFs for the CI. Note that CSFs may  also  be  eliminated
from the CI list because they are of the wrong spin/space symmetry.
 
    example 1:
 
      EXCIT OCTAL 7
 
    This  excitation  mask will cause the reference CSFs and the single and
double external excitations generated from them to be included in the final
CI list of CSFs.
 
    example 2:
 
      EXCIT OCTAL 5
 
    Will  cause  all the reference CSFs and all double external excitations
generated therefrom to be added to the list of CSFs for the CI.
 
    example 3:
 
       EXCIT OCTAL 4
 
    Will cause the double external excitations of the reference  states  to
appear  in  the  final list of CSFs. Note the reference and single external
excited CSFs are excluded from the CI list.
 
    If a second octal integer is defined, the reference CSFs have undergone
a  single  internal  excitation process. That is, a transfer of an electron
from one internal MO to another. This second integer defines  the  external
excitation  mask  on  these  newly constructed internal CSFs. A third octal
integer defines the external excitation pattern  after  a  double  internal
excitation.  Additional octal integers may be presented, up to a maximum to
21 integers. Thus it is possible to define a state which is up to  20  fold
internally excited and up to doubly externally excited.
 
    example 4:
 
      EXCIT OCTAL 7 3 1
 
    corresponds  to a CI list containing the reference CSFs plus all single
and double excitations (internally and externally).
 
    If the BINARY option is chosen, then the full binary patterns  of  each
equivalent octal integer must be given.
 
 
    example 5:
 
      EXCIT OCTAL 7 3 1
 
      EXCIT BINARY  1 1 1  0 1 1  0 0 1
 
    are equivalent.
 
    It  is  possible  to  give  different  excitation patterns to different
reference CSFs.
 
    example 6:
 
      EXCIT OCTAL 7 3 1
      CONF
      .
      .
      .
      .
      EXCIT OCTAL 5 0 1
      CONF
      .
      .
      .
 
    The first set of reference CSFs  are  associated  with  the  excitation
pattern 7 3 1, while the second set have an excitation pattern 5 0 1.
 
    If  the  EXCIT  directive  is  not  invoked the excitation pattern will
default to the setting  7 3 1,  corresponding  to  all  single  and  double
excitations.  An  EXCIT  directive  presented without parameters will cause
restoration of the 7 3 1 default.
 

The CONF Directive
 
    The CONF directive is used to specify the reference  CSFs  for  the  CI
expansion.  CONF may be presented more than once in the data input, usually
in conjunction with a different excitation pattern (see the EXCIT directive
above)  acting  on the reference CSFs. The first line of the CONF directive
is set to the character string  CONF.  Each  subsequent  line  specifies  a
reference CSF by giving the number of electrons (0,1 or 2) in each internal
MO. Thus each reference CSF is defined by NINT  numbers,  the  ordering  of
which  should  conform to the order of the internal MOs as specified by the
REORDER directive (see above) if the latter is presented. If necessary, CSF
defining data may be carried over to further lines.
 
    example 1:
 
    Consider  the  example quoted under the SYMMETRY directive above, where
we have 2 A1,1 B1, and 1 B2 internal MO. To define a fully occupied pattern
use:
 
      CONF
      2 2 2 2
 
    example 2:
 
    The  situation  is  as  in  example  1, except that we wish to define a
7-electron reference CSF, with the B1 MO singly occupied.  We  assume  that
the  REORDER  directive  has been used to get the MOs properly ordered. The
data would look like:
 
      CONF
      2 2 1 2
 
    example 3:
 
    The  situation  is  as in example 2 except that SYMDET has been used to
determine the irreps, so that the user has not  needed  to  use  a  REORDER
directive.  Remembering  that the original ordering of the internal MOs was
A1 B2 A1 B1, appropriate data to define the 7 electron B1 state would  look
like:
 
      CONF
      2 2 2 1
 
    example 4:
 
      CONF
      2 2 1 2
      1 2 2 2
 
    Multiple reference CSFs are allowed; thus the above  data  defines  two
7-electron reference CSFs of A1 symmetry, assuming that SYMDET was used. If
however the SYMMETRY and REORDER directives were used, the first  reference
CSF will be of B1 symmetry, while the second will be A1.
 
    The  CONF  directive  directive may be omitted, when a single reference
CSF will be generated by the program, where the first  NEL/2  internal  MOs
will  be  populated with 2 electrons, and if NEL is odd, 1 further electron
will be added to the next internal  MO.  Note  however  that  this  default
reference  CSF will not be generated until all the data has been processed,
and so will be unavailable for use by the REFGEN directive described below.

Alternatively the CONF directive may be used to specify the complete configuration space. The syntax for this use of the CONF directive is:

    CONF
    VACUUM
      [ conf1 [ ... ]]
    N-1
      [ conf2 [ ... ]]
    N-2
      [ conf3 [ ... ]]
Note that Example:

For a calculation on a Lithium atom where the 1S and 2S are the active orbitals the following configuration space may be specified:

    CONF
    VACUUM
      2 1
      1 2
    N-1
      2 0 
      1 1
      0 2
    N-2
      1 0
      0 1

The REFGEN Directive
 
    The first line should consist of the character  string  REFGEN  in  the
first data field. Subsequent lines are read in I-format, to paired integers
IA and IC. As many such lines as required may be presented.
 
    IA and IC define  annihilation  and  creation  operators  respectively,
which  will be allowed to operate on the set of reference CSFs in existence
at the time when REFGEN is called. Thus at least one  CONF  directive  must
have  been  presented  before using REFGEN, and the IA,IC integers refer to
internal MOs. The result  of  the  annihilation/creation  process  will  be
further  reference  CSFs,  whose  excitation  mask will be that of the most
recently issued EXCIT directive.
 
    example 1:
 
      EXCIT OCTAL 7 3 1
      CONF
      2 2 0 0
      EXCIT OCTAL 5
      REFGEN
      1 3
      2 4
 
    will result in a further two reference states, to give three in all, of
the form:
 
      CSFS        EXCITATION MASK        ORIGIN
      ____        _______________        ______
      2 2 0 0     7 3 1                  CONF directive
      1 2 1 0     5                      REFGEN directive
      2 1 0 1     5                      REFGEN directive
 
    example 2:
 
      EXCIT OCTAL 7 3 1
      CONF
      2 2 0 0
      EXCIT OCTAL 5
      REFGEN
      1 3 2 4
 
    is equivalent to example 1; more than one IA/IC pair may be given on  a
single line.
 
    example 3:
 
      EXCIT OCTAL 7 3 1
      CONF
      2 2 0 0
      EXCIT OCTAL 5
      REFGEN
      1 3
      EXCIT OCTAL 3
      REFGEN
      2 4
 
    will produce 4 reference CSFs, of the form:
 
      CSFS        EXCITATION MASK        ORIGIN
      ____        _______________        ______
      2 2 0 0     7 3 1                  CONF directive
      1 2 1 0     5                      First REFGEN directive
      2 1 0 1     3                      Second REFGEN directive
      1 1 1 1     3                      Second REFGEN directive
 
    example 4:
 
      EXCIT 7 3 1
      CONF
      2 2 0 0
      REFGEN
      1 3 1 4 2 3 2 4
      REFGEN
      1 3 1 4 2 3 2 4
      REFGEN
      1 3 1 4 2 3 2 4
      REFGEN
      1 3 1 4 2 3 2 4
 
    will produce a reference space consisting of all possible CSFs that can
be generated by distributing 4 electrons in 4 MOs.
 

The CASGEN Directive

    The CASGEN directive is meant for generating CAS or full-CI 
wavefunctions. If one or more reference configuration was specified please
read the documentation on the EXCIT subdirective. This directive consists 
of one line 

      TEXT OPTION1 [ OPTION2 ] [ OPTION3 ] ...

    TEXT should be set to the string CASGEN.

    The options may be any of the following (the text between quotes is the
literal keyword specifying the option):

      "DOC" NDOC 
 
         This option specifies the number NDOC of orbitals that will remain
       doubly occupied in the CAS or full-CI wavefunction. The orbitals
       remaining doubly occupied are the first NDOC orbitals in order on 
       the dumpfile. Note that DOC and SDOC are mutually exclusive.

      "SDOC" NDOC1 NDOC2 ...

         This option related to the DOC option. However SDOC specifies the
       the number of doubly occupied orbitals per symmetry. The orbitals
       remaining doubly occupied are the first NDOC orbitals in order on
       the dumpfile. Note that DOC and SDOC are mutually exclusive.

      "NORB" NORBC

         This option specifies the number of orbitals considered by the
       wavefunction generator. The wavefunction generator will use the
       first NORBC orbitals in the order they were found on the dumpfile.
       By default the wavefunction generator considers the number of
       internal orbitals as specified in the CNTRL
       directive.

      "MAXEX" NMAX 

         This option specifies the maximum excitation level NMAX with 
       respect to the current reference set. By default the wavefunction
       generator performs all possible excitations within the active
       orbitals.

      "EXCIT"

         This option selects the current excitation allowance for the
       newly generated configurations only. By default the wavefunction 
       generator performs no internal excitations on the newly generated
       configurations (see also the EXCIT directive).

      "NOSYM"

         This option specifies that the wavefunction generator should
       not use symmetry to select the configurations. By default the
       wavefunction generator assumes the NOSYM option. The reason for
       this default is that symmetry allowed configurations can be 
       generated from symmetry forbidden configurations. These 
       configurations will be lost if symmetry selection is applied.

      "SYM"

         This option specifies that the wavefunction generator should
       use symmetry to select the configurations. Note that by default
       the wavefunction generator does not use symmetry selection. The 
       reason for this default is that symmetry allowed configurations can 
       be generated from symmetry forbidden configurations. These 
       configurations will be lost if symmetry selection is applied.

      "SPIN"

         This option specifies that the wavefunction generator should
       select the configurations according to spin-symmetry.

      "PRINT"

         This option specifies that the reference configurations should
       be printed after executing the CAS generator. This allows 
       inspection of the generated configurations and their excitation
       patterns.


The SCREEN Directive
 
    This directive consists of one  line  whose  first  data  field  should
contain  the  character  string  SCREEN. If this directive is presented all
reference configurations will be checked to see if they  are  of  the  same
spin/space  symmetry  as  that of the required CI wavefunction. If they are
not, they will be eliminated from the reference space,  and  will  take  no
part  in  the  excitation  process.  Normally,  this  directive may only be
required if a REFGEN directive is  presented,  since  reference  states  of
undesired  properties  will  not  usually be presented under control of the
CONF directive.
 

The RESTRICT Directive
 
    This directive provides a means of selectively  eliminating  CSFs  from
the  CI  expansion  by specifying a minimum and maximum number of electrons
which user specified sets of internal MOs may carry. The first line  should
contain  the  character string RESTRICT in the first data field. Subsequent
lines are read to TEXT,MIN,MAX,(IORBS(i),i=1,m), in format (A,2I,mI).
 
    TEXT    should be set to one of the character strings REF, VAC, N-1  or
N-2.  If  REF  is chosen the restrictions will apply to the reference CSFs;
should such a state fail to comply with the  restriction  applied  it  will
take  no  part  in the excitation process used to generate the CI list, and
will most probably be used when REFGEN directives are used.  The  character
strings  VAC,  N-1  and  N-2  refer  to CSFs with 0,1 or 2 electrons in the
external space respectively.
 
    MIN,MAX specify the minimum and  maximum  number  of  electrons  to  be
allowed to populate the internal MOs defined by the IORBS parameters.
 
    IORBS   A  sequence of internal MO indices terminated by the integer 0.
This data may be carried over to subsequent lines  if  necessary,  and  the
character  string  TO  may  be  used  to shorten the data if desired. These
parameters refer to the reordered MO  list  if  a  REORDER  directive  (see
above) has been presented.
 
    example:
 
      RESTRICT
      VAC 7 8 1 TO 4 0
      N-1 7 8 1 TO 4 0
      N-2 7 8 1 TO 4 0
 
    Internal MOs 1 to 4 inclusive are  allowed  to  carry  either  7  or  8
electrons in vacuum,N-1 and N-2 CSFs.
 

The PRCONF Directive
 
    This directive is meant to limit the amount of output produced in
printing occupation patterns. For example, in situations were many 
reference CSFs are specified one will want to withhold the program from 
printing all occupation patterns. 

    The directive is read to TEXT,IPR in format (A,I).
 
    TEXT    should be set to the character string PRCONF.
 
    IPR     specifies that every IPR'th occupation pattern generated by the
            configuration generator is to be printed. If IPR=0, no 
            occupation patterns will be printed.
 
    The directive may be omitted, then all occupation patterns generated by
the configuration generator will be printed. 
 

The * Directive
 
    This directive allows the user to introduce comments in his input data,
and consists of one line, with a * character in column  1,  followed  by  a
space  character,  followed  by up to 78 characters comprising the comment.
The comment will be sent to the lineprinter output, but will otherwise have
no effect. Any number of * directives can be placed in the input data.
 
    example:
 
      * THIS IS AN EXAMPLE OF A COMMENT CARD
 

The CEPA Directive

The CEPA directive allows the user to perform a CI calculation corrected for unlinked cluster contributions. The CEPA approach is more accurate than the Davidson correction. Activating the CEPA option forces the diagonaliser to work in Out-of-Store mode. Currently single reference and multi reference CEPA options are available, although some approaches may only work in single reference calculations.

The syntax of the CEPA directive is

    "CEPA" [ MODE ] [ SUBDIR ] [ ... ]
The literal string CEPA may be followed by an optional parameter
MODE
The parameter MODE may be set to any of the strings '0', '1', '2' or 'MRD'. The first three modes are the single reference modes corresponding to the number in the string. (see also [6]). The 'MRD' mode is the multi reference CEPA mode (see also [8]). By default mode '1' is selected.
After this parameter any of the following subdirective may be used
"SIN" / "NOSIN"
The strings SIN and NOSIN select and deselect the single excitation shift option respectively. The default is SIN.
"IT" ITCEPA
This subdirective indicates after what iteration the CEPA mode may start. The integer parameter ITCEPA is the iteration number after which the CEPA mode may be switched on. By default ITCEPA is set to 3.
"CRIT" FCRIT
This subdirective indicates that the CEPA mode should be invoked at a particular threshold determined by the TESTER in the diagonalisation phase of the CI calculation. The threshold FCRIT should be set to a floating point value. By default FCRIT is set to 0.01.
"MICRO" IMICRO FMICRO
This subdirective controls the micro iteration proces. The integer IMICRO is the maximum number of micro iteractions that may be performed each iteration. The micro iteration proces may terminate in less than IMICRO iterations if a treshold becomes less than the floating point number FMICRO. The default is MICRO 3 0.01d0.
"PRINT"
This subdirective requests intermediate printing within the CEPA mode.
"PAUL"
This subdirective refers only to the CEPA 2 mode, and invokes an unpublished EPV correction formula due to P.J.A. Ruttink.
This directive can be invoked without parameters, which will result in the default values being observed. The defaults are equivalent to the following example:
   Example:

      CEPA 1 SIN IT 3 CRIT 0.01d0


The MP Directive

The MP directive allows the user to perform internally contracted (multi reference) MP 2 / 3 calculations. The current implementation allows the usage of the MP vector as a start for a (MR)CI or (MR)CEPA calculation.

The syntax of the MP directive is

   "MP" [ IORDER ] [ SUBDIR ] [ ... ] 
The literal string MP may be followed by an optional parameter
IORDER
This parameter selects the order of perturbation-theory that will be calculated. Currently IORDER may be set to 2 or 3. By default IORDER is set to 2.
After this parameter any of the following subdirectives may be used
"MODEL" IMODEL
This subdirective selects the zeroth-order Hamiltonian for the calculation. In the case of a multi-configurational (MC) reference function the reference wavefunction is not necessarily an eigenfunction of the Fock operator. To obtain a zeroth-oder Hamiltonian from the Fock operator that has the MC reference function as eigenfunction it suffices to split the into a part working on the reference function and a part working on the remainder of the configuration space (i.e. the singles and doubles). For this purpose the projection operators |P0>, |P1> |P2> and |P1+2> are used. These operators project onto the reference space, the space of the singly excited states, the space of the doubly excited states, and the space of the singly and doubly excited states respectively.

Using the projection operators the following zeroth order Hamiltonians have been implemented

The desired zeroth Hamiltonian may be selected by setting IMODEL to the appropriate value. By default IMODEL is set to 1.
"PRINT" IPRINT
This subdirective sets the output level of the MP routines. The higher the value of IPRINT the more output will be generated. By default IPRINT is set to 1, the highest value of IPRINT currently is 10001.
"CRIT" RCRIT ICRIT
This subdirective sets the convergence criterion for the linear system solver in the MP calculation. Here RCRIT is a real value and ICRIT is an integer value, the convergence criterion is calculated as MPCRIT = RCRIT * 10 ** (- ICRIT). By default the criterion is set to 1.0D-6.
"SCHMIDT" RSCHM ISCHM
Sets the convergence criterion for the schmidt orthogonormalisation procedure. Here RSCHM is a value and ISCHM is an integer, the convergence criterion is set to SCRIT = RSCHM * 10 ** (- ISCHM). By default the criterion is set to 1.0D-7. By default the Schmidt orthonormalisation is used.
"QR" RQR IQR
Sets the convergence criterion for the QR orthogonormalisation procedure. The QR orthonormalisation procedure is an more accurate alternative to the Schmidt orthonormalisation (although it is called QR it is not certain that it really is a QR). Basically the overlap matrix is diagonalized to find the transformation to orthogonal vectors, the zero-eigenvalues are removed to eliminate linear dependencies. Although this procedure is more accurate that modified Gramm-Schmidt it is also more expensive. Here RQR is a value and IQR is an integer, the convergence criterion is set to SCRIT = RQR * 10 ** (- IQR). By default the criterion is set to 1.0D-7. If this directive is not specified the Schmidt orthonormalisation is used.
"LEVEL" RLEVEL1 [ ICYC RLEVEL2 ]
This subdirective sets the level shifter for the linear system solver in the MP calculation. The first ICYC iterations level shifter RLEVEL1 will be used. After ICYC iterations level shifter RLEVEL2 will be used. ICYC may be set to any integer in the range from 1 to 9. By default RLEVEL1 is set to 0.0D0, ICYC is set to 0, and RLEVEL2 is set to 0.0D0.
"MAXCYC" MCYC
This subdirective sets the maximum number of iterations for the linear system solver in the MP calculation. By default MCYC is 50.
"FIGNORE" RIGNORE IIGNORE
This subdirective sets a threshold for the calculations of the FOCK-matrix elements. The threshold is calculated as MPIGNORE = RIGNORE * 10 ** (- IIGNORE). All matrix elements that are smaller in absolute value than MPIGNORE are ignored. By default MPIGNORE is 1.0D-8.
"FOCK" DUMPFILE IBLOCK ISECTION
This subdirective specifies the dumpfile, the number of the starting block on the dumpfile and the section number at which the FOCK-integrals should be stored. By default DUMPFILE is set to "ed3" and the values of IBLOCK and ISECTION are calculated by the program.
"NODOC"
This directive instructs the program to treat doubly occupied orbitals as virtual orbitals. This directive should be used for debugging purposes only.
"NODIAG"
This directive instructs the program to assume the external FOCK-integral-matrix to be non-diagonal. This directive should be used for debugging purposes only.
Because of the default settings the two input lines in the following example are equivalent
   Example:

     MP

     MP 2 MODEL 1 PRINT 1 CRIT 1.0 6 SCHMIDT 1.0 7 LEVEL 0.0 0 0.0 MAXCYC 50 FIGNORE 1.0 6

NOTE: The MP directive has a few side effects. Although these side effects are very reasonable you may want to get around them. The side effects are

MAXCYCLE set to zero in CI/CEPA.
The MP directive resets the maximum number of CI or CEPA cycles to zero. This ensures that only a MPPT calculation will be performed. If you want the program to continue with a CI or CEPA calculation after the MPPT calculation is completed you should type a MAXCYCLE directive after the MP directive.
Configuration printing is disabled.
The MP directive disables the printing of the configurations that are generated. As the MPPT part of the program use contracted functions these configurations have limited meaning. However to enable printing of the configurations type a PRCONF directive after the MP directive.

The CCI Directive

The CCI directive allows the user to perform internally contracted multi reference CI calculations. The syntax of the directive is

    "CCI" [ SUBDIR ] [ ... ]
The subdirectives may be any of the following
"PRINT" IPRINT
This subdirective allows the printing of additional information. In particular it switches on the printing of the contracted CI-vector. The integer value IPRINT determines the amount of extra information printed. More information is printed if the number is enlarged (up to a maximum of 2000). By default printing is off.
"NODOC"
This subdirective forces the program to behave as if all internal orbitals are active orbitals. This means the program believes that there are no doubly occupied orbitals. This option is meant for debugging purposes.

The CCEPA Directive

The CCEPA directive allows the user to perform internally contracted multi reference CEPA calculations. The syntax of the directive is

    "CCEPA" [ SUBDIR ] [ ... ]
The subdirectives may be any of the following
"SIN" / "NOSIN"
The strings SIN and NOSIN select and deselect the single excitation shift option respectively. The default is SIN.
"IT" ITCEPA
This subdirective indicates after what iteration the CEPA mode may start. The integer parameter ITCEPA is the iteration number after which the CEPA mode may be switched on. By default ITCEPA is set to 3.
"CRIT" FCRIT
This subdirective indicates that the CEPA mode should be invoked at a particular threshold determined by the TESTER in the diagonalisation phase of the CI calculation. The threshold FCRIT should be set to a floating point value. By default FCRIT is set to 0.01.
"PRINT" IPRINT
This subdirective allows the printing of additional information. In particular it switches on the printing of the contracted CI-vector. The integer value IPRINT determines the amount of extra information printed. More information is printed if the number is enlarged (up to a maximum of 2000). By default printing is off.
"MICRO" IMICRO FMICRO
This subdirective controls the micro iteration proces. The integer IMICRO is the maximum number of micro iteractions that may be performed each iteration. The micro iteration proces may terminate in less than IMICRO iterations if a treshold becomes less than the floating point number FMICRO. The default is MICRO 3 0.01d0.
"NODOC"
This subdirective forces the program to behave as if all internal orbitals are active orbitals. This means the program believes that there are no doubly occupied orbitals. This option is meant for debugging purposes.

The ENTER Directive
 
    This should be the  last  directive  presented,  and  consists  of  the
character  string  ENTER  or  FINISH  in  the first data field. The program
collates all the previous data  and  checks  it  for  obvious  errors,  and
commences the CI calculation.
 

The RESTORE Directive
 
    This  is  an  alternative  to  the ENTER directive described above, and
should be the last line presented. It  consists  of  the  character  string
RESTORE in the first data field.
 
    If  a  RESTORE  directive  is  used  then  ED7  must  be saved from the
preceeding job and then used in the RESTORE run, to  provide  a  source  of
trial CI vector.
 

The Program Output


The Core Usage Diagnostics

Near the of the direct-CI output at tabel with core usage diagnostics is printed. These diagnostics may be used to trim the core usage of the program for optimal performance. A typical example of a core usage diagnostics tabel is:

Each heading in the tabel defines a phase in the calculation. The amount in words following a heading gives the maximum total memory usage during that phase. In this example the maximum memory usage while performing the matrix-vector multiplication in "genz" is 1226 words.

Notes per heading:

sort
The amount of memory used in the sort phase should fit in the physical memory of the computer. If this amount doesn't fit the performance of your computer may be severly degraded due to extensive swapping.
genz
The amount of memory used in this phase may be reduced using the outstore directive.


Spin Functions


 
    It  may be necessary for the user to understand the nature and order of
spin functions associated with a  given  occupation  pattern.  The  program
makes  use  of  Yamanouchi-Kotani geneological spin functions, the coupling
order being such that higher indexed MOs are coupled before  lower  indexed
MOs. The ordering of the MOs is as defined with the ACTIVE directive of the
transformation program [3], or the REORDER directive  (see  above),  or  as
assigned by the program if the SYMDET directive (see above) was presented.
 
    Use  the  digits  0  and  1  to  denote  down  and  up  spin   coupling
respectively.  Proceeding  from  the  highest  to the lowest indexed singly
occupied MO, write down the digitized representation of the  possible  spin
functions,  the  digits  being  written  from  left to right. The resultant
binary number defines the lexical ordering  of  the  members  of  the  spin
canonical set, the higher the number, the higher the lexical index.
 
    example:
 
    Consider  5 doubly occupied MOs coupled to a doublet. The possible spin
functions in digitized representation are, in order of  increasing  lexical
index:
 
        10101   -   Spin function 1
        10110   -   Spin function 2
        11001   -   Spin function 3
        11010   -   Spin function 4
        11100   -   Spin function 5
 
 
 

Error Monitoring


 
    A brief explanation of the possible ATMOL error codes is given below:
 
  Error Code   Explanation
  __________   ___________
 
          16   Directive unknown.
          20   Occupation number in CONF directive should be 0,1, or 2.
          42   File name in ONELEC or FFILE directive not known.
          50   Invalid parameter in WIDTH pre-directive.
          61   Index block of DUMPFILE not in correct format.
          62   ATMOL block with invalid checksum has been read,
               or input/output error on ATMOL file. If the
               latter, a finite VSOS error code will be given
               whose explanation will be found in [7].
          63   A DUMPFILE Section number outside the allowed range of
               1 to 190 has been specified.
          64   The section used to hold the transformed 1-electron
               integrals on the DUMPFILE is not defined. Check
               that the transformation program ran to completion.
          65   A DUMPFILE Section is of the wrong TYPE.
          67   Illegal search of an ATMOL file.
          68   Illegal character found in F-format data field.
          69   Illegal character found in I-format data field.
          71   The program has attempted to expand the DUMPFILE
               beyond its maximum size. This may occur when NOs
               are written to the DUMPFILE.
          72   An attempt has been made to overwrite a section on
               the DUMPFILE with a section of greater length. This
               may occur when NOs are written to the DUMPFILE.
         213   SYMDET unable to determine point group.
         444   The user has attempted to use ED7 or MT7 as
               DUMPFILE or FINAL MAINFILE.
         446   Illegal parameter in the REORDER directive.
         447   Same parameter twice in REORDER directive.
         448   Invalid number of MO labels in REORDER directive.
               There should be NINT+NEXT MO labels.
         666   End of file condition detected on FORTRAN
               stream 5. The program expects more data.
         771   The sum of the NIRO or NERO parameters in the
               SYMMETRY directive do not equal the NINT or NEXT
               parameters of the CNTRL directive respectively.
         772   A SYMMETRY directive appears after a SYMDET directive.
         773   A SYMDET directive appears after a SYMMETRY directive.
         774   The SYMMETRY directive has been presented twice.
         777   The SCREEN directive can find no reference
               configurations of the required symmetry.
         778   Invalid value for NSPIN in the SPIN directive. NSPIN
               should be odd or even as NELEC is even or odd respectively.
         999   Insufficient main memory for the program to continue.
        1232   Invalid number of electrons in a reference CSF.
        1410   The wavefunction generated by the TRIAL directive cannot
               be normalized. Probably all CCSF parameters are zero.
        1411   Invalid ICSF parameter in TRIAL directive.
        1412   Too many parameters in TRIAL directive. The maximum
               number of CSFs that can be included is 20.
        1505   TPOINT parameter in the SYMMETRY directive is unknown.
        1516   A CSF with more than 16 singly occupied MOs
               has been detected in the CI list.
        1517   Too many spin functions associated with a given occupation
               pattern in a CSF. The maximum is 50, although a special
               version of the program is available capable of handling
               spin canonical sets of dimension up to 130.
        1631   The value of NINT in the CNTRL directive is invalid.
               It should be greater than 0 and less than 63.
        1632   The sum of the NINT and NEXT parameters of the CNTRL
               directive is invalid. Should be greater than 0 and less
               than 201. This diagnostic may be produced if CNTRL is not
               presented first.
        1633   Illegal value for NELEC parameter in the CNTRL directive.
               Should be greater than 0 and less than or equal to NINT*2.
        1711   Illegal CSFTYPE parameter in RESTRICT directive.
        1712   Too many restrictions imposed by the the RESTRICT
               directive. The maximum number is 10.
        1713   Invalid MO label in RESTRICT directive. Should be
               greater than 0 and less than or equal to NINT.
        1888   No CSFs in final CI list. This may be because a RESTRICT
               directive prevents the construction of any CSFs.
        1903   Non-empty orbitals encountered while building reference
               configuration in CASGEN.
        1904   Number of electrons too small to doubly occupy all internal
               orbitals in CASGEN.
        2210   REFGEN directive appears before the first CONF directive.
        2211   Invalid annihilator or creator label in REFGEN directive.
               Should be greater than 0 and less than or equal to NINT.
        3333   AFN not recognized in the FILE pre-directive.
        3801   Conditions for running CEPA not acceptable. There
               should be only one closed-shell reference CSF, with
               a maximum number of internal MOs of 15.
        3810   Parameter on CEPA directive unknown.
        3811   The CASGEN directive has been used more than 3 times.
               However, 3 times is the maximum.
 
 
 

Specimen Jobs


 
    The following examples do not illustrate all the features of  Direct-CI
program, only a guide is intended.
 
    Specimen Job 1:
 
    This  example  illustrates  a  CI calculation on the H2O monomer, where
maximum use is made  of  the  program  defaults.  The  transformed  1-  and
2-electron  integrals  were  taken  from  the  H2O monomer example shown as
specimen job 1 of [3]. A single root closed shell CI calculation is  shown,
such  that  the internal MO space consists of the occupied Hartree-Fock MOs
(not including the oxygen  1s  inner  shell  MO  and  it's  associated  two
electrons,  which  have  been  factored from the CI problem with the FROZEN
directive of the transformation program [3]). The external  space  consists
of  all  the  Hartree-Fock  virtual  MOs. Automatic MO symmetry analysis is
invoked by means of the SYMDET directive. The default diagonalization  mode
is EMIN, so the program will seek out the ground state.
 
     /*JOB JOBNAME,ACCOUNT,ST=(C20,LP=1,WS=400),PW=PASSWORD,TI=9,C=B
     REQUEST,SORT.
     REQUEST,PSORT.
     REQUEST,ED7,RT=U.
     ATTACH,ED3V,ED6V,ACC=RW.
     PATTACH,ATMOL.
     DIRECT.
     ####S
     LPAGE 1
     FILE ED3 ED3V ED6 ED6V
     CNTRL 8 4 20
     TITLE
     H2O DEFAULT EXAMPLE
     SYMDET
     ENTER
     ####S
 
 
    Specimen Job 2:
 
    As  in  the  previous  example, except that explicit use is made of the
directives, with parameters  corresponding  to  the  program  defaults.  MO
symmetry assignment is by means of the SYMMETRY and REORDER directives.
 
     /*JOB JOBNAME,ACCOUNT,ST=(C20,LP=1,WS=400),PW=PASSWORD,TI=9,C=B
     REQUEST,PSORT.
     REQUEST,SORT.
     REQUEST,ED7,RT=U.
     ATTACH,ED3V,ED6V,ACC=RW.
     PATTACH,ATMOL.
     DIRECT.
     ####S
     LPAGE 1
     FILE ED3 ED3V ED6 ED6V
     CNTRL 8 4 20
     TITLE
     H2O    WITH ALL DIRECTIVES EXPLICITLY STATED
     THRESH 3E-4
     MAXCYC 50
     SHIFT 0.0
     EMIN 50
     TRIAL
     1 1.0
     VPRINT 100 1E-7
     SPIN SINGLET
     ONELEC ED3 1
     SYMMETRY C2V A1
     2 9
     0 2
     1 3
     1 6
     PSORT 12
     SORT 12
     REORDER
     1 3 4 2
     5 8 10 12 14 16 21 22 24 13 20 7 15 19 6 9 11 17 18 23
     EXCIT OCTAL 7 3 1
     CONF
     2 2 2 2
     MAXCYC 50
     ENTER
     ####S
 
 
    Specimen Job 3:
 
    This  example is based on the H2O dimer. User attention is drawn to the
specific routing of the large PSORT, SORT and ED7 data sets to  PACK01  and
PACK04,  which  are  the  scratch  discs on the UMRCC Cyber-205 system. The
transformed 1- and 2-electron integrals  were  taken  from  the  H2O  dimer
example  shown  as  specimen  job  2  in [3]. There are 8 and 72 MOs in the
internal and external spaces respectively. Note that 4 electrons  from  the
two  oxygen  1s  MOs have been factored from the CI problem with the FROZEN
directive of the transformation program  [3].  MO  symmetry  assignment  is
through the SYMMETRY and REORDER directives.
 
     /*JOB JOBNAME,ACCOUNT,ST=(C20,LP=6,WS=900),PW=PASSWORD,TI=320,C=C
     REQUEST,SORT,PACK=PACK04.
     REQUEST,PSORT,PACK=PACK04.
     REQUEST,ED7,PACK=PACK01,RT=U.
     ATTACH,DIMED3,DIMED6,ACC=RW.
     PATTACH,ATMOL.
     DIRECT.
     ####S
     LPAGE 6
     FILE ED6 DIMED6 ED3 DIMED3
     TITLE
     (H2O)2 1 ROOT  EXTERNAL:72 ORBITALS:PSORT:24:SORT:24
     CNTRL 16 8 72
     PSORT 24
     SORT 24
     VMIN 40
     SHIFT  0.10
     REORDER
     1 2 4 5 6 7
     3 8
     9 10 12 13 15 16 17 19 20 22 23 25 27 28 31 32 34 35 36 38 39
     40 43 44 46 47 48 50 52 53 54 59 61 62 63 64 65 67 68 69 70 73
     74 76 77 78 80
     11 14 18 21 24 26 29 30 33 37 41 42 45 49 51 55 56 57 58 60 66
     71 72 75 79
     EXCIT OCTAL 7 3 1
     CONF
     2 2 2 2 2 2 2 2
     MAXCYC 10
     SYMMETRY CS A'
     6 47
     2 25
     SPIN SINGLET
     ENTER
     ####S
 
 
 

References


[1] V.R. Saunders and J.H. van Lenthe, Mol. Phys., 48, 923, (1983).
[2] D.Moncrieff and V.R. Saunders, ATMOL-Introductory Notes.
[3] D.Moncrieff and V.R. Saunders, ATMOL-Transformation Program.
[4] E.R. Davidson, J. Comp. Phys., 17, 87, (1975); J. Weber, R. Lacroix and G. Wanner, Computers and Chemistry, 4, 55, (1980).
[5] W. Butscher and W.E. Kammer, J. Comp. Phys., 20, 313, (1976).
[6] C. Zirz and R. Ahlrichs, in 'Electron Correlation: Proceedings of the Daresbury Study Weekend', eds. M.F. Guest and S. Wilson, (Daresbury Laboratory Report DL/SCI/R14), 83, (1980).
[7] CDC VSOS Manual, Form 60459410, Control Data Corporation; VSOS Reference Manual, NAT 208, University of Manchester Regional Computer Centre, (1985).
[8] P.J.A. Ruttink, J.H. van Lenthe, R. Zwaans, and G.C. Groenenboom, J. Chem. Phys., 94, 11, 1991
[9] "A Space-Saving Modification of Davidson's Eigenvector Algorithm", Johan H. van Lenthe, Peter Pulay, J. Comput. Chem., 11, 1164-1168, (1990)