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 SERV program provides data handling facilities commonly required when handling ATMOL files, and is oriented towards manipulation of MAINFILE datasets in particular. The program will copy, list, check, summarize, edit etc such files. To invoke the SERV program on the Cyber-205 at UMRCC, use the following JCL:
PATTACH,ATMOL.
SERV.
Data input and printed output is on FORTRAN streams 5 and 6 respectively. There is normally no need to mention these streams in the JCL. Punched output, if requested, is routed to FORTRAN stream 7, and in such cases the user should request a VSOS file with record type, RT=R [1], and VSOS local file name TAPE7.
ATMOL datasets may be assigned using any ATMOL file name (AFN). Some functions of SERV (specifically COPY, EDIT, COPYDUMP and MERGE) require input and output areas on ATMOL files. It is possible for input and output to be taken from the same ATMOL file, with certain restrictions which apply when the input and output areas overlap. The following rules apply:
The SERV program does not require the use of large pages, so the MEMORY and LPAGE pre-directives [2] are of no significance. The program does not monitor time, so that the TIME pre-directive is also irrelevant; only the WIDTH and FILE pre-directives are applicable, and should be presented before the program specific data.
SERV is a collection of routines, which may be called in any order, as dicated by the user. Each routine will require some input data, and will perform a task. When the task is complete, control is handed to the next routine nominated by the user. On successful completion, all routines reply with the printed message:
NAME COMPLETED
where NAME is the name of the routine. The routines will now be described in turn.
Data is read to TEXT,DDSCAN,IBLK in format (2A,2I).
TEXT should be set to the string SCAN.
DDSCAN specifies the AFN of the dataset to be SCANned.
IBLK specifies the starting block for the SCAN operation. Alternatively the character * may be used, when the SCAN will commence from the 'current position' of the file. Note that at the start of execution all files are positioned at block 1. The syntax '* + m' or '* - m' where m is an integer may also be used, when IBLK will be the 'current position' + or - m respectively.
SCAN will read the nominated dataset from the block specified by the IBLK paramter, until an ENDFILE block is detected. The dataset will be positioned immediately after the ENDFILE block on termination of the operation. SCAN will read blocks with invalid checksum words without diagnosing an error.
Example:
To position MT4 immediately after the third ENDFILE block:
SCAN MT4 1
SCAN MT4 *
SCAN MT4 *
Data for LIST is read to TEXT,DDLIST,IBLK,NBLK in format (2A,2I).
TEXT should be set to the string LIST.
DDLIST should be set to the AFN of the input dataset.
IBLK specifies the starting block number of the file to be LISTed. The * or * + m or * - m formats can be used, as in SCAN described above.
NBLK specifies the number of blocks to be LISTed. If NBLK is set to zero (or omitted), listing continues until an ENDFILE block is detected.
A list of the 2-electron integrals, with associated indices (labelled I, J, K and L) in the dataset assigned with AFN DDLIST will be printed on FORTRAN stream 6. Listing commences from the block specified and continues for NBLK blocks (or to an ENDFILE block if NBLK=0).
Example 1:
LIST ED6 * + 1 0
If the above is presented prior to any other operation on ED6, (which will therefore be positioned at block 1), then ED6 will be listed from block 2 (* + 1 = 2) until an ENDFILE block is detected.
Example 2:
To list MT5 from block 98 for 5 blocks:
LIST MT5 98 5
Data for the PUNCH directive is read to TEXT,DDPUNC,IBLK,NBLK in format (2A,2I).
TEXT should be set to the string PUNCH.
DDPUNC should be set to the AFN of the input dataset.
IBLK specifies the starting block of the input file. The * or * + m or * - m formats may be used, as in SCAN described above.
NBLK specifies the number of blocks to be PUNCHed. If NBLK is zero (or omitted), the file will be PUNCHed until an ENDFILE block is detected.
The 2-electron integrals, with associated indices, as stored on the ATMOL file specified by the DDPUNC starting at block IBLK for NBLK blocks (or until an ENDFILE block is detected if NBLK=0) will be punched on FORTRAN stream 7. Each line is produced by the FORTRAN code of the form:
WRITE(7,1)ISEQ,N,(I(M),J(M),K(M),L(M),G(M),M=1,N)
1 FORMAT(I4,I2,2(4I4,F17.10)
where
ISEQ is a card sequence number.
N is an integer whose value may be 1 or 2.
I,J,K,L,G are arrays to hold the indices and values respectively of up to two integrals. ATMOL blocks normally contain 340 integrals, so each block is likely to produce 170 punched records.
Example 1:
PUNCH MT1 75 5
MT1 will be PUNCHed starting at block 75 for 5 blocks.
Example 2:
PUNCH ED2 * 0
ED2 will be PUNCHed from the current position (block 1 if first access) until an ENDFILE block is detected.
Data for SUMMARY is read to TEXT,DDSUM,IBLK,NBLK in format (2A,2I).
TEXT should be set to the string SUMMARY.
DDSUM should be set to the AFN of the dataset to be summarised.
IBLK specifies the starting block of the input file. The * or * + m or * - m formats may be used, as in SCAN described above.
NBLK specifies the number of blocks to be summarised. If NBLK is set to zero (or omitted), the file will be summarised until an ENDFILE block is detected.
SUMMARY causes one printed line per ATMOL block, each block being assumed to be used for the storage of 2-electron integrals. The printing consists of the first and last 2-electron integral in the block (with associated indices) plus the number of integrals stored in the block.
Example:
SUMMARY MT4 1 0
MT4 is summarised from block 1 until an ENDFILE block is detected.
Data for CHECKSUM is read to TEXT,DDCHEK,IBLK,NBLK in format (2A,2I).
TEXT should be set to the string CHECKSUM.
DDCHEK should be set to the AFN of the dataset to be CHECKSUMmed.
IBLK specifies the starting block of the input file. The * or * + m or * - m formats can be used, as in SCAN described above.
NBLK specifies the number of blocks to be CHECKSUMmed. If set to zero (or omitted), the dataset will be CHECKSUMmed until an ENDFILE block is detected.
CHECKSUM scans the nominated blocks of the stated dataset. Blocks with an invalid checksum words cause the message:
BLOCK x CHECKSUM ERROR
to be printed, where x is the block number. ENDFILE blocks give rise to the message:
BLOCK x ENDFILE
Example:
CHECKSUM ED2 1 999
ED2 will be CHECKSUMmed from block 1 for 999 blocks.
CHECK provides a more complete check facility for a 2-electron integral file than is provided by CHECKSUM. Data is read to TEXT,DDCHEK,IBLK,NBLK,FP,FN in format (2A,2I,2F).
TEXT should be set to the string CHECK.
DDCHEK specifies the AFN of the input dataset.
IBLK specifies the starting block of the input dataset. The * or * + m or * - m formats may be used, as in SCAN described above.
NBLK specifies the number of blocks to be CHECKed. If NBLK is zero, CHECKing continues until an ENDFILE block is read.
FP is a positive valued variable whose value is used to monitor positive valued 2-electron integrals. If such an integral is found to be greater than FP, its value plus associated indices is printed.
FN is a positive valued variable. If the absolute value of a negative value 2-electron integral is found to be greater than FN, its value plus its associated index is printed. FN may be omitted, when it will be assigned the value 0.5. If FN is omitted, then FP may also be omitted when the latter will be assigned the value 5.0.
CHECK reads the nominated blocks of a given dataset, printing messages if unusual conditions are met. The printing is of the general form:
BLOCK x message
where x is the block number, and 'message' denotes explanatory text, as follows:
Message Explanation
_______ ___________
CHECKSUM ERROR The block has an invalid checksum word.
NOT MAINFILE The block is not in MAINFILE format.
ENDFILE An ENDFILE block has been read.
G,I,J,K,L= The characters g,i,j,k,l correspond to the
g,i,j,k,l value and associated indices respectively of a
2-electron integral. A +ve integral whose value
is greater than FP, or a -ve integral whose
absolute value is greater than FN has been read.
Example :
CHECK MT5 * 0 8 .3
MT5 will be CHECKed from the current position to an ENDFILE block. Positive integrals greater than 8.0 or negative integrals with absolute values greater than 0.3 will be flagged.
Data for COPY is read to TEXT,DDIN,IBLK,DDOUT,JBLK,NBLK in format (2A,I,A,2I).
TEXT should be set to the string COPY.
DDIN specifies the AFN of the input dataset.
IBLK specifies the starting block of the input dataset. The * or * + m or * - m formats may be used, as in SCAN described above.
DDOUT specifies the AFN of the output dataset.
JBLK specifies the starting block of the output dataset. The * or * + m or * - m formats may be used, as in SCAN described above.
NBLK specifies the number of blocks to be copied. If NBLK is zero (or omitted), the copy continues until an ENDFILE block is read from the input file. In this case the ENDFILE block is copied to the output file.
Example 1:
COPY ED2 11 MT2 * 0
ED2 will be copied from block 11 until an ENDFILE block is detected, the copied blocks being routed to MT2 starting at the current position.
Example 2:
COPY ED4 500 ED4 499 10
The above illustrates a valid 'intra' dataset copy with overlapping input and output areas. The effect is to move the information one block down the dataset.
Example 3:
COPY ED4 500 ED4 501 10
The above illustrates an invalid 'intra' dataset copy. An error will be diagnosed when block 501 is read, since it will have been overwritten by the copied block 500.
EDIT is used to selectively copy MAINFILE datasets. Integrals whose absolute value are less than an input threshold are not copied to the output dataset. The first line of data is read to TEXT,DDOUT,JBLK,IACC in format (2A,2I).
TEXT should be set to the string EDIT.
DDOUT specifies the AFN of the output dataset.
JBLK specifies the starting block of the output dataset. The * or * + m or * - m formats may be used, as in SCAN described above.
IACC the quantity 10**(-IACC) is calculated, and used as the threshold.
Subsequent lines define the input files, each line being read to DDIN,IBLK,LBLK in format (A,2I). An EDITed copy of the dataset specified by DDIN starting at block IBLK and continuing up to but not including LBLK will be for output. Thus LBLK-IBLK blocks of the input file are read. The * or * + m or * - m formats may be used to specify IBLK, as in SCAN described above. If LBLK is zero (or omitted), EDITing will continue until an ENDFILE block is read from the input dataset. Further 'input file definition lines' may be presented, the output generated by each line being appended to the already generated EDIT output. The sequence is terminated by a line whose first field contains the string END. The routine will then append an ENDFILE block to the output dataset.
Example 1:
EDIT MT4 1 60
ED2 1 0
ED3 1 0
END
The MAINFILE held in two sections starting at block 1 of ED2 and ED3 is edited to MT4 starting at block 1, where it will be held as one section terminated by an ENDFILE block. The threshold of 10**(-60) ensures that all integrals are transcribed.
Example 2:
EDIT ED2 1 7
ED3 1 0
END
ED3 will be EDITed to ED2, both files commencing at block 1. The EDIT terminates when an ENDFILE block is read from ED3. The threshold is 10**(-7), so the output file would be expected to be shorter than the input file. Use of the output file would reduce the time required for an SCF cycle, for example. If an editing threshold of 10**(-7) is used, it is unreasonable to converge the SCF to an accuracy better than 10**(-4).
It is necessary to read the present notes in conjunction with the integrals program documentation [3], in particular the GTOS and MERGE directives thereof.
The MERGE idea is based upon the fact that frequently the user wishes to perform a calculation on a 'new' molecular system which is closely related to some previous studied 'old' system. Many of the integrals required in the 'new' calculation will be available from the 'old' calculation, and can be re-used. The basis functions of the 'new' calculation are classified as:
OLD Such functions appear in the 'old' calculation, centred at identical positions, and with identical radial and angular functional form.
NEW Such functions have no exact counterpart in the 'old' calculation.
The 2-electron integrals of the 'new' calculation may be classified thus:
MERGE extracts from the OLD FILE all integrals of the set X, and outputs these to the MERGEFILE. Note that an OLD function may have a different index in the 'new' calculation when compared with that in the 'old' calculation. For example, if the 'new' basis set differs from the old by the addition of a single function at the start of the 'new' basis set list, then all functions which appeared in the 'old' calculation indexed from 1 up will appear in the 'new' calculation indexed from 2 up. MERGE provides suitable re-indexing facilities. The NEW FILE and the MERGE FILE comprise the complete list of 2-electron integrals required, for example, by the SCF program [4], and should be presented to that program under control of its MFILE directive.
The first line of data for MERGE is read to TEXT,DDOUT,JBLK in format (2A,I).
TEXT should be set to the string MERGE.
DDOUT specifies the AFN of the output dataset, which is used to hold the MERGE FILE.
JBLK specifies the starting block of the MERGE FILE. The * or * + m or * - m formats may be used, as in SCAN described above.
The next phase of data input consists of a number of lines read to I,J,K in format (3I). Each line specifies that functions I to J (inclusive) in the 'old' calculation appear as OLD functions in the 'new' calculation, indexed K onwards. Such 'basis function re-indexing lines' should be presented until all OLD functions in the 'new' calculation have been re-indexed. The sequence is terminated by a line with the string END in the first data field.
The final phase of data input consists of a sequence of 'input file definition lines', each line being read to DDIN,IBLK,LBLK in format (A,2I). Each 'input file definition line' specifies a section of the input file (OLD FILE). Thus for each section, the dataset specified by DDIN will be read starting at block IBLK (* or * + m or * - m formats may be used) and continuing up to, but not including LBLK, so that the number of blocks read will be LBLK-IBLK. LBLK may be set to zero, when input processing continues until an ENDFILE block is detected.
All integrals involving four OLD functions (set X) will be transcribed to the MERGE FILE, with appropiate adjustment of the associated indices. The output generated by each section of the OLD FILE is appended to the MERGE FILE. When all the 'input file definition lines' have been presented, the sequence is terminated by a line with the string END in the first field. An ENDFILE block will be appended to the output file.
Example:
Consider the 25 basis function H2O monomer example shown in [3] [4]. Suppose now it is desired to add an s-orbital to the oxygen basis, this extra function appearing as basis function 5 in the 'new' calculation. Thus basis functions 1-4 of the 'old' and 'new' calculations are identical, while basis functions 5-25 of the 'old' calculation appear as functions 6-26 in the 'new'. The input OLD FILE is on ED2 starting at block 1. The MERGE FILE is to be routed to ED2 commencing at block 100. Data for MERGE would be:
MERGE ED2 100
1 4 1
5 25 6
END
ED2 1 0
END
Data for ENDFILE is read to TEXT,DDOUT,JBLK in format (2A,I).
TEXT should be set to the string ENDFILE.
DDOUT specifies the AFN of the output dataset.
JBLK specifies the block number where an ENDFILE block is to be written. The * or * + m or * - m formats may be used, as in SCAN described above.
Example:
To write an ENDFILE block to MT0 at the current position:
ENDFILE MT0 *
Data for COPYDUMP is read to TEXT,DDIN,IBLK,DDOUT,JBLK in format (2A,I,A,I).
TEXT should be set to the string COPYDUMP.
DDIN specifies the AFN of the input dataset.
IBLK specifies the starting block of the DUMPFILE on the input dataset. The * or * + m or * - m formats may be used, as described in SCAN above.
DDOUT specifies the AFN of the output dataset.
JBLK specifies the starting block of the output dataset. The * or * + m or * - m formats may be used as in SCAN described above.
The DUMP FILE resident on the dataset nominated by DDIN, and starting at block IBLK, is copied to the dataset nominated by DDOUT starting at block JBLK.
Example:
COPYDUMP ED2 1 MT2 *
The DUMP FILE at block 1 of ED2 is copied to MT2 at the current position.
Data for FINDDUMP is read to TEXT,DDIN,IBLK,NBLK,TEST in format (2A,2I,A).
TEXT should be set to the string FINDDUMP, (FINDUMP is also acceptable).
DDIN specifies the AFN of the input dataset.
IBLK specifies the starting block number of the input file. The * or * + m or * - m formats may be used, as in SCAN described above.
NBLK specifies the number of blocks to be read. NBLK may not be set to zero.
TEST should be set to one of the strings HIGH or LOW. If omitted the default is LOW.
The nominated blocks will be searched for evidence of DUMP FILEs. A summary of any DUMP FILEs detected will be printed, the scale of the printing being controlled by the setting of TEST. If TEST=HIGH, a fairly complete listing will be issued; if TEST=LOW, a minimal summary will be produced. FINDDUMP will skip blocks with invalid checksum words.
Example:
FINDDUMP ED3 1 600 HIGH
will cause the first 600 blocks of ED3 to be searched for DUMP FILES. A complete listing of any DUMP FILEs found will be produced.
The STOP directive must be the last presented, and consists of one line with either the string STOP or EXIT in the first field. All ATMOL files will be closed, and execution ended.
A brief explanation of the possible ATMOL error codes is given below:
Error Code Explanation
__________ ___________
16 Directive unknown.
42 AFN not recognized.
44 Input and output areas on the same file,
and an illegal 'overlap' situation has arisen.
45 Invalid re-indexing parameter in the MERGE option.
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 [1].
63 A DUMP FILE Section number outside the
allowed range 1 to 190 has been specified.
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.
450 The NBLK parameter in FINDDUMP is less than 1.
451 TEST parameter of FINDDUMP not recognized.
666 End of file condition detected on FORTRAN stream 5.
The program expects more data.
3333 AFN not recognized in the FILE pre-directive.
The following job is used to copy a MAINFILE dataset from block 1 of ED4 to block 1 of MT4, the copy operation being terminated when an ENDFILE block is detected. The next stage of the job consists of copying a DUMP FILE from ED4 (at block 600) to MT4, starting at the position left by the first copy operation. Finally, an ENDFILE block is appended MT4.
/*JOB JOBNAME,ACCOUNT,ST=(C20,LP=0,WS=256),PW=PASSWORD,TI=9,C=A
PATTACH,ATMOL.
ATTACH,FILEA,ACC=RW.
REQUEST,FILEB,RT=U.
SERV.
DEFINE,FILEB.
####S
FILE ED4 FILEA MT4 FILEB
COPY ED4 * MT4 * 0
COPYDUMP ED4 600 MT4 *
ENDFILE MT4 *
STOP
####S
The job shown below uses the datasets ED2V and ED3V, generated by the test examples in [3] and [4]. The first phase of the job uses the MERGE routine to re-index the basis functions 2 - 10 to 1 - 9, output being to ED6. The next two stages involve the LIST routine, the whole of ED6 and block 3 of ED2 being LISTed. Finally, FINDDUMP is used to examine the DUMP FILE on ED3 at block 1.
/*JOB JOBNAME,ACCOUNT,ST=(C20,LP=0,WS=256),PW=PASSWORD,TI=9,C=A
PATTACH,ATMOL.
REQUEST,ED6X,RT=U.
ATTACH,ED2V,ED3V,ACC=RW.
SERV.
####S
FILE ED6 ED6X ED2 ED2V ED3 ED3V
MERGE ED6 1
2 10 1
END
ED2 1 0
END
LIST ED6 1 0
LIST ED2 3 1
FINDDUMP ED3 1 1 HIGH
EXIT
####S
[1] CDC VSOS Manual, Form 60459410, Control Data Corporation; VSOS Reference Manual, NAT 208, University of Manchester Regional Computer Centre, (1985).
[2] D. Moncrieff and V.R. Saunders, ATMOL-Introductory Notes.
[3] D. Moncrieff and V.R. Saunders, ATMOL-Integrals program.
[4] D. Moncrieff and V.R. Saunders, ATMOL-SCF program.