 Documentation for DENPROP  - The Density Matrix and Properties Code

 Charles J Gillan, Dec 1993 
 Lesley Morgan, Nov 1997
 UKRmol+ developers

 Contents:

   1.   Introduction 
        What does DENPROP do.
   2(a) DASD data needed before running DENPROP 
        Summary of the components of a CI wavefunction
   2(b) Scratch space used by DENPROP
   2(c) Output datasets
   2(d) Namelist cards, &INPUT, controlling the run
   3.   Example card decks containing JCL and input data
 
 1. Introduction
 ---------------

 This manual describes the user interface to the code DENPROP whose purpose
 is to calculate density matrices and wavefunction properties. In R-matrix
 calculations the computed properties for pairs of wavefunctions may be used
 to build the asymptotic potential or to evaluate photo-ionization cross
 sections. 

 For a useful background information see the book 

     Methods of Molecular Quantum Mechanics

     by Brian Sutcliffe and Roy McWeeny 

 in particular the chapter on density matrices.

 Terms Used
 ----------

 A pair of wavefunctions may be combined to generate a transition density
 matrix. Multiplication of this matrix with property integrals matrices
 yields transition properties or transition moments as they are sometimes
 known. One well known transition property is the dipole because it arises
 in photo-ionization studies.

 A single wavefunction may be combined with itself in a similar fashion to
 generate a density matrix which gives wavefunction properties or moments
 when that matrix is multiplied by property integrals. The density matrix
 is also a representation of the electronic charge density in the molecule;
 it may be used to generate pseudo-natural orbitals for better CI convergence.

 Restrictions in DENPROP
 -----------------------
 
 The major restriction in DENPROP are as follows:
 
  All wavefunctions for any one molecular system in any one
  physical approximation must be built from combinations of
  molecular orbitals belonging to the same common set of orbitals.

  In summary - all target states must be be expanded in the same orbital
  set. This means that state dependent natural orbitals cannot be used !
 
 2(a). Disk Files Needed Before Running DENPROP
 -------------------------------------------

 In order to understand how to prepare for a DENPROP run it is necessary
 to know the 'anatomy' and 'morphology' of a CI wavefunction. This is 
 briefly summarized in the next paragraph.
 
 Configuration interaction (CI) wavefunctions are composed of CSF expansions
 which are defined by 

       (i)  CI eigenvector coefficients associated with

      (ii)  Configuration State Functions each of which consists of
            linear combinations space and symmetry adapted Slater
            determinants which are composed of

     (iii)  antisymmetric products of molecular orbitals which are expanded
            in terms of 

      (iv)  linear combinations of atom centered basis functions. These basis
            functions can be Slater, Gaussian or numerical type. 
     
 In order to run DENPROP one must first run a CI calculation which involves
 definition of (iv) followed by computation of (iii), (ii) and (i). Only then
 can one compute density matrices and properties with DENPROP.
 
 Integrals
 ---------
 
     A file of molecular property integrals between all of the orbitals in the
  common set is required in order to calculate moments from the density matrix.
 
  Wavefunctions
  -------------
 
     For each wavefunction symmetry, ie. CSF expansion, it is necessary to have
  the following two files:
 
  a) The sorted symbolic codes for the hamiltonian matrix elements
     that are output by the program CONGEN on unit NFTA. It is on this
     dataset that the proper spatial and symmetry adapted Slater
     determinant expansions are located and read by DENPROP.
 
  b) The CI vectors generated by the diagonalization program SCATCI.
 
 Note that for each a) there are, in general, many CI vectors because the 
 Hamiltonian has many roots.

 While the files in a) are all sequential and therefore there is one for each
 symmetry, it is generally only necessary to have one file of CI vectors.
 The CI program permits one to stack various sets of vectors into one file.
 The author for example stores the ground state and pseudo state vectors into
 one file when doing polarized pseudo state calculations. The moments code can
 cope with the situation where the CI vectors are in different files, however
 it saves buffer space if only one CI file is used.
 
 2(b). Scratch Space Requirements
 --------------------------------
 
     The amount of scratch file space usage has been kept to a minimum. 
     However, scratch files are required as follows,
 
     a) For the storage of the moment expressions as they are calculated
 
     b) For the storage of the sorted moment expressions.
 
     c) A direct access file for the sorting procedure
  
 2(c). Output
 ------------
 
     The code generates two or three output files.
 
     a) A line printer listing
 
     b) A file of transition moments which feeds directly into the
        external region codes.
 
     c) (Optionally) a file of target properties which feeds directly into
         the external region codes.
  
 2(d). The Input Data
 --------------------
 
    The code is driven by a single namelist &INPUT which contains all data
 for the run.
 
 The format used to describe variables is

       (Name, Type, Dimension, Default, Limits, ! description)
 

     &INPUT
 
       GROUNDEN  R   1           0.0     [:]
         ! energy of the ground electronic state of the target at the 
           equilibrium geometry in Hartree. Only necessary if PLOTFLAG=1. 
           If set to zero, absolute energies are saved in fort.45 
           (see below).

       IDIAG  I       1           0     [0|1]
         ! If IDIAG=1 only diagonal density matrices are calculated.

       IPLOTFG  I    1       0          [:] 
         ! Print flag. If =1, then a file (fort.45) containing the target 
           energies relative to the ground state at equilibrium geometry 
           in a format adequate for plotting is produced. (Data is not in
           energy order, but in the order congen is run).

       IPOL   I      1            0      [:]
         ! Controls calculation of dipole polarizabilities from moments
           stored on unit NFTMT
           IPOL = 0 do not calculate;
           IPOL > 0 calculate at end of run;
           IPOL < 0 run to only calculate polarizabilities (moments must
                    already exist on unit NFTMT).
       IPROP  I       1           1     [0|1]
         ! Switch on calculation of properties. IPROP=0 terminates run
           after calculation of density matrices.
       
       IQDFG    I    1       0          [:] 
         !Print flag. If =1, then a file with ordered target energies is 
          produced. These data may be used for complex quantum defect 
          calculations.

       ISW    I       1           0     [0|1]
         ! Diagonal moments switch:
           ISW = 0 Include nuclear contribution;
           ISW = 1 Electronic contribution only.

       IWRITE I       1           6      [1:]
         ! Logical unit number for the line printer.

       ksym: 
             
           ! an integer that enables denprop to distinguish between point 
	     groups with the same number of IRs (irreducible representation)
             The values are:
             D2h ksym=1;
             C2v ksym=1;
             C2h ksym=2;          
             D2  ksym=3;
             Cs  ksym=1;
             C2  ksym=2;
             default value of ksym is 1.

       LCOF   I       1       10000      [1:]
         ! Box size, in words, for handling input from SORT.
       LDAR   I       1         620      [1:]
         ! Length in words of the direct access records in file NFDA.
       LNGTH  I       1        4095      [1:]
         ! Length of buffer, in words, for the diagonal moment expressions.
       LENGTH I       1         819      [1:]
         ! Length of buffer, in words, for the off-diagonal moment expressions.
       NAME   C      60        '   '
         ! Name for this run.
       NFDA   I       1          20      [1:]
         ! Unit for the direct access file used in sorting.
       NFTA   I       1          30      [1:]
         ! Unit for the scratch file which holds the sorted moment expressions.
       NFTD   I       1          21      [1:]
         ! Logical unit number for the scratch file which holds the initial
           moment expressions.
       NFTDL  I       1          60      [1:]
         ! Logical unit number for output of density matrices.
       NFTG   I       1          25      [1:]
         ! Logical unit for the CI vectors. 
       NFTINT I       1          17      [1:]
         ! Logical unit number for the file of molecular property integrals.
       NFTSOR   I     NTGT       NTGT*0  [1:]
         ! Logical unit numbers for the files of sorted HAMILTONIAN 
           expressions (output from CONGEN).
       NFTMT  I       1          24      [1:]
         ! Logical unit number for final target properties file.
       NFTMOM  I      1          61      [1:]
         ! Logical unit number for scratch target properties file.
       NMSET  I       1           1      [0:]
         ! Moments output set number on NFTMT (if 0 append to existing file).
       NMSET2 I       1           1      [0:]
         ! Moments output set number on NFTMOM (if 0 append to existing file).
       NPFLG  I      11        11*0      [0:3]
         ! Print as follows :-
           (1) Data read by namelist &input.
           (2) Data passed to diagonal element calculator.
           (3) i. Determinants used for the
                  evaluation of off-diagonal elements.
              ii. The orbital/spin-orbital table.
           (4) Calculated raw formulae.
           (5) Molecular property integrals read from the TRANS dumpfile.
           (6) Sorted formulae.
           (7) Density matrix for each pair of states.
           (8) Wavefunction data read from the CI file(s).
           (9) Computed moments.
           (10) Target property file as it is constructed.
           (11) Input data for polarizability calculation.
           In order to avoid printout always set the flag to zero. To have
           print out set the flag to some positive integer. If a flag controls
           only one print operation, then setting it to 1 would be sufficient.
           If a flag controls several print operations then setting it to 1
           obtains the first; setting it to 2 obtains both the first and
           second; 3 the first, second and third etc.
           WARNING : With the exception of NPFLG(1), the use of certain
           combinations of the other flags can results in an enormous amount of
           output. 
       NTGT   I       1           1      [0:]
         ! Number of CSF expansions used. This is the number of different
           SORT output files to be read. Usually there is one SORT output
           for each wavefunction symmetry.
       NTGTF  I    NTGT      NTGT*0      [:]
         !  Defines the set number, on unit NFTG where the CI vectors for
            this symmetry are to be found.
       NTGTL  I    NTGT      NTGT*0      [:]
         !  Defines the sequence number, within the set specified by NTGTF,
            of the last CI vector to be used            
       NTGTS  I    NTGT      NTGT*0      [:]
         !  Defines the sequence number, within the set specified by NTGTF,
            of the first CI vector to be used            
       UKRMOLP_INTS L 1 (.true.)
         !    This switch applies to UKRmol+ calculations. It is not effective for
              calculations using the non-Abelian point groups. If set to .true.  it
              indicates that the transformed integrals on unit NFTINT were 
              calculated using SCACTI_INTEGRALS.
       ZLAST  L       1     .false.      [:]
         ! When set to .true. identifies that this card deck is the last in
           the stack of &INPUT decks. This variable need not be set but it
           save CPU cycles if it is defined. An end of file error would be
           generated by the I/O handlers and processed by DENPROP in its
           absence. It is a sueful parameter when debugging a stack of
           &INPUT decks in stepwise fashion.
      &END
  
