The Atlas ATMOL Manual is no longer available. This version of the Manual dates from 1982 after ATMOL was ported to the Cyber 205 at UMRCC.
The PLOT program provides graphical analysis of molecular wavefunctions. To invoke the Graphical Analysis program on the Cyber-205 at UMRCC use the following JCL:
PATTACH,ATMOL.
PLOT.
The program is capable of generating contour and perspective plots which depict :
In default the program will request 3 large pages of main memory, this can be varied by means of the pre-directives LPAGE or MEMORY [1]. All pre-directives [1] are applicable and should be presented before the main program directives.
Data input and printed output are on FORTRAN streams 5 and 6 respectively. These streams need not normally be mentioned in the JCL.
The following data sets will be used by the program, and should be mentioned in the JCL, in REQUEST, ATTACH, MFLINK or GETFEP commands:
DUMP FILE: The data set used by the Gaussian integrals program [2] to store the geometry and basis of the system under investigation. Recovery of the eigen vectors from a specified section is used to generate the required graphical output. This data set may be used by the program to store grid data used in the generation of contour and perspective plots.
SCRATCH FILE: A data set used as a scratch area for the program, should be assigned to AFN ED7.
PLOT FILE: The user is directed to reference [3] to obtain the mechanism by which the graphical output is produced on UMRCC Benson plotters, by a GINO file.
Two types of plot may be generated by the program to provide a pictorial representation of a given density or potential function in a specified molecular plane:
Both types of plot are generated from a grid of function values produced by the program.
The generation of graphical output involves four stages of computation, which can be summarised as follows:
Each of the stages outlined has certain data input associated to it. While the program operates in BASIS MODE at the commencement of the job, and in TERMINATION MODE upon completion of the graphical analysis, the intermediate processing is determined by the user, who specifies, via data input, the sequence of GRID MODE and PLOT MODE to be undertaken by the program. The following notes give an indication of typical mode sequences which may be specified:
BASIC MODE
GRID MODE
PLOT MODE ------ Plot 1
GRID MODE
PLOT MODE ------ Plot 2
TERMINATION MODE
should be specified, so that the generation of each plot requires that the
program should run in GRID MODE and PLOT MODE.
BASIS MODE
GRID MODE
PLOT MODE ------ Plot 1
PLOT MODE ------ Plot 2
TERMINATION MODE
Since the program can only produce a single plot when operating in PLOT
MODE, it is necessary to specify two successive PLOT MODES, each
responsible for generating a plot. Note that the grid of values used in
generating a plot is that constructed when the program was last in GRID
MODE. Thus the following sequence:
BASIC MODE
PLOT MODE
TERMINATION MODE
is not valid, since no mechanism is present to make a grid of values
accessible for plotting.
BASIS MODE
GRID MODE
GRID MODE
GRID MODE
TERMINATION MODE
may be specified, in which case the program will be concerned solely with
the construction of grids, and not with plotting. In such cases all
references to the data sets assigned for graphical output may be omitted
from the JCL. When operating in this manner it is clearly imperative to
route each grid to the DUMP FILE, failure to do so for a given grid will
result in that grid being inaccessible to a subsequent job concerned with
generation of graphical output. The following sequence:
BASIS MODE
GRID MODE
PLOT MODE ------ Plot 1
GRID MODE
PLOT MODE ------ Plot 2
GRID MODE
PLOT MODE ------ Plot 3
TERMINATION MODE
must be specified in the subsequent job, where each grid in turn will be
restored from the DUMP FILE and the graphical output generated.As detailed previously, a typical run of the analysis program involves four distinct modes of operation, namely BASIS MODE, GRID MODE, PLOT MODE and TERMINATION MODE, each of which requires certain data input. While the program operates in BASIC MODE only once, at the commencement of the job, subsequent processing undertaken by the program is determined by the user, who controls, via data input, the sequence of modes required. The input associated with both GRID MODE and PLOT MODE consists of a sequence of directives, introduced by a mode definition line. Upon detection of such a data line the program switches control to the specific mode, and having input the data associated with the nominated mode, carries out the process requested, either the construction of a grid of function values (GRID MODE) or the generation of graphical output based on such a grid (PLOT MODE). When all the necessary computation has been completed, the program should be placed into TERMINATION MODE by means of the STOP directive, which must be presented last in the data input. The data input applicable to each mode will now be described.
Details of the molecular and basis set specifications, together with the wavefunction under analysis, are retreived exclusively from the DUMP FILE at commencement of the job, when the program operates in BASIC MODE. The first two data lines in the input stream provide the relevant information to effect this retrieval, and must be presented as follows:
The first data line is read to variables NBASIS,IBKLD,DDDUMP using format (2I,A).
NBASIS specifies the number of basis functions as defined during the Gaussian integral evaluation.
IBKLD specifies the starting block of the DUMP FILE.
DDDUMP specifies the AFN used to assign the DUMP FILE. Valid AFNs being ED0-ED6 and MT0-MT7. If the DDDUMP parameter is omitted, the DUMP FILE will be assumed to reside on AFN ED3.
The second line is read to variables TEXT,ISECT,TEXTA using format (A,I,A).
TEXT should be set to the character string VECTORS.
ISECT should be used to identify the section on the DUMP FILE where the set of eigen vectors that are to be analysed, may be found. Such vectors will normally have been placed on the DUMP FILE by the SCF [3], APSG [[4] and Direct CI [5] program.
TEXTA should be set to the character string PRINT if a listing of the restored eigen vectors is required. If this parameter is omitted, no listing will be generated.
Data input consists a sequence of directives, which should be presented as outlined below. Not all directives may be required.
This directive consists of a single data line with the character string GRIDMODE in the first data field, and acts as the mode definition line. It causes control to be passed to those routines responsible for the input data specifying details of the grid of function values to be computed, while operating in GRID MODE.
This directive allows the user to define an 80 character title for use in labelling the grid and any graphical output subsequently generated from the grid. The first data line contains the character string TITLE in the first data field, the second data line contains the required 80 character title.
Example :
TITLE
H2O --- GRAPHICAL ANALYSIS
The purpose of this directive is to allow the user to define the occupation numbers for the molecular orbitals to be analysed. In the absence of the OCCDEF directive, the occupation numbers will be taken from the section of the DUMP FILE specified in the BASIC MODE data input.
The first data line contains the character string OCCDEF in the first data field. Following the directive initiator are the occupation definition lines. The first data field of such a line is read in F-format, and should contain a specified occupation number. Subsequent data fields are read in I-format. Let the value of an integer specified in such a field be j. Then the j'th molecular orbital will be assigned the occupation number specified in the first data field of the line. The following:
2.0 1 2 3 4 5 7
comprises a valid occupation definition line. Such a line may be shortened if a sequence of consecutive integers appear by means of the character string TO. Thus the abbreviated form of the above line is:
2.0 1 TO 5 7
The occupation definition lines are presented until all the orbitals to be assigned a finite occupancy have been declared. A data line containing the text END in the first data field must be presented to terminate the OCCDEF directive.
The following points must be noted:
Example 1:
The appropriate OCCDEF directive when generating a grid of values for use in construction of the amplitude of the 13th molecular orbital is:
OCCDEF
1.0 13
END
The OCCDEF directive should be used when analysis of the electron density associated with a certain subset of orbitals is required.
Example 2:
OCCDEF
2.0 1 TO 5 7
END
The grid of values will be generated assuming the first five molecular orbitals, together with orbital 7 are doubly occupied. All other orbitals will be assigned zero occupancy.
The CONFIG directive is only applicable when generating a grid of atomic density difference, and may be used to specify the configurations to be used in computing the atomic density distribution corresponding to the ground state of the atoms. In the absence of this directive spherically symmetric atoms are chosen, with equal occupation of the degenerate open shell orbitals.
Example :
The atomic configuration chosen in default for the carbon atom would be:
2 2 .666667 .666667 .666667
(1s) (2s) (2px) (2py) (2pz)
for the iron atom (d6s2 high spin):
2 2 2 2 2 2 2 2 2 2
(1s) (2s) (2px) (2py) (2pz) (3s) (3px) (3py) (3pz) (4s)
1.2 1.2 1.2 1.2 1.2
(3dxy) (3dxz) (3dyz) (3dx-y) (3dz2)
The CONFIG directive consists of three types of data line. The first line, the directive initiator, consists of the character string CONFIG in the first data field, the last line, the directive terminator, consists of the character string END in the first data field. Lines presented between the directive initiator and terminator are the 'configuration definition' lines. If there are NAT atoms whose configuration are to be specified, then NAT 'configuration' lines are required. Each line consists of (NORB+1) data fields, where NORB is the total number of doubly and partially occupied orbitals in the atom. The first data field is read to the variable ALAB, using format A, while the remainder of the data line should contain real numbers read in F-format to a vector (OCC(I),I=1,NORB). ALAB should be set to the label parameter of the nucleus, as specified by the corresponding 'nucleus definition' lines in the GEOMETRY or GEOMGEN directives of the Gaussian integrals program [2]. OCC(I) should be set to the occupation number of the i'th atomic orbital. The latter must be input in order of symmetry - s,p,d etc - with the partially occupied orbitals preceded by the doubly occupied orbitals, within each symmetry class.
Example 1:
Suppose the user wishes the following configuration for a carbon atom, which has been labelled as nucleus C1:
2 2 1 1
C : (1s) (2s) (2px) (2py)
then the following configuration definition line should be presented:
C1 2.0 2.0 1.0 1.0 0.0
Example 2:
To specify the configuration :
2 2 6 2 1
(1s) (2s) (2p) (3s) (3pz)
for an aluminium atom, labelled AL by the GEOMETRY directive, the user must present the following configuration definition line:
AL 2.0 2.0 2.0 2.0 2.0 2.0 0.0 0.0 1.0
where the first three 2.0 give the occupation of the s orbitals, while the remainder details the occupation of the p orbitals.
Example 3:
To specify the configuration
2 2 6 2 6
(1s) (2s) (2p) (3s) (3p)
2 2 2 0 0
(3dxy) (3dxz) (3dyz) (3dx-y) (3dz2)
for an iron atom, which has been labelled 1, the user should present the following line :
1 2.0 2.0 2.0 2.0 2.0 2.0 2.0 2.0 2.0 2.0 2.0 2.0 2.0 0.0 0.0
< s orbitals > < p orbitals > < d orbitals >
Note that the occupation numbers of the three p orbitals should be input in the order x,y,z and those of the five d orbitals in the order dxy,dxz,dyz,dx-y,dz2.
The GRID directive consists of a single data line read to variables TEXT,NGRID using format (A,I).
TEXT should be set to the character string GRID.
NGRID is an integer used to control the appearance of the final plot. The area to be studied (see PLANE directive) is divided into a mesh of (NGRID*NGRID) points, and the appropriate function evaluated at each point. The plotting routine will subsequently interpolate the computed grid to produce as smooth contours as possible. Obviously the finer the mesh (the larger NGRID), the smoother the resultant contours, but the greater the computer time and memory allocation required to generate the grid. The size of line printer contour plot is also affected by the grid size parameter, and is (NGRID*NGRID) characters in area.
Some points to note on the GRID directive:
The PLANE directive is used to define the molecular plane to be studied. The first data line is read to variables TEXT,SIZE using format (A,F).
TEXT should be set to the character string PLANE.
SIZE is the area covered by the plot, in the molecular plane, defined as (SIZE*SIZE) Bohr. This variable may be omitted, when an area of (10*10) Bohr will be covered.
The remainder of the PLANE directive consists of three data lines, in which the molecular plane is defined.
Line 1 is read to variables X1,Y1,Z1 using format (3F). These are the co-ordinates of a point P1 in the molecular co-ordinate system, defining the centre of the the plane to be studied.
Line 2 is read to variables X2,Y2,Z2 using format (3F). These are the molecular co-ordinates of a second point, P2, which in conjunction with P1, define the y (vertical) axis of the plot.
Line 3 is read to variables X3,Y3,Z3 using format (3F). These are the molecular co-ordinates of a third point, P3, which should not be co-linear with P1 and P2. P3, in conjunction with P1 and P2, define the molecular plane being studied. The x (horizontal) axis is is generated by Schmidt orthogonalising the vector P1-P3 to the vector P1-P2.
Example 1:
The following example is based on the HCO radical. To generate a grid covering and area of (5*5) Bohr in the plane containing the molecule (xy-plane), with the C atom at the centre of the plane, the user should present the following data lines for the PLANE directive:
PLANE 5.0
0.0 0.0 0.0
0.0 0.0 1.0
0.0 1.0 0.0
Example 2:
Based on the planar structure of the H2O molecule, the generation of a grid covering an area of (7*7) Bohr, in the plane containing the O H1 and H2 atoms, with the O atom at the centre of the plane. The user should present the GRID data (geometry is assumed to be that of experimental) as :
PLANE 7.0
0.0 0.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
The IPRINT directive may be used to increase the quantity of printed output produced by the program, while operating in GRID MODE. The directive consists of one data line, the first data field contains the character string IPRINT. Subsequent data fields are read in A-format, and specify that printing as in Table 1 is to occur.
Table 1
_______
Parameters of the IPRINT directive
__________________________________
Data Field Causes printing
ATOMSCF Various intermediate results from
the atomic SCF calculations performed
in generating a grid of atomic density
differences. Includes matrices of
integrals over basis functions and
final closed and open shell Fock
matrices.
GVAL The (NGRID*NGRID) matrix of grid
values.
This directive is used to specify the function to be used in grid construction (the type of grid to be generated), and consists of a single data line read to variables TEXT,TEST,ISECT using format (2A,I).
TEXT should be set to the character string GTYPE.
TEST should be set to one of the character strings specified in Table 2.
ISECT specifies the section number on the DUMP FILE where the grid of values is to be placed. ISECT may be omitted, in which case the grid of values will not be routed to the DUMP FILE.
Table 2
_______
Parameters of the GTYPE Directive
_________________________________
TEST Grid Function
DENSITY Electron density
NOSQUARE Orbital amplitude
ATOM Atomic difference density
POTENTIAL Molecular electrostatic potential
The following points when using the GTYPE directive, should be noted:
The nominated section of the DUMP FILE used to hold the grid of values is of TYPE=50. While a detailed account of the structure of this section is not given, the following may be used to deduce the space requirements of the section.
Let :
L = ((NGRID+2) * (NGRID+2) + 1) / 2
where NGRID is the integer parameter of the GRID directive. The number of
blocks in the grid section is given by :
N = ((L-1) / 511) + 2
where division is accomplished by rounding down to the nearest integer. Thus the output of a grid of (97*97) points would require 11 blocks, the output of a grid of (51*51) points would require 4 blocks and the output of a grid of (25*25) points 2 blocks.
Example :
To generate a grid of atomic difference density, and to route the grid to section 30 of the DUMP FILE, the user should present the following data line :
GTYPE ATOM 30
The considerable increase in computer time required to generate a grid of electrostatic potentials relative to that used in the generation of a density function grid, has required the introduction of restart facilities. The graphical analysis program will monitor SBU time remaining for a run, and when insufficient time remains to usefully continue, a standard dump is invoked. Dump control information, together with the current status of the grid of potentials, is sent to the nominated section of the DUMP FILE as specified by the GTYPE directive. Line printer output is generated, informing the user of the current status of the calculation. The message :
GRID GENERATION INCOMPLETE--RESTART
will be sent to the output file, indicating the need for a restart job. The RESTART directive may be used to restart the PLOT job, and consists of a single data line read to variables TEXT,ISECT using format (A,I).
TEXT should specify the character string RESTART.
ISECT should be used to identify the section on the DUMP FILE, as specified by the GTYPE directive of the startup run, where the grid of potentials may be found.
The following points on the RESTART directive should be noted:
RESTORED GRID IS COMPLETED
is seen on the printed output.Example :
Suppose that the following GRID MODE data was used in the startup job:
GRIDMODE
TITLE
WATER POTENTIAL PLOT
GRID 25
0.0 0.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
GTYPE POTE 20
with the grid of potentials routed to section 20 of the DUMP FILE. The GRID MODE data for the restart would be :
GRIDMODE
RESTART 20
GTYPE POTE 20
This directive may be used to construct a grid resulting from the addition and/or subtraction of up to a maximum of 15 component grids, and provides a mechanism for generating a grid of Molecular Density difference. All component grids must have been previously written to the current DUMP FILE or to a foreign DUMP FILE (a DUMP FILE different from that associated with the present job). The first data line contains the directive initiator in the first data field, read to the variable TEXT using A-format. If the resultant grid to be constructed is generated from a total of N grids, then successive data fields are read to the vectors (SIGN(I),LABEL(I),I=1,N) in A-format.
TEXT should be set to the character string DIFF.
SIGN(I) contains the character string '+' or '-', depending on whether the I'th grid is to be added to, or subtracted from, the resultant grid.
LABEL(I) is used to give the I'th grid a label by which it will be subsequently known. LABEL may be up to eight characters long, and should not include a space character.
N subsequent 'grid definition' lines are input, the format of which depends on the location of the component grid. In those cases where the grid resides on the current DUMP FILE, the definition line is read to variables TEXT,ISECT using variables (A,I).
TEXT should be set to the LABEL of the grid in question, as specified on the first data line.
ISECT is an integer used to specify the section wherein the required grid is to be found on the DUMP FILE. This integer was specified on the GTYPE directive of the job which created the grid.
In the case of a grid to be restored from a 'foreign' DUMP FILE, the grid definition lines are read to variables TEXT,DDFORN,IBLKF,ISECTF using format (2A,2I).
TEXT should be set to the LABEL of the grid in question.
DDFORN,IBLKF the location of the 'foreign' DUMP FILE resides on the AFN specified by DDFORN which commences at block specified by IBLKF. The 'foreign' DUMP FILE may reside on the AFNs ED0-ED6 or MT0-MT7.
ISECTF is an integer used to specify the section wherein the required grid is to be found on the 'foreign' DUMP FILE. This integer was specified on the GTYPE directive of the run which created the grid.
The following points should be noted when using the DIFFERNCE directive.
Any attempt to combine grids which do not satisfy these three conditions will be treated as an invalid operation, and results in an error condition.
Example 1:
Suppose the user wishes to construct a grid, and a subsequent contour plot, to illustrate the changes in electron density resulting from addition of polarisation functions to a double zeta (DZ) basis set calculation on water. Having constructed the wavefunction from each basis set, assume the following:
Basis Set DZ DZPOL
(4s2p/2s) (4s2p1d/2s1p)
NBASIS 14 25
Starting block 1 50
of DUMP FILE
SCF vectors routed 2 4
to section
where the DUMP FILE from each calculation resides on the same data set. The construction of the required grid is achieved by using two runs of the graphical analysis program.
Run 1, generates the grid of total electron density from the DZPOL basis. Assuming the grid is to be output to section 5 of the DUMP FILE which is assigned using the AFN ED2, the following BASIS MODE, GRID MODE and TERMINATION MODE data should be presented:
25 50 ED2
VECTORS 4
GRIDMODE
TITLE
H2O - DZPOL BASIS
GRID 97
PLANE 5.0
0.0 0.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
GTYPE DENS 5
STOP
Note that the molecular plane definition is based on the co-ordinate system of the water geometry. The absence of the PLOT MODE directives means that no graphical output will be generated from this job.
Run 2, contains two sets of GRID MODE directives, the first generating the grid of total electron density for the DZ basis set and routing it to section 6 of the DZ-DUMP FILE. The second generates the required (DZPOL-DZ) molecular difference grid, with the DZPOL-DUMP FILE being treated as a 'foreign' DUMP FILE in the DIFFERNCE directive. The following data should be presented :
14 1 ED2
VECTORS 1
GRIDMODE
TITLE
H2O - DZ BASIS Grid Mode 1
GRID 97
PLANE 5.0
0.0 0.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
GTYPE DENS 6
GRIDMODE
TITLE
H2O DZPOL - DZ Grid Mode 2
IPRINT GVAL
DIFF + DZPOL - DZ
DZPOL ED2 50 5
DZ 6
PLOTMODE
PTYPE CONTOUR LINE
STOP
Note that the definition of the molecular plane under study and the grid size are identical in both cases. The resultant grid of difference density will be output to the line printer. Details of the PLOT MODE directives used in generating the required contour plot are given in section 7.
Example 2:
Suppose that having generated the difference plot from example 1, the user subsequently requires a plot of the DZPOL density alone. Remembering that the DZPOL grid was output to section 5 of the DZPOL-DUMP FILE, the user may use the DIFFERENCE directive to restore the grid for subsequent processing by the PLOT MODE directives. The following sequence of data may be presented to accomplish this task:
25 50 ED2
VECTORS 4
GRIDMODE
TITLE
H2O DZPOL BASIS
DIFF + DZPOL
DZPOL 5
which will restore the appropriate grid prior to plotting.
Data input consists of a sequence of directives which should be presented in the following order. Not all directives may be required in a single run.
This directive consists of a single data line with the character string PLOTMODE in the first data field. This data line acts as the mode definition line and causes control to be passed to those routines reponsible for the input of data to be used in generating graphical output.
This directive may be used to define a set of function values for which contours are required. The first data line consists of the character string CVALUES in the first data field. If contours at NOCON values are required, subsequent data lines should contain NOCON real numbers, read in F format to a vector (CVAL(I),I=1,NOCON). The last data field should contain the character string END. Thus the sequences :
CVALUES
.7 .5 .3 .1 .03 END
and
CVALUES
.7 .5 .1
.03
END
are equivalent. CVAL(I) should be set to the values to be associated with the I'th contour.
The CVALUES directive may be omitted, when the default set of contour values given in Table 3 will be used. The following points should be noted.
Table 3
_______
Default contour values used for potential
and density contour plots as a function
of the grid type.
iso-energy iso-density curves
(kcal/mol) (atomic units)
GTYPE setting POTE DENS NOSQUARE ATOM or DIFF
210.0 64.7837 1.0 0.8691
180.0 16.1959 0.5 0.43455
150.0 4.0490 0.25 0.21727
120.0 1.0122 0.125 0.10864
90.0 0.5061 0.0625 0.05432
75.0 0.2531 0.03125 0.02716
60.0 0.1265 0.01562 0.01358
40.0 0.0633 0.00781 0.00697
20.0 0.0316 0.00391 0.00339
10.0 0.0158 0.00195 0.00170
5.0 0.0079 0.00098 0.00085
2.0 0.0040 0.00049 0.00042
0.0 0.0020 0.0 0.0
0.0010
Contour values for POTE, NOSQUARE, ATOM and DIFF settings have also corresponding negative values.
The VIEW directive is only relevant when generating perspective plots, and when plotting via the J06HEF routine (not the default), and is used to specify the angle of view and viewing distance (Figure 4). The grid of electron densities or potentials define the z-values of the surface on a two-dimensional (x,y) grid of points covering the specified area of the molecular plane under investigation.
The directive consists of a single data line read to variables TEXT, THETAV,THETAH,DIST using format (A,3F).
TEXT should be set to the character string VIEW.
THETAV specifies the elevation of the view axis above the horizontal base-plane in degrees.
THETAH specifies the rotation of the vertical axis through the centre of the grid in a clockwise direction, in degrees (see Figure 4). For 0.0 < THETAH < 180.0, the surface appears to rotate in a clockwise direction as THETAH increases.
DIST specifies the viewing distance in Bohr.
The VIEW directive may be omitted, when THETAV and THETAH will given the value 30, and DIST will be set to the value of SIZE specified by the PLANE directive.
Example :
To view the surface edge-on along the y-axis, from a distance of 10 Bohr, the following data line should be presented :
VIEW 0.0 0.0 10.0
This directive is only relevant when generating perspective plots, and may be used to normalise the stereo-graphic projection to certain values of electron density or potential function. The directive consists of a single data line read to variables TEXT,SCAMAX,SCAMIN,FACTOR using format (A,4F).
TEXT should be set to the character string SCALE.
SCAMAX,FACTOR the grid of values to be plotted is scanned to detect all local maxima, which will appear as peaks on the project plot, and thus to determine VMAX, the value of the greatest maximum < SCAMAX. In the event that no such maximum is detected, VMAX will be set to SCAMAX. All maxima with a greater value than (VMAX*FACTOR) will appear as beheaded peaks on the final plot.
SCAMIN,FACTOR the grid of values is scaned to detect all local minima, which will appear as troughs on the projected plot, and thus to determine VMIN, the value of the lowest minimum > SCAMIN. In the event that no such minimum is detected, VMIN will be set to SCAMIN. All minima with a value less than (VMIN*FACTOR) will appear as 'beheaded' troughs on the final plot.
The projected plot will be normalised to (VMAX*FACTOR-VMIN*FACTOR). The SCALE directive may be omitted, when SCAMAX is set to 0.7, SCAMIN to -0.7 and FACTOR to 1.2.
The LABEL directive allows the user to specify the frequency of the contour heights that are labelled. The directive consists of a single data line read to variables TEXT, NLABEL using format (A,I).
TEXT should be set to the character string LABEL.
NLABEL is an integer used to control the frequency of the labelling. NLABEL contour heights will be labelled.
This directive is only valid when a CONTOUR NAG plot is produced. By default every second contour is labelled. If a user does not wish to have any contours labelled, it is suggested to set NLABEL to a very large integer.
Example :
LABEL 4
Invoking this directive, every fourth contour height will be labelled in the subsequent contour plot.
The NOKEY directive suppresses the contour key. The directive consists of a single data line containing the character string NOKEY. This directive is valid only when a CONTOUR NAG plot is produced.
This directive allows the user to specify the view generated by PERSPECT in default mode (J06HBF). The directive consists of a single data line read to variables TEXT, IROT using format (A,I).
TEXT should be set to the character string ROTATION.
IROT should be set to a integer in the range 0 to 3.
By default, IROT is set to 0. Each increment of IROT rotates the perspective view by 90 degrees through the centre of the vertical axis, in a clockwise direction. This directive is valid for only the default PERSPECT mode (J06HBF).
Example :
ROTATION 2
This will rotate the perspective view through 180 degrees, from the default setting.
This directive should not be confused with the TITLE directive in GRID MODE. The purpose of this directive is to allow the user to specify a title, that will be printed on the hardcopy graphical plot. The TITLE directive consists of two data lines, the first data line contains the character string TITLE in the first data field. Second data line contains the required title to be printed on the hardcopy graphics output, upto a maximum 80 character title is permitted.
This directive allows the user to specify the position of the hardcopy plot within the graphic frame. The WINDOW directive consists of a single data line read to variables TEXT,SMINX,SMAXX,SMINY,SMAXY using format (A,4F)
TEXT should be set to the character string WINDOW.
SMINX,SMAXX,SMINY,SMAXY specifies the position of the plot within the graphic frame. SMINX and SMAXX give minimum and maximum values in the x-direction, while SMINY and SMAXY give minimum and maximum vaules in the y-direction for a given plot. The parameters must be within 0.0 to 1.0.
For a contour plot, the WINDOW directive can be used to enlarge or reduce the size of the plot, the contour key box will also vary in size. The WINDOW directive is only valid for contour hardcopy plots.
Default values for the WINDOW parameters are:
SMIN = 0.0 SMAXX = 0.6 SMINY = 0.0 SMAXY = 0.8
Example :
WINDOW 0.1 0.65 0.1 0.85
This directive consists of a single data line read to the variables TEXT,NPLOT using format (A,I).
TEXT should specify the character string MULTPLOT.
NPLOT is an integer specifying the number of the plot within a single frame. This should be set to 1.
This directive should be used in the first PLOTMODE of a multi-frame plot run, this tells the job that subsequent plots are to be processed and this is the first plot. This directive is not required in a single plot job.
The purpose of this directive is to allow the user to have multi-frame plots produced in a single job. The directive consists of a single data line read to the character string NEXTFRAME.
This directive must be presented when ever a new plot is produced, except on the first plot. This directive is not required in a single plot job.
The ENDFRAME directive terminates a multi-frame plot job and should be presented in the last PLOTMODE of the job. The directive consists of a single data line read to the character string ENDFRAME. The NEXTFRAME directive should also appear in the last PLOTMODE.
This directive is used to specify the type of plot to be generated and to define the output medium for the graphical output. The directive consists of a single data line, the first two data fields of which are read to the variables TEXT,PLOT using format (2A).
TEXT should be set to the character string PTYPE.
PLOT should be set to the character string CONTOUR if a contour plot of the function is required, or to the character string PERSPECT if a perspective plot of the function is required.
Subsequent data fields are read in A-format, and specify the output media as detailed in Table 4, for the graphical output.
Table 4
_______
Parameters for the PTYPE directive.
Data Field Media Output
LINE lineprinter. Note that it is only possible
to generate a contour plot, and not a
perspective plot.
NAG if specified, a contour plot will be
generated via the NAG-GINO package. The hard
copy graphical output is generated on the
Benson plotter-B1130 (narrow drum). Valid
only with the CONTOUR sub-directive.
NAG routine used J06GBF.
J06HEF if specified, a perspective plot will be
generated via the NAG-GINO package. The
hard copy graphical output is generated on
the Benson plotter-B1130 (narrow drum).
Valid only with the PERSPECT sub-directive.
This directive will override the default
perspective plot.
NAG routine used J06HEF.
A perspective plot may be generated by just specifying PERSPECT in the PTYPE data line. The graphical plot will be generated by the NAG-GINO package. The hard copy plot is generated on the Benson plotter-B1130 (narrow drum). NAG routine used J06HBF.
Users are referred to the reference [7] for more detailed information on the NAG routines used in the Graphical Anaylsis program and the error codes that may be generated.
The PTYPE directive instructs the program to commence generation of the specified plot, and should be presented last in the PLOT MODE sequence of directives.
Example 1:
To generate a version of a contour plot on the Benson plotter, the user should present the following data line :
PTYPE CONTOUR NAG
Example 2:
To generate a perspective plot on the Benson plotter using the default option (J06HBF), the user should present the following data line :
PTYPE PERSPECT
The STOP directive consists of a single data line, with either of the character strings STOP or EXIT in the first data field, and indicates that no more GRID MODE or PLOT MODE data is to be processed. The STOP directive must be the last presented in the data input stream, the effect being to cause the program to terminate execution: any directives presented after STOP will be ignored.
A pictorial representation of the electronic charge distribution of a molecular system is provided by the construction of plots associated with:
The output generated by each MODE of the Graphical Analysis program is as follows.
BASIS MODE: output commences with an ordered list of basis functions and details of the molecular geometry, as read from the dump control section of the DUMP FILE. If the PRINT parameter on the second program data line is used a listing of the matrix eigen vectors as read from the nominated section of the DUMP FILE is printed, with each column containing the coefficients of the LCBF in a given molecular orbital.
GRID MODE: output commences with a summary of the options selected by the user. When generating a grid of atomic density differnce, the program will output details of the atomic SCF calculations performed. This output includes details of the basis set used, together with the final SCF results including total energy, kinetic energy, virial test, eigen values and vectors. Various intermediary results from the SCF calculations will be output if the ATOMSCF parameter of the IPRINT is used.
The co-ordinates of the points P1, P2 and P3, as specified by the PLANE directive are output as in the following example:
INPUT PLANE DEFINITION
X Y Z
P1 0.0 0.0 0.0
P2 0.0 1.0 0.0
P3 0.0 0.0 -1.0
Upon completion of grid construction, the program scans the grid to detect all local maxima and minima, which will be output to the printer. If the GVAL parameter of the IPRINT directive is used, the complete grid of values is output in a matrix labelled 'MATRIX OF GRID VALUES'. The columns and rows of this matrix are labelled by an index running from -NGRID/2 through zero to +NGRID/2, where NGRID is the integer parameter of the GRID directive.
PLOT MODE: output commences with a summary of the options selected by the user. If the LINE parameter of the PTYPE directive is used when generating a contour plot, there follows a plane definition normalized to one character displacements on the line printer plot, as follows:
NORMALISED PLANE DEFINITION (FOR 1 CHARACTER ON LINE PRINTER PLOT)
X Y Z
P1 0.0 0.0 0.0
P2 0.0 0.2 0.0
P3 0.0 0.0 -0.2
The co-ordinates of P1 denote the molecular co-ordinates corresponding to the centre of the line printer output. P2 denotes the molecular co-ordinates (relative to the molecular co-ordinates of the point P1) of a point displaced 1 character vertically from the centre of the line printer plot. P3 denotes the molecular co-ordinates (relative to the molecular co-ordinates of the point P1) of a point displaced 1 character to the right of the centre of the line printer plot. The line printer contour plot is framed in a grid of NGRID * NGRID characters. The axes of this plot are labelled in the same way as 'MATRIX OF GRID VALUES'. Each of the distinct function values for which contours are required is associated with a given plotting character. Contours of positive value will be labelled alphabetically, whilst numeric (0-9) and certain other characters are used to label contours of negative value. The characters, together with their associated values, are listed under the plot.
The possible ATMOL error codes with a brief explanation are given in the following table:
Error Code Explanation
__________ ___________
16 Directive unknown.
50 Invalid parameter in WIDTH pre-directive.
61 Index block of DUMP FILE is not in correct
format.
62 ATMOL block with invalid checksum has been read,
or input/output error on ATMOL file. If the latter,
a finite VSOS error code will be given whose
explanation will be found in [8].
63 An attempt has been made to use a section number on a
DUMP FILE outside the allowed range.
64 Section number specified on input has not been
defined on the DUMP FILE.
65 Section specified on the DUMP FILE is of the wrong
TYPE.
66 ATMOL data set not assigned.
67 Illegal search of an ATMOL data set.
68 A data field was read in F-free format, and an illegal
character was found.
69 A data field was read in I-free format, and an illegal
character was found.
71 The program has attemped to expand the DUMP FILE
beyond its maximum size.
72 An attempt has been made to overwrite a section
on the DUMP FILE with a section of greater length.
666 End of file condition detected on FORTRAN stream 5.
The program expects more data.
700 Mode not known. This error may occur when attempting
to interpret a MODE directive, and may be caused by
a faulty ordering of directives.
701 Illegal value for NBASIS (1 10**(-3) and
< 10**(4).
722 Invalid number of contours specified in the CVALUES
directive (should be 2< and <51).
724 An error has been detected in contour plotting routines.
This may be caused by the plotting algorithm 'breaking
down' for a specific contour : in such case details of the
'rogue' contour will be printed, allowing the user to
regenerate the plot, deleting the function value involved
by means of the CVALUES directive.
725 An error has been detected in the perspective plotting
routines, which are unable to generate a plot from the
grid of dunction values supplied.
728 The generation of a grid of electrostatic potentials has
been requested, when using a wavefunction constructed
from non-Gaussian orbitals.
730 An invalid parameter has been detected in the first data
line of a DIFFERENCE directive.
731 Invalid number of component grids specified on the DIFF
line (valid 1-15).
732 Invalid LABEL presented in the first data field of a grid
definition line of a DIFFERENCE directive.
734 The component grids specified in a DIFFERENCE directive are
not compatible. Note that all grids combined under control
of this directive must contain values of the same density
or potential function, and should have been created with
the same dimensions and PLANE specifications.
737 A grid retrieved by the DIFFERENCE directive is not complete.
This error should only arise when retrieving a grid of
potentials, and indicates that further restart jobs are
necessary to construct the grid.
740 Invalid number of parameters specified in VIEW directive.
741 Invalid number of parameters specified in SCALE directive.
742 An illegal parameter has been detected in a PTYPE directive.
743 Invalid number of parameters specified in WINDOW directive.
744 Invalid integer in ROTATION directive.
Valid integers are 0,1,2 or 3.
745 Values specified in the WINDOW directive are invalid.
SMINX must be less than SMAXX, SMINY must be less than SMAXY.
999 Insufficient main memory for the program to continue.
3333 AFN not recognized in the FILE pre-directive.
Error codes 718-721 (*) may only result when generating atom-difference grids, and are necessitated by the requirements of the Atomic SCF program.
The following examples do not illustrate all the features of Graphical Analysis program, only a guide is intended.
This example is based on the H2O molecule, the eigen vectors are taken from the closed shell SCF calculation [4]. The plane to be analysed is the yz plane, the same plane as specified by the H2O molecular geometry [2]. The mode of the graphic program is to calculate an atom difference plot. Grid values have been routed to section 10 of the DUMP FILE. A contour plot will be generated on line printer output.
/*JOB JOBNAME,ACCOUNT,ST=(C20,LP=1,WS=300),PW=PASSWWORD,TI=20,C=B
REQUEST,ED7V,RT=U.
ATTACH,ED3V,ACC=RW.
PATTACH,ATMOL.
PLOT.
####S
LPAGE 1
CHANGE ED3 ED3V ED7 ED7V
25 1 ED3
VECT 1
GRIDMODE
TITLE
H2O CONTOUR LINE PRINTER
PLANE
0 0 0
0 1 0
0 0 1
GTYP ATOM 10
PLOTMODE
PTYPE CONTOUR LINE
STOP
####S
As with the previous example, an atom difference plot is to be generated. This time a line printer and hardcopy NAG-GINO plot will be produced. The user will notice extra data lines in the JCL, this will invoke the transfer of the NAG-GINO plot grid to the UMRCC Benson plotters [3].
A title, as shown in PLOT MODE phase, will be printed on the hard copy plot. The LABEL directive has been used, to label every 4th contour.
/*JOB JOBNAME,ACCOUNT,ST=(C20,LP=1,WS=300),PW=PASSWWORD,TI=20,C=B
REQUEST,ED7V,RT=U.
ATTACH,ED3V,ACC=RW.
PATTACH,ATMOL.
PLOT.
PATTACH,PROCLIB.
BEGIN,,PLOTPEN,F=TAPE7.
####S
LPAGE 1
CHANGE ED3 ED3V ED7 ED7V
25 1 ED3
VECT 1
GRIDMODE
TITLE
H2O CONTOUR NAG-GINO
PLANE
0 0 0
0 1 0
0 0 1
GTYP ATOM 10
PLOTMODE
TITLE
ATOM DIFFERENCE PLOT CONTOUR
LABEL 4
PTYPE CONTOUR LINE NAG
STOP
####S
Again an atom difference plot is produced. The graphic analysis is based on a perspective plot. The VIEW directive has been used to view the graphic analysis, 45 degrees from the horizontal and vertical axis at a distance of 10 Bohrs, from the centre of the plane. A hard copy plot will be produced.
/*JOB JOBNAME,ACCOUNT,ST=(C20,LP=1,WS=300),PW=PASSWWORD,TI=20,C=B
REQUEST,ED7V,RT=U.
ATTACH,ED3V,ACC=RW.
PATTACH,ATMOL.
PLOT.
PATTACH,PROCLIB.
BEGIN,,PLOTPEN,F=TAPE7.
####S
LPAGE 1
CHANGE ED3 ED3V ED7 ED7V
25 1 ED3
VECT 1
GRIDMODE
TITLE
H2O PERSPECT NAG-GINO
PLANE
0 0 0
0 1 0
0 0 1
OCCDEF
2.0 1 TO 5
END
GTYP ATOM 10
PLOTMODE
TITLE
ATOM DIFFERENCE PLOT : PERSPECTIVE PLOT
VIEW 45 45 10
PTYPE PERSPECT J06HEF
STOP
####S
The following example illustrates a multi-plot job. Three plots are produced, ATOM DIFFERENCE, ELECTRON DENSITY and ELECTROSTATIC POTENTIAL plots, of the H2O molecule.
/*JOB JOBNAME,ACCOUNT,ST=(C20,LP=1,WS=300),PW=PASSWORD,TI=99,C=B,
ATTACH,ED3V,ACC=RW.
REQUEST,ED7V,RT=U.
PATTACH,ATMOL.
PLOT.
PATTACH,PROCLIB.
BEGIN,,PLOTPEN,F=TAPE7.
####S
LPAGE 1
CHANGE ED3 ED3V ED7 ED7V
25 1 ED3
VECT 1
GRIDMODE
TITLE
H2O ATOM DIFFERENCE
PLANE
0 0 0
0 0 1
0 1 0
GTYP ATOM 10
PLOTMODE
TITLE
MULTI-PLOT ATOM DIFFERENCE CONTOUR PLOT
LABEL 4
MULTPLOT 1
PTYPE CONTOUR NAG
GRIDMODE
TITLE
H2O ELECTRON DENSITY
PLANE
0 0 0
0 0 1
0 1 0
GTYP DENS 11
PLOTMODE
TITLE
MULTI-PLOT ELECTRON DENSITY CONTOUR PLOT
LABEL 4
NEWFRAME
PTYPE CONTOUR NAG
GRIDMODE
TITLE
H2O ELECTROSTATIC POTENTIAL
PLANE
0 0 0
0 0 1
0 1 0
GTYP POTE 12
PLOTMODE
TITLE
MULTI-PLOT ELECTROSTATIC POTENTIAL CONTOUR PLOT
LABEL 4
NEWFRAME
ENDFRAME
PTYPE CONTOUR NAG
STOP
####S
[1] D.Moncrieff and V.R. Saunders, ATMOL-Introductory Notes.
[2] D.Moncrieff and V.R. Saunders, ATMOL-Gaussian Integrals Program.
[3] GINO Manual (FORTRAN 77 Version), NWD 35 (second edition), November, 1985.
[4] D.Moncrieff and V.R. Saunders, ATMOL-SCF Program.
[5] D.Moncrieff and V.R. Saunders, ATMOL-APSG Program.
[6] D.Moncrieff and V.R. Saunders, ATMOL-Direct CI Program.
[7] The NAG Graphical Supplement Manual - Mark 2, 1st Edition, 1985; Cyber-205 Note, Number 34, UMRCC, March 1986.
[8] CDC VSOS Manual, Form 60459410, Control Data Corporation; VSOS Reference Manual, NAT 208, UMRCC, 1985.