DIRDIF 1. handout.txt                                   file: 01-handout
[Preliminary version]                                       28 July 2007
                               DIRDIF-2007  
                           
                          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)                       


Documents: see the files in DIRDIF / DOCS  !
-  the PRIMER files [ -1-handout, -2-intro, -3-...] with short write-ups
-  the MANUAL files [ 1-MANUAL, 2-PATTY ...] with theoretical background
-  the GALLERY.ps   a visualization of  ORBASE with molecular fragments,
see files -2-intro and 1.MANUAL for contents of various documents.

Input data: the usual crystal data and observed reflection data, and
1. ===> for heavy atoms structures: nothing else !
2. ===> for appr. equal atoms: one or MORE known structural 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.  When ab-initio direct methods gave a misplaced fragment ....: TRACOR
4.  For expansion of a small fragment to the complete structure : PHASEX
5.  For an enantiomorph, or a super- or pseudo-symmetry problem : PHASEX

 
How to run DIRDIF ( CCODE identifies the structure )
----------------- [ Change to directory CCODE ...! ]
                  (For test runs on structure MONOS, see file -4-monos)

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:
   Just 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.

Additional options:
 
3. Positioning of a  misplaced fragment  (fractional  atomic coordinates
   given in an ATOMS file):
=====> DIRDIF CCODE TRACOR
 
4+5. Expansion  and recycling of a partial structure  (fractional atomic
     coordinates in ATOMS file):
=====> DIRDIF CCODE PHASEX
 
Special options:

6. 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

7. To find the absolute structure by the Bijvoet-coefficient, enter:
=====> DIRDIF CCODE BIJVOET

8. For a variety of utilities, enter:
=====> DIRDIF CCODE NUTS


In case of problems:
 
=====> DIRDIF H   : invokes a limited help session.
=====> DIRDIF CCODE   : starts an interactive run.
=====> DIRDIF CCODE PHASEX NORECY : call PHASEX,
                                    but recycling is suppressed!
=====> DIRDIF CCODE NOFREE : re-assign atom names following CRYSIN,
                                    using one Fourier synthesis.

Aliasses and abbreviations:

The instruction DIRDIFX may be prepared to call a plot program after the
final structure expansion has been completed. 
The abbreviations DD and DDX may be used for DIRDIF and DIRDIFX, respec.
After the first DIRDIF run for a given coumpound, the compound code name
( CCODE ) may be omitted in the following calls. 


DIRDIF files
------------
 
The filename dictates the contents and the format of the file.
Filenames  are represented here  (as in all programs) by capitals. Local
implementation may change  capitals into lower case , and/or concatenate
the name to the compound code (e.g. the CRYSIN file may be:  'crysin' or
'monos.crysin' where 'monos' is the CCODE of test structure MONOS).
 
Reflection data files (options); DIRDIF finds out which one is input:
FREF alias FREFA FREFB FREFC : formatted reflection data file (F values)
HKL alias SHELX SHELXL : formatted reflection data file (F or F-squared)
        An HKLF record defines whether  F or F**2 is given  (see PRIMER)
 
Crystal data files (options); DIRDIF finds out which one is input:
CRYSIN   :  primary crystal data
INS, RES :  SHELXL control data files (contains a HKLF record).
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 input data are appended to ATOLD.
ATOLD  file with a collection of successively produced and/or used ATOMS
       files (back up).
XYZN   file with control data and atomic parameters in SHELXL format.
       The XYZN file is written by NUTS at the end of the recycling
       procedure. When you rename it to INS the file is ready for input
       to the SHELXL least squares refinement.
SPF    atomic parameters in PLUTON format (A.Spek) output by program
       NUTS.
 
Other DIRDIF files: [2007: 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 DIRDIF
       runs.
CRYSDA extended crystal data (automatically prepared and usually 
       destroyed again, unless it was called by:   DIRDIF CCODE CRYSDA).
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  ATOMS file  (and/or XYZN/SPF file); one
proceeds with this file as input to a 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,  given on LIS2.  (Or rerun  DIRDIF  without the automatic
recycling;  the  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 change in DIRDIF-2007: 

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!   or 
4.  Vector Search: the program will orient all fragments given in ATMOD;
TRACOR will position all  oriented fragments,  then  TRAVEC analyses all
positions for each orientation of each input model, and decides how many
atoms sets should be subjected to the  PHASEX/FOUR  recycling procedure.
The program ORFLEX can be used to generate ( many ) models of a flexible molecular fragment.

               [2007: adres for correspondence:]

     Crystallography Laboratory, Radboud University Nijmegen, 
     Toernooiveld 1,  6525 ED,   Nijmegen,    The Netherlands
     Email: PTB@hetnet.nl  ( only accepted subject: DIRDIF !)

