PRIMER file: 1-handout.txt    [ dirdif manual chapter 1 ]   15 Aug. 2008

A summary about DIRDIF                                       
------------------------------------------------------------------------                               DIRDIF-2008  
                           
                          A computer program for
         
          Crystal Structure Determination by Patterson Methods and
          Direct Methods  applied to  Difference Structure Factors

          How to solve crystal structures using chemical knowledge 
 
          Paul T. Beurskens,   Gezina Beurskens,   Rene de Gelder,      
          Jan M.M. Smits (Nijmegen),   S. Garcia-Granda (Oviedo) &      
                          R.O. Gould (Edinburgh)                       

Notation: in this MANUAL all names of programs, parameters, keywords, 
    etcetera, are written in capitals, but all input data may also be 
    given in lower case lettering. 
    All data files are defined in lower case
    although in this MANUAL capitals may be used. 

Documents: files stored in directory dirdif/ DOCS  
-  PRIMER files: 1-handout, 2-intro, 3-options, 4-files, 5-monos, etc.
-  gallery.pdf : a visualization of orbase = data base of mol.fragments
-  the MANUAL  which includes the PRIMER files and the ORBASE GALLERY,
   and contains theoretical background of major subprograms  PATTY, 
   ORIENT, etcetera, and the write-up for some DIRDIF DEMO structures.

Input data: the usual crystal data and observed reflection data, and
1. ===> for heavy atoms structures: nothing else !
2. ===> for Vector Search: one or MORE known molecular fragments.
   Some options (see below) require atomic coordinates.
 
When to use DIRDIF for routine structure analysis:
1.  For structures with heavy atoms, including P and S      call:  PATTY
2.  For structures of molecules with (partly) known geometry ...: ORIENT
 
When to use DIRDIF for (special) problem structures:
3.  For expansion of a small fragment to the complete structure : PHASEX
3.  For an enantiomorph, or a super- or pseudo-symmetry problem : PHASEX

 
How to run DIRDIF  ( CCODE identifies the structure + working directory)
-----------------  [ Change to working directory <CCODE>  ! ]

In most options, the structural parameters ( atomic coordinates,  either
user-supplied  or found by Patterson methods) are expanded  and recycled
(calling repeatedly the appropriate programs) to determine the  complete
structure. Output: atoms file.
 
1. Patterson option PATTY for Heavy Atom Patterson interpretation.
   To solve  a heavy-atom  structure  (including S or P  in a light atom
   structure), use PATTY. No input atoms needed. Enter:
=====>   DIRDIF <CCODE> PATTY
 
2. Patterson option ORIENT for application of Vector Search methods.
   Vector Search methods  are used  when a (relatively small)  part of a
   structure  has known geometry. Prior  to running  ORIENT,  the search
   model  (atmod  file,  fractional  or Cartesian  coordinates)  must be
   prepared.  To verify  the format  of your  prefab  atmod file,  or to
   retrieve a model from orbase  (see ORBASE-GALLERY),  and/or to modify
   the model interactively, enter:
=====>   DIRDIF <CCODE> ATMOD
   Then, for application of ORIENT (valid atmod file needed), enter:
=====>   DIRDIF <CCODE> ORIENT
   The orientation of the model is found by program ORIENT, using Vector
   Search. Thereafter, programs TRACOR and TRAVEC are called to position
   the model, and PHASEX and FOUR expand the structure  to completeness.

3. Structure expansion (fractional atomic coordinates in atoms file).
   Expansion and recycling of a partial structure, especially for an 
   enantiomorph, or a super- or pseudo-symmetry problem, enter:
=====> DIRDIF <CCODE> PHASEX

 
Special options:

To generate multiple search fragments for a flexible search model, in
   case the flexibility can be described by rotations around atom bonds:
=====> DIRDIF <CCODE> ORFLEX   (input: atoms, output many models in atmod)

To find the absolute structure by the Bijvoet-coefficient, enter:
=====> DIRDIF <CCODE> BIJVOET  (input: <ccode>.ins [priority] or atoms )

For some other utilities, enter:
=====> DIRDIF <CCODE> AT2X     to convert atoms file into <ccode>.res 
=====> DIRDIF <CCODE> X2AT     to convert <ccode>.ins file into atoms


In case of problems:
 
=====> DIRDIF <CCODE> NORECY : call FOUR but recycling is suppressed!
=====> DIRDIF <CCODE> NOFREE : re-assign atom names following 
                             file crysin, using one Fourier synthesis.
                               
Aliasses and abbreviations:

The abbreviation 'DD' may be used for 'DIRDIF' .
The instruction 'DDD' may be prepared to call a plot program after the
final structure expansion has been completed. 
After the first DIRDIF run for a given coumpound, or in case
    the CRYSIN file has been generated with the proper compound code, 
the parameter <CCODE> may be omitted in the following calls. 


DIRDIF files
------------
 
The filename dictates the contents and the format of the file.
Filenames sometimes are represented (in programs, documents, and
output listings) by capitals. The actual file names are in lower case , 
but some concatenate the name to the compound code ( denoted CCODE ).
 
Reflection data files (options); DIRDIF finds out which one is input:
fref       formatted reflection data file  (F values)
<ccode>.hkl  formatted reflection data (F or F-squared)
      An HKLF record defines whether  F or F**2 is given (default: F**2) 

Crystal data files (options); DIRDIF finds out which one is input:
crysin    :  primary crystal data
<ccode>.ins or <ccode>.res : SHELXL control data (may contain a HKLF record)
<ccode>.cif :  the IUCr-ActaCryst CIF file (for crystal data only)

Atomic parameters files:
atmod  atomic parameters (fractional or Cartesian coordinates) of a
       molecular model (fragment) for input to ORIENT. This file can be
       prepared manually, or by calling ORBASE and retrieving a model
       from orbase/oruser . Various procedures overwrite this file but
       input data are copied/appended to the atold file for back up.
       The atmod file may contain more than one fragment (CART. coords).
atoms  atomic parameters (in fractional coordinates) of the structure or
       of a part of the structure, either as input or as output. Various
       programs overwrite the atoms file with intermediate or final
       atomic parameters, but some input data are appended to atold.
atold  file with a collection of successively produced and/or used atoms
       files (back up).
<ccode>.res  file with output atomic parameters in SHELX format.
           This file is written at the end of the recycling procedure.
<ccode>.ins  file with refined atomic parameters in SHELX format for use
           in program BIJVOET .
<ccode>.spf  atomic parameters in PLUTON format (A.Spek).
 
Other DIRDIF files: [2008: lis1 and lis2 give too much nonsence now... ] 
lis1   output file with a summary of results and comments to be
       inspected and (optionally) printed.
lis2   auxiliary output file  with more (intermediate) information, only
       to be inspected when lis1 did not show the complete structure and
       you want to figure out what went wrong.
ddlog  file on which the system keeps some data on the subsequent runs.
ddstop with information after an error stop.
Note: many more files will be generated: don't change any of them. 

Results of DIRDIF
-----------------
 
      When the structure  has been solved  correctly  the output  atomic
parameters are written onto the files atoms (and <ccode>.res,  <ccode>.spf);
one proceeds with this file as input to a plot or LS refinement program.
      If your structure  has not come out correctly,  the output listing
files lis1 and lis2 give indications to detect where the solution of the
structure  (probably)  went wrong,  and  you can  set up  an appropriate
strategy  to run DIRDIF  again:  either with  non-default parameters, or
with a changed model.  
      Sometimes  the automatic  recycling  in the expansion part  of the
procedure  (PHASEX / FOUR)  does not work  properly  (f.i. when the cell
contents are  far off):  do inspect  the  results  of the first cycle of
PHASEX / FOUR or rerun DIRDIF without automatic recycling. An additional
calling  parameter  NORECY  suppresses  the automatic recycling.
      To change the space group or the contents of the unit cell:
change the crysin file .   Note:
after a change of crysin (especially the cell contents) you may reassign
the atomic designation by entering:  DIRDIF <CCODE> NOFREE  .


[ 2007 ] Major changes in DIRDIF-2008: 

1.  The  former collection of  many individual programs  now are  united
    into one single program DIRDIF.
2.  Former computer dependent routines are removed:  DIRDIF  is believed
    to be  computer independent.
3.  Heavy atoms: the program analyses all possible PATTY solutions!    
4.  Vector Search: the program will orient all fragments given in ATMOD;
    TRACOR will position all oriented fragments, and TRAVEC analyses all
    positions for each orientation of each input model, and decides how
    many atoms sets will be subjected to the PHASEX recycling procedure.
5.  The program ORFLEX can be used to generate ( many ) models of a          flexible molecular fragment.
6.  The program BIJVOET is called and if appropriate (wrong absolute         structure), the structure will be inverted.
7.  All file names are in lower case (important for unix users !)
8.  Conventions for using SHELX files in DIRDIF are changed: beware!
    <ccode>.ins = input,  <ccode>.res = output .

Adres for correspondence:
     P.T.Beurskens, c/o  Dr. R. de Gelder
     Crystallography Laboratory, Radboud University Nijmegen, 
     Toernooiveld 1,  6525 ED,   Nijmegen,    The Netherlands
     Email: PTBeurskens [at] hetnet.nl (only accepted subject: DIRDIF !)

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