File: DIRDIF.MANUAL Manual Manual Manual Manual Manual Manual Manual Version 14 Dec. 1994 Very much incomplete !!!!!!!!!!!!!!!!!!!! Update: 11 Jan. 1995 DIRDIF-94 ========= A Computer Program System for Crystal Structure Determination by Patterson Methods and Direct Methods applied to Difference Structure Factors Paul T. Beurskens, G. Admiraal, Gezina Beurskens, W.P. Bosman, Rene de Gelder, Randy Israel, and Jan M.M. Smits. Crystallography Laboratory, University of Nijmegen, Toernooiveld 1, 6525 ED Nijmegen, The Netherlands. FAX: 31-80-553450 E-mail: U625002 at vm.uci.kun.nl Contents of this MANUAL ======================= This document gives some technical information which can be useful for programmmers. It is not relevant for your daly structural problems. For a description of the DIRDIF system, see the documents: HANDOUT, PRIMER and the DIRDIF USER'S GUIDE ...... Section 1. The program CRYSDA and the CRYSDA file Section 2. The NIJX SUBROUTINES Section 1. The program CRYSDA and the CRYSDA file =================================================== The program CRYSDA prepares a CRYSDA file with crystal data and various items which are of importance for the execution of all crystallographic programs. The CRYSDA file is a permanent fixed-format character file. A detailed description of the contents of the CRYSDA file is given below. Input files: CAD4 : setting angles of up to 25 reflections and wavelength. For a write-up: see comment lines in the program CRYSDA. Users outside Nijmegen should not use this file: use CRYSIN instead. CRYSIN: file with primary crystal data. Write-up: see DIRDIF.PRIMER . Contents: compound code, celldimensions, standard deviations, space group, cellcontents, wavelength and number of molecules in the unit cell. If the file is present, it will be used; if not, it will be created. CRYSDA: crystal data file. See below. If the CRYSDA file is present, it will be used; if not === or incomplete === it will be created or updated. Output files CRYSDA: crystal data file. This file will be written over an already existing CRYSDA file. CRYSIN: primary crystal data file. This file will be written over an already existing CRYSIN file. Its main purpose is to facilidate updating the CRYSDA file. IPR2, LISTING: output listing file. Printed information for your archives. Normally the program will run on-line. Batch execution is possible, in which case a CRYSIN file must be created beforehand, by a local editor. At the start of the program all pertinent information that is present in any already existing files, is read in. This information is used as default information which may be kept or modified at will during the execution. The subroutines RDCRYS, RDCRYB and RDCRYX (S. Garcia Granda, 1987?) are used to read the CRYSDA file: see comments in the NIJX2.FOR file. Description of the CRYSDA file ------------------------------ Rules: - On all records the first ten positions are reserved for the keyword. If more than six characters are given, only the first six are used. - In those cases that the information could not be contained on one record, the continuation records have blank keywords. - Where possible a format composed of (A6,4X), I10 and F10.n is used. - Records that are meant to be copied may or may not have a keyword in the first six positions, depending on the requirements of the program for which they are meant. - A block of data that doest't have a fixed length (e.g. symmetry) is always preceded by a record giving the number of data records of that block. In this case no other records (such as REMARK) are allowed. - Where possible, a short alphanumeric explanation of the numeric value on a record is given. This text is not used by any program. - The order of the records is as defined below, but additional records (undefined in this write-up) are allowed (e.g. REMARK records). DESCRIPTION OF THE RECORDS ========================== Note: new FORMAT convention: replace Hollerith by quotes, e.g.: 3Habc ===> 'abc' ! "CRYSDA"-RECORD FORMAT (10HCRYSDA ,A6,4X,17HCRYSTAL DATA FILE) This record contains the compound code, denoted CCODE . It is up to 6 characters long. Note: CCODE must be in accordance with the naming conventions for any input-output files declarations on the computer system in use. "CELL "-RECORD FORMAT (10HCELL ,6F10.5) This record contains the direct celldimensions A,B,C,ALPHA,BETA and GAMMA. The axial lengths are in angstrom, the angles in degrees. They are calculated from the information present in the CAD-4 file, using a lattice symmetry restrained least-squares refinement procedure based on THETA-values. If no least-squares procedure is possible (no CAD4-file, or insufficient information avialable) the direct celldimensions are asked for or read in from a previously created CRYSDA-file. Also in this case symmetry restraints, as derived from the space group symbol, are applied (values which should be equal are averaged). "CELLSD"-RECORD FORMAT (10HCELLSD ,6F10.5) This record contains the standard deviations in the direct celldimensions as given on the "CELL"-record. The standard deviations in the axial lengths are in angstrom, those in the angles in degrees. If possible, the values are derived from the lattice symmetry restrained least-squares refinement. If that is not possible, the values are asked for or read in from a previously created CRYSDA file, in which case lattice symmetry restraints are applied to the values given (values which should be equal are averaged). "SPGR "-RECORD FORMAT (10HSPGR ,30A1) This record contains the space group symbol. This isn't necessarily a standard setting as given in the international tables. On the setting given in this record the symmetry information and the lattice symmetry restraints are based. "CELCON"-RECORD FORMAT (10HCELCON ,10(A2,I3,1X)) This record contains the cell-contents i.e. the atom types and the totaL number ot these atom types in the whole unit cell. The atom type and number of this atom type in the cell are given right behind each other in pairs. The maximum number of atom types is 10. The numbers are based on those given for the molecular formula multiplied by the number of formula units in the whole unit cell and then rounded off to the nearest INTEGER. Partial occupancies of less than 0.5 in the whole unit cell are rounded off to zero and left as such as a warning and reminder in this record. This record is supplied in order to ensure compatibility with existing CRYSDA files. Normally the information in the "CELLCO"- record should be used. "CELLCO"-RECORD FORMAT (10HCELLCO ,5(A2,I6,4X)) or: FORMAT (10HCELLCO ,5(A2,I6,4X),2H = / 10X, 5(A2,I6,4X)) This record has the same function as the "CELCON"-record, but with a different format to allow for larger numbers. There is a maximum of five pairs on the first record. If there are between six and ten pairs, a continuation record follows, Indicated by a continuation marker "=" in column 72 of the first record. "RCELL "-RECORD FORMAT (10HRCELL ,3F10.7,3F10.5) This record contains the reciprocal celldimensions, as calculated from the direct celldimensions on the "CELL"-record, in the order A*, B*, C*, ALPHA*, BETA* and GAMMA*. The axial lengths are in A**-1, the angles in degrees. "VOLUM "-RECORD FORMAT (10HVOLUM ,2F10.3,F10.7,10X,'VOL, SIG(VOL), VOL**-1') This record contains the volume in A**3, the standard deviation in the volume in A**3 and the volume of the reciprocal cell in A**-3. "WAVE "-RECORD FORMAT (10HWAVE ,A2,8X,4F10.6,12H ,A1,A2,B) This record contains the radiation used as an alphanumeric word and the corresponding wavelengths K(), K(ALPHA1), K(ALPHA2) and K(BETA) in ANGSTROM. Data from international tables for X-ray crystallography, Vol IV The Kynoch Press, Birmingham, ENGLAND, 1974. table 1.1A, pp. 6 (CR and FE), 7 (CU), 8(MO) and 9 (AG). Values for K(ALPHA1), K(ALPHA2) and K(BETA) have been taken from the table. Values for K() have been calculated from these: K() = ( 2.0 * K(ALPHA1) + K(ALPHA2) ) / 3.0 Normally, the value of K() should be used in programs and stated in structural papers. Only in special cases (e.g. splitting of high-order reflections used for celldimensions) should K(ALPHA1) and/or K(ALPHA2) values be used and stated. "FORMUL"-RECORD FORMAT (10HFORMUL ,5(A2,F9.2,1X)) or: FORMAT (10HFORMUL ,5(A2,F9.2,1X),2H = / 10X, 5(A2,F9.2,1X)) This record contains the molecular formula, organised in the same way and in the same order as the "CELLCO"-record. (Note: in COMMON /CRYSA/ this data is stored as follows: CELALL(I) contains FORMUL * Z (number of atoms), and CELATY(I) contains atomname (CHARACTER*2) of this type) "MOLW "-RECORD FORMAT (10HMOLW ,F10.3,10X,16HMOLECULAR WEIGHT) This record contains the molecular weight in GR/CM**3 (The weight for CARBON is 12.01100 GR/CM**3). "Z "-RECORD FORMAT (10HZ ,I10,10X,'NR of FORMULA UNITS / CELL') This record contains the number of formula units per unit cell (Note: in COMMON /CRYSA/ denoted: ZET) "NELEC "-RECORD FORMAT (10HNELEC ,I10,10X,'TOTAL NR OF ELECTRONS') This record contains the total number of electrons in the unit cell and thus the value for F000, independent of the radiation used, i.e. DELTA-F' and DELTA-F'' are not taken into account. "F000 "-RECORD FORMAT (10HF000 ,F10.2,10X,'F000 (INCL. ANOMALOUS SCATT.)') This record contains F000, dependent of the radiation used, calculated by taking DELTA-F' and DELTA-F'' into account. "MU "-RECORD FORMAT (10HMU ,F10.3,10X,28HLINEAR ABS. COEFF. IN CM**-1) This record contains the linear absorption coefficient MU in CM**-1. (based on the mass attenuation coefficients MU/RHO IN CM**2/GR AS given in table 2.1C of INT. TABLES, Vol. IV, pp. 61-66.) To convert to MM**-1, divide the number by 10. (Note: in COMMON /CRYSA/ denoted: ABSMU) "DCALC "-RECORD FORMAT (10HDCALC ,F10.3,10X,18HCALCULATED DENSITY) This record contains the calculated density in GR/CM**3. "DOBS "-RECORD FORMAT (10HDOBS ,F10.3,10X,16HOBSERVED DENSITY) This record contains the observed density in GR/CM**3; zero if unknown. "ICENT "-RECORD FORMAT (10HICENT ,9X,1H1,10X,18HNONCENTROSYMMETRIC) FORMAT (10HICENT ,9X,1H2,10X,15HCENTROSYMMETRIC) This record contains an indicator for the centricity of the space group: ICENT = 1 non-centrosymmetric ICENT = 2 centrosymmetric "ILATT "-RECORD FORMAT (10HILATT ,I10,10X,3A4) This record contains an indicator for the BRAVAIS lattice type ILATT = 1 Primitive (including rhombohedral) ILATT = 2 A-Centered ILATT = 3 B-Centered ILATT = 4 C-Centered ILATT = 5 I-Centered ILATT = 6 F-Centered ILATT = 7 R-Centered (hexagonal setting) "ISYST "-RECORD FORMAT (10HISYST ,I10,10X,3A4) This record contains an indicator for the system type ISYST = 1 Triclinic ISYST = 2 Monoclinic ISYST = 3 Orthorhombic ISYST = 4 TetragonaL ISYST = 5 Trigonal with rhombohedral axes ISYST = 6 Trigonal with hexagonal axes ISYST = 7 Hexagonal ISYST = 8 Cubic "ILAUE "-RECORD FORMAT (10HILAUE ,I10,10X,2A4) This record contains an indicator for the Laue group ILAUE = 1 1BAR ILAUE = 2 2/M ILAUE = 3 MMM ILAUE = 4 4/M ILAUE = 5 4/MMM ILAUE = 6 3BAR (Rhombohedral axes, primitive cell) ILAUE = 7 3BARM (Rhombohedral axes, primitive cell) ILAUE = 8 3BAR (Hexagonal axes) ILAUE = 9 3BARM1 (Hexagonal axes, mirror perpendicular to a-axis) ILAUE = 10 3BAR1M (Hexagonal axes, mirror perpendicular to diagonal) ILAUE = 11 6/M ILAUE = 12 6/MMM ILAUE = 13 M3BAR (Previously called m3) ILAUE = 14 M3BARM (Previously called m3m) "EQRHOM"-RECORD FORMAT (10HEQRHOM ,2F10.5,10X,24HRHOMBOHEDRAL A and ALPHA) If a rhombohedral space group is given, described on hexagonal axes, i.e. when ILAUE = 8, 9 or 10, ILATT = 7 and ISYST = 6, this record contains the equivalent rhombohedral celldimensions, i.e. A in angstrom and ALPHA in degrees. In all other cases this record is left out !! In the program the test is on ILATT = 7. "EQHEXA"-RECORD FORMAT (10HEQHEXA ,2F10.5,10X,17HHEXAGONAL A and C) If a rhombohedral space group is given, described on rhombohedral axis. i.e. when ILAUE = 6 or 7 (rhombohedral), ILATT = 1 and ISYST = 5, this record contains the equivalent hexagonal celldimensions, i.e. A and C in angstrom. In all other cases this record is left out !! In the program the test is on ISYST = 5. "IMULT "-RECORD FORMAT (10HIMULT ,I10,10X,32HMULTIPLICITY of GENERAL POSITION) This record contains the multiplicity of the general position; IMULT = NLATT * ICENT * NSYMM "IUNIQ "-RECORD FORMAT (10HIUNIQ ,I10,10X,A1,12H AXIS UNIQUE) FORMAT (10HIUNIQ ,I10,10X,14HNO UNIQUE AXIS) This record contains an indicator for a possible unique axis IUNIQ = 0 No unique axis IUNIQ = 1 A-Axis unique IUNIQ = 2 B-Axis unique IUNIQ = 3 C-Axis unique N.B. For hexagonal, trigonal and tetragonal settings the C-axis is unique by default with IUNIQ = 3. "IPOLA "-RECORD FORMAT (10HIPOLA ,I10,10X,12HPOLAR ALONG ,A4) FORMAT (10HIPOLA ,I10,10X,9HNOT POLAR) This record contains an indicator for polar space groups IPOLA = 0 Non-polar space group IPOLA = 1 Polar along X-axis IPOLA = 2 Polar along Y-axis IPOLA = 3 Polar in the XY-plane IPOLA = 4 Polar along Z-axis IPOLA = 5 Polar in the XZ-plane IPOLA = 6 Polar in the YZ-plane IPOLA = 7 Polar in XYZ IPOLA = 8 Polar along 111 "NTYPE "-RECORD FORMAT (10HNTYPE ,I10,10X,20HNUMBER OF ATOM TYPES) This record contains the number of atom types in the asymmetric unit. For each atom type follow here three records: the "ELEM"-RECORD and the "SFAC"-RECORD with its continuation record. "ELEM "-RECORD FORMAT (10HELEM ,A2,x2,I6,5F10.5) There is one such record for each atom type. It contains information about the chemical element involved. The following items are present in this order: 1. The keyword "ELEM" 2. The chemical symbol (ALPHANUMERIC) 3. The atomic number = number of electrons (NUMERIC) 4. The atomic weight, based on C=12.01100, in GR/CM**3 (NUMERIC) 5. The atomic absorption factor MU/RHO in CM**2/GR (NUMERIC) (mass attenuation coefficients as given in table 2.1C of INT. TABLES, Vol. IV, pp. 61-66.) 6. Pearson (1972) Atomic radius in angstrom (NUMERIC) 7. Covalent atomic radius in angstrom (NUMERIC) 8. Atomic radius according to SARGENT-WELCH in angstrom (NUMERIC) The "ELEM "-RECORD is followed by "SFAC " . "SFAC "-RECORD FORMAT (6HSFAC ,A4,6F10.5,2H =) and: FORMAT (10H ,3F10.5,2F7.3,F11.3,F5.2) This record has a continuation record !! It is formatted for SHELX input and those records for which no default values are present in the SHELX package should be copied to the SHELX input file. It contains the following items in this order: 1. The keyword "SFAC" 2. The chemical symbol (ALPHANUMERIC) 3. The coefficient A1 for the analytical approximation to the mean scattering factors in electrons for free atoms, as given in table 2.2B of INT. TABLES, Vol IV, pp. 99-101 (NUMERIC) 4. The coefficient B1 (NUMERIC) 5. The coefficient A2 (NUMERIC) 6. The coefficient B2 (NUMERIC) 7. The coefficient A3 (NUMERIC) 8. The coefficient B3 (NUMERIC) 9. The continuation marker "=" The continuation record contains the following items 1. The coefficient A4 (NUMERIC) 2. The coefficient B4 (NUMERIC) 3. The coefficient C (NUMERIC) 4. Real dispersion correction (DELTA-F') for atomic scattering factors in electrons as given in table 2.3.1 of INT. TABLES, Vol. IV, pp. 149-150. (NUMERIC) 5. Imaginary dispersion correction (DELTA-F'') for atomic scattering factors in electrons as given in table 2.3.1. of INT. TABLES, VoL. IV, pp. 149-150. (NUMERIC) 6. Atomic absorption factor. To obtain the correct units for SHELX, the atomic absorption factor as given on the "ELEM"- RECORD is multiplied by the atomic weight as given on the "ELEM"-RECORD, and then multiplied by 1.66043 (see SHELX INSTRUCTION MANUAL, p. 13) (NUMERIC) 7. The covalent atomic radius in angstrom (NUMERIC) Thereafter an "ELEM "-record may follow for next atom type. "NSYMM "-RECORD FORMAT (10HNSYMM ,I10,10X,27HNUMBER OF SYMMETRY MATRICES) This record contains the number of symmetry matrix records that follow this record. The symmetry operations are those generated for the space group given on the "SPGR"-record. Only the "ASYMMETRIC" part of the symmetry is given, i.e. no "SYMMAT"-records are entered for those positions generated by a possible inversion centre, or by possible lattice centering vectors. Note: this record may only be followed by SYMMAT-records. "SYMMAT"-RECORD FORMAT (10HSYMMAT ,3(3I3,1X,F10.7)) There are as many "SYMMAT"-records as is indicated on the "NSYMM "-record. Each "SYMMAT"-record contains the rotation matrix R and translation vector T for one symmetry-related position. It contains 12 numeric values (besides the alphanumeric keyword) for the following operation: X' = R11*X + R12*Y + R13*Z + T1 Y' = R21*X + R22*Y + R23*Z + T2 Z' = R31*X + R32*Y + R33*Z + T3 in the following order: R11 R12 R13 T1 R21 R22 R23 T2 R31 R32 R33 T3 Note: the first operation allways is the unit operation. Note: no other record types may be inserted here. "NLATT "-RECORD FORMAT (10HNLATT ,I10,10X,32HNR. OF LATTICE CENTERING VECTORS) This record contains the number of following lattice centering vectors. Note: this record may only be followed by CENVEC-records. "CENVEC"-RECORD FORMAT (10HCENVEC ,3F10.7) There are as many "CENVEC"-records as is indicated on the "NLATT "-record. Eache"CENVEC"-record contains the three (NUMERIC) components of a lattice centering vector. There is at least one such vector: (0,0,0) for a primitive lattice. The maximum number of "CENVEC"-records is 4. Note: no other record types may be inserted here. "NSXYZ "-RECORD FORMAT (10HNSXYZ ,I10,10X,30HNUMBER OF X,Y,Z SYMMETRY CARDS) This record contains the number of X,Y,Z-symmetry records ("SYMIT ") that follow this record. The symmetry records are those generated including a possible inversion centre and including a possible lattice centering. The number of records must therefore be equal to IMULT, the multiplicity of the general position. Note: this record may only be followed by CENVEC-records. "SYMIT "-RECORD FORMAT (10HSYMIT , 2(A3,A4,3H , ),A3,A4) or FORMAT ( 'SYMIT ' , A27) There are as many "SYMIT "-records as is indicated on the "NSXYZ"-record, which is equal to IMULT. Each record gives an operation in the (alphameric) x,y,z-notation as used by the INTERNATIONAL TABLES. The first NSYMM records are the symmetry operations as defined above ("SYMMAT"), in the same order. The following records are those generated by a possible inversion centre and including a possible lattice centering. Note: this notation is suitable for printing, and is also used to generate input control data for, say, SHELX. Note: no other record types may be inserted here. "FRAC2C"-RECORD FORMAT (10HFRAC2C ,3F15.6,/,10X,3F15.6,/,10X,3F15.6) This record contains the matrix that is needed to convert fractional coordinates to CARTESIAN coordinates, with the usual ordering of elements diveded over this record and two continuation records. This matrix is the inverse of the one given on the "CART2F"-record. FRAC2C(1,1)=A FRAC2C(1,2)=B*CC Note: CC = cos(gamma) FRAC2C(1,3)=C*CB CB = cos(beta) FRAC2C(2,1)=0. SC = sin(gamma) etc. FRAC2C(2,2)=B*SC FRAC2C(2,3)=C*(CA-CB*CC)/SC or: FRAC2C(2,3)=-C*SB*CAstar FRAC2C(3,1)=0. FRAC2C(3,2)=0. FRAC2C(3,3)=VOLUM/(A*B*SC) or: FRAC2C(3,3)=C*SB*SAstar "CART2F"-RECORD FORMAT (10HCART2F ,3F15.11,/,10X,3F15.11,/,10X,3F15.11) This record contains the matrix that is needed to convert CARTESIAN coordinates to fractional coordinates, with the usual ordering of elements divided over this record and two continuation records. This matrix is the inverse of the one given on the "FRAC2C"-record. CART2F(1,1)=1.0 / FRAC2C(1,1) CART2F(1,2)=-CC / (A*SC) CART2F(1,3)=B*C*(CA*CC-CB) / (VOLUM*SC) CART2F(2,1)=0. CART2F(2,2)=1.0 / FRAC2C(2,2) CART2F(2,3)=A*C*(CB*CC-CA) / (VOLUM*SC) CART2F(3,1)=0. CART2F(3,2)=0. CART2F(3,3)=1.0 / FRAC2C(3,3) "RRMAT "-RECORD FORMAT (10HRRMAT ,3F15.6,/,10X,3F15.6,/,10X,3F15.6) This record contains the real space metric tensor, also called the contravariant metric tensor, with the usual ordering of elements diveded over this record and two continuation records. Note: (length of vector x,y,z)**2 = (x,y,z) * RRMAT RRMAT is the inverse of SSMAT given on the "SSMAT "-record. RRMAT(1,1)=A*A RRMAT(1,2)=A*B*CC RRMAT(1,3)=A*C*CB RRMAT(2,1)=RRMAT(1,2) RRMAT(2,2)=B*B RRMAT(2,3)=B*C*CA RRMAT(3,1)=RRMAT(1,3) RRMAT(3,2)=RRMAT(2,3) RRMAT(3,3)=C*C "SSMAT "-RECORD FORMAT (10HSSMAT ,3F15.11,/,10X,3F15.11,/,10X,3F15.11) This record contains the reciprocal space metric tensor, also called the covariant metric tensor, with the usual ordering of elements divided over this record and two continuation records. Note: (2 sin(th)/lambda)**2 = SSMAT * (h,k,l) SSMAT is the inverse of RRMAT given on the "RRMAT "-record. SSMAT(1,1)=B*B*C*C*SA*SA / V**2 Note: V**2=VOLUM*VOLUM SSMAT(1,2)=A*B*C*C*(CA*CB-CC) / V**2 SSMAT(1,3)=A*B*B*C*(CA*CC-CB) / V**2 SSMAT(2,1)=SSMAT(1,2) SSMAT(2,2)=A*A*C*C*SB*SB / V**2 SSMAT(2,3)=A*A*B*C*(CB*CC-CA) / V**2 SSMAT(3,1)=SSMAT(1,3) SSMAT(3,2)=SSMAT(2,3) SSMAT(3,3)=A*A*B*B*SC*SC / V**2 "ORIN "-RECORD FORMAT (10HORIN ,3F15.11,/,10X,3F15.11,/,10X,3F15.11) This record contains the reciprocal axes orientation matrix as found from the CAD4-file. If this file is not available, This information is read in from a possibly previously created CRYSDA file or MATRIX file, or otherwise put to zero. "DIRECT"-RECORD FORMAT (10HDIRECT ,3F15.6,/,10X,3F15.6,/,10X,3F15.6) The unit cell axes matrix, i.e. the inverse of "ORIN ". "NIGGLI"-RECORD FORMAT (10HNIGGLI ,3F15.6,/,10X,3F15.6,/,10X,3F15.6) The Niggli matrix. "SIGDIR"-RECORD FORMAT (10HSIGDIR ,3F15.6,/,10X,3F15.6,/,10X,3F15.6) The matrix containing the standard deviations of the "DIRECT" matrix. "END "-RECORD FORMAT (10HEND ) This record concludes the CRYSDA file. Section 2. The NIJX SUBROUTINES =============================== NIJX: a collection of subroutines for the DIRDIF program system. NIJX.FOR is composed of the distributed file NIJX1.FOR... + NIJX2.FOR . Programming conventions. _______________________ - language: FORTRAN 77 - Implicit 'INTEGER' and 'REAL' conventions are used throughout - the name of a program is defined as CHARACTER*8 - the name of a subroutine is defined as CHARACTER*6 - control data input is defined via CHARACTER*6 - Labeled COMMON statements are of the same size and have the same order for INTEGER and REAL dimensions in all subroutines. Only for blank common different sizes are allowed. - Subroutine identification. The first line of a subroutine is a comment line beginning with: CSUBROUTINE NAME... or CSUBFUNCTION NAME... Freeformat conventions ______________________ Input lines of control data (for interactive use as well as control data files, crystal data, atomic parameters, etc.) are read with FORTRAN FORMAT A80 (the number of characters used is MCOL; usually it is 72). A free format interpretation routine will identify character strings with- out blanks or comma's as words (literal strings and/or numbers). A word is identified as a number if it consists of - (optional:) a plus or minus sign (+, -) - (followed by) one or more digits (0, 1, 3, .....9) - (optional:) one decimal point (.) somewhere. Examples (7 numbers): 0 0. .0 +0 -.003 +000. 15.33 A signed number may also be written with blanks inbetween the sign and the figures, i.e. " - 3 " is interpreted as the negative number "-3 ". Any other character or character string is called a literal word. Examples (9 literals): A A+ A3 3A + . 33.3+ 3-3+ $$ Blanks and comma's are used as separators between literals and between one literal and on number. However, signs (+ and -) may also been inter- preted as separators between numbers under the condition that the sepa- rating sign is not followed by blank(s). The reason for this rule is to make formatted output (e.g. 3F8.5) interpretable by the free format rou- tines. Examples (7 numbers): 0-2-3 0.0+7.2 - 2.0-3.0 Examples (4 literals and 1 number): 0-2-3- 0.0+7.2A - 2.0- 3.0 Note: a period or a sign alone is a literal; a comma alone is a sepator. Notation of numbers in exponential form is not permitted. General layout of a JOB stream. ______________________________ A complete JOB (RUN) usually begins with one interactive program DDSTART which prepares control data (the CONDA file) for all other programs to be executed. Terminal input is free-format. Syntax errors are detected and may be corrected at this stage. This scheme is programmed in two ways: (a) for interactive use: the program DDSTART is used to prepare the CONDA file. The user will be given the opportunity to correct the control data. Thereafter the JOB may be submitted to the Batch stream. (b) for batch use: the CONDA file may be prepared according to instruc- tions described in the program manuals: the program DDSTART then prepares the control file for the batch JOB. All following programs then are executed in batch mode according to the contents of control data file. Thus, during the execution of any program requiring lengthy calculations, all control data are preset or defaulted (i.e. calculated) by the program in execution. The file CCODE CONDA The control data file (CONDA file), usually available as input/output unit 4 or 5, contains a list of programs to be executed in the given order,and with each program name it contains a list of control data (executional parameters, crystallographic data, etc.) The file is a formatted file, max. 72 columns, with a key-word as first entry on any one record. The contents of a record are identified by its key-word. A program calling card has Key-word = 'PROGRAM' , followed by: PROGNM (program name) Following control data records are identified by its key-word. Last record: 'END' After the 'END' record of a program follows the program calling card for next program. Nevertheless: any uninterpretable record serves as an 'END' or 'STOP' indication for the present program. (For more details, see write-up of the CONDA file.) This sequence is repeated for various programs to be executed. The last record of a CONDA file is a 'FINISH' record. At the end of the execution of one program, the control data file may be modified: (i) by removing the control data for the present program, (ii) and possibly by modifying the data for the execution of following programs. At the first execution of the DIRDIF system, an interactive program CRYSDA is called, which generates a crystal data file, the CRYSDA file. At the first call of any program requiring reflection data, the program MERBIN is called, which generates a binary data f ile, the BINFO file. General lay-out of a main program _________________________________ - Various standard common blocks /SYSTA/, /SYSTB/, etc. (see below) - CALL KEPROG for program initiation - calculations / call subroutines - CALL KEPROX to stop NIJX Subroutines 1991 (short write-up) ----------------------------------------- The =NIJX= subroutines are used in a number of crystallographic pro- grams, written at the University of Nijmegen. These routines perform various standard operations, such as free format interpretation of con- trol data, time and error messages, and macro's for internal use. The most important subroutines, especially those intended for general use, are described in this write-up. Others, listed at the end (in Appendix I), may be studied by reading the comment cards given in each subroutine. Other general subroutines (for mathematical, geometrical, and crystallographic operations) are added to the NIJX subroutine file; they are listed (in Appendix II) and some are described in this write- up. The use of the NIJX subroutines is ensured in all programs (for export as well as for general internal use) and implies the use of a standard layout for the main program, subroutines, and some standard commons. Some simple 'KERN' subroutines ________________________________ KERNAB, KERNAI, KERNZA, KERNZI, KERNZ1, KERNZ6, are simple utilities which replace copy and clear DO-loops. KEREQ1, KEREQ6, KERC2I, and KERI2C replace often occurring data and character test loops. These subroutines may be used at any time; they will be present in the highest overlay level. They do not require any COMMON definitions. They operate only on normal word length. (IBM: 32 bits; not to be used for half-words or double-precision words). SUBROUTINE KERNAB (A,B,N) Transport contents of array A to array B (N words for floating point numbers) SUBROUTINE KERNAI (IA,IB,N) Transport contents of array IA to array IB (N words of integer data) SUBROUTINE KERNZA (X,A,N) Fill array A with X (N words of equal floating point numbers, usually X = 0.0) SUBROUTINE KERNZI (IX,IA,N) Fill array IA with IX (N words of equal integers, usually IX = 0) SUBROUTINE KERNZ1 (CH, CHA, N) Fill array CHA with CH (N words of equal type CHARACTER*1) SUBROUTINE KERNZ6 (CH, CHA, N) Fill array CHA with CH (N words of equal type CHARACTER*6) SUBROUTINE KEREQ1 (L, LL, N, KEND) Compare L with contents of array LL. KEND is the position of L in array LL, or -1 if not present. SUBROUTINE KEREQ6 (L6, LL6, N, KEND) Compare array L6 with contents of array LL6(N). KEND is the position of L in array LL, or -1 if not present. SUBROUTINE KERC2I (L, KEND) Compare L with contents of internal array (letters and digits), translate character C to interger number I from internal array KEND = -1 IF L IS NOT RECOGNIZED KEND = 0 IF L=0 KEND = 1- 9 IF 1, 2, 3, ... 9 KEND = 10 BLANK KEND = 11-36 IF A, B, C, .... Z KEND = 37-50 IF + - . , * / = $ ' ( ) ? ? ? ==>: 37 38 39 40 41 42 43 44 45 46 47 48 49 50 SUBROUTINE KERI2C (I, CCC, N) Convert number I to CHARACTER * 6 CCC Time and date routines ---------------------- A separately supplied, computer dependent, time/clock routine retrieves the date and the CPU-time from the computer. The subroutines DATIME, KEDATE and KETIME store the information in ITIME(4): ITIME(1) = year e.g. 1986 ITIME(2) = month 2 ITIME(3) = day 24 ITIME(4) = CPU time used 0 in msec The subroutines DATIME, KEDATE and KETIME are not essential for the program performance. The subroutine KEPROG initiates the array ITIME. SUBROUTINE DATIME (I1, I2, I3) Store date in (I3) and CPU-time in (I2). This is an IBM assembler routine. A dummy subroutine is provided. SUBROUTINE KEDATE Call date and store in ITIME(1), (2), (3). SUBROUTINE KETIME (IPRX) Call the cpu-time used and store in ITIME(4). IPRX = printer unit (IPR=6 or IPR2=10). Initiation, return and error routines ------------------------------------- SUBROUTINE KEPROG is the first subroutine to be called in the execution of the main program. The use of the other subroutines is not essential. KEPROG program initiation KERROX end of subroutine or end of program KERNER error stop routine KERROR another error stop routine These subroutines use COMMON /SYSTA/ and /SYSTB/ . KEPROG (including the time initiation routine) is used at the begin. The other subroutines can be called at any time. SUBROUTINE KEPROG (NAME) Input CHARACTER NAME * 8 Initiate program (called only once) = set INPUT/OUTPUT unit numbers in array IFILE = initiate time routine; print date. etcetera: see comment lines in the NIJX2.FOR file . SUBROUTINE KEPROX (NAME) Input: CHARACTER NAME * 6 Print 'END OF PROGRAM' etc. SUBROUTINE KERNER (KEY, NAME) Error stop routine, print PROSNM, MODULE='NAME' Input: CHARACTER NAME * 6 , NAME = subroutine name Thereafter the program STOPS. (Not if .... if KEYS(3).NE.0) SUBROUTINE KERROR (TEXT, KEY, NAME) ??? Input: CHARACTER NAME * 6 , NAME = subroutine name Error stop routine, print TEXT, .... Thereafter the program STOPS. (Not if .... if KEYS(3).NE.0) Freeformat input and interpretation routines -------------------------------------------- The subroutines KERINA, KERINB, KERINF, KERINC, KERIFF and KETERM read and interpretr input control cards, atomic param- eters, and some other formatted files. The the higher level reading and interpretation subroutine KERIFF is used for standard control data input, and KETERM is used for interactive terminal input. These routines use the above named subroutines. Because of the complicated control operations, KERIFF is not advised for large fixed formatted data files (such as HKL files). The information is stored in COMMON /SYSTA/ and /SYSTB/. SUBROUTINE KERINA (IRD, LUSER, LUMAX, LEND) Read one data record from unit IRD into character word CHIN *72 Interpret free format alpha-numeric data in CHIN. Check literals against LUSER(LMAX), a user supplied list of literal data. (Do not check system cards : see KERIFF) SUBROUTINE KERINB (LUSER, LUMAX) Interpret free format alpha-numeric data in CHIN. Check literals against LUSER(LMAX), a user supplied list of literal data. (Do not check system cards : see KERIFF) SUBROUTINE KERINF (CHIN, I, K, FF, KEND) Read floating point number FF from CHIN. SUBROUTINE KERINC (IRD, IPRX, LEND) Interpret system keywords END, FINISH, ..) and act accordingly. SUBROUTINE KERIFF (IRD, L, LMAX, LEND) Read free format record into array CHIN. Interpret free format data (by subroutine KERINB) and store the numbers in array FNUM(I) and the literals in array LIT(I). Interpret the literals to form keywords against L(LMAX), which is a user supplied list of keywords, and store interpreted keywords in array NLUSER. Interpret keywords against a list of system keywords and act accordingly. SUBROUTINE KETERM (KNUM, KLIT, KEND) Read free format record from terminal response into array CHIN. Check the number of numeric words, NFNUM, against the requested num- ber of numeric words, KNUM, and check the number of words of literals, NLIT, against the requested number, KLIT. If NFNUM and NLIT do not satisfy the conditions set by KNUM and KLIT, or if record is empty: print message and read again. CRYSDA file reading routines ____________________________ see NIJX2.FOR SUBROUTINE RDCRYS (ICRYS, KEND) SUBROUTINE RDCRYB (ICRYS, LLIT, KEND) SUBROUTINE RDCRYX Binary file input/output routines _________________________________ see NIJX2.FOR SUBROUTINE BINOX (IFO, FILENM< NIT, NW1, BUF) SUBROUTINE BINIX (IFI, FILENM, NIT, NW1, BUF) SUBROUTINE BINOFF (KEY, IFO, FILENM, FITEMS, NIT, BUF, NEND) SUBROUTINE BINIFF (KEY, IFI, FILENM, FITEMS, NIT, BUF, NEND) Atomic parameters input/output routines _______________________________________ see NIJX2.FOR SUBROUTINE ATOMIZ (LM, NLET, IZ) SUBROUTINE ATOMCH (IFNUM, NM, IZ) SUBROUTINE ATOMSH (IFNUM, NM, IZ, ISFFAC) SUBROUTINE ATOMIA (IFAT, ATXYZ, NSLOT, ATNAME, IZAT, MAXAT, NAT) SUBROUTINE ATOMIS (IFAT,L,LMAX,ATXYZ,NSLOT,ATNAME,IZAT,MAXAT,NAT) SUBROUTINE ATOSHX (FVAR, MFVAR, NVAR, ATXYZ, NSLOT, MAXAT, NAT, KI) SUBROUTINE ATOMIN (IFAT,KEY,ATXYZ,NSLOT,ATNAME,IZAT,MAXAT,NAT,KEND) === END of file DIRDIF.MANUAL ==========================================