PRIMER file: 3-options.txt    [ dirdif manual chapter 3 ]   15 Aug. 2008

How to run the various options of DIRDIF
------------------------------------------------------------------------
 
Preliminary comments on input/output files  (for details see section 4).
Most programs need a reflection data file and a crystal data file.
For the application of vector search methods (ORIENT), the user has to
prepare the atmod file (with the a-priori known molecular geometry)
either before the automatic execution of ORIENT, or in an interactive
session on request. 
For some programs (in cases with problem structures) the user has to
prepare an ATOMS file. No control data is needed at the outset of a job.
      Atomic parameters of all possible solutions obtained by programs
PATTY, or ORIENT, TRACOR and TRAVEC, and also atomic parameters of some
intermediate results (program FOUR) are stored in the atold file or in some other files (to be listed is section 4).
      The ddlog file keeps record of some data of subsequent runs.
      When the structure has been solved you find results and comments
on the lis1 and lis2 files and the atomic parameters of the structure
on the atoms file as well as on a SHELX's <ccode>.res file and on some 
other files (to be listed is section 4).
 
Instruction syntax:  DIRDIF [CCODE] [PROGRAM [PARAMETER(S)]] 

   CCODE: compound code, name of the structure, working directory   
   PROGRAM: program name or option,    
   ====> means : enter the instruction ( being in directory <CCODE> ) 
 
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 compound, or in case the
   CRYSIN file has been generated with the proper compound code name, 
   the compound code ( CCODE ) may be omitted in all following calls. 
   In this write-up we stick to the full instruction syntax.

Major program calls
-------------------

For the execution of any of the structure-solving programs PATTY,
ORIENT, TRACOR, PHASEX, and FOUR the user has the choice between the
automatic mode and the interactive mode:
=====>   DIRDIF  <CCODE>  PROGRAM          for automatic execution
=====>   DIRDIF                          for interactive execution
In the interactive mode every question is provided with a help facility.
 
The execution of some additional options (see below) and the execution
of the program NUTS and any of the programs collected in NUTS
(AT2X, BIJVOET, etc., see Section 2) is interactive, see below.
 
 
Patterson option 1: 
------------------ run PATTY for Heavy Atom Patterson interpretation.
When the structure contains Heavy Atoms (including S or P in a light
atom structure):
 
=====>   DIRDIF <CCODE> PATTY

      No input atoms needed. The system automatically arranges for the
      following procedure: first calculate the Patterson function
      (program FOUR), then locates the heavy atom(s) (program PATTY),
      expand the partial structure (program PHASEX, followed by FOUR),
      and recycle several times (programs DDMAIN, PHASEX and FOUR) for
      complete elucidation of the structure. 
      Output: structural parameters in the atoms file.
 Note : all acceptable PATTY solutions will be tested, and sorted
      on a FOM (figure of merit) based on the Patterson fit and the R2 
      value; the most probable solutions are partly expanded, and the
      result with the lowest R2 value is fully expanded to find the
      complete structure.

Patterson option 2:
------------------- run ORIENT for application of Vector Search methods.
Vector Search methods are used when a (relatively small) part of a
structure has known geometry. The known part usually (but not
necessarily) is a rigid molecular fragment. The search model (ATMOD
file, fractional or Cartesian coordinates) must be prepared before
executing ORIENT (see Section 4 for the write-up of the atmod file):
 
=====>   DIRDIF <CCODE> ATMOD

      Procedures:
   -: When the user has prepared an atmod file in advance (from
      literature data, molecular modelling or his own archieves):
      checking the format of the file.
   -: Else: interactive retrieval of a model from the database ORBASE
      and/or ORUSER (see the fragments listed in the ORBASE-GALLERY).
   -: In either case: interactive fragment modification (add atoms,
      delete or rename atoms, etcetera).
      Output: an (updated) atmod file with Cartesian coordinates.
 Note : the user may manually store more then one atoms sets
      in the atmod file (must be in Cartesian coordinates).   

=====>   DIRDIF <CCODE> ORFLEX  
   
       When a flexible molecular fragment is available (stored in file
       atoms), and in case the flexibility can be described by rotations
       around atom bonds, the user is asked to supply these bonds, and
       the program ORFLEX generates multiple search fragments
       Output: many search models, stored in the atmod file.

=====>   DIRDIF <CCODE> ORIENT

      Input: atmod file with one or more Cartesion molecular fragments.

      When the user calls for ORIENT, the system automatically arranges
      for the following procedure: 
    - first check and perhaps rewrite the atmod file with the atomic
      parameters of the model, 
    - then calculate the Patterson function (program FOUR), 
    - search for the orientation of the model (program ORIENT),
      and repeat this for all search fragments, 
    - use translation functions to position the model according to space
      group symmetry (program TRACOR)
      and repeat this for all accepted ORIENT results,
    - call program TRAVEC to collect all results of TRACOR for all 
      orientations for all input models, and to calculate a FOM based on
      TRACOR correlation results, TRAVEC vector fit results and R2 for 
      all resulting trial structures. Output: selected trial structures.
    - expand all selected partial structures, and recycle several times
      (programs DDMAIN, PHASEX, FOUR) for partial structure elucidation.     - select the best result, based on R2, and recycle again to achieve
      complete structure elucidation. 
      Output: atoms file (and other files) with final atomic parameters.
 
Additional options  (for various kinds of problems)
 
=====>   DIRDIF <CCODE> TRACOR

      Input fractional atomic coordinates given in an atoms file.
      The program is used for expanding structural fragments with cor-
      rect orientation but unknown position. The program is automatic-
      ally executed in the procedure initiated by calling ORIENT.
      The program is explicitely called by the user in a number of cases
         A correctly oriented fragment sometimes is available as the
      result of a failure of ab-initio direct methods; when a recogni-
      zable fragment does not allow expansion or refinement, then the
      fragment may be misplaced, though the orientation is correct. The
      user may supply this fragment (input: atoms file) and call for
      TRACOR.
         The program is also a powerful tool for the elucidation of
      troublesome heavy atom structures. For instance, the origin and
      the next largest non-Harker Patterson peak define a pair of heavy        atoms which can be used as a well oriented model to be positioned
      by the program TRACOR.
         When TRACOR is called, the following procedure is executed: 
    - first expand the reflection data to a half-sphere and use the
      fragment to calculate partial structure factors (program DDMAIN),      - then find the position of the fragment (program TRACOR)  and
    - continue as described above (with TRAVEC), and structure expansion
      (with programs DDMAIN, PHASEX and FOUR) to complete the
      structure elucidation. 
      Output: atoms file with atomic parameters.

      (Note: the user cannot call program TRAVEC individually.)
 
=====>   DIRDIF <CCODE> PHASEX

      Expansion and recycling of a partial structure, i.e. when some
      atoms are known (on correct positions). Input fractional atomic
      coordinates are given in the atoms file.
      The program is automatically executed after PATTY, ORIENT or
      TRACOR.
      The program is explicitely called by the user in a number of cases
    - The user should call for PHASEX when he has his own suggestions
      for atomic positions: for instance he may have modified the atoms
      in the ATOMS file available from a foregoing DIRDIF run (which, of
      course, is only useful if something went wrong ...).
   -  When the user calls for PHASEX, the system automatically arranges
      for structure factor calculation and normalization (program
      DDMAIN), then executes the program PHASEX to expand and refine the
      phases of the difference structure factors, calculates and
      interprets a Fourier synthesis (program FOUR), and finally organi-
      zes recycling several times (programs DDMAIN, PHASEX and FOUR) for
      expansion of the fragment and completion of the structure. 
      Output: atomic parameters in atoms file.
 
=====>   DIRDIF <CCODE> FOUR

      The program FOUR is automatically executed after PATTY, ORIENT,
      TRACOR or PHASEX
      The program is explicitely called by the user in a number of cases
      similar as for PHASEX (see above). Input: atoms file.
      When the user calls for FOUR, the system will automatically
      arrange for structure  factor calculation (by program DDMAIN)  and
      then  calls  program  FOUR  for a default  Fourier synthesis.  The
      program FOUR then  arranges  for recycling  (programs  DDMAIN  and
      FOUR)  until the structure evaluation  is completed. 
      Output: atomic parameters in the atoms file.

=====>   DIRDIF <CCODE> BIJVOET

      This call for the NUTS option BIJVOET is especially useful after
      the structure has been refined, for finding the absolute structure
      in case of a non-centrosymmetric space group. . Input atomic 
      parameters: <ccode>.ins  [priority] or atoms . Output only when 
      structure inversion is required: <ccode>.res and atoms 
 
=====>   DIRDIF <CCODE> AT2X
=====>   DIRDIF <CCODE> X2AT

      AT2X is a subprogram for the conversion of the (final) atoms file 
      into files for other propgrams (SHELXL, PLUTON, SCHAKAL).
         One output file is <ccode>.res .
      X2AT converses a SHELX <ccode>.ins file into an atoms file.

=====>   DIRDIF <CCODE> NUTS (or for instance ===> DIRDIF <CCODE> AT2X )

      This call invokes an interactive session for the execution of
      various utility calculations such as: AT2X, X2AT, BIJVOET, SHAT, 
      EULER, INVERT: call NUTS for more information.
      The programs AT2X and BIJVOET, and maybe INVERT, are automatically 
      executed at the end of all structure solving procedures.

=====>   DIRDIF <CCODE> CRYSDA

      To prepare a 'permanent' crysda file with extended crystal data.
      Usually the crysda file is generated automatically, and deleted
      at the end of a job.
      This call is useful when the user wishes to inspect the extended
      crystal data. At next call for DIRDIF, the crysda file is erased.
      When the user wants to modify the crystyal data (e.g. space group
      or cell contents) he should make those changes in the crysin file.
 
In case of problems:
 
=====>   DIRDIF H
      Invokes a short help session. (No CCODE given, no data needed.)
      For the new DIRDIF user it is really useful to try out all
      possibilities in order to get used to the system.
 
=====>   DIRDIF 
      Starts an interactive run.
   -  When DIRDIF is activated in interactive mode the user is asked to
      select an option or program (ORIENT, PATTY,...) and then whether
      or not special control data is wanted. Interactive help facilities
      are available. For a first run we strongly advise to use the
      default values.
 
Restart DIRDIF:

=====>   DIRDIF <CCODE> FOUR
      Starts an automatic Fourier recycling run, which is usefull
      in case the structure solution is almost completed, but some of
      lower peaks are not well nominated.
 
=====>   DIRDIF <CCODE> FOUR NORECY
=====>   DIRDIF <CCODE> NORECY
      Prepare one more Fourier systhesis with interpretation, which may
      be very usefull if just a few atoms are renamed, or the cell 
      contents are slightly modified in crysin.


Restarting DIRDIF - summary
---------------------------
 
When you want to rerun one of the options of DIRDIF you have to consider
which atomic parameter set is to be used as input. You can start your
own recycling procedure using the existing ATOMS file (output from last
DIRDIF run), or you can select one of the parameter sets stored in one of the back-up files and copy it to the ATOMS file. Use local editing
facilities to modify the ATOMS file to suit your idea of the best set of
atomic parameters.
To decide which option of DIRDIF you want to call, consider their
consecutive actions:
 
         find heavy   fragment       fragment      fragment        make
         atom(s)     orientation    positioning   expansion      Fourier
call:
PATTY    PATTY  --------------------------------->  PHASEX  ----->  FOUR
ORIENT                ORIENT ----->  TRACOR ----->  PHASEX  ----->  FOUR
TRACOR                               TRACOR ----->  PHASEX  ----->  FOUR
PHASEX                                              PHASEX  ----->  FOUR
FOUR                                                                FOUR
 
-----------------------------------------------------------------------

