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.
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:
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
ATMOL programs use FORTRAN streams as follows:
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.
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:
0
762
+4033
-6149
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, occasionally 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:
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.
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.
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))".
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".
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.
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".
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.
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)".
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 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 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.
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 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.
FILE ED2 MFILE ED3 DFILE
is 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) * 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.
This pre-directive provides another mechanism for specifying the size of unlabelled COMMON, and is read to TEXT,NW in format (A,I).
MEMORY 65536
is equivalent to:
LPAGE 1
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:
TEXT OPTION
where
Note that by default the signal handling is switched on.
The signal handler catches the following user signals:
Note that if the signal handling is off sending these signals will cause the program to EXIT.
Specifying the pre-directive
SIGNAL ON
Switches 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.
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
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.