PRIMER 3.  Options                                      file: 03-options
[Preliminary version]           DIRDIF-2007                 28 July 2007

------------------------------------------------------------------------
PRIMER
Section 3.     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 an XYZN file  (equivalent to SHELXL's
INS 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 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,
   respectively. After the first DIRDIF run for a given compound,the
   compound code name ( CCODE ) may be omitted in the 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  CCODE                   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:
=====>   DIRDIF  CCODE  PROGRAM
=====>   DIRDIF  CCODE  NOFREE
=====>   DIRDIF  CCODE
 
 
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 [2007] : 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 partle 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 ORTIENT (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  [2007]
   
       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),
      [2007] and repeat this for all search fragments, 
    - use translation functions to position the model according to space
      group symmetry (program TRACOR)
      [2007] 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 ahieve       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 the user calls TRACOR, 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 NUTS    (or for instance  ===> DIRDIF CCODE AT2X )

      This call invokes an interactive session for the execution of
      various utility calculations. One option is AT2X, a subprogram for
      the conversion of the final ATOMS file into files for other
      propgrams (SHELXL, PLUTON, SCHAKAL). Other options (sub-programs)
      are X2AT, BIJVOET, SHAT, EULER, INVERT: call NUTS for more
      information.
      The program NUTS (option AT2X) is automatically executed in all
      structure solving procedures after the final execution of program
      FOUR.

=====>   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.
 
=====>   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 CCODE
      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
      def ault values.
 
=====>   DIRDIF CCODE DIRP1
      Starts a procedure which helps the user to solve the structure in
      space group P1 or centered equivalent.
   -  It is used in case the space group, the composition of the
      compound, and/or the position of some heavy atoms are very
      uncertain. The input partial structure (ATOMS file) may be, for
      instance, one atom in the origin!
   -  Procedure: the reflection data are expanded to space group P1 (or
      centered equivalent e.g. C1) and the program PHASEX is executed
      for elucidation of the structure in P1. (The one-atom case is made
      asymmetric by the enantiomorph-fixing procedure.)
   -  After inspection of the results the user decides how to continue.
      There is no automatic recycling. After several 'hand'-controlled
      restarts (editing the output ATOMS file by hand, perhaps changing
      the crystal data), the user must recognize and locate the symmetry
      elements himself.  ( But calling TRACOR may be helpful. )
 
=====>   DIRDIF CCODE PHASEX NORECY
      Starts an automatic PHASEX run, but suppresses the recycling
      procedure ! (Similar for progams PATTY, ORIENT and TRACOR).
 
=====>   DIRDIF CCODE FOUR 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 the
back-up file ATOLD 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
 
* PHASEX and/or FOUR are recycled by default until completion of the
structure. The recycling procedure is suppressed by the calling
parameter 'NORECY'.
 
 
-----------------------------------------------------------------------

