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
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
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.
0 762 +4033 -6149
0 .0 0. 0.0 +0.0as are:
0.0001 1E-4 1D-4 0.1E-3 +10E-5and:
-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 PRINTread 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 LONGSTRINGto (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 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:
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  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.
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))".
PATTACH,ATMOL. REQUEST,ED2V,RT=U. REQUEST,ED3V,RT=U. INTEGV. . . MFLINK,ED2V,ST=AMD,DD=UU,JCS="REPLACE,DSN=AMDED2V".
PATTACH,ATMOL. REQUEST,ED2V,RT=U. REQUEST,ED3V,RT=U. INTEGV. . . PATTACH,PROCLIB. BEGIN,,PUTFEP,ED2V,AMDED2V,FO=BINARY,ACTION=CREATE.
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.
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)".
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 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
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 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).
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).
FILE ED2 MFILEwill 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.
FILE ED2 MFILE ED3 DFILEis equivalent to:
FILE ED2 MFILE FILE ED3 DFILE
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).
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) * 128thus 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.
This pre-directive provides another mechanism for specifying the size of unlabelled COMMON, and is read to TEXT,NW in format (A,I).
MEMORY 65536is equivalent to:
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
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).
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 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:
The signal handler catches the following user signals:
SIGNAL ONwitches 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 PIDwill cause the program to flush the standard output buffer.
Example: * SYMDET ? SINGLE 3 5 8 0 < ACCURACY 40 80 > FULLCI 13 2 2
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.