Configuration generation program: CONGEN 
Documentation 9 April 96 Jonathan Tennyson, updates UKRmol+ developers.
Version to drive SCATCI.

CONGEN generates the necessary configurations for doing CI calculations.
It provides the necessary configuration file(s) required by SCATCI/MPI-SCATCI and 
DENPROP/CDENPROP. 

Test runs: (RMAT) H2CIPSG EXAMPLE (time=610 CPU S)
           (positron-H2 run with CI target and CI pseudo-states)
           (RMAT) H2CITARG EXAMPLE (quick)
           (CI target generation for the above example)

Input: General considerations

Input data to CONGEN is by NAMELISTs read from unit 5. The NAMELISTs are:
1. &STATE  Specification of symmetry of the CSFs to be generated, the reference 
configuration and other general parameters
2. &WFNGRP Specifies the CFS to be generated.


In setting up a CONGEN calculation the overall symmetry of all CSF's
(n-particle basis functions) must be specified.  This is done in the first
namelist, &STATE. A reference determinant is also given in this section
relative to which all CSF's will be stored.

The second namelist &WFNGRP is used to select CSF's which are to be included
in the N-particle basis.  The procedure followed in the selection process is
as follows:

1)  define a set of movable electrons
    This is done in the section entitled "Description of Reference
Distribution."

2)  define the set of orbitals into which the movable electrons are to be
distributed.
    This is done in the section on "Definition of Orbitals."

3)  place constraints on the CSF's generated
    Constraints can be placed upon which CSF's resulting from the
distributions given will be accepted.  Tests are made upon occupation
relative to some reference occupancies.
     The description of constraints is given in the section "Constraints
upon CSF's."

Several &WFNGRP decks can be used for a single run.  This allows the user to build 
CSF's according to different 'rules'.


NAMELIST DESCRIPTION

The information in the previous &WFNGRP is used as default for the following
&WFNGRP except for QNTAR, NELECP, GNAME, and DEFLTC.

Fixed dimensions are specified by PARAMETER
  NTGTMX=50 maximum number of target electronic symmetries

In defining the modified input the following format is used
       (Name, Type, Dimension, Default, Limits, ! description)
        Unless specified otherwise, the default value applies to all elements
        of array variables.

NAMELIST /STATE/

Control flag

ISCAT I    1    0   [0,1]
!  = 0 provide input for SPEEDY (no longer used)
   = 1 provide input for SCATCI/DENPROP
   = 2 provide input for SCATCI/DENPROP including information for phase
       correcting target CI wavefunctions 
       (QNTAR must be set for target plus continuum WFNGRPs with this option).

This section gives the symmetry and multiplicity of all CSF's to be generated.

SYMTYP  I   1          -1     [0,2]
      ! gives the symmetry designation for the nuclear framework.
        = 0 for Cinfv (not available in UKRmol+)
        = 1 for Dinfh (not available in UKRmol+)
        = 2 for D2h or a subgroup of D2h

QNTOT   I    3  -2   [1:],[0:],[-1,+1]

QNTOT(1) is the spin multiplicity 2S + 1.

QNTOT(2) is the spatial symmetry quantum number.  For C inf v and D inf h
the value is selected as follows:
Sigma    = 0
Pi       = 1
Delta    = 2
etc
For molecules with D2h symmetry or the symmetry of one of its subgroups,
numerical values for the symmetry (irreducible representation)  are assigned 
in the order discussed in the CPC paper.  The first irreducible representation 
is given the value zero.

QNTOT (3) gives the +- character for the state for C inf v and D inf h
= +1  if the state is Sigma +
= -1  if the state is Sigma -
=  0  all other cases

ISZ     I    1   QNTOT(1)  [1:]
    != 2Sz + 1

GUTOT   I    1    0 [-1,+1]

!   is used for Dinfh only.  It gives the total G (gerade) or U (ungerade)
symmetry.
      =  1 G (gerade)
      = -1 U(ungerade)

NTGSYM  I    1  MXTARG [0,MXTARG]
!   Maximun number of target state symmetries.
    Needed if ISCAT=2 and QNTAR is used to constrain the coupling of L**2 CSFs.

IPOSIT   I   1          0    [-2,+2]
! Exotic particle flag:
       = 0 for electron only run
       = +/-1 for positively charged exotic particle (eg a positron)
       = +/-2 for negatively charged exotic particle (eg a muon)
       > 0 run with separate electronic and exotic particle
           L**2 orbitals (i.e. IPOSIT>0 used in MOS)
       < 0 run with identical electronic and exotic particle
           L**2 orbitals (i.e. IPOSIT=0 used in MOS)

NELECT  I    1    0   [1:]
!   total number of electrons

NOB    I   NSYM    0     [0:]   (total must be less than 256)
      ! Total number of orbitals for each symmetry.
        If IPOSIT > = 0, same as NOB defined in MOS/SCATCI_INTEGRALS
        If IPOSIT < 0,   NOB(I) = 2*NOB(I) (as in MOS/SCATCI_INTEGRALS) 
        NOTE: this means that for positron runs the electrons and positron
        are treated as occupying DIFFERENT orbitals even when (for IPOSIT=-1)
        these orbitals are actually the same. This rule must be observed when
        setting PQN in NAMELIST /WFNGRP/.

NOB0    I   NSYM  0     [0:]
      ! Number of target orbitals for each symmetry.
        Required if IPOSIT=+/-1 and/or SCATCI run
        For SCATCI (needed when IDIAG > 1 and/or NFTG=0 or NCORB=0):
        NOB0 defines the number of orbitals of each symmetry
        used in the (CI) target representations. Target virtual orbitals
        included in the scattering calculation only should not be counted.
        NOB0 will thus usually be less than the number of target orbitals
        defined in MOS.
        For IPOSIT=+/-1:
        Number of electronic L**2 orbitals for each symmetry
        (= total number of L**2 orbitals defined in MOS if IPOSIT < 0)
NOBE    I   NSYM  0     [0:]
      ! Needed only if  IPOSIT < 0
      !  Total number of orbitals for each symmetry (i.e. same as NOB when
      ! IPOSIT > = 0
      
NOBP    I   NSYM  0     [0:]
      ! Needed only if  IPOSIT < 0
      !  Total number of orbitals for each symmetry (i.e. same as NOB when
      ! IPOSIT > = 0
      
NOBV    I   NSYM  0     [0:]
      ! Currently not used. Needed only if  IPOSIT < 0 and 'extra virutals' are 
      ! used. NOB0 + number of additional target orbitals ('extra virtuals')  
      ! used in building L**2 functions (needs confirmation when implemented).
      
NBMX    I    1   2000000 [1:]
      ! Number of Mwords memory allocated for CSF generation.
        Default usually sufficient.

Reference determinant

NREFO   I    1    0   [1,150]
! number of reference quintets given in REFORB needed to describe the
reference determinant.  At least one reference quintet is given for each
symmetry which has occupied orbitals.

REFORB   I  (5,NREFO)  -2
! series of NREFO quintets needed to describe the reference
determinant.  The entries in the quintets have the following meaning:
REFORB (1,NREFO) =  M(symmetry quantum number) value of the group of orbitals
                    to be described by this quintet.
       (2,NREFO) =  the serial number of first orbital of symmetry M to be
                    filled for the group of orbitals described in this quintet.
       (3,NREFO) =  the number of electrons to be put into this shell filling
                    each orbital to its maximum occupation if possible.
       (4,NREFO) =  entries (4) and (5) are used to specify the symmetry of the
       (5,NREFO)    open shells.  For closed shells set both entries to zero.
For nondegenerate orbitals the spin of the singly occupied orbitals is given by:
REFORB(4,NREFO)   = 0 alpha
                  = 1 beta
and
REFORB (5,NREFO) = 0.
For degenerate orbitals (never the case in UKRmol+) with two electrons or less the i
entries correspond to the occupied orbitals:
REFORB(4,NREFO) is assigned the value according to the following chart for
the first electron in the open occupied orbital.  REFORB(5,NREFO) is
assigned the corresponding value for the second electron.  If the orbital is
singly occupied, this last entry is set to zero.
= 0 lambda + alpha
= 1 lambda + beta
= 2 lambda - alpha
= 3 lambda - beta
For more than two electrons in a degenerate orbital, the specification of
the hole is given by the above rules.
Example:     Pi_+alpha Pi_-alpha  (4) = 0,     (5) = 2
             Theta_alpha          (4) = 0,     (5) = 0
             Pi_+alpha Pi_+beta Pi_-beta     (4) = 2,      (5) = 0

REFGU   I    NREFO    -2 [-1,+1]
! g or u symmetry for the M value of each reference quintet.  Used
only for D inf h molecules.
= -1 u(ungerade)
=  1 g(gerade)

Fortran Data Sets

MEGUL    I  1  13 [1:99]
! Data set to be passed to SPEEDY/SCATCI/DENPROP which contains the CSF's.

MEGU     I  1  14 [1:99]
! Data set which contains the namelist input to be passed to SPEEDY.
 (Not used as not needed if  SCATCI=1)

Print Flags

NPMULT    I  1  0 [0,1]
! Print flag for the D2h multiplication table.
= 0 do not print the multiplication table
= 1 print the multiplication table

CONFPF   I  1   1 [1,40]
! print flag for the amount of print given of configurations and prototypes.
=  1  Minimum print; number of states for each prototype
= 10  PQN (see description of PQN in next namelist) for each configuration
      plus the  above
= 20  PQN for each state plus the above
= 30  PQN for each state and determinant for each prototype plus the above
= 40  every configuration is given in terms of determinants plus the above

LPP      I   1   60      [1:60]
! Length of line printer page. Used to determine where to put page banner.

SNAME    C*80  1    '       '
! Name given to run

Other parameters

CDIMX    I   1  400
NDIMX    I   1 4000
NODIMX   I   1  100
! Dimension controls: defaults normally sufficient

NNDEL    I   1   0
! NNDEL > 0 read CSFs directly from input stream.


Namelist data which is passed to SPEEDY (or SCATCI)

NFTO     I  1  15 [1:99]
! Fortran data set number for output tape of SPEEDY.

NPFLG   I  6 0  [0,3]
!  print flags for SPEEDY (SCATCI)
       (1)  = 1  print input CSF's in packed form
            = 0  no print of CSF's
       (2)  = 1  print open orbitals
            = 0  no print of open orbitals
       (3)  = 1  print output CSF's in packed form
            = 0  no print of output CSF's
       (4)  = 1  print diagonal density expression, off diagonal density
             expression, and off diagonal energy expression
            = 0  no print of these items
       (5)  = 1  ISCAT=2: print target phases calculated when
                 ISCAT=0: project the wavefunction, only do not compute the
                 energy expression.  Useful only in checking input to SPEEDY.
            = 0  no print / checking. For ISCAT = 0 usual calculation.
       (6)  = 1  print D2h multiplication table and integral pointers/boxes
            = 0  do not print 

THRES    R   1   1.0E-10  [0.0:]
! Threshold for storing coefficients of matrix elements that contribute to
HIJ.  If coefficient <THRES, it is not stored.

LCDT     I    1   500    [1:]
LNDT     I    1   5000   [1:]
! LCDT and LNDT control assignment of temporary storage.  Defaults permit the
maximum number of determinants in any input CSF to be 500 (LCDT) and the
maximum number of integers required to describe the determinants in any CSF
to be 5000 (LNDT).

LCDO     I    1   500    [1:]
LNDO     I    1   5000   [1:]
! LCDO and LNDO control assignment of temporary storage.  Defaults permit the
maximum number of determinants in any output CSF to be 200 (LCDO) and the
maximum number of integers required to describe the determinants in any CSF
to be 2000 (LNDO).

BYPROJ  I   1          1      [-1,0,+1]
      ! = 1 do wavefunction projection in CONGEN
        = 0 do wavefunction projection in SPEEDY
        = -1 don't do wavefunction projection (probably gives wrong answers)
      (note: there is no option to project wavefunctions in SCATCI and
             wavefunctions to be input to DENPROP must be already projected).

NRERUN  I    1    0   [?:?]
! Restart flag for SPEEDY (no longer used)

LTRI    i    1   300

IDIAG   I    1   0 (for SPEEDY) 1 (for SCATCI) [0:3]
! Matrix element evaluation flag passed to SPEEDY or SCATCI:
   = 0  Evaluate matrix elements as difference from first element
        (Do not use this option with SCATCI option IEXPC=1)
   = 1  Evaluate all matrix elements in full
   = 2  Do not evaluate pure target integrals
        (and with automatic target generation, evaluate target
         matrix elements as difference from first element)
   = 3  Do not evaluate pure target integrals

  IDIAG = 2 is STRONGLY recommended with SCATCI option ICITG=1
  but must NOT be used with SPEEDY or for target only calculations.
  NOB0 must be set for options IDIAG=2 or 3.
  Note that IDIAG can be (re)set in using namelist &INPUT in SCATCI.


QMOLN   L   .FALSE.   [.TRUE. or .FALSE.]
        .TRUE.   Write use friendly message regarding no. of generated
                 CSFs to fort.400
        .FALSE.  Do not write any Quantemol-N files



NAMELIST /WFNGRP/ Description of Reference Distribution

A reference distribution will be given which describes the number and type of
movable electrons.  Constraints upon this distribution can then be applied.
these constraints will be described in one of the following sections.

NELECG  I    1    0   [1:]
!  The total number of electrons which are movable.

NREFOG   I    1    0   [1:]
! the number of quintets given in REFORG needed to describe the movable
  electrons.

REFORG   I  (5,NEFO)  -2
! series of quintets which describe the movable electrons in the
  reference determinant.
 (1,NREFOG)  =  M symmetry quantum number of electrons in reference determinant
                of the shell which contains the electron which can be moved.
 (2,NREFOG)  =  the serial number of the first spin orbital of symmetry M
                which can be moved.
 (3,NREFOG)  =  the number of electrons in the shell
 (4,NREFOG)  =  the fourth and fifth entries specify
 (5,NREFOG)  =  the symmetry of the open shells.  The entries are the same
                as for REFORB(4,NREFO) and REFORB(5,NREFO).
 Example; REFORG = 0,2,2,0,0 1,2,1,0,0 2,2,1,0,0

REFGUG  I    NREFGO    -2 [-1,+1]
! Used for D inf h to give the g or u symmetry for the M values of each
 reference quintet.
= -1 u(ungerade)
=  1 g(gerade)

Definition of orbitals into which movable electrons can be distributed

The orbitals used for the occupation of movable electrons can be divided into a
maximum of five sets.  Division into sets allows the user to specify
internal and external orbitals and facilitates the expression of excitations
which are possible from the reference distributions.

NDPROD  I    1    0   [1:]
The number of sets into which the orbitals, which are used for the
distribution of movable electrons, are to be divided.

NELECP  I    NDPROD  -1  [1:]
The number of electrons which are to be distributed in each orbital set used for
movable electrons.

NSHLP   I    NDPROD  0   [1:75]
! The number of PQN triplets needed to describe each set of orbitals.  At
 least one triplet is given for each symmetry in each set.
 Example 1; NSHLP = 4

PQN    I    (3,NSHLP)
!  Series of triplets needed to describe each set of orbitals.  At lease one
 triplet is needed for each symmetry in each set of orbitals.  Each triplet
 will describe what will be referred to as a shell.  The triplets can have
 two meanings which follow:
1)  PQN(1,NSHLP) = 0 THEN PQN(2,NSHLP), and PQN(3,NSHLP) represent the
serial numbers of the initial and final orbitals in the set for that
symmetry.  (Serial numbers for orbitals are sequentially numbered starting
with 1 in each symmetry at the 1st orbital of that symmetry.)
2)  PQN(1,NSHLP) = the serial number of the orbital in the set.  The second
and third entries are set equal to zero.

MSHL   I    NSHLP       [0:]
!  For each PQN triplet give the symmetry quantum number of the set of orbitals
 described.  The symmetry quantum numbers are the same as given in QNTOT.

GUSHL  I    NSHLP  -2  [-1,+1]
! Used only for D inf h.  Gives the g and u character of the orbitals
  described in each PQN.
= +1 g(gerade)
= -1 u(ungerade)

DEFLTC  I    1    0   [0:1]
! The user can specify the order of the intermediate couplings between shells
  in the array or use the default couplings given for CUP.
      = 1 user will specify couplings
      = 0 default values of CUP will be used.

CUP     I  (3,sum NSHLP - 1)  default and range explained below
! array which allows the user to specify intermediate couplings.
 First each shell is assigned a serial number in the order n which it was
 described in PQN. Suppose there were N shells, then the user would specify
 N-1 couplings.  One such coupling would have the following form:
    CUP = N_i,N_j,N+1,
 which means shell N_i is coupled to shell N_j to form a new intermediate
 shell N +1.
 The N +1 shell would then be coupled to another one of the N shells.

 The default coupling is simply that the first shell is coupled to the second
 to form an intermediate shell which is coupled to the third shell, etc.

NPCUPF  I    1    0   [1:]
! Print option which allows the user to specify if coupling information will
  be printed.
  = 0 do not print couplings
  = 1 print couplings

Constraints upon CSF's accepted

Constraints can be placed on the distributions described in the previous
sections. There are two kinds of constraints.  The first requires
replacements relative to a reference configuration for a given shell to be
to a given number and the second requires replacements to be greater than a
certain number.  The description of the reference occupation of the shells
used in the constraint tests are given in the array TCON which follows.
QNTAR is used regularly, all the other decks in this section are rarely used. 


QNTAR I     3     -1,0,0     [0:;0:;-1,+1]
      ! Controls the coupling of the first N-1 electrons as defined in the PQN
        groups to a state of total symmetry as specified by QNTAR. The
        entries are the same as QNTOT in NAMELIST /STATE/ except that if
        QNTAR(1)=-1 then there is no constraint on the coupling, i.e. QNTAR is
        ignored.
        If ISCAT=2, QNTAR must be set for all target states even if not
        needed for other reasons.

NTCON  I    1    0   [0:10]
! number of constraints to be given.  A maximum of 10 constraints possible.

NSHCON  I   NTCON  0
NSHCON gives the number of triplets required in TCON to describe the constraint.

TCON    I  (3,NSHCON(I),NTCON) default of each triplet is (-1,0,0,)
! For each constraint NSHCON(NTCON) triplets are given which describe the
  reference shells used to check the CSF against.
  This array is similar to PQN and controls constraints that
  may be included in selecting CSFs. It is incorrectly documented in the
  ALCHEMY manual. For each constraint NSHCON(NTCON) triplets are given
  which describe the reference shells used to check the CSF against.
  The triplets have the following meaning:
       (1) Symmetry quantum number,
           i.e For cinfv 0 = sigma, 1 = pi, 2 = delta, etc
               For Dinfh 0 = sigma g, 1 = sigma u, 2 = pi u, 3 = pi g, etc
       (2) Serial number of the first ORBITAL (not spin orbital - this mistake
           occurs in the manual for REFORG and REFORB) of symmetry M to be
           filled for the shell.
       (3) Number of electrons to be put into this shell. It appears that the
           number of electrons described by the constraints MUST equal NELECG.
           This is not made clear.
  Note that the array in the code is of fixed dimension (3,75,10) - care should 
  be taken to input the elements of this array correctly.

NRCON  I   NTCON  -1
!  The number of replacements or occupancies that can deviate from the reference
   occupancies given in TCON for each constraint.

TEST  I    NTCON  1
!  Test signals which of the two types of constraints will be applied.
= 1 then replacements which are  NRCON(NTCON) will be accepted
= 0 then replacements which greater than NRCON(NTCON) will be accepted
If NTCON is > 1 then there are the following three cases:
1)   All TEST entries are 1's.  The set of CSF's are the union of those from
     each constraint.
2)   All TEST entries are 0's.  The set of CSF's is the intersection of
     those from each constraint.
3)   A mixture of 1's and 0's for TEST entries.  The set of CSF's is the
     intersection of those which are the union of the 1's with the
     intersection of the 0's.



Miscellaneous

GNAME    C*80  1    '        '
! Name given to &WFNGRP deck


NOTES ON USAGE:

1. CI TARGET calculations:
As implemented in the SCATCI/CI modules, the contraction of the Hamiltonian for
CI targets makes assumptions about how the CSFs were generated in CONGEN. These
are:
a. ALL CSFs involving continuum functions must be before any purely L**2 CSFs.
b. CSFs should be generated in the following order (inner loop fastest):
   i. Loop over target states of different total symmetry
   ii. Loop over components of target state in the same order as on the target
       file (NFTG in CI)
   iii. Loop over M symmetry of the continuum orbitals
   iv. Loop over continuum orbitals in the same order for every value of loops
       ii and iii for a given value of loop i.
c. It is assumed that the coefficients for all target states of the same
   symmetry will be in one SET on file NFTG in CI/SCATCI.

2. The use of QNTAR to ensure coupling to the correct target state will be
   necessary for nearly all target CI and exotic particle scattering runs.
   It must be used whenever ISCAT=2 as it defines the target states for
   which phase corrections have to be computed.

3. Data input for SORT:
Namelist data can read into SORT but will not usually be required.
(Note some of record length and buffer size defaults have been changed).

