PRIMER  2. Introduction                                   file: 02-intro
[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)                       


          Crystallography Laboratory, Radboud University Nijmegen,
          Toernooiveld 1,  6525 ED  Nijmegen,      The Netherlands
          E-mail: PTBeurskens@hetnet.nl [ subject only: DIRDIF ! ] 

 
The complete DIRDIF documentation,  distributed with the program DIRDIF,
consists of a number of small files, stored in directory  /dirdif/DOCS .
They are: 
-  PRIMER files related to the use of the program:
     -1-handout.txt, -2-intro.txt, -3-.... etc, all ascii text files ,
     -1-handout.doc, -2-intro.doc, .., same contents in WORD .doc format
-  MANUAL files with the theoretical background of varfious procedures :
     1-DIRDIF.doc, 2-PATTY.doc, 2-ORIENT.doc, ..., in WORD .doc format ,
-  a file describing the short data base of molecular fragments:
     gallery.ps ,  in postscript format.


Contents of the PRIMER files                                       
file         section   contents    

01-handout   Section 1. forgoing file with summary of important items
02-intro     Section 2. When to use DIRDIF. Main options & programs  
03-options   Section 3. How to run the various options of DIRDIF     04-files     Section 4. DIRDIF file definitions  
05-monos     Section 5. Examples (test structure MONOS)
06-final     Section 6. How to interpret the results, problems?      
    ..       Section 7. Notes for various computers    
    ..       Section 8. Acknowledgements and references
 


------------------------------------------------------------------------
PRIMER
Section 2.  Introduction.   When to use DIRDIF.  Main options & programs
 
            DIRDIF = using your chemical knowledge !

DIRDIF  is a program for solving crystal structures.  Major features are
---> powerful Patterson methods for use of your chemical knowledge, both
     fot heavy atoms structures and equal atoms structures, and
---> direct methods applied to difference structure factors, with 
     special techniques for solving  symmetry problems,  all followed by ---> automated R2-driven dual-space structure expanding procedures.   
 
The program is designed to operate under a wide variety of circumstances
using automated as well as interactive routines.  Most options are fully
fully  automated  and can be used as a black box,  but the (experienced) user has on-line  control  for adapting  his strategy  to the problem at 
hand. An on-line help-facility is provided;  it is limited in scope  and
not meant to replace the present PRIMER files.
 
All programs are written in standard  FORTRAN-77  and are believed to be
fully  computer-independent.
 
 
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

Two main options in using Patterson methods
-------------------------------------------
 
1.  To solve a heavy atom  structure  (including S or P  in a light atom
structure)  use the program PATTY.  Input:  crystal data and  reflection
data.  No input atoms  or control data needed.  After locating the heavy
atoms the structure is automatically expanded until completeness.
 
2.  To solve a structure with a partly known model  (molecular fragment,
often  a rigid part  of the molecule)  use  Vector Search  methods.  The
search model (file with atomic coordinates) must be prepared in advance.
To retrieve a model  from the ORBASE fragment database  and/or to modify
the model  and/or  verify  the format  of your  prefab file  (all inter-
actively), use the option ORBASE .
      To solve  the structure  with this  search model,  use the program
ORIENT. After orientation,  the model is  automatically  positioned  and
further expanded to the complete structure.
 
 
The main individual routines   ( denoted 'programs') ; a short write-up:
----------------------------
 
DDSTART and DDMAIN are programs which are essential
members of the system; they are automatically executed when needed, and
they can also be excuted on request of the user, see Section 4. Details
are available also by using the H (=help) option.
 
DDSTART  Starting up an automatic or interactive run  
         (including option ATMOD)
DDMAIN   Various calculations  (Fcalc, R2, etc.)  and recycling control.
 
 
PATTY, ORIENT, TRACOR, PHASEX and FOUR  are  the main  structure-solving
programs. The programs can be called interactively or in automatic mode;
in both cases  the  system will  automatically  continue  to perform all
necessary calculations for the completion of the structure.
 
PATTY    is a program  for the interpretation  of a sharpened Patterson.
         It  uses  Buerger's  implication  theory  (i.e.  the  so called
         symmetry map) and checks all cross vectors  using the  minimum-
         function value as a selection criterion.
        -   The program is used for  heavy atom structures  with unknown
            heavy atom positions (including not-so-heavy-atoms like S or
            P in a light atom structure).
 
ORIENT   is a program  to find  the orientation  of a molecular fragment
         (model) by means of Vector Search methods (Nordman).  The input
         model is used for the calculation  of interatomic vectors.
         The  shape  function  of a single  interatomic  vector  peak is
         approximated from the shape of the origin peak of the Patterson
         function,  and it is used  for the  calculation  of the overlap
         inbetween neighbouring vectors of the model. Vectors to be used
         the search  are selected on weight (including overlap), length,
         and mutual separation.  A fast cyclic  search system in angular
         space (Eulerian angles denoted A, B, C),  employing  increasing
         resolution per cycle,  leads to the best fitting orientation of
         the model.   The fitting  criterion  is  the  Nordman  'minimum
         average' function value.
        -   The program  is used for structures  with known geometry for
            a (relatively small) part  of the molecule.  Note that often
            such a  molecular  fragment  (model)  is available  from the
            users own collection of related structures.
 
TRACOR   is a program to find the position of a molecular fragment (with
         known  correct  orientation)   by  means  of  reciprocal  space
         correlation  functions.  The input fragment (the ATOMS file) is
         used for the  calculation of  partial structure factors for all
         reflections  (for the entire  expanded  data set).  The partial
         structure factor (which is the sum of partial structure factors
         of symmetry related fragments) depends on the vector t used for
         shifting   the  input  fragment   to   another  position.   The
         correlation between  calculated and  observed structure factors
         (intensities) determines the best value for the shift vector t.
         The calculations are done by the  Fast-Fourier-Transform method
         employing all symmetry elements simultaneously.
        -   The program  is used  for positioning a  structural fragment
            with correct orientation  but unknown position.  The program
            is  automatically  executed  in the procedure  initiated  by
            calling ORIENT (see above).
        -   A correctly oriented fragment  sometimes is available as the
            result of a failure of ab-initio direct methods;
            when a recognizable  fragment  does not allow  expansion  or
            refinement,  then the fragment may be misplaced,  though the
            orientation is correct.

TRAVEC   is  a  program  which  is  automatically  executed  after   the
         execution of TRACOR:  it is based on vector search methods. 
         It is used  to test the ( maybe many ) results from ORIENT  and
         and TRACOR, and it decides which partial structure is promising
         enough to warrant further structure expansion by PHASEX.

PHASEX   is a program to EXpand and refine the PHASes  of the difference
         structure  factors  by  direct methods.  The input fragment  (a
         correct  but incomplete set of atomic parameters,  for instance
         known  heavy  atoms  or  an oriented  and positioned  molecular
         model)  is used  to calculate  normalized  difference structure
         factors (Wilson-Parthasarathy) giving 'E1' values.  Weights are
         calculated (Woolfson or Sim)  and the  E1 values  with the most
         reliable  phases are  input to a  modified  tangent  formula to
         refine  the input phases and  to calculate  phases for unphased
         reflections.

    The application of DIRect methods to the DIFference structure
    factors is particularly powerful:
    .    when the known part of the structure is only marginally
         sufficient to solve the structure,
    .    when the model has higher translation symmetry than the space
         group (superstructure),
    .    when the centrosymmetric input model comprizes an enantiomorph
         problem,
    .    when the known atoms comprise another pseudosymmetry problem
         such as a 'chicken wire' fragment.
    The program recognizes the symmetry problem and uses a special
    symbolic addition procedure to solve the enantiomorph and/or
    origin ambiguity problem.
        -   The program is used for expanding a partial structure. The
            program is automatically executed in the procedures
            initiated by calling PATTY, ORIENT or TRACOR.
 
FOUR     is a program for the calculation of Fourier and Patterson maps.
         It implies calculation of distances and angles,  assignment and
         shuffling  of  new  peaks  into  connected  atoms,  plotting of
         the asymmetric part  of the structure.  The program  FOUR  also
         arranges for  further expansion of the structure  and recycling
         (reactivating programs DDMAIN, PHASEX and FOUR).
         Note that the  program's  decision of  how to assign peaks  and
         which atoms  to use  is based  on peak heights,  partly  peak -
         integral  values  and  geometrical  considerations,  but not on
         valid  chemical arguments:  the user should apply  his chemical
         knowledge  and make the  appropriate modifications in the final          output atomic parameters.
        -   The program uses  input files  generated by  other  programs
            (via program DDMAIN).  It is  automatically  executed in the
            procedures  initiated  by calling  PATTY, ORIENT, TRACOR  or
            PHASEX.  When the known part  of the structure is relatively
            large,  program FOUR is executed  instead of  PHASEX because
            the difference structure factors then are unreliable.
 
Finally we describe some additional options, parameters and programs,
which are important tools in using the DIRDIF program.

ATMOD    is a special  option  which can be used  to prepare  a suitable
         model for input to the  Vector Search program  ORIENT.  A model
         can  be  selected  interactively  from  the  ORBASE  or  ORUSER
         database of  molecular fragments.  (See  ORBASE-GALLERY.)  Some
         facilities are available for modifying the model. 
         Note: this option generates one model, although many models may
         be (manually) stored in the ATMOD file.

ORFLEX   is an intractive program to generate  multiple search fragments
         for a flexible molecular fragment,  in case the flexibility can
         be described by rotations around atom bonds. The resulting many
         models are stored in the ATMOD file.
 
DIRP1    is  an  option  that  can  be  useful  for  the solution  of  a
         structure  in case the user is uncertain about the space group,
         the composition of the compound,  and/or  the position  of some
         heavy atoms.  The option DIRP1 causes the reflection data to be
         expanded  to space group  P1  (or  centered equivalent e.g. C1)
         and calls  the option  PHASEX  for elucidation of the structure
         in P1.  The input model may be, for instance, one heavy atom in
         the origin!

NORECY   is an  additional calling parameter  which is used  to suppress
         the automatic recycling procedure.  The keyword NORECY is added
         to the  calling parameters.  The recycling  should be  bypassed
         only when the automatic procedure failed  to solve the complete
         structure.

BIJVOET  is a program to find the absolute structure by  calculating the          Bijvoet-coefficient from differences in observed intensities of
         Friedel-related reflections.  The ideal result would be  either
         +1 for the correct structure or  -1 for the inverted structure.

NUTS     is a collection  of sub-programs for various  utility functions
         which contains for intance:
     AT2X     conversion of ATOMS to XYZN (for SHELXL) and other formats
     X2AT     conversion of XYZN to ATOMS (DIRDIF format)
     SHAT     shift atoms
     EULER    rotation of a rigid fragment  (by A,B,C, in angular space)
     INVERT   inversion of atomic parameters
 

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

