PSI/88 Version 1.0
                                        
                                        
    Purpose:       To plot wavefunctions in three dimensions from
                  semi-empirical and most popular ab initio basis sets. 
                  Valence semi-empirical, STO-3G, 3-21++G(*) and
                  6-31++G(d,p) basis sets are implemented for atoms
                  H-Ar.
    
    Language:      FORTRAN 77
    
    Tested on:     Silicon Graphics, SUN, VMS, ULTRIX, CYBER 205, CRAY.
                   Should be easily portable to others.
    
    Required:      Any CALCOMP compatible graphics library - some are
                  included in the distribution
    
    Memory:        200K Single precision 32bit words - PSI1, PSICON
                   400K Single precision 32bit words - PSI2
    
    Authors:       William L. Jorgensen
                   Daniel L. Severance
                   Department of Chemistry
                   Yale University
                   P.O. Box 6666
                   New Haven, CT 06511, USA.
                   Phone (203) 432-6288
                   Fax (203) 432-6144
                   Internet: dan@rani.chem.yale.edu
    
    Abstract:      attached
    
    Sample data:   attached

   -------------------------------------------------------------------

                            Differences from PSI/77
         
         
         This set of programs is a complete rewrite of the wavefunction
    computation section of PSI1, as well as major modification of the
    hidden line portion of PSI2.  All three routines have been written
    in standard FORTRAN 77 and were tested on a variety of machines to
    ensure portability.  PSI1/88 will auto-vectorize on vector machines
    and runs 1-2 orders of magnitude faster on scalar hardware.  This
    allows the use of high level basis sets for plotting without
    introducing approximations into the basis set.  The process of
    hidden line elimination using the PSI/88 contours constituted a
    significant amount of time using the original PSI2 program
    (approximately one hour for a plot).  PSI2/88 is an order of
    magnitude faster.  The problem of plotting depressions and doughnuts
    which were troublesome with the original version is also addressed.
         During the development of the program, execution speed was
    given top priority relative to minimization of memory usage.  It is
    almost routine to have moderate amounts of memory in the current
    generation of computers.  The 400Kwrds needed for the PSI2 plotting
    program (1.5Mbytes) is even within reach of personal computers.
         PSI/88 consists of three separate programs, PSI1, PSICON, and
    PSI2.  The first two programs are responsible for generation of the
    3-dimensional contours which are rotated and plotted using PSI2. Two
    programs enable generation of the orbital value grid (time consuming
    step) separate from the application of contour cutoffs (contour
    generation).  The user may now generate plots at different contour
    levels with only one execution of PSI1/88.  The third program, PSI2,
    is used to read the 3-dimensional contours and rotate the system
    according to user input.  Hidden line elimination is performed on
    the resultant contours and the final plot is output.
         The output of PSI1 consists of a file containing the value of
    the wavefunction at evenly spaced points (yi(x,y,z) orbital value
    grid) within a rectangular space about the molecule (the plotting
    box, a 513 3-dimensional grid, 6X, 6Y, and 6Z may have different
    values).  The contribution from each of the primitive gaussians are
    summed to generate each point in the orbital value grid, yi(x,y,z). 
    The actual gaussian primitives are used for each of the supported
    basis sets without contraction or approximation.  The semi-empirical
    routine uses the STO-3G valence gaussians to approximate the
    corresponding Slater functions.  The necessary Slater exponents are
    read in along with the MOs to allow the routine to be general.
         The PSICON program is used to generate a series of parallel
    plotting contours at the user specified contour level.  The contours
    represent the 3-dimensional iso-valued surface with
    yi(x,y,z)=constant.  If one specifies a contour level of 0.075 a.u.,
    the plotted surface is the visible surface with yi(x,y,z)=+0.075. 
    The positive and negative contours are differentiated by
    solid/dashed lines and/or different colors.  An increase in the
    contour level results in a decrease in the size of the surface being
    viewed.
         3-D contours of the same MO at different contour levels may be
    generated by multiple runs of the PSICON program.  It is not
    neccessary to run the PSI1 program to recompute the orbital value
    grid.  This results in a considerable time savings for the user.
         The modified input format accommodates the new basis functions,
    and better allows for future changes without incompatibilities. 
    Plotting planes are no longer specified as input, since all three
    planes are now used in plotting the orbital.  The min and max
    dimensions of the plotting box are input in place of the plane
    specifications, or are automatically generated as in PSI/77.
         There is no longer a way to apply a distance cut-off in the
    computation of the orbital value grid.  Compilation with the no
    underflow checking option is a neccessity for efficient execution.

 
    ----------------------------------------------------------------------
                              MO Plotting Details
                                        
         A good orbital plot will use a contour level which allows the
    important features of the MO to be displayed.  It will be viewed
    using a set of angles which will show off the 3 dimensionality of
    the orbital.  As a rule, one should use at least two angles which
    significantly deviate from multiples of 900.  This permits the curve
    of the contours which are going back into the plane of the paper to
    be discerned.  This curvature is what gives the drawings the 3
    dimensional flavor.  There are examples at the end of this manual to
    illustrate the effects of both contour level and orientation.
         0.5-1.5 a.u. are reasonable starting values for the orbital
    amplitude.  Larger molecules require smaller values due to the
    dispersion of density over more atoms.
         Much of the protocol for making plots in PSI/88 is analogous to
    the procedure used for PSI/77.  First, perform an MO calculation on
    the molecule of interest using an ab initio or semi-empirical
    method.  Write the Cartesian coordinates and all MO eigenvectors to
    a disk file, or place the coordinates and a single MO in the PSI1
    input file.  A program is provided to generate all necessary PSI/88
    input files for a specified MO from VAX Gaussian 82 or 86 checkpoint
    files.  It was written by James Briggs at Purdue.
         Another program is included which reads MOPAC graph (.GPT)
    files and outputs a disk file, complete with the necessary Z values.
         The drawings consist of stacked, parallel, two dimensional
    slices superimposed with the set from each of the other two
    dimensions.  This superposition, along with the subsequent hidden
    line elimination to hide that which is blocked from the viewer's
    line of sight, generates an image which shows 3-dimensional detail.
         The first program in the set is used to read molecular
    coordinates and eigenvectors and generate a file containing the
    value of the wavefunction along an evenly spaced grid.  This file is
    read in using the PSICON program for application of the contour
    level.  The contour curves are generated and stored for input to the
    PSI2 program.  A new contour value may be input and the PSICON
    program run again without further execution of PSI1 as long as the
    PSI1 output file is intact.
         The second program is responsible for computing the contour
    curves.  Only one contour level is computed for each two dimensional
    map, (any smaller of multiple contours is hidden beneath the surface
    defined by the largest contour).  The same contour value is computed
    for each of the 51 planes in the grid file in each of the three
    Cartesian directions.  This produces three sets of 51 parallel
    contours to be taken on to the hidden line/plotting program.
         The PSI2 plotting program is used to create the actual MO plot.
    The user inputs an orientation for the molecule specified by three
    angles ( 5, [, 7 ), title, and size of the plot.
         The information content of the plots are as accurate as the
    wavefunctions that are being used.  They are generated using the
    same basis functions with no approximations in producing the
    drawings.  Due to continuity of the basis functions, the orbital
    shape varies insignificantly with the amplitude value as long as a
    reasonable cutoff value is selected.


    ----------------------------------------------------------------------

                               PSI1 Input Format:
                                        
                                        
    Line 1:        Basis Set (A20 format)
                   Currently the implemented atoms H-Ar for the following 
                     wavefunctions: (functions in [ ] denote additional 
                                     functions supported for the basis set)
                   STO-3G         : S and p functions.
                   SEMI           : Generic semi-empirical routine.  The
                        Slater Z values are read in after the wavefunction,
                        one atom per line.
                   3-21[++]G[(*)] : Fully implemented.
                   6-31[++]G[**]  : The 6-31G(d,p) notation is also
                        recognized.  Currently no higher basis sets have been
                        implemented.
    
    Line 2:        AUTO,ONEMO (A4,I1) 
                   AUTO  = 'AUTO' : Determine the size and location of
                        the plotting boundary about the molecule from the
                        Cartesian coordinates.  The box may also be scaled by
                        use of the scale parameter in line 3. If used, skip to
                        line 3.
                   ONEMO = 1      : Only one MO is to be read in from the
                        input deck, rather than a list of all of the MOs.
                        If ONEMO is not 1, all MOs are expected in the input
                        deck.
                        Reading the MOs from a separate file is no longer
                        supported.
    
    Line 2a:       Omit this line if AUTO u 'AUTO'   (case insensitive).
                   Input 3 lines defining the boundaries of the plotting
                        region.
                   Xmin, Xmax (2F10.6 Format)
                   Ymin, Ymax (2F10.6 Format)
                   Zmin, Zmax (2F10.6 Format)
    
    Line 3:        MO number to plot, Scale for the plotting box
                        (I2,2x,F10.6).  Ignored if ONEMO above is 1, 
                        otherwise set it to the number of the desired MO 
                        to plot from the input deck.
    
    Line 4:        Charge (I2), Title (A40).  The charge is unused at
                        present, but will be used at a later date if density
                        plots are implemented.

    Line 5+:       Atomic number, X,Y, and Z (I2,3F10.6), one atom per line.
                        End this input section with 99 for the atomic number.

    Line 6+:       The MO to read in (8F10.6 Format).


    --------------------------------------------------------------------------

                              PSICON Input Format:
                                        
                                        
    Line 1:        Basis Set (A20) This is an informational line for the
                        user and is read, but not used in the program.
    
    Line 2:        NCON, ICONN, ICONZ, and NORB (4I2)

                   Use the values 01010001 with the current version of
                        the program.  These parameters are mainly for
                        compatibility with previous features which have not
                        yet been implemented in the current version.

                   NCON  = 01 : use one contour level for plotting
                   ICONN = 01 : plot negative contours too (default = 1)
                   ICONZ = 01 : plot a zero contour (default = 0)
                   NORB  = 02 : charge density plot (currently disabled)
    
    Line 3:        Contour level.  (F10.6 Format)
                        Smaller numbers yield larger orbitals, choose what
                        looks good.


    --------------------------------------------------------------------------

                               PSI2 Input Format:
                                        
                                        
    Line 1:        Title to plot along the bottom edge of the figure.
                         (A120 Format)
    
    Line 2:        Subtitle to plot slightly below and to the left of the
                         molecule, i.e. orbital energy, orbital identifier,
                         etc. (A40 Format, centered)
    
    Line 3:        IRDXYZ,MOL,NHL,FACTOR (3I2,F4.3)
                   IRDXYZ = 01 : The molecular coordinates are read from
                         the input deck - Always expected.
                   MOL    = 01 : Draw the structure without the contours
                   NHL    = 01 : Suppress hidden line elimination.
                   FACTOR = 0.6: Scale size of view port. The default
                         value of 0.60 works well for HP plotters using 8.5x11
                         paper, but a value of 1.0 will expand the plot to fill
                         a piece of 11x14 paper.
                   RECOMMENDED VALUES - leave this line blank, equivalent
                         to 000000 0.0 defaults will be used.
    
    Line 4:        Number of bonds, (I2 format) Set this to zero for
                         automatic determination of the connectivity using
                         covalent radii.
    
    Line 4a:       If the number of bonds above is non-zero, follow it
                         with one line per bond between atoms.
                         (2I2 Format)
    
                   IRDXYZ is always set to 01 so:
    Line 4b:       Molecular title (A120 Format)
    line 4c:       Atomic number and atomic coordinates, one atom per
                         line.  Terminate this input with atomic number 99. 
                         (I2,8X,3F10.6 Format)
    
    Line 5:        Gamma, Phi, and Psi rotation angles, Scale (4F10.6 Format)
                         I promise these will be replaced soon.....
    
    Line 6:        For each atom with atomic number greater than 18, read
                         in the atomic symbol and the length of the atomic
                         symbol (A2,I1); otherwise omit this line.
    
    Line 7:        Control for color and dash.  Use 00 for
                         monochrome/dashed, 01 for color/solid, and 02 for
                         color/dashed. (I2 Format)


    --------------------------------------------------------------------------

                             Sample Input
                                   
                   (CH3)2O - H2O Complex Input Data:
                           PSI1 Input File:
                                   
3-21G                   ! Basis set
AUTO1                   ! Auto Size, Read MO and coord from input
 1 1  1.000000          ! read first MO, Scale auto-box by 1.0
 0 Acetone-water complex - experimental geometries 3-21G        ! User info
 6          0.000000  0.775358  0.000000
 8         -0.898498 -0.052883  0.000000
 6         -0.401969  2.227760  0.000000
 6          1.414944  0.256724  0.000000
 1         -1.485246  2.288892  0.000000
 1          1.387869 -0.827938  0.000000
 1         -0.001011  2.699672  0.890930
 1         -0.001011  2.699672 -0.890930
 1          1.917871  0.618019 -0.890930
 1          1.917871  0.618019  0.890930
 1         -0.407335 -1.844758  0.000000
 8         -0.154294 -2.767906  0.000000
 1         -0.984515 -3.244314  0.000000
 99     ! end of geometry,     MO input follows:
 -0.001129  0.001280  0.135475 -0.148048  0.000000  0.010292 -0.012350 -0.005258
  0.000000 -0.000949  0.002466 -0.288062  0.311097  0.000000 -0.003927 -0.350226
  0.367085  0.000000  0.031262 -0.020507 -0.019829  0.205547  0.000000 -0.234359
 -0.031103  0.207217  0.000000 -0.029388  0.019791 -0.201140  0.039368  0.000000
  0.216797 -0.203039  0.066162  0.000000  0.007894  0.072827 -0.012100 -0.047950
  0.043949  0.072106  0.043949  0.072106 -0.043812 -0.071520 -0.043812 -0.071520
  0.034120 -0.042968  0.004541 -0.009276 -0.064717  0.095409  0.000000  0.001910
 -0.082908  0.122359  0.000000 -0.004831 -0.000738

                          PSICON Input File:

3-21G           ! User info 
 1 1 0 1        ! Use these values
 0.075000       ! Cutoff value

                           PSI2 Input File:
                                   
(This input file corresponds with the last of the three plots on the
following page)

Acetone-water complex - experimental geometries 3-21G   ! Title
HOMO-2                                                  ! Sub-title
010000 1.0      ! Read coords from this file, Draw contours, use HLE
00              ! Auto connectivity determination
 6          0.000000  0.775358  0.000000
 8         -0.898498 -0.052883  0.000000
 6         -0.401969  2.227760  0.000000
 6          1.414944  0.256724  0.000000
 1         -1.485246  2.288892  0.000000
 1          1.387869 -0.827938  0.000000
 1         -0.001011  2.699672  0.890930
 1         -0.001011  2.699672 -0.890930
 1          1.917871  0.618019 -0.890930
 1          1.917871  0.618019  0.890930
 1         -0.407335 -1.844758  0.000000
 8         -0.154294 -2.767906  0.000000
 1         -0.984515 -3.244314  0.000000
99      ! End of geom input
  61.1000  132.1000    1.1000    0.8500         ! Theta, Gamma, Phi, Scale
02                                      ! Plot in color and dashed negative contours
                            H2O - CCl2 Input Data:
                                       
                               PSI1 Input File:

6-31G*  ! Basis set 
AUTO1           ! Auto for auto sizing, 1, read the MO and geom in this file
0101 1.7        ! read first MO, scale the auto-sized box 1.7 times larger
 0   H2O...CCL2 //MP2/6-31G*                    ! user information
 6           .000000   .000000   .000000
17          1.404414   .000000   .977839
17         -1.404414   .000000   .977839
 8           .000000 -2.536703 -1.208120
 1           .081292 -1.634178 -1.516458
 1          -.901404 -2.781513 -1.417334
99              ! end of geometry input         ! MO Input follows:
-.094628   .213553  -.001500   .000037  -.399432   .386339  -.002937   .013293
-.307475  -.021126   .010696  -.019951   .000042   .000132   .000084  -.003903
 .013545  -.011965   .003853  -.144090  -.048199   .031047  -.010501   .382332
 .042386  -.028536  -.006197   .216540  -.024993   .001069   .013505   .000047
-.003857   .000313  -.003944   .013964   .015048   .005330  -.140884  -.047974
-.039345  -.014595   .373818   .037035   .022056  -.007278   .214974  -.024953
 .001100   .013730  -.000143   .003492   .000073   .003522  -.003701   .027602
-.097318  -.045537  -.036276   .023607  -.085789  -.030322   .001131  -.004445
 .003663   .003784   .001378   .003731  -.020055   .039405   .006647   .007515

                              PSICON Input File:

6-31G*          ! User information
 1 1 0 1        ! Use these values
0.055000        ! Cutoff value

                               PSI2 Input File:

H2O...CCL2 //MP2/6-31G*                 ! Title
HOMO                                            ! Subtitle
010000 0.80     ! read coordinates from cards (below)
00              ! input connectivity information (immed follows if <> 00)
H2O...CCL2 //MP2/6-31G*                 ! Title from coord file
 6           .000000   .000000   .000000
17          1.404414   .000000   .977839
17         -1.404414   .000000   .977839
 8           .000000 -2.536703 -1.208120
 1           .081292 -1.634178 -1.516458
 1          -.901404 -2.781513 -1.417334
99                                              ! End of coord input
    0.3000   33.5000   72.0000    1.0000        ! Theta, Phi, Gamma, Scale
02   ! 00 for Monochrome w/Dash, 01 for Color-Solid, 02 for Color w/Dash
                             Sample Output
                                   
                           H2O - CCl2  Plot Output: