PRIMER file: 4-files.txt      [ dirdif manual chapter 4 ]   15 Aug. 2008
------------------------------------------------------------------------

                       DIRDIF file definitions

 
Filenames are dependent on the computer and on local use. The different
files of the DIRDIF system are referred to by its functional type. 
(The filename dictates the contents and the format of the file.) 
File names always are written in lower case, although Within the
FORTRAN programs and in some documents, file names are represented by 
capital letters. Some files may maybe concatenated by compound code.
Example: for the test compound MONOS the primary crystal data is given
in the crysin file while output parameters are given in the atoms file
and in the file monos.res .
 
Input data:
DIRDIF needs an input reflection data file. 
The primary crystal data may be supplied manually, but it is preferred
to prepare the crysin file in advance, using local conversion programs. 
For some options atomic parameters files are needed: 
for ORIENT: the model parameters => atmod,  
for TRACOR or PHASEX: parameters of the partial structure => atoms.
 
Standard file structure:  Most files consist of free-format records of
at most 72 characters each. The order of words (literals, numbers) in a
record usually is fixed. 
-  The first record is a header record with at least FILENAME and CCODE. 
-  The first word of a record is a keyword for identification. 
-  REMARK records (keyword=REMARK) may be inserted anytime. 
-  The last record is an END or a FINISH record.
Note: reflection files have fixed format; REMARK records are not
permitted.
 
 
4a.   Listing files lis1 and lis2
 
The system produces a listing file lis1  ( = printable output ) which
gives mostly technical information on the solution of the structure.
In addition a much longer listing file, lis2, is produced which gives
information on the input data, the execution of the various programs,
and their results. Inspect the file lis2 only if you are interested or
when the structure did not come out as you hoped or expected. With the
aid of the detailed information you might be able to detect where things
went wrong, then change input data and start DIRDIF again. Certainly
lis2 should not be printed routinely. But if things really go wrong, do
send the lis1 and lis2 files to Nijmegen: we will be glad to help you!             
Note: before next run is executed, lis1 lis2 are copied to lis1x lis2x.
 
 
4b.   Atomic parameter files atoms and atmod
 
The input and output atomic parameter files of the DIRDIF system are:
- atoms file: input to most programs, replaced by output parameters,
- atmod file with the model parameters input to the program ORIENT,
- atold file: a collection of parameter sets, to be used as back-up,
- <ccode>.ins and <ccode>.res : SHELX control data files 
        Note: <ccode>.res is a file ready for input to SHELX LS program.
- <ccode>.spf : input for PLUTON (A.Spek), 
- schakal : input for plot program SCHAKAL.
 
The atoms file consists of the following records, each containing a
keyword followed by data:
 
atoms    CCODE    more-info       (CCODE = compound code)
ATOM     atomname   x  y  z       (x,y,z: fractional atomic coordinates)
                                  (one atom / record, as many as needed)
REMARK   comments                 (optional, as many as desirable)
END                               (last record)
 
The atomname begins with the chemical symbol and may be followed by one
or more characters (e.g. C7, C+7, C7+, C7A are carbon atoms; CA is a
calcium atom, CX is an error). Alternatively the atomname may consist of
the chemical symbol, one or more blanks, and one unsigned integer number
( e.g. C  27 ). Uninterpreted (residual) peaks of a Fourier map are
given atomname = Q .
 
It is possible to supply a site occupancy factor sof (sof = 1.00 also
for atoms on special positions; sof < 1.00 for disordered atoms) and an
isotropic temperature factor (B) on the ATOM record, but do so only if
you are sure about the data, because it will have a significant effect
on the scaling procedure.
 
When the structure has been solved the output ATOM records are provided
with a site occupancy factor (sof = 1.00) and an isotropic temperature
factor (B):
ATOM        atomname   x  y  z   sof   B
 
At the end of a structure solving run, the program NUTS/AT2X converts
the output atoms file to a <ccode>.res file.
of the least-squares refinement program SHELXL) and to <ccode>.spf and
schakal files (input to plot programs PLUTON and SCHAKAL, respectively).
  
Note: the atoms file may contain more atoms sets, after the closing
      'END' may follow another 'atoms' record, etc., but in most cases
      only the first atoms set is used.

 
The atmod file has the same structure as the atoms file.
 
Possible header records are:
ATMOD    MCODE    more-info                 (MCODE = Model code)
ATMOD    MNUM     MCODE                     (MNUM = Model number)
ATMOD    MCODE    MCELL a b c alpha beta gamma
ATMOD    CART
ATMOD    MCODE CART MNUM
ATMOD    CCODE                             (using cell of present CCODE)
 
ATOM records with atomic parameters  (one atom / record, as many records
as needed) contain either
     fractional coordinates:             ATOM   atomname    x  y  z
     or Cartesian coordinates:           ATOM   atomname    X  Y  Z
For the atomname see under atoms file.
 
REMARK records can be inserted (after the header) whenever needed.
END is the last record.
 
Notes.
The information CART (for Cartesian) is optional as DIRDIF finds out
whether the parameters are fractional or Cartesian. The information
'MCELL a b c alpha beta gamma' is necessary only when the fractional
atomic parameters of the model or fragment are represented in a unit
cell that is different from the present compound CCODE. (In stead of
'MCELL' also 'CELL' is accepted.) In an interactive session the MCELL
data can also be provided at the terminal.
 
Atomic parameters of a known molecular model can be retrieved from the
DIRDIF-ORBASE fragment file at an interactive terminal session. For
larger structures these fragments may be too small. The Vector Search
method can often be employed more powerful if you retrieve molecular
models from your own solved structures, or from the literature, or by
molecular modelling. It is convenient to prepare an atmod file in
advance, and modify the model (delete, rename, and add atoms)
interactively.
 
The atmod file, described so far, is input (e.g. by instruction: DIRDIF
<CCODE> ORBASE), and after checking, editing, possibly re-orientation,
a new atmod file is output with Cartesian coordinates (the original
input file is saved in the ATOLD file for back-up).

Note: the atmod file may contain more atoms sets, after the closing
      'END' may follow another 'atmod' record, etc., and each atmod set
      is used by ORIENT.
      Such a multiple atmod file may be dreated by program ORFLEX.


4c.   Crystal data files crysin and CRYSDA
 
crysin :     primary crystal data = standard DIRDIF input file.
<ccode>.ins or <ccode>.res: SHELXL control data files 
			(contains the HKLF record, see 3d)
<ccode>.cif  : IUCr-ActaCryst CIF data file for crystal data only
crysda :     extended crystal data, generated by subroutine CRYSDA
 
The program CRYSDA (usually called automatically) reads crystal data
from a crysin file (highest priority) and/or from other input
possibilities (existing crysda, ins/res, cis, keyboard) and produces a
crysda file which contains the input crystal data and extended data such
as cell volume, calculated density, tables of scattering factors, etc.
If no crysin file was available, or if the data in the crysin file was
incomplete, or if the crystal data was modified interactively, a (new)
crysin file will be output. The crysin files is to be kept. Normally,
the crysda file is deleted at the end of the job.
 

The crysin file contains the following records:
 
crysin   CCODE    more-info        (header)
TITLE    any user supplied information     (to be printed only once)
CELL     a b c alpha beta gamma            (Angstrom, degree)
CELLSD   esd's                             (six numbers)
SPGR     e.g. P 1 or P 21 21 21 or R -3    (axial directions are
                                           ( separated by blank(s))
FORMUL   At1 Nr1 At2 Nr2 At3 Nr3 ......    (Ati=chem.symbol,   Nri=nr of
                                           ( atoms Ati ,  max. 10 kinds)
         At7 Nr7 At8 Nr8 At9 Nr9 ......    (continuation record allowed)
                                           Example:    for  Na2CO3.7H2O:
                                           FORMUL NA 2 C 1 O 3  H 14 O 7
Z        number of FORMUL units / cell
                                        (Note: cell contents = Z*FORMUL)
                                        (! Z is not a symmetry factor !)
WAVE     Cu or Mo or Fe or Ag or Cr     (one atom type; no number)
ORIN     crystal orientation matrix     (OPTIONAL,  3 records)
HKLF     number                         (OPTIONAL, 3 or 4, for 
                                        (F or F**2 on <ccode>.hkl file)
END
 
Notes:
- When during the crystal structure analysis you wish to alter the cell
contents or the space group, you should do this in the crysin file.
 
 

4d.   Reflection data files
 
Input : <ccode>.hkl [ priority ] or fref

        DIRDIF finds out which input data file is present
        Formats of the reflection data files:
 
 
<ccode>.hkl : SHELX formatted reflection data, 28 characters/record
                         with |Fobs| or |Fobs|**2 values
                         (defined by a HKLF record: default F**2)
      First record:      HKLF header (optional, not SHELXL convention)
         First word:     'HKLF' on columns 1 - 4
         Second word:    the CCODE (optional, not checked)
         Then:           one number, either 3 or -3 : |Fobs| expected, 
                                     or  4 or -4 : |Fobs|**2 expected !
      Following records: 1 reflection/record,    FORMAT (3I4, 2F8.2)
                              for:  h, k, l, |Fobs|,    sigma
                              or:   h, k, l, |Fobs|**2, sigma
                (Note: the SHELXL batch number on cc. 29-32 is ignored.)
      Last record:       h = k = l = 0 (or: all blanks)
 
      (Note about the SHELXL indices transformation matrix  Rij given on
      the HKLF record: This feature is available,
      but should be used with care !! It is not used on crystal data!)
 
 
fref :            formatted reflection data file,   28 characters/record
                               (standard DIRDIF file)  with  Fobs values
      first record:      header with 'fref' or 'frefA' ... and CCODE
      following records: 1 reflection each, FORMAT (A1,3I3,I2,F9.2,F7.2)
                              for:  ' ', h, k, l, JC, Fobs, sigma
                              JC=2 for 'unobserved' or 'unreliable',
                              else JC=1 or blank
      last record:       'E'


Mind that a cif file or a <ccode>.ins/res file (SHELXL) can only be used
for crystal data input, not for reflection data input.
 
 
4e.   ddlog file ('readable data')
 
This file contains a summary of DIRDIF runs with pertinent data. This
file is to be kept.
 
 
4f.   orbase and oruser files
 
orbase : a data base with molecular fragments.
oruser : a private extension of orbase  (with your own favourite models)
A write-up of these files is given in the header lines of these files.
The user is urged to add (manually) his own structural molecular
fragments to the file oruser for future use when solving 'similar'
compounds.
 
4g.   Note about the use of <ccode>.ins and <ccode>.res files

Note: DIRDIF uses these SHELX control and parameter files as follows:
*   <ccode>.ins and 
    <ccode>.res files may be used to create the crysin file
*   <ccode>.res is output after structure expansion or if called by AT2X
*   <ccode>.ins is input to X2AT to create an atoms file, and
    <ccode>.ins has priority input when the user calls program BIJVOET ,
                in which case - if the structure has to be inverted -
    <ccode>.res is output.

------------------------------------------------------------------------
