******************************************************************************
 
                                   DESCRIPTION
 
                                     OF THE
 
                       OHIO STATE RESTRICTED HARTREE-FOCK
                            SELF-CONSISTENT-FIELD AND
                         TWO-CONFIGURATION MCSCF PROGRAM
                                     (SCFPQ)
 
******************************************************************************
 
 
PROCEDURE NAME:  SCFPQ
 
DESCRIPTION:  This program uses symmetry-orbital integrals to calculate
              Restricted Hartree-Fock wavefunctions and energies
 
 
INPUT FILE:  SCFPQIN
 
PRINT OUTPUT FILE:  SCFPQLS
 
SUPERMATRIX INTEGRAL FILE:  PKINTS
 
MOLECULAR ORBITAL COEFFICIENT FILE (optional):  MOCOEF
 
See detailed file list below for additional files (all optional or scratch)
 
DOCUMENTATION:  Russell M. Pitzer
                Department of Chemistry              BITNET:
                The Ohio State University            TS0775 at OHSTVMA
                120 W. 18th Ave.
                Columbus, OH 43210
                USA
 
 
LAST REVISION:  11-Sep-91 (rls)
 
REFERENCES:  BISON System,
             A. C. Wahl, P. J. Bertoncini, K. Kaiser, and R. H. Land, Argonne
             Nat. Lab. Rep. ANL-7271 (1968); Int. J. Quantum Chem., Symp. 3,
             499 (1970)
 
             One-Hamiltonian Formulation, Level Shifting,
             H. L. Hsu, E. R. Davidson, and R. M. Pitzer, J. Chem. Phys. 65,
             609, (1976)
 
             Energy Expressions, Open-Shell Energy Coefficients,
             R. M. Pitzer, OSU-TCG Rep. No. 101
 
             DIIS extrapolation,
             P. Pulay, J. Comput. Chem. 3, 556 (1982).  M. J. M. Pepper,
             Ph. D. dissertation, Department of Chemistry, Ohio State
             University (1989)
 
DESCRIPTION:
 
     This program uses symmetry-orbital integrals from molecular-integral
programs to calculate restricted Hartree-Fock wavefunctions and energies,
using the Roothaan type of formulation.  The energy must be expressible in
terms of shell-averaged coulomb and exchange integrals.  Only one open-shell
density matrix may be used for each irrep.
 
     The program can provide input for computing energy gradients.
 
     If there is sufficient memory, the program will store the P and Q
supermatrices in main memory rather than on disk.  The memory allocation
actually needed is always printed in the output.  Two-configuration
calculations cannot yet be done with in-memory processing.
 
     The optional DIIS extrapolation method works by defining an error matrix
as (FDS-SDF), where F, D, and S are the Fock, density, and overlap matrices.
The error matrices are stored for up to eight iterations, and then the Fock
matrix is extrapolated using the set of linear coefficients which
correspondingly minimize the square of the error matrix.  The number of
iterations is usually reduced, but at some cost in increased time per
iteration.  The extrapolation starts only when the maximum magnitude of error
matrix elements is less than 0.1 of the total energy.
 
     For the two-configuration MCSCF case, both configuratioms must be of the
closed-shell type.  They must differ by a double replacement of an MO
belonging to one one-dimensional irrep by an MO belonging to a different
one-dimensional irrep.  It is also possible, under some conditions, to have
an open shell common to both configurations.
 
INPUT:
 
 LINE NO.    FORMAT     VARIABLES AND DESCRIPTION
 
     1        A80     Title Card     The suggested information is the electron
                                     configuration and state designation.  The
                                     title card from the integral file is also
                                     printed out, and it should contain
                                     molecule, basis set, and geometry
                                     information.
 
     2        24I4    IPRCT --       If greater than zero, then number of
                                     iterations between P matrix extrapolation.
                                     (at least 3).
                                     If less than zero, then DIIS extrapolation
                                     is used, and -IPRCT is equal to the number
                                     of error matrices saved.  (5 is usually
                                     sufficient; 8 is maximum; value is rarely
                                     critical).
 
                      ISCF --        10**(-ISCF) is the relative convergence
                                     required in both the one- and two-electron
                                     energies for termination of iterations.
 
                      I2CON --        0  restricted Hartree-Fock calculation
                                      2  two-configuration MCSCF calculation
                                         (see below)
 
                      INFLG --       Source of initial guess of MO
                                     coefficients.
                                     -1  generate by diagonalizing H matrix
                                      0  use simplified form described below
                                      5  read from input file
                                      8,9, etc. read from disk or tape with
                                                this unit no.
 
                      IVECT --       Amount of MO coefficient output.
                                     -1  none
                                      0  occupied and other designated MO
                                         coefficients upon convergence
                                      1  also prints these coefficients after
                                         every iteration.
 
                      IPUNCH --      Unit no. for writing MO coefficient file
                                     upon completion of run (formatted file).
                                      0         none
                                      8,9, etc. disk or tape.
 
                      IPRINT --      Printing of integral values.
                                      0  none
                                      1  S,H,P,Q,FC,FO matrices
                                      2  also T,V, core potential matrices
                                      3  also P,Q supermatrices
                                      4  also P,K/2 input supermatrices
 
                      IDEBUG --      Printing of additional iteration
                                     information.
                                      0  none
                                      1  MO coeffficients after
                                         orthogonalizations, density matrices
 
                      ISAVE --       Use of results from previous state treated
                                     in same run.  Must be 0 for first state.
                                      0  none
                                      1  use MO coefficients from previous
                                         state
                                      2  use MO coefficients and occupation
                                         numbers from previous state
 
                      ITMAX --       Maximum no. of iterations.  Default is 40.
 
                      ISTO --        10**(-ISTO) is the normalization threshold
                                     which trips error messages during Schmidt
                                     orthogonalization.  Default is 20.
 
                      MICMX --       No. of microiterations per iteration.
                                     This can only be applied with open-shell
                                     states since the same matrix-element
                                     formula is not used in all areas of the
                                     Fock matrix.  This option is rarely used.
                                      0         none
                                      1,2 etc.
 
                      IAUTO --        0  none
                                      1  orders the MOs by orbital energy each
                                         cycle
 
                      IDFIX --        0  damping factor variable
                                      1  damping factor fixed (recommended)
 
                      ITPREP --      Unit no. for storage of additional data
                                     needed if damping and extrapolation used
                                     (unformatted file).
                                      0          none
                                      8,9, etc.
 
                      ITCON --       Unit no. for reading of additional data
                                     for resumption of iterations using damping
                                     and extrapolation (unformatted file).
                                      0          none
                                      8,9, etc.
 
                      IALL --        If set to 1, converged vectors for each
                                     irrep are ordered by orbital energy and
                                     all vectors are written onto the MO
                                     coefficient file, irrespective of the
                                     NI(LA) values on card 4.  This is set to 1
                                     if the SCF vectors are going to be used
                                     for CI calculations.  If set to -1, the
                                     above applies and all vectors are expected
                                     in the input also.
                                     -1  all vectors in input and (ordered) in
                                         output
                                      0  vectors only as specified by NI(LA)
                                      1  all vectors (ordered) in output
 
                      IVO --         Do an improved virtual orbital (IVO)
                                     calculation.  For each irrep for which
                                     IVOs are desired, set one virtual-orbital
                                     occupation number to -1, and include the
                                     appropriate open-shell energy
                                     coefficients.
                                      0  none
                                      1  IVO calculation
 
                      IGRAD --       Unit no. for writing the SCF gradient
                                     input (formatted file).
                                      0          none
                                      8,9, etc.  disk or tape
 
                      IDMAT --       Unit no. for writing the closed-shell and
                                     open-shell Fock matrices for the SCF
                                     gradient.  Needed for open-shell cases.
                                     (unformatted file).
                                      0          none
                                      8,9, etc.  disk or tape
 
     3         A80    FMTA
       (if INFLG = 5                 Format for reading in initial MO
       and ISAVE = 0)                coefficients.  If coefficients read from a
                                     unit other than 5, FMTA is the first
                                     record of that file.
 
     4        20I4    NI(LA), LA = 1, LAU where LAU is the number of irreps
       (if ISAVE = 0)                No. of MOs for each irrep (irreps in the
                                     same order as in the integral program),
                                     for which initial MO coefficients will be
                                     in both input and output.  All occupied
                                     MOs must be included, and unoccupied MOs
                                     for excited states to be treated later are
                                     often also included.
 
For each irrep: (if NI(LA) GT 0 and ISAVE LT 2)
 
     5       40F2.0   AN(I), BN(I), I = 1, NI(LA)
                                     Occupation numbers of the NI(LA) MOs of
                                     this irrep.  For fractional occupancies,
                                     enter the numerator and denominator in
                                     AN(I) and BN(I), respectively.  For
                                     integer occupancies, enter the values in
                                     BN(I) and leave AN(I) blank.  For
                                     two-configuration MCSCF cases, enter 1 for
                                     the two MO's involved in the double
                                     replacement.
 
     6        20I4    IXTI(I), I = 1, NI(LA)
       (if INFLG = 0                 The index of the symmetry orbital (set)
        and ISAVE = 0)               expected to have the most important
                                     coefficient in the Ith MO.
 
     6        FMTA    FOR I = 1, NI(LA)
                      C((I-1)*IPU + IP), IP = 1, IPU where IPU = No. of
       (if INFLG = 5                     symmetry orbital (sets) for this irrep
        and ISAVE = 0)               MO coefficients for each of the NI(LA) MOs
                                     for this irrep.
 ______________________________________________________________________________
 
                   repeat lines 5 and 6 for all irreps with NI(LA) > 0
 ______________________________________________________________________________
 
     7  2(I6,1X,I3)   IAN, IAD, IBN, IBD
                                     Open-shell energy coefficients for each
                                     pair of irreps with open shells.  See
                                     OSU-TCG Report No. 101 for definitions and
                                     examples.
                                      1st     1st
                                      2nd     1st
                                      2nd     2nd, etc.
                                     These are supplied in fractional form:
                                      alpha = IAN/IAD   beta = IBN/IBD
                                     The denominators default to 1.  For the
                                     two-configuration MCSCF case, enter
                                          0   0
                                          0  -1
                                          0   0
 
     8       2F20.0   DAMP, DAM1     DAMP is the initial value of the damping
                                     factor.  DAM1 is the level shift
                                     parameter.  A reasonable choice in the
                                     absence of other information is to use
                                     level shifting only (IDFIX=1, DAMP=0.0,
                                     DAM1=1.0).  Increase DAM1 if oscillation
                                     occurs; decrease it if convergence is very
                                     smooth and too painfully slow.
 
     9         A80    FMTA
       (if IPUNCH GT 0)              Format for saving MO coefficients on disk
                                     or tape.  A blank line may be input, in
                                     which case a default format will be used.
 
    10         I4     NEWST --        0  run another state; go to card 1.
                                      1  end of run
 
 NOTES:
 
     This program originated as the SCF section of the BISON program for
diatomic molecules, written at Argonne National Laboratory by A. C. Wahl,
P. Bertoncini, K. Kaiser, and R. Land.  It used the Roothaan two-Hamiltonian
formalism for open-shell cases.  R. C. Raffenetti (K. Ruedenberg group) at
Iowa State University generalized it to use any point-group symmetry and
modified it in a number of other ways.  H. L. Hsu and R. M. Pitzer modified it
to use integrals from the SAINT (I43210) program.  H. L. Hsu, E. R. Davidson
(on leave from the University of Washington), and R. M. Pitzer changed it to a
one-Hamiltonian formulation and installed damping and level shifting.
S. B. Auster put in I/O improvements and files for continuing runs with
damping.  D. M. Hood (H. F. Schaefer group) at the University of California,
Berkeley, added population analysis.  R. M. Pitzer (working with the
H. F. Schaefer group at the University of Texas) added the two-configuration
MCSCF feature.  D. C. Comeau (I. Shavitt group) added fractional occupation
number input.  M. J. M. Pepper (I. Shavitt group) added DIIS extrapolation.
R. N. Diffenderfer added bare-nucleus starting and filling-by-orbital-energy
options.  R. J. Zellmer (I. Shavitt group) added an interface for gradient
output.  E. A. Stahlberg (I. Shavitt group) added the option for in-core
storage of the P and Q supermatrices.
 
     In addition to Ohio State University and the above institutions, support
has been provided by the Department of Energy, the National Science
Foundation, and Cray Research, Inc.
 
     Distribution of this program is handled primarily through Argonne
National Laboratory as part of the COLUMBUS system of programs.  Contact
shepard@tcg.anl.gov.
 
 
 *******************************************************************
 
    This computer program contains work performed partially by the
    Argonne National Laboratory Theoretical Chemistry Group under
    the auspices of the Office of Basic Energy Sciences,
    Division of Chemical Sciences, U.S. Department of Energy,
    under contract W-31-109-ENG-38.
 
    These programs may not be (re)distributed without the
    written consent of the Argonne Theoretical Chemistry Group.
 
    Since these programs are under development, correct results
    are not guaranteed.
 
 *******************************************************************
 
 FILES USED:
 
      Files needed for individual electronic states are specified only by unit
 number.  The corresponding file names are given in job control statements or
 generated by the operating system as the result of OPEN statements.
 
   File      Unit
   Name      No.     Description
 
  .......    NOUT    P, Q supermatrices, T, V, (cor) integrals, if not in core
              =2     (scratch file)
 
  PKINTS     NIN     S, T, V, (cor), integrals, P, K/2 supermatrices; from
              =3     CNVRT or SAINT
 
  SCFPQIN   NINPUT   Input
              =5
 
  SCFPQLS   NLIST    Output listing
              =6
 
 (unit no.) INFLG    Starting MO coefficients (optional)
 
  MOCOEF    IPUNCH   MO coefficients (optional)
 
 (unit no.) ITCON    Input data to continue iterations using damping (optional)
 
 (unit no.) ITPREP   Output data to continue iterations using damping
                     (optional)
 
 (unit no.) IGRAD    Output data for gradient calculation (optional)
 
 (unit no.) IDMAT    Additional output data for gradient calculation; needed
                     for open-shell cases (optional)

MACHINE-DEPENDENT FEATURES:

VMS: On VAX VMS computers, all filenames are translated using the standard
logical name tables.  If SCFPQ is defined as a foreign command with the VMS DCL
statement "DEFINE SCFPQ:==$DEVICE:[DIRECTORY]SCFPQ.EXE" (the $ is important),
then the workspace memory may be set from the command line. For example,

    $ ASSIGN MY_DEVICE:[MY.DIRECTORY]MY_PKINTS.DAT     PKINTS
    $ SCFPQ /M=50000

would cause scfpq to use the indicated device and filename instead of the
default []PKINTS.DAT file in the default directory.  SCFPQ would only use 50000
REAL*8 words of workspace, allocated from a blank common pool, instead of the
usual default value.  The maximum allowable value is determined by the
dimensioned size of the blank common pool.

Unix: On unix computers, all filenames are translated using the process
environment variables.  Upper-case variables only are valid matches.  Workspace
size may be set from the command line using "-M nnnnnn".  Both upper and lower
case "M" are valid.  For example, from the Bourne shell:

    $ PKINTS=my/directory/my_pkints  $COLUMBUS/scfpq.x -m 50000

or

    $ PKINTS=my/directory/my_pkints
    $ export PKINTS
    $ $COLUMBUS/scfpq.x -m 50000

or from the C shell:

    % setenv PKINTS my/directory/my_pkints
    % $COLUMBUS/scfpq.x -m 50000 

causes the input integral file to be redirected and the workspace size to be
set as indicated.  On unix machines, there is no upper limit on the workspace
allocated imposed by program scfpq; invalid requests result in a nonzero return
status.

IBM: On IBM machines, the optional MOCOEF file is accessed by unit number and
not by filename.

PARALLEL EXECUTION: On unix machines, SCFPQ may be prepared to run in a
parallel message-passing environment.  In this mode of execution, the input and
output filenames (e.g. pkints and scfpqls) are appended with a 3-digit parallel
process number (e.g. scfpqls_000, scfpqls_001, etc.).  A simple deterministic
distribution of the workload is used to distribute the effort across several
CPUs or across a heterogeneous network of machines.  The TCGMSG library and
documentation should be consulted for details.  The TCGMSG library may be
obtained using anonymous FTP from ftp.tcg.anl.gov.  See the directory
$COLUMBUS/source/p_scfpq for more information and for sample test cases.
 
SAMPLE DATA:
 
 CH2 (3a1)1 (1b1)1  3B1 State  (Total Energy: -6.5072742731)
  -8   9   0   0   0   8   0   0   0  80   0   0   0   1   0   0   1
   2   0   1   1
   2   1
   2   3
   1
   1
   2
   1
     1         1
     0        -1
     1         1
        0.0                 1.0
(4(1PD20.13))
   0
 CH2 (3a1)2, (1b1)2  1A1 State  (Total Energy: -6.5276934340)
   4   7   2   0   0   0   0   0   2  80   0   0   0   1   0   0
     0         0
     0        -1
     0         0
        0.0                 2.0
   1