
 
 
        AIMPAC graphic packages:
 
        This packages of programs allows for the graphic analysis of
the charge density and its characteristic functions.
 
        Graphic Compatability:
 
        These programs have been written so as to be as machine and package
independent as possible.  The reader will see at once that these programs
are quite simple and could easily and quickly adapted to most environments.
The vast majority of the graphics depends upon the concept that the user
need only supply a routine which draws a line segment from the present 
position to the passed coorindtes in two-dimensional space in absolute 
coordinates.  The call which does this is
 
        CALL PLOT (X,Y,IPEN)
 
which moves the pen from the present coordinates to the coordinates X,Y
in absolute space.  The coordinates are passed as single precision numbers.
The integer value IPEN determines the pen up/pen down state:
 
        CALL PLOT (X,Y,2)  :  Move the pen to (X,Y) with pen down.
        CALL PLOT (X,Y,3)  :  Move the pen to (X,Y) with pen up.
        CALL PLOT (X,Y,4-9):  Move the pen to (X,Y) with dashed line.
        CALL PLOT (X,Y,99) :  Move the pen to (0.,0.) and reset plotter.
 
The plotter sequence is inititalized with a call 
 
        CALL PLOTS (53,0,6)
 
which assigns all output to unit 6.  The only other thing the reader need
consider is the dashed line the symbolizes the contors of positive del-squared
rho (by new convention).  The line type choice is made in the routine COUPLR
within the program CONTOR. 
 
        GRIDV:
 
        GRIDV calculates the chosen function at grid points defined by the user.
 
        The input to GRIDV is free format with the first seven characters of
each card being ignored by the routine and used by the user as labels for ease
of use.  An example of the input is given here.
 
TITLE:  Formaldehyde HF/3-21G//HF/3-21G rho 
INCRM:  10.0 0.100
CENTR:  0.0 0.0 0.0
PLANE:  0 1 2 3 4
NFUNC:  1
 
The cards are used as follows:
 
TITLE:  Formaldehyde HF/3-21G//HF/3-21G rho 
The first card is a 60 character title card.
 
INCRM:  10.0 0.100
The second card defines the grid size and density.  The first real number (N1)
is the length of either axis of the grid in atomic units (all values are in
atomic units). The second real number (N2) is the distance between each grid
point along the axis. This defines the density of the grid as there will be
N1/N2 points along each axis and hence (N1/N2)**2 grid points in total.  GRID is
dimensioned to handle up to a 200 X 200 grid. 
 
CENTR:  0.0 0.0 0.0
The third card defines the center of the plot in the molecular frame of
reference. The grid will be evenly placed about this point. 
 
PLANE:  0 1 2 3 4
The fourth card allows the user to define the plane of interest for this
calculation rotating it to the XY plane of the plotter. The user has a choice of
two methods for description of the plane, inertial axis or Euler angles.  The
first integer read determines which method is used.  If the integer value is
zero inertial axis is to be used.  The integers following are the atom numbers
of those atoms within the plane.  Any number of atoms (up to 30) may be used to
define the plane (three atoms define a plane, but more may be entered).  In this
case, the user has requested that atoms 1, 2, 3, and 4 be placed in the plane.
If the atoms do not define a plane, the routine will make a best fit to the
plane and the results will most likely not be desirable. If the integer value is
1 then Euler angles will be used.  The first real number is the rotation, in
degrees, about the molecular Z axis.  (Positive rotations correspond to
clockwise rotations when viewing down that axis toward the origin from the
positive axis)  The second real number is the rotation about the molecular X
axis.  The third is the rotation about the Z axis of the plotter's frame.  For
example if the formaldehyde molecule were in the YZ plane in the wavefunction
file the following card would place the molecule in the plotter's XY plane. 
PLANE:  1 90.0 90.0 0.0
This corresponds to rotation about the Z axis, placing the molecule in the XZ
plane.  The second rotation about the X axis places the molecule in the XY
plane. And the user has decided not to reorient the molecule now that it is in
the XY plane, hence the third angle is 0.0. 
 
NFUNC:  1
The last card chooses the function to be calculated at each point in the grid. 
An integer value of 1 chooses rho while a value of 2 chooses del-squared rho. 
Other functions are presently being implemented and will follow in later
releases. 
 
        GRIDV uses the following Fortran units:
 
        The wavefunction file is read from unit 10.
        The above mentioned input file is read from unit 20.
        The grid is written to unit 30.
 
        CONTOR:
 
        CONTOR reads the grid generated by GRID and creates a contour map of the
function.  CONTOUR determines whether the function is positive or negative, for
the case of del-squared rho, and makes the positive del-squared rho contours
dashed and the negative contours positive (a new convention).  CONTOR requires
no other input other than the grid produced by GRID. 
 
        The contour values are 2.0D-03, 4.0D-3, 8.0D-03, 2.0D-02, ..., 8.0D+02.
Similarly the negative contours have the same absolute values, but are negative
in sign.  Squareness of contours is due to a coarse grid.  Increasing the
density of the grid points will reduce this problem.
 
        CONTOR uses the following Fortran units:
 
        The grid is read from unit 30.
        The contours to be plotted are output to unit 6.
 

 
        RELIEF:
 
        RELIEF generates a relief map of a two dimensional grid of data points
with the third dimension (z: out of the plane) representing the value of the 
function.  This is done using the two dimensional grid from GRID.  
 
        RELIEF asked the following questions interactively:
 
        EYE POSITION IN THREE-SPACE:  This requests three unit 
vectors, the relative values of which are used to determine the viewing
position for the plot.  For example, an eye position of 1.0,1.0,1.0 will
generate a view of the plane down the bisector of the X and Y axis, above the
plane by an equivalent amount.  Modification of the ratios between the vectors
will allow for differing heights and angles for the view.  For viewing 
del-squared rho, a Z unit vecotr with a negative value will look under the plane
and hence show the -(del-squared) rho surface.
 
        CUTOFF, MAGNIFICATION, AND VERTICAL ACCENTUATION:  These three real
describe the maximum absolute value for that function, the plot magnification
factor, and the vertical accentuation factor.  The cutoff is used to limit the
maximum value of the function so as not to swamp other, smaller peaks.  The
magnification factor (1.0 being the usual value) determines the physical size
of the plot on the plotter.  The larger the value, the larger the plot.  Beware
of the physical size limitations of the plotter!  The vertical accentuation 
factor is used to increse the z value of a function.  The larger the value, the
higher the resulting peaks will become.
 
        RELIEF uses the following Fortran units:
 
        The grid is read from unit 30.
        The surface to be plotted output to unit 6.
 


          GRDVEC or SCHUSS: 
 
     GRDVEC or SCHUSS - calculate gradient paths of a charge distribution
 
 
DESCRIPTION
 
     GRDVEC or SCHUSS calculate gradient paths in the charge distribution
        as requested by the user outputting the calculated paths
        into a file ready to be sent to the plotter.  The vecfile 
        contains the number and type of gradient paths desired as 
        outlined below.  The wfnfile contains the wavefunction for 
        the molecule in terms of basis functions calculated by one 
        of the ab initio molecular orbital packages.  The gradient
        paths are calculated and written to an output file for 
        redirection to the plotter.
 
ARGUMENTS
 
     vecfile (for example 'c4h4.vec')
        The vecfile, described below, describes the orientation
        of the chosen plane, the number, and the types of origins
        desired within that plane.
 
     wfnfile (for example 'c4h4.wfn')
        The wavefunction file contains the basis set and optimized
        coefficients from a SCF calculation describing the charge
        distribution of that molecule.
 
FORMAT
 
        The input to GRDVEC or SCHUSS is free format with the first seven 
        characters of each card being ignored by the routine and used by 
        the user as labels for ease of use.  An example of the input is 
        given here.
 
        TITLE:  Tetrahedrane HF/6-31G**/HF/6-31G*
        PLOT:   10.0 0.100
        CENTR:  0.0 0.0 0.0
        PARAM:  0.1 0.005 0.005 1.0E-12 0 1
        PLANE:  0 1 2 5 6
        NORIG:  4
          0.97775600     -0.97775600     -0.97775600       0    0  36
         -0.97775600     -0.97775600      0.97775600       0    0  36
          6.36117174E-09 -1.15576876E+00  1.59025028E-08   1    2   2  
          1.72948502E+00 -1.72948502E+00 -1.72948502E+00   1    2   2
 
        The cards are used as follows:
 
     TITLE:  Tetrahedrane HF/6-31G**/HF/6-31G*
 
        The first card is a 60 character title card.
 
     PLOT:   10.0 0.100
 
        The second card defines the grid size and density.  The first real 
        number (N1) is the length of either axis of the grid in atomic 
        units (all values are in atomic units).  The second real number (N2) 
        is the distance between each grid point along the axis.  This 
        defines the density of the grid as there will be N1/N2 points 
        along each axis and hence (N1/N2)**2 grid points in total.  GRDVEC
        uses this information for scaling of the plots only, not in
        the determination of the gradient paths.  It is a good and
        suggested practice to use the same values for PLOT for
        GRDVEC as used in GRIDV.
 
     CENTR:  0.0 0.0 0.0
 
        The third card defines the center of the plot in the molecular 
        frame of reference.  The grid will be evenly placed about this 
        point.
 
     PARAM:  0.1 0.005 0.005 1.0E-12 0 1
 
        The PARAM line contains five parameters used in the walking
        algorithm.  The first number is the distance (in a.u., as are
        the rest) from an attractor that the walk is started.  The 
        second and third are the distances from the defined repellors
        that the uphill and downhill walks are started, respectively.
        The fourth number is the endpoint criterion for all walks.  The
        next number determines whether the gradient vector paths are 
        allowed out of the plane or not.  A zero (0) means that the paths
        are to remain in the plane and a one (1) allows the gradient
        vectors to leave the plane of the atoms.  The former is used
        most often while the latter is used primarily for molecular
        graphs. The last number is the slow/fast walking switch.  A zero
        (0) means walk slowly (carefully) and a one (1) means step
        quickly.  The fast switch should be set first and only turned
        off if difficulty is encountered.
 
     PLANE:  0 1 2 5 6
 
        The fourth card allows the user to define the plane of interest 
        for this calculation rotating it to the XY plane of the plotter.
        The user has a choice of two methods for description of the plane, 
        inertial axis or Euler angles.  The first integer read determines 
        which method is used.  If the integer value is zero inertial axis 
        is to be used.  The integers following are the atom numbers of 
        those atoms within the plane.  Any number of atoms (up to 30) may 
        be used to define the plane (three atoms define a plane, but more 
        may be entered).  In this case, the user has requested that atoms 
        1, 2, 5, and 6 be placed in the plane.  If the atoms do not define 
        a plane, the routine will make a best fit to the plane and the 
        results will most likely not be desirable.  
 
        If the integer value is 1 then Euler angles will be used.  The 
        first real number is the rotation, in degrees, about the molecular 
        Z axis.  (Positive rotations correspond to clockwise rotations 
        when viewing down that axis toward the origin from the positive 
        axis)  The second real number is the rotation about the molecular 
        X axis.  The third is the rotation about the Z axis of the 
        plotter's frame.  For example if the tetrahedrane molecule were 
        such that the four atoms of interest were in the YZ plane in the 
        wavefunction file the following card would place those atoms in 
        the plotter's XY plane.
 
     PLANE:  1 90.0 90.0 0.0
 
        This corresponds to rotation about the Z axis, placing the atoms
        in the XZ plane.  The second rotation about the X axis places 
        the atoms in the XY plane.  And the user has decided not to 
        reorient the plane now that it is in the XY plane, hence the 
        third angle is 0.0.
 
     NORIG:  4
 
        This card inputs the number of origins to be used.  GRDVEC is
        dimensioned to handle up to 60 origins. Following this card are 
        NORIG cards upon which are the origin coordinates and descriptors.
 
       0.97775600     -0.97775600     -0.97775600       0    0  36
      -0.97775600     -0.97775600      0.97775600       0    0  36
       6.36117174E-09 -1.15576876E+00  1.59025028E-08   1    2   2  
       1.72948502E+00 -1.72948502E+00 -1.72948502E+00   1    2   2
 
        Each card lists the Cartesian coordinates of the origin followed
        be three integers describing the type of origin and number of
        ascending and descending gradient paths from that origin.  A (2,-2)
        origin in the plane is an attractor in that plane and is
        described by a descriptor '0'.  From each attractor there are
        no ascending paths of grad rho, only descending. (e.g. from that
        point paths of grad rho may only descend.  Thus for the first
        two cards in the example, each is an attractor in the chosen
        plane and the user has requested that 36 descending gradient
        paths be mapped from each one.  The other critical point of
        interest in a plane is the (2,0) (the (2,+2) paths are always
        the end points of gradient paths and will always be found by
        descending paths in grad rho from the other two types of critical
        points.) and it is described by a descriptor of '1'.  The user
        has requested that 2 ascending and 2 descending gradient paths be
        calculated from these points.
        



          CUBEV:
 
     CUBEV - calculates cube of properties
 
SYNOPSIS
     CUBEV infile wfnfile 
 
DESCRIPTION
 
        The CUBEV program reads the input data from the infile 
        and the wavefuction from the wfnfile and calculates
        a cube of values of the requested property.
 
ARGUMENTS
 
     infile (for example 'hcoh.inf')
        The input file describes the type and characteristics of the 
        desired calculation.
 
     wfnfile (for example 'hcoh.wfn')
        The wavefunciton file contains the basis set and optimized 
        coefficients from a SCF calculation describing the charge 
        distribution of that molecule.
 
FORMAT
 
        The input to CUBEV is free format with the first seven characters 
        of each card being ignored by the routine and used by the user 
        as labels for ease of use.  An example of the input is given here.
 
        TITLE:  Formaldehyde HF/3-21G//HF/3-21G rho 
        INCRM:  10.0 0.100 0
        CENTR:  0.0 0.0 0.0
        PLANE:  0 1 2 3 4
        NFUNC:  1
 
        The cards are used as follows:
 
        TITLE:  Formaldehyde HF/3-21G//HF/3-21G rho 
        The first card is a 60 character title card.
 
        INCRM:  10.0 0.100 0
        The second card defines the cube size and density.  The first real 
        number (N1) is the length of the axis of the cube in atomic 
        units (all values are in atomic units).  The second real number (N2) 
        is the distance between each cube point along each axis.  This 
        defines the density of the cube as there will be N1/N2 points 
        along each axis and hence (N1/N2)**3 CUBE points in total.  CUBE
        is dimensioned to handle up to a 200 X 200 X 200 CUBE.
        The third (integer) number alows the user to take advantage of 
        molecular symmetry which will speed up the calculation of the cube.
        A value of 0 means the cube will be calculated by not taking advantage
        of symmetry.  A value of 1 means there is symmetry in Y.  A value
        of 2 means there is symmetry in both X and Y.
 
CENTR:  0.0 0.0 0.0
        The third card defines the center of the plot in the molecular 
        frame of reference.  The cube will be evenly placed about this 
        point.
 
PLANE:  0 1 2 3 4
        The fourth card allows the user to define the plane of interest 
        for this calculation rotating it to the XY plane of the plotter.
        The user has a choice of two methods for description of the plane, 
        inertial axis or Euler angles.  The first integer read determines 
        which method is used.  If the integer value is zero inertial axis 
        is to be used.  The integers following are the atom numbers of 
        those atoms within the plane.  Any number of atoms (up to 30) may 
        be used to define the plane (three atoms define a plane, but more 
        may be entered).  In this case, the user has requested that atoms 
        1, 2, 3, and 4 be placed in the plane.  If the atoms do not define 
        a plane, the routine will make a best fit to the plane and the 
        results will most likely not be desirable.  If the integer value 
        is 1 then Euler angles will be used.  The first real number is 
        the rotation, in degrees, about the molecular Z axis.  (Positive
        rotations correspond to clockwise rotations when viewing down 
        that axis toward the origin from the positive axis)  The second 
        real number is the rotation about the molecular X axis.  The third 
        is the rotation about the Z axis of the plotter's frame.  For 
        example if the formaldehyde molecule were in the YZ plane in 
        the wavefunction file the following card would place the molecule 
        in the plotter's XY plane.
 
PLANE:  1 90.0 90.0 0.0
 
        This corresponds to rotation about the Z axis, placing the molecule 
        in the XZ plane.  The second rotation about the X axis places 
        the molecule in the XY plane.  And the user has decided not to 
        reorient the molecule now that it is in the XY plane, hence the 
        third angle is 0.0.
 
        This feature is merely a carry-over from the GRID routine and is
        not terribly usefull here.  It is suggested that the initial CUBE
        runs use the following card;
 
PLANE:  0
 
        which performs no orientation manipulation on the cube.
 
NFUNC:  1
        The last card chooses the function to be calculated at each point 
        in the cube.  An integer value of 1 chooses rho while a value of 
        2 chooses del-squared rho.  Other functions are presently being 
        implemented and will follow in later releases.
 
 
        CUBEV generates a file containing the requested cube of data.
        The cube may be processed by running it through ENVELOPE.
 
 

          ENVELOPE:
 
     ENVELOPE - produces 3-D envelopes of CUBEV output
 
SYNOPSIS
     ENVELOPE qubfile envfile
 
DESCRIPTION
 
        The ENVELOPE program reads in a cube of data (qubfile) 
        output by CUBEV and produces an iso-valued envelope of the 
        function, output to envfile.  This is done using interactive 
        queries of the user for plotting information.  The resulting 
        file is these redirected to the output device for plotting.
 
ARGUMENTS
 
     qubfile (for example 'hcoh.qub')
        The qubfile contains a cube of data output by the program
        CUBE.
 
     envfile (for example 'hcoh.rel')
        The output envfile contains the plotter calls to produce
        the envelope.  This output file is redirected to the 
        plotter directly. 
 
INTERACTIVE DIALOG
 
        Once the program has read in the cube of data the following
        questions are asked of the user;
 
        1) EYE POSITION
 
        This requests the position of the eye of the viewer.  This point
        can be considered as placed on an extended cube.  A good starting
        point is 5*NX, 3.5*NY, 2*NZ.  For example, for a 100X100X100 cube,
 
        EYE POSITION  500,350,200
 
        would make a good initial guess.
 
        2) OUTER CONTOUR VALUE
 
        This is the value of the iso-surface.
 
        3) LARGER VALUES INSIDE OR OUTSIDE ENVELOPE
 
        The algorithm assumes that either the larger values are inside
        the iso-surface (repsond with -1) or they are outside the
        surface (respond with 1).  If you get a cube as the result try
        using the other response.
 


