Introduction Manual

Revision: 1.7 Date: 1997/08/14 14:14:00


Table of Contents


 





 
                                  PREFACE
                                  _______
 
    This manual gives an Introduction to the ATMOL programs, as implemented
on the Cyber-205 at UMRCC. This document is one  in  a  series  of  twelve,
supporting the ATMOL packages on the Cyber-205.
 
 
                               ATMOL MANUALS
                               _____________
 
 
                          1.   Introduction.
                          2.   Allocator.
                          3.   Gaussian Integrals.
                          4.   Gaussian Library.
                          5.   SCF.
                          6.   APSG.
                          7.   Transformation.
                          8.   Direct CI.
                          9.   Mulliken Analysis.
                         10.   Graphical Analysis.
                         11.   Property.
                         12.   Service.
 
 
 
                             TABLE OF CONTENTS
                             _________________
 
 
    1.   Introduction.                                               1
    2.   FORTRAN Data Sets.                                          2
    3.   Data Input Conventions.                                     3
    4.   ATMOL Files.                                                4
    5.   File Transfer.                                              6
    6.   The ATMOL DUMP FILE.                                        8
    7.   The Pre-Directives.                                         8
      7.1   The WIDTH Pre-Directive.                                 8
      7.2   The FILE Pre-Directive.                                  9
      7.3   The LPAGE Pre-Directive.                                 9
      7.4   The MEMORY Pre-Directive.                               10
      7.5   The TIME Pre-Directive.                                 10
    8.    Error Monitoring.                                         12
 
 
 

Introduction


ATMOL is an integrated suite of programs for the calculation of molecular electronic wavefunctions and their properties. Program communication is provided by means of a common filing system, and thus occurs at dataset level. A free format data input system is provided throughout the system, which provides another unifying feature. The present note gives an overall description of the system as available on the CDC Cyber-205 at UMRCC. Currently available programs are:
INTEGV
Gaussian integrals for s,p and d functions. Cartesian and spherical gaussians can be used.
LIBV
To maintain a library of basis functions for INTEGV.
INTEGW
Gaussian integrals for s,p,d,f,g,h and i functions. Only spherical gaussians can be used.
LIBW
To maintain a library of basis functions for INTEGW.
SCF
To carry out closed and open shell restricted or unrestricted Hartree-Fock calculations. The code also incorporates a molecular orbital (MO) localization procedure due to Boys, and a coupled Hartree-Fock scheme for the calculation of NMR spin-spin coupling constants.
APSG
To carry out perfect pairing multi-configuration SCF calculations on closed shell molecules. Anti-symmetrized products of strongly orthogonal geminals (APSG) may also be optimized.
MULL
To perform a Mulliken population analysis.
PLOT
To produce contour plots of electron density or electrostatic potentials. Atom difference plots may also be produced.
PROP1E
To evaluate 1-electron properties of molecular wavefunctions.
TRAN
To transform molecular integrals from an atomic orbital (AO) to a MO basis.
DIRECT
A general purpose direct configuration interaction (CI) code capable of allowing single and double excitations from an arbitrary root set.
SERV
A program for copying and manipulating ATMOL files.
All the above programs are stored as executable load modules in a pool called ATMOL.

Typical UNIX, to access INTEGV, SCF, TRAN and DIRECT in sequence for example, would look like:

 
      #!/bin/csh
      INTEGV << **
      .
      .
      Data for INTEGV.
      .
      .
      **
      SCF << **
      .
      .
      Data for SCF.
      .
      .
      **
      TRAN << **
      .
      .
      Data for TRAN.
      .
      .
      **
      DIRECT << **
      .
      .
      Data for DIRECT.
      .
      .
      **
Typical JCL, to access INTEGV, SCF, TRAN and DIRECT in sequence for example, would look like:
 
 
      .
      .
      .
      PATTACH,ATMOL.
      INTEGV.
      SCF.
      TRAN.
      DIRECT.
      .
      .
      .
      ####S
      .
      .
      Data for INTEGV.
      .
      .
      ####S
      .
      .
      Data for SCF.
      .
      .
      ####S
      .
      .
      Data for TRAN.
      .
      .
      ####S
      .
      .
      Data for DIRECT.
      .
      .
      ####S
 

FORTRAN Data Sets


ATMOL programs use FORTRAN streams as follows:
FORTRAN stream 5
This is used for card input. In default, data will be read from the VSOS file INPUT, which corresponds to data embedded in the job.
FORTRAN stream 6
This is used for lineprinter output. In default, printed output is routed to VSOS file OUTPUT, which causes it to be sent to the print queue on the front end machine, together with the dayfile.
FORTRAN stream 7
This stream can be used by some ATMOL programs (LIBV, LIBW, SCF, APSG, PLOT and SERV) for producing punched card output.
Some ATMOL programs (LIBV, LIBW, SCF, APSG, PLOT and SERV) are capable of producing punched card output using FORTRAN stream 7. In default, such output will be routed to a VSOS file TAPE7, which will have VSOS RT=R. TAPE7 should thus be REQUESTed by means of the following JCL:
 
      REQUEST,TAPE7,RT=R.
It is possible to change the routing of the above FORTRAN datasets. Suppose for example it is desired to send the printed and punched output of the SCF program to VSOS files SCFPR and SCFPU respectively, and to read the card input from VSOS file SCFDAT. The following JCL should be used:
 
      SCF**SCFDAT,SCFPR,SCFPU,TAPE5=SCFDAT,TAPE6=SCFPR,TAPE7=SCFPU.
when invoking the SCF program.


Data Input Conventions


An ATMOL data line consists of a number of data fields, the fields being separated by at least one space character. The separating spaces are not considered part of the data field. Data lines normally end at column 72, although this can be altered by means of the pre-directive WIDTH (see below). A data field consists of a succession of non-space characters on a single line. Three types of field are in use:
  1. A-fields are used for the introduction of textual material, in the form of character strings. The maximum length of an A-field is 8 characters. A-fields of less than 8 characters are padded to the right with spaces, while if more than 8 characters are found, the field is truncated from the right, so that only the leftmost 8 characters are significant.
  2. I-fields are used for the introduction of numeric data in the form of integers, and consist of a succession of decimal digits possibly preceded by a + or - sign. The sign character may be omitted, when the integer is assumed to be positive. The following are examples of valid I-fields:
     
          0
          762
          +4033
          -6149
    
  3. F-fields are used for the input of floating point numbers. They are as I-fields except that a 'decimal point' character may appear to the right of the sign character. To introduce a decimal exponent a concatanation of a F-field, followed by the character E or D, followed by an I-field, without intervening blanks is allowed. The following are equivalent F-fields:
     
          0      .0      0.      0.0      +0.0
    
    as are:
     
          0.0001      1E-4      1D-4      0.1E-3     +10E-5
    
    and:
     
          -100.0       -100      -1E2      -1E+2      -1D+2
    

Format descriptors are used to describe a data line. The simplest of these takes the form nA, or nI or nF, where n is a decimal integer. Thus the format nF describes a line consisting of n successive F-fields. The omission of the integer (n) before a letter code implies that n=1. More complicated descriptors are used; for example (iA,jI,kF) describes a line consisting of i A-fields, followed by j I-fields, followed by k F-fields. Consider the following line:

 
           FOLD 11 2 88.3 PRINT
read to the variables TEXT,I,X,Y,BTEXT in format (A,I,2F,A).
 
      TEXT    will be set to the character string FOLD.
      I       will be set to the decimal integer 11.
      X       will be set to the floating point value 2.0.
      Y       will be set to the floating point value 88.3.
      BTEXT   will be set to the character string PRINT.
The same line could be read to variables TEXT,X,Y,ATEXT,BTEXT in format (A,2F,2A), so that:
 
      TEXT    will be set to the character string FOLD.
      X       will be set to the floating point value 11.0.
      Y       will be set to the floating point value 2.0.
      ATEXT   will be set to the character string 88.3.
      BTEXT   will be set to the character string PRINT.
Consider reading the following line:
 
             THIS IS A LONGSTRING
to (A(I),I=1,4) in format (4A).
 
      A(1)    will be set to the string THIS.
      A(2)    will be set to the string IS.
      A(3)    will be set to the string A.
      A(4)    will be set to the string LONGSTRI. 
              Note the truncation.

Data input to ATMOL programs is largely structured as a sequence of 'directives'. Directives sometimes extend over many lines, sometimes they comprise a single line, and usually contain some reasonably self-contained data, built up out of A,I, and/or F-field. Directives commence on a new line, and the first field of a directive is invariably an A-field, carrying the name of the directive. Usually directives can be processed in any order. However, occasionaly the order in which directives must be presented is fixed, or the significance of the data is order dependent. Such cases are specifically noted in the documentation of the individual programs.


ATMOL Files


ATMOL generated datasets are built up out of 512 word records, each record being referred to as a block. The last word in the block is used to store block control information, and is unavailable for data. Thus each block can contain a maximum of 511 data words. Such blocks are stored in VSOS disc files of RT=U, and in default the VSOS local file name (LFN) is the same as the ATMOL file name (AFN), valid AFNs being ED0, ED1, ED2, ED3, ED4, ED5, ED6, ED7 and MT0, MT1, MT2, MT3, MT4, MT5, MT6, MT7. AFNs may be specified within the data input to control the routing of datasets. The pre-directive FILE (see below) may be used in all ATMOL programs to associate a file with a given VSOS LFN with a given AFN.

ATMOL blocks are referred to by block number, the first accessible block being block 1, the second as block 2, etc. When an ATMOL block is written, all other blocks in the file remain uncorrupted. Any block may be written at any time, so it is for example possible to commence output at block numbers other than 1.

Some of the ATMOL files are used throughout the package to store specific data. The AFN's by default have the following meaning:

ED0
This file contains the basisset if the basisset was extract from the Gaussian Library. The file may be read by the integral programs.
ED1
This file contains symmetry adapted integrals that are generated by and used in a MCSCF calculation.
ED2 (MAIN FILE)
This file contains the integrals as generated by the integral programs.
ED3 (DUMP FILE)
This file is used to communicate among the various ATMOL programs. It is perhaps the single most important file in a calculation, see also "the ATMOL DUMP FILE".
ED4
This file contains half transformed integrals that are generated in a integral transformation run.
ED6
This file contains the final transformed integrals as generated by a integral transformation run.
ED7
This file is a scratch file used and generated by the direct CI program.
The above information is especially useful for large calculations in which not all file can be kept throughout the complete run. It may help you to decide which file should be thrown away at what stage.


File Transfer


Due to finite disc capacity, datasets are not secure on the Cyber-205 disc packs. For this reason it is prudent to backup Cyber-205 datasets on the Amdahl. The Remote Host Facility (RHF) is the software which enables communication between the Cyber-205 and the Amdahl. The task which runs on the Cyber-205 to invoke file transfer is called MFLINK. The user is directed to Appendix 2 of [1] to see the syntax of MFLINK, GETFEP and PUTFEP commands, the latter two having been supplied by UMRCC as an easier user interface for file transfer. For ATMOL files the data conversion mode should be set to DD=UU (MFLINK) or FO=BINARY (PUTFEP,GETFEP). For PUNCHed datasets the data conversion mode should be set to DD=C8 (MFLINK) or FO=TEXT (PUTFEP,GETFEP), since these are in card image format. The use of the MFLINK, PUTFEP and GETFEP commands is illustrated in the following examples.

example 1

The MFLINK command is used to create a backup of a MAINFILE dataset, ED2V, on the Amdahl. If the Cyber-205 job is running under account AABBBBB, the Amdahl backup file will be created under catalogue entry AA.BBBBB, so its fully qualified name will be AA.BBBBB.AMDED2V. Approximately 4.5 ATMOL blocks can be stored in one track of an Amdahl disc.
 
     PATTACH,ATMOL.
     REQUEST,ED2V,RT=U.
     REQUEST,ED3V,RT=U.
     INTEGV.
     .
     .
     MFLINK,ED2V,ST=AMD,DD=UU,JCS="CREATE,DSN=AMDED2V,UNIT=SYSDA,",
     "DCB=(RECFM=U,BLKSIZE=3665),DISP=NEW,SPACE=(TRK,(PRI,SEC))".

example 2

As example 1 except that the Amdahl dataset AMDED2V already exist.
 
     PATTACH,ATMOL.
     REQUEST,ED2V,RT=U.
     REQUEST,ED3V,RT=U.
     INTEGV.
     .
     .
     MFLINK,ED2V,ST=AMD,DD=UU,JCS="REPLACE,DSN=AMDED2V".

example 3

As example 1, using PUTFEP to create the Amdahl data set. Note that the pool PROCLIB must be attached.
 
     PATTACH,ATMOL.
     REQUEST,ED2V,RT=U.
     REQUEST,ED3V,RT=U.
     INTEGV.
     .
     .
     PATTACH,PROCLIB.
     BEGIN,,PUTFEP,ED2V,AMDED2V,FO=BINARY,ACTION=CREATE.

example 4

To restore the dataset AMDED2V back to the Cyber-205 and make the file permanent on the Cyber-205 disc packs.
 
     DEFINE,ED2V,RT=U.
     MFLINK,ED2V,ST=AMD,DD=UU,JCS="GET,DSN=AMDED2V".

example 5

The GETFEP directive maybe used in place of the MFLINK command detailed in the last example. Again, as in the PUTFEP directive, the pool PROCLIB must be attached.
 
     PATTACH,PROCLIB.
     DEFINE,ED2V,RT=U.
     BEGIN,,GETFEP,ED2V,AMDED2V,FO=BINARY.
In all the previous examples the transfer between the Amdahl and Cyber has been from disc to disc. For large files, 'back-ups' should be made on magnetic tape. For files over 10M bytes, it is recommended that transfer should be to tape via the Amdahl.

example 6

Consider example 1, but this time the transfer is to tape on the Amdahl. Assume that the tape in question is volume AL0001 and the dataset is the first one on this tape.
 
     PATTACH,ATMOL.
     REQUEST,ED2V,RT=U.
     REQUEST,ED3V,RT=U.
     INTEGV.
     .
     .
     MFLINK,ED2V,ST=AMD,DD=UU,JCS="CREATE,DSN=AMDED2V,",
     "UNIT=TAPE,VOL=SER=AL0001,DCB=(RECFM=U,BLKSIZE=19096),",
     "LABEL=(1,SL)".

example 7

Consider the transfer of the ED2V file to the same tape as in example 6, but this time using the PUTFEP directive.
 
     PATTACH,ATMOL.
     REQUEST,ED2V,RT=U.
     REQUEST,ED3V,RT=U.
     INTEGV.
     .
     .
     PATTACH,PROCLIB.
     BEGIN,,PUTFEP,ED2V,AMDED2V,FO=BINARY,ACTION=CREATE,VOL1=AL0001,SEQN=1.


The ATMOL DUMP FILE


The various ATMOL programs communicate by means of dataset, and the ATMOL DUMP FILE provides the most important mechanism for system communication. It is used in many ways, for example as a repository of the molecular geometry and basis function data, to store 1-electron integrals, and MO coefficient arrays etc. The first block of the DUMP FILE is known as the 'index block', the function of which is to facilitate the addressing of up to 204 separate 'sections' of the DUMP FILE. Each section will normally be used to store some relatively self contained data such as a MO coefficient matrix. Sections 1 to 190 are reserved for the user, and at many points in the data input for ATMOL programs the user is required to supply an integer defining the section number where data is to be written. Sections 191 to 204 are reserved for the system, current useage being

191
Created by INTEGV or INTEGW and used to store molecular geometry and basis set data, plus restart control information for the integrals programs.
192
Created by INTEGV or INTEGW and used to store 1-electron over AOs. Overlap, kinetic energy, nuclear attraction and dipole integrals are stored.
198
Created by TRAN and used to store a 1-electron Fock operator in a MO basis.
203
Restart control information for TRAN.
Every section is associated with a TYPE parameter. For example, sections used to store MO coefficient arrays are of TYPE 3. The TYPE parameter provides a simple checking mechanism when sections are read from the DUMP FILE. It is possible to overwrite sections with data of another TYPE. However, it is not possible to overwrite sections with data which requires more space than that allocated when the section was first created.


The Pre-Directives


Every ATMOL program is capable of processing a set of 'pre-directives', each such directive extending over one line, and appearing as input data before the program specific data. The pre-directives can be processed in any order, and are as follows:


The WIDTH Pre-Directive

The default width of an ATMOL data line is 72 characters. The WIDTH pre-directive may be invoked to alter the line width, and is read to TEXT,NWIDTH using format (A,I).

TEXT
should be set to the character string WIDTH.
NWIDTH
specifies the line width. The maximum line width is 80 characters, and attempts to set a greater width will result in the program selecting this maximum.


The FILE Pre-Directive

This pre-directive can be used to associate a file of a given VSOS LFN with a given AFN. The basic form of the directive is read to variables TEXT,AFILE,VFILE in format (3A).

TEXT
should be set to the character string FILE, although CHANGE or SWITCH are also acceptable.
AFILE
should contain a valid AFN.
VFILE
should contain a VSOS LFN, and consists of up to 7 characters.

example 1:

 
      FILE ED2 MFILE
will cause ATMOL to process the VSOS file MFILE as ATMOL file ED2.

In fact, it is possible to specify more than one AFILE,VFILE pair of parameters on a FILE pre-directive.

example 2:

 
      FILE ED2 MFILE ED3 DFILE
is equivalent to:
 
      FILE ED2 MFILE
      FILE ED3 DFILE


The LPAGE Pre-Directive

All ATMOL programs except LIBV, LIBW and SERV use unlabelled COMMON as a stack, for storing large arrays. In the Cyber-205 versions, unlabelled COMMON has been placed in the 'large page' memory region, a large page being a block of 65536 words of main memory. The number of large pages allocated to a job is as specified on the LP parameter of the job card, (or zero in default). It is necessary for most ATMOL programs to know the number of large pages in use, and the LPAGE pre-directive has been implemented to allow this. It is read to TEXT,NLP in format (A,I).

TEXT
should be set to the character string LPAGE, although LP is also acceptable.
NLP
specifies the number of large pages the program is allowed to use. Normally it should not exceed the LP parameter on the job card, or an excessive number of large page faults will be generated. The pre-directive can be omitted, when the default NLP=3 will be assumed, in which case the user should request at least 3 large pages on the job card.

Note that the total main memory used by a program must also incorporate the small page region, wherein the program instructions and small arrays are stored. The total memory allocation is controlled by the WS parameter of the job card, which allocates memory in 512 word blocks. There are 128 memory blocks per large page, and we recommend that the WS parameter be related to the LP parameter of the job card according to:

 
      WS = (LP + 1) * 128
thus ensuring an allocation of 128 memory blocks for the small page region. If the small page region is made much smaller than this, a large number of small page faults will usually result.


The MEMORY Pre-Directive

This pre-directive provides another mechanism for specifying the size of unlabelled COMMON, and is read to TEXT,NW in format (A,I).

TEXT
should be set to the character string MEMORY, although STORE and CORE are also acceptable.
NW
specifies the length of blank COMMON in units of words. Note that it is most sensible for NW to be a multiple of 65536 on the Cyber 205. In any event NW should not be greater than the large page allocation (as specified in the job card) multiplied by 65536.

Example:

 
      MEMORY 65536
is equivalent to:
 
      LPAGE 1


The SHORT Pre-Directive

The programs INTEGV, INTEGW, SCF, MCSCF, and DIRECT are able to produce a short version of the output. This short output contains only the very essential data from a job. This option can be activated using the SHORT pre-directive, with the syntax:

    SHORT FILENAME [ NOECHO ]
where
SHORT
is a literal string.
FILENAME
is a string defining the file on which the short output should be written. If FILENAME is an existing file then the short output will be appended to it.
NOECHO
is a literal string telling the program not to echo the input to the short output file. By default all input will be echoed to the short output.


The TIME Pre-Directive

The programs INTEGV, SCF, APSG and TRAN monitor the time available at intervals. If it is found that insufficient time remains to usefully continue, these programs will send restart control information to the DUMP FILE, and terminate execution. In default, these programs obtain the time remaining at the beginning of the job step (TIMLIM) by means of a call to VSOS. When the time consumed by the job step approaches TIMLIM, the dumping action takes place. The TIME directive has been implemented to allow the user to specify or alter TIMLIM, and is read to TEXT,TIMEX in format (A,F).

TEXT
should be set to the character string TIME.
TIMEX
If positive, then TIMLIM will be set equal to TIMEX. If negative, then TIMEX will be added to TIMLIM, thus reducing the time apparently available to the job, and thereby increasing the probability that successful dumping action will be taken. TIMEX should be specified in units of seconds.

Note that ATMOL programs actually monitor resource utilization in system billing units (SBUs), which include charges for input/output, page faults, CPU utilization etc.


The SIGNAL Pre-Directive

The ATMOL programs have a facility for catching signals from the operating system. This signal facility may be switched 'on' or 'off' by the SIGNAL Pre-Directive. The syntax of the pre-directive is:

      TEXT OPTION
where
TEXT
This should be set to the literal string SIGNAL.
OPTION
This should be set to either the literal string OFF or the literal string ON to switch the signal handling off or on respectively.
Note that by default the signal handling is switched on.

The signal handler catches the following user signals:

Signal 15 (SIGTERM)
Sending this signal causes the program to flush the standard output buffer, close all files and terminate the program.
Signal 16 (SIGUSR1)
Sending this signal causes the program to flush the standard output buffer. The program continues after the signal is handled. This is useful in long runs when one wants to view the output that is pending in the output buffer.
Signal 17 (SIGUSR2)
Sending this signal causes the program to flush the standard output buffer and reset the time limit to zero. The program continues execution until the first appropriate point to orderly terminate.
Note that if the signal handling is off sending these signals will cause the program to EXIT.

Example:

Specifying the pre-directive
      SIGNAL ON
witches the signal handling on. After this sending signal 16 to an ATMOL program running under UNIX with process identifier PID (where PID is an integer)
      kill -16 PID
will cause the program to flush the standard output buffer.


The ATMOL Comment Lines


All ATMOL programs are capable of handling comment lines. A comment line is a line of input starting with a *, ?, < or >. These lines are echoed to the standard output and have no effect in the execution of the program. Some examples of comment lines are:
    Example:

      * SYMDET
      ? SINGLE 3 5 8 0
      < ACCURACY 40 80
      > FULLCI 13 2 2

Error Monitoring


All ATMOL programs examine data input for logical consistency, and seek to determine if internal array sizes would be exceeded. In the event of error, the following message will be sent to the lineprinter:

 
      *** ATMOL ERROR  nnnn ***
where nnnn represents a decimal integer, known as the error code. The meaning of the error code is normally program specific, but certain error codes have system wide applicability, as follows:
 
  Error Code   Explanation
  __________   ___________
 
          50   Invalid parameter in WIDTH pre-directive.
          61   Index block of DUMP FILE 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 the CDC
               VSOS manual.
          63   A DUMP FILE Section number outside the allowed range of
               1 to 190 has been specified.
          64   Undefined DUMP FILE Section retrieved.
          65   A DUMP FILE Section is of the wrong TYPE.
          67   Illegal search of an ATMOL file.
          68   Illegal character found in F-format data field.
          69   Illegal character found in I-format data field.
          71   An attempt has been made to expand the DUMP FILE beyond
               its maximum size (as specified by a SIZE directive).
          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.
         999   Insufficient main memory for the program to continue.
        3333   AFN not recognized in the FILE pre-directive.