C ==========================================================================
   
    
         ---- Molecular Replacement --- 
                                             /Vers 5.0; 21.06.99/ 

      MOLREP   - is an automated program for molecular replacement
               
               * a full-symmetry translation and Packing function.
               * an automated choice of search parameters.
               * scaling by Patterson origin peaks. 
               * soft low resolution cut-off.
               * anisotropic correction of data.
               * rigid body refinement.
               * allows input of a priori knowledge of similarity and
                 completeness of the model.
               * can use second fixed model.
               * can check several peaks of rotation function by computing
                 each translation function and select result by correlation
                 coefficient.
               * if the number of monomers is known MOLREP can position
                 the input number of monomers in a simple run.
               * can check and manage pseudo-translation.
               * can improve the model before to use.
               * can use MTZ file.
               * can compute only Cross rotation or only Translation function.
               * can compute Self Rotation Function with PostScript plots.
               * Spherically averaged phased translation function.
               * Phased Rotation and Phased Translation functions.
               * fitting two models.
C ==========================================================================

   Author:      A.A.Vagin
                email: alexei@yorvic.york.ac.uk

   Reference:   A.A.Vagin, New translation and packing functions.,
                Newsletter on protein crystallography., Daresbury
                Laboratory, (1989) 24, pp 117-121.

                A.Vagin,A.Teplyakov, MOLREP: an automated program for
                molecular replacement.,
                J. Appl. Cryst. (1997) 30, 1022-1025.

C ==========================================================================



I. Installation.


     Copy file molrep.tar.gz from ftp site: ftp.yorvic.york.ac.uk
                                            (  user: anonymous
                                               cd pub/alexei   )
      and uncompress it (`gunzip molrep.tar.gz')  

      After untaring `molrep.tar' ( command: tar xvf molrep.tar ) 
      you will get a molrep directory, with src, doc, dic, data and bin 
      subdirectory and README file. 
      To build the executable, go to src and then you will have 
      following options:

     1. `make all', the executable (molrep) will finish up in the bin
         directory; providing the full pathname (.../molrep/bin/molrep) one 
         can execute it from anywhere without having to define and 
         environmental variable.

     2. `make ccp4' ( CCP4 distribution which can read MTZ file ) the executable
         (molrep) will finish up in the bin directory; providing the full
         pathname (.../molrep/bin/molrep) one can execute it from anywhere 
         without having to define and environmental variable, except
         variable CLIB which defines directory of CCP4 libraries.

     3. `make lnx` ( Linux distribution )
     
     4. `make lnx_ccp4` ( Linux distribution with ccp4)
     

C ==========================================================================

II. Input/output files


    Input file formats.


    1. Format input file of coordinates is PDB or CIF or BLANC.

    2. Input file of structure factors and phases.

       A. Input formatted file of structure factors.

          This file of structure factors must be in PDB-format or CIFile
          which contains indices and structure factors or intensities.
          (also simple formatted file with "h,k,l,!F!,sig(F)" or "h,k,l,!F!" 
          and without titles is acceptable)

          !!! The best format of input file of amplitudes is CIF.

       B. Input formatted file of structure factors and phases.

          This file must be CIFile which contains indices ,structure factors
          and phases. ( with "h,k,l,!F!,sig(F),Phi" or "h,k,l,!F!,sig(F),Phi,
          Fom")

       C. Alternative input file of structure factors or phases is 
          unformatted file of BLANC suite.

       D. MTZ file.

    You can find some examples of input files in Appedix C.

    Space group and unit cell parameters of unknown structure will be
    taken from file of structure factors but if this file has not such 
    information it will be taken from coordinate file. In this case
    input PDB_file of coordinates must contain correct CRYST1 cards with 
    unit cell parameters and space group name for unknown structure.


 Output files 


        molrep.crd  -  new coordinates of model ( + model_2) corresponding to
                       the best solution of Cross Rotation and Translation
                       Function.

        molrep.pdb  -  new PDB coordinate file with molrep solution
                       (if you started from PDB file).

        molrep.doc  -  protocol. This file wiil be created if
                       keyword DOC = 'Y' or 'A'.

        molrep.bat  -  batch file.  This file wiil be created if
                       keyword DOC = 'Y' or 'A'. You can repete 
                       calculation using this file:
                             cp molrep.bat bat 
                             sh bat

        molrep_rf.tab - List of peaks of rotation function. You can edit
                       this file and use for next calculation without 
                       compute rotation function ( keyword FUN = 'L' )

        molrep_srf.ps - PostScript file of Self Rotation Function

      Other output files will not be deleted if keyword LIST = 'L'.
      They have internal format of BLANC program suite and can be used 
      by programs of this suite. About BLANC see file README from ftp site:
      ftp.yorvic.york.ac.uk  (  user: anonymous
                                cd pub/alexei   )

        crossrot_alo   - spherical coefficients of F_observed 
        crossrot_alm   - spherical coefficients of F_model
        crossrot_dns   - rotation function
        trfun_cf       - coefficients of translation function
        trfun_dns.dat  - translation function
        trfun.crd      - trfun solution       
        molrep_fob.dat - F_observed
      
      also ( if you started from MTZ file )

        molrep_mtz.cif - formatted CIFile of F_observed

C ==========================================================================


III. How to use MOLREP

    * Self rotation function only.

        If you define only file of structure factors (Fobs) program
        will compute Self Rotation function with cut-off radius RAD = 30 
        as default. Use keyword RAD if you want another value.
        Also useful to use keywords RESMAX, RES_R 

        Result is PostScript file of Self Rotation Function "molrep_srf.ps" 

    * Search model in Electron density map.

        You need to have phases in CIFile of structure factors or
        use corresponding keywords for MTZ file or
        use keyword PHASE for BLANC file of phases

        1) with keyword PRF = 'N' (default value) :

            Rotation function (in Patterson space) and Phased Translation 
            function will be used.

        2) with keyword PRF = 'Y'
       
            SAPTF (Spherically averaged phased translation function), 
            Phased Rotation function and Phased Translation functions
            will be used.

        Also useful to use keywords NP, NPT, NMON, RESMAX, COMPL, SIM 

    * Fitting two models.

        If you define only files of models (searching model and model_2) without
        file of structure factors (Fobs) program will fit searching model
        ( keyword FILE_M ) to second model ( keyword MODEL_2 ).

        1) with keyword PRF = 'N' (default value) :

           Rotation function (Patterson space) to search  the orientation
           and Phased Translation function (Real space) to search position.
    
        2) with keyword PRF = 'Y'

           All functions in real space.
           Spherically averaged phased translation function gives
           expected position for model. 
           Phased Rotation function for expected position gives orientation.
           Phased Translation function checks and refines the translation
           vector.

        Also useful to use keywords NP, NPT, NMON, RESMAX, COMPL, SIM 

        Result is file "molrep.crd"( or "molrep.pdb") - model
        fitted to second model.

    * You can use MOLREP by dialogue or by batch file. 

    * Simple way to use MOLREP is to define files Fobs and model and use
      default values for all parameters (i.e without to use any keywords.)

    * Some keywords ( 'ordinary keywords' ) can be useful for special 
      structures or you want to use second fixed model :

         NP , NPT ,NMON , COMPL , SIM , FUN , MODEL_2 
 
         NP: <10>    number of peaks of rotation function to be checked.
                     Maximum: 50. Default: 10

         NPT: <20>   number of peaks of translation function to be checked.
                     Maximum: 50. Default: 20

         NMON: <1>   number of monomes. Program will try to create full model
                     which will consist NMON initial models + model_2 

         COMPL: <0>  completeness of model: from 0.2 to 1.0. It corresponds
                     to Boff: from 400 to 1600. If COMPL is used keywords
                     RES_R,RES_T are ignored. Default: automatic choice of Boff
                     For example , if you have a dimer in asymm. part of unit
                     cell put COMPL=0.5   

         SIM: <0>    similarity of model: from 0.1 to 1.0 It corresponds
                     to Badd: from (B_limit-Boverall) to -Boverall, where 
                     B_limit corresponds Optical Resolution (see Apendix D). 
                     SIM = 1 means normalized F will be used. If SIM is used 
                     keywords BADD is ignored. Default: Badd = 0
                     SIM (Badd)   - controls high resolution data
                     COMPL (Boff) - controls low resolution data
                     If you have not idea about similarity put SIM=0.5
                     for the beginning.
  
                     The use  BOFF and BADD means to change Fobs and Fmodel :
                     !F!new = !F!input *EXP(-BADD*RSQ)*(1-EXP(-BOFF*RSQ)



         FUN: <A>,R,L,T - R  calc only Rotation Function
                          T  calc only Translation Function
                          A  calc both: RF and TF
                          L  calc only Translation Function, reading list 
                             of peaks of RF from file: "molrep_rf.tab"

                     Program reads from "molrep_rf.tab" peak's number and
                     euler angles: alpha,beta,gamma and use only euler's
                     angle. Format is free. 

                     Example of one line of this file:

                      "  23  10.0    22.2 40.0"  
                      
                     In case Phased Rotation function program reads from 
                     "molrep_rf.tab" peak's number, euler angles: alpha,beta,
                     gamma and shift: sx, sy, sz.

                      "  23  10.0    22.2 40.0  .564 .443 .032"  

                     Anytime after Rotation Function program creats file
                     "molrep_rf.tab" with list of peaks of RF            
                               
         MODEL_2: filename - input file with the 2nd (fixed) model with correct
                             position and orientation.(format PDB or CIF or BLANC)
                             This model will be fixed during the search.
                             Default: no model_2

                             In case fitting two models second model is target
                             model.

     * and also useful PST VPST SURF :


         PST:  <N>,Y  Y - means to use pseudo-translation. 
                      In this case for Translation Function program will add
                      to model a copy of model which is translated by pseudo-
                      translation vector.  

         VPST: <0,0,0>  pseudo-translation vector (in fract.) which will 
                      used if PST = 'Y'. Default values is taken from Patterson
                      automatically.

         SURF: <N>,Y  Y - means to do the model correction. 
                      Correction means to remove from model water molecules, 
                      H atoms, atoms with  alternative position (except first),
                      atoms with occupacy = 0 , to compute atomic accessible
                      surface area and replace atomic B to 
                      B = 15.0 + SURFACE_AREA*10.0 


   * If you want to play with parameters use also 'Keywords for special cases'
    
   * Without file of model program computes only Self Rotation Function.

   * If FUN = 'R' and LIST = 'L' program computes and writes to molrep.doc 
     all symmetry realated peaks of Rotation Function.

   * If FUN = 'R' and LIST = 'L' program computes list of peaks of Patterson
     and writes to molrep.doc. It may be useful to detect pseudo-translation.




  Dialogue and keywords


    
     Any time you have to answer for first three questions:

  1. Do you want to have FILE-DOCUMENT /molrep.doc/ ? /<N>/Y/A :
       N - means without DOC-file
       Y - with new contents
       A - means to keep old contents and add new information
          with DOC-file program creates batch file: molrep.bat
    _DOC:

       DOC-file contains protocol of program's running. 
       If this file is exist and the answer is "A" program
       will add information to the end of file.

  2. Input file with Fobs (format  ASCII (CIF or PDB) or BLANC or MTZ) 
     FILE_F:
                          - name of formatted file of structure factors
                            / PDB or CIFile of structure factors/
                                       or 
                            internal BLANC file of structure factors
                                       or
                                     MTZ file
                                       or
                                " " - case of fitting two models

  3. Input file with model (format PDB or BLANC)
                        Unit cell and space group of this file must be the same
                        as for file with Fobs ( unknown structure )
     FILE_M:
                          -  name of input PDB_file 
                                      or
                             CIFile of blanc-system.

            Without this file program computes Self Rotation Function 
            and plots RF(theta,phi,chi) for
                        chi = 180, 90, 120 , 30.
            You can change 4th value of chi (30) by keyword: CHI
            You can change scale of these plots of RF by  keyword: SCALE
                       




  Ordinary keywords:




 #
 #NP:    <10>      - number of peaks of rotation function to be checked.
 #                   Maximum: 50. Default: 10

 #NPT:   <20>      - number of peaks of translation function to be checked.
 #                   Maximum: 50. Default: 20

 #NMON:   <1>      - number of monomes. Program will try to create full model

 #COMPL:  <0>      - completeness of model: from 0.2 to 1.0. It corresponds
 #                   to Boff: from 400 to 1600. If COMPL is used keywords
 #                   RES_R,RES_T are ignored. Default: automatic choice
 #
 #SIM:    <0>      - similarity of model: from 0.1 to 1.0 It corresponds
 #                   to Badd: from (B_limit-Boverall) to -Boverall, where 
 #                   B_limit corresponds Optical Resolution. SIM=1 means
 #                   normalized F will be used. If SIM is used keywords
 #                   BADD is ignored. Default: Badd=0
 #                   SIM (Badd)   - controls high resolution data
 #                   COMPL (Boff) - controls low resolution data
 #
 #                   The use  BOFF and BADD means to change Fobs and Fmodel :
 #                   !F!new = !F!input *EXP(-BADD*RSQ)*(1-EXP(-BOFF*RSQ)

 #FUN: <A>,R,L,T   - R  calc only Rotation Function
 #                   T  calc only Translation Function
 #                   L  calc only Translation Function, reading list of peaks
 #                      of RF from file: "molrep_rf.tab"
 #                   A  calc both: RF and TF
                        
 #MODEL_2: filename - input file with the 2nd (fixed) model in the same
 #                    format as model_1 (PDB or BLANC). This model will
 #                    be fixed during the search. Default: no model_2


 #SURF: <N>,Y        - Y - model correction. 
                      Correction means to remove water, H atoms, atoms with
                      alternative position (except first), atoms with
                      occupacy = 0 , to compute atomic accessible surface area 
                      and replace atomic B to B = 15.0 + SURFACE_AREA*10.0 



  Keywords for special cases:





 #PST : <N>,Y         - Y - use pseudo-translation. 
                        In this case for Translation Function program will add
                        to model a copy of model which is translated by 
                        pseudo-translation vector.  

 #VPST: <0,0,0>       - pseudo-translation vector (in fract.coord.system)
 #                      default: automatically from Patterson

 #
 #MODE:     <F>,S     - Fast or Slow
 #                      In Slow MODE advanced rotation and translation
 #                      functions and rigid body refinement are used.
 #                      In Fast MODE standard rotation and translation
 #                      functions are used without rigid body refinement
 #                      Fast MODE is much faster

 #RAD:   <automatic>  - cut-off radius for Patterson search or for
 #                      Electron Density search.
                        Default value is calculated from the model,
                        Default for Self-RF : 30A

 #RESMAX:   <3>       - maximal resolution. Default = 3A

 #RES_R: <automatic>  - minimal resolution for Rotation Function
 #RES_T: <automatic>  - minimal resolution for Translation Function
 #                      Instead to apply RES_min program use all data and
 #                      applies Boff=4*RES_min^2. 
 #                      Default: RES_R=15, BES_T - from model

 #BADD:     <0>         BOFF and BADD mean :
 #                      !F!new = !F!input *EXP(-BADD*RSQ)*(1-EXP(-BOFF*RSQ)

 #ANISO: <N>,Y,C,S    - Y anisothermal correction and scaling
 #                      C use anisothermal correction Fobs for RF only
 #                      S use anisothermal scaling for TF only

 #PACK:    <Y>,N      - use Packing Function with Translation Function

 #LMIN:    <4>        - miniimal L-index of sherical coefficients
                        Program doesn't use coefficients with L=0.
                        Possible values are 2,4,6,...
                        L = 2 means to use all coefficient up to Lmax.

 #LMAX: <automatic>,30,60 - maximal L-index of sherical coefficients
                            Possible value are 30 AND 60 only.

 #PRF:    <N>,Y      - Y means SAPTF (Spherically averaged phased translation
                       function) and Phased Rotation Function wiil be used.
                       In this case you have to use the phases
                       (see keyword PHASE)

                       If keyword FUN = L program reads from file "molrep_rf.tab"
                       peak's number, euler angles: alpha,beta, gamma and shift:
                       sx, sy, sz instead to compute any Rotation function.

 #PHASE: < >,+,-     - If you want to use phases from CIF or MTZ tape 
 #                     "+" or "-". (CIF or MTZ file must contains phases 
                       and you have to use corresponding keywords for MTZ) 

 #                     If you want to use the BLANC file of phase tape 
 #                     "+name" or "-name", where "name" is name of file 
                       with phases.

 #                     ("-" means inverted phases will *be used)

                       IF keyword PRF = N Rotation function and Phase Translation 
                       function will be computed. 
                       IF keyword PRF = Y  SAPTF, Phased Rotation Function
                       and Phase Translation function will be computed. 


 #LIST: <S>,L        - S - short DOC-file, L - long.

 #ANGLES:  <0,0,0>   - rotation angles of model /only for FUN="T"/


 #P2:     <0>        - experimental option, if P2 (percent of model_2) > 0
 #                     program uses !!Fobs!-!Fmod2!*(P2/100)! for RF
 #                     instead of !Fobs!    


 #
 #   Without file of model program computes Self Rotation Function
 #
 #CHI:    <60>     - angle chi of additional 4th section of RF(thetA,phi,chi)
 #SCALE:  <6>      - maximal value of RF is SCALE * SIGMA(RF)
 #
 #          molrep_rf.ps - PostScript file of Self or Cross Rotation Function
 #




  Batch file


     Best way to prepare batch-file is to run molrep once by dialogue.
     If "molrep.doc" file was defined program creates batch-file
     ( "molrep.bat") automatically.

     See some examples of batch files in Appendix E.


  MOLREP version for CCP4.


    1. You can have CCP4 version of MOLREP which can read MTZ file.

 
    2. This possibility uses CCP4 libraries. 
       You must define the path to this libraries by variable CLIB.
       Give command: setenv CLIB <path_to_lib>

    3. Keywords for reading MTZ file.

       
       #     Next keywords are necessary only for MTZ file
       #
       #  F:        < >       - label of F or F(+)
       #  SIGF:     < >       - label of sigma F or sigma F(+)
       #  F-:       < >       - label of F(+)
       #  SIGF-:    < >       - label of sigma F(-)
       #  I:        < >       - label of I or I(+)
       #  SIGI:     < >       - label of sigma I or  sigma I(+)
       #  I-:       < >       - label of I(-)
       #  SIGI-:    < >       - label of sigma I(-)
       #  PH:       < >       - label of phases
       #  FOM:      < >       - label of figure of merit
     
    
C ==========================================================================
 
 
IV. Testing super_program MOLREP:
 
 
      In directory "../molrep/doc/" there are two files:
 
        .../molrep/doc/test.bat - batch file of the test 
        .../molrep/doc/test.doc - protocol of this test
     
      In directory "../molrep/data/" there are four files for test:
        
         .../molrep/data/test.cif      - formatted CIFile of Structure Factors. 
         .../molrep/data/test.mtz      - MTZ file of Structure Factors. 
         .../molrep/data/test_mod.pdb  - PDB cordinate file of model
         .../molrep/data/test_mod2.pdb - PDB cordinate file of second model
 
       Structure contains two molecule in assymetric part of unit cell.
       Model is first molecule with only back bond and CB atoms with random 
       coordinate error rms=0.25. Molecule was rotated and shifted from correct
       position.
       Second model is solution for one molecule.
 
 
       "test.bat" contains four tests:
   
          1. Example with input MTZ file of structure factors
             Fobs : test.mtz
             Model: test_mod.pdb 

          2. Example with input CIFile of structure factors
             Fobs : test.cif
             Model: test_mod.pdb 

          3. Example with input CIFile of structure factors and second model
             which is solution for first peak of Rotation Function.
             Fobs   : test.cif
             Model  : test_mod.pdb 
             Model_2: test_mod2.pdb is solution for first peak of 
                      Rotation Function. 

          4. Example to use NMON keyword with input CIFile of structure 
             factors. In this case program will find two molecules related
             by non-crystallographical symmetry. 
             Fobs   : test.cif
             Model  : test_mod.pdb 
   

     1. copy files test.cif , test.mtz , test_mod.pdb , test_mod2.pdb
        and test.bat to some directory

     2. check and correct path to program "molrep" in the file "test.bat"
 
     3. run test:   sh test.bat
 
     4. compare result with ".../molrep/doc/test.doc"

C ==========================================================================


Appendix A.


  Molecular replacement method:



     There are two major steps in the Molecular replacement method :
     orientation and translation search. They are performed by Rotation
     and Translation function. Both of them are correlation functions
     ( or overlapping functions ) between observed and calculated from model 
     Patterson.
     
     Rotation function: 

              ROT(R) = I Pobs(r) * Pcalc(R,r) dr
                      rad
                          where R     - operator of rotation.
                                I     - integral inside a sphere in the centre 
                                rad     of patterson with radius= rad 
                                Pobs  - observed Patterson
                                Pcalc - calculated Patterson for rotated (R)
                                        model 


     Translation function:

            TR(s)  = I Pobs(r) * Pcalc(s,r) dr  =
                    cell

                   = Sum ( I Pobs(r) * Pcalc_ij_(s,r) dr) = Sum TRij(s)  
                     i#j                                    i#j

                           where s   - vector of translation
                                 I   - integral  
                                 i,j - cryst. symmetry operator numbers.
                                 Pcalc_ij_(s,r) - calculated Patterson for
                                      model corresponding to ith operator and
                                      model corresponding to jth operator and
                                 TRij(s) - translation function of Pattersons
                                        Pobs(r) and  Pcalc_ij_(s,r).

             Translation function is the sum of translation function for
             each pairs of different cryst. symmetry operators    


     The best rotation function algorithm is the Crowther Fast Rotation
     Function  which we use here. It utilizes FFT. Program can compute the
     Rotation Function for three different orientation of model and average
     them. That reduces the noise of Rotation function. 

     Translation function algorithm was developed by the author and perform 
     calculation in the reciprocal space using FFT 

     There are two major differences from other trunslation function.

    1.Instead of summation of translation function for two operators TRij we
      use their multiplication which makes the resulting map far more contrast.

    2.Finally we can multiply translation function by Packing function to
      remove peaks correspondingto incorrect solution with bad packing.

        Packing function is overlaping function :
    
              P(s) = Sum ( I  Roi(r) * Roj(r) dr )
                     i#j  cell
                                    where Roi(r) - electron density of model
                                          which corresponds ith operator
                                          cryst. symmetry.
        The algorithm of calculation of Packing function is similar to the one
        for translation function and performed by the same program.

        Finally advanced Translation function is:

            TR(s)  = [  M  TRij(s) ] * P(s)
                       i#j
                                     where M means multiplication of 
                                             different TRij.

     Success of molecular replacement method depends on:
     1. quality of the model, homology, conformation.
     2. quality of experimental data
     3. scaling !F!_obs and !F!_calc.
     4. low resolution limit.
     5. high resolution limit.

  Patterson scaling.

     For scaling we use a completely new strategy based on scaling of two
     Patterson maps. This method makes it possible to have a very good
     aproximation for scaling problem even if only low resolution data is avai-
     lable  where other methods don't work. Scaling by Patterson also is
     useful for Cross rotation function where we have for model different
     cell then for the unknown structure.

  Low resolution cut-off (Boff)

     Low resolution cut-off introduces systematical errors in the electron 
     density especially near the surface of the model. It is the series 
     termination effect. Instead to use of usual low resolution cut-off 
     program  multiplies the modules of structure factors by special 
     coefficient: 

         Fnew = Fold (1-exp(-Boff*s^2)) , where Boff= 4resmin^2

      Boff is called "soft low resolution cut-off", which allows to remove 
      structure factors in this resolution range without inroducing 
      the series termination effect.

  The use of a priori knowledge of similarity and completeness of the model.
     
     For low similarity the high resolution reflections are weighted down. 
     Program uses for this additional overall factor Badd:

         Fnew = Fold exp(-Badd*s^2)

     Value of similarity 'SIM' can be : from 0.1 to 1.0 It corresponds
     to Badd: from (B_limit-Boverall) to -Boverall, where B_limit corresponds
     Optical Resolution (see Apendix D). SIM=1 means normalized F will be used.

     For low completeness e.g. when there are several molecules in the a.u. 
     the contribution of low resolution reflections is weighted down. 
     To manage of completeness of model program uses low resolution
     cut-off (Boff). Completeness of model 'COMPL' can be : from 0.2 to 1.0.
     It corresponds to Boff: from 400 to 1600. 

  Functions of real space searching.

  Spherically averaged phased translation function (SAPTF).

     SAPTF gives expected position of model in Electron density map by
     the comparison spherically averaged density of model with locally
     spherically averaged observed density.

              SAPTF(s) = I Robs(r,s) * Rcalc(r) dr
                      rad(s)

                        where   I     - integral inside a sphere centred 
                              rad(s)    in point s of Electron density  
                                        with radius= rad 

                                Robs  - spherically averaged around point s 
                                        observed Electron density

                                Rcalc - spherically averaged around origin of
                                        coordinate system calculated Electron
                                        density for model 
  Phased Rotation function (PRF).

     PRF gives the orientation of model placed in some point of Electron density.

           PROT(O) = I Robs(r) * Rcalc(O,r) dr
                      rad(s)

                          where O     - operator of rotation.
 
                                I     - integral inside a sphere centred 
                              rad(s)    in point s of Electron density  
                                        with radius= rad 

                                Robs  - observed Electron density
                                Rcalc - calculated Electron density for 
                                        rotated (O) model 

  Phased Translation function (PTF).

     Translation search in Elecron density map.

           PTR(s)  = I Robs(r) * Rcalc(s,r) dr  =
                    cell

                           where s   - vector of translation
                                 I   - integral  
                                 Robs       - observed Electron density
                                 Rcalc(s,r) - calculated Electron density for
                                              model placed in the vector s.


  Fitting two models.

      Fitting through Electron density. Second model (MODEL_2) is the
      target model which converted to electron density.
      To search the best overlaping of electron densities of models
      there are two algorithms:

        1) Rotation function (Patterson space) and Phased Translation
           function (Real space).
    
        2) All functions in real space.
           Spherically averaged phased translation function gives
           expected position for model. 
           Phased Rotation function for expected position gives orientation.
           Phased Translation function checks and refines the translation
           vector.

C ==========================================================================


Appendix B


  MOLREP flowchart


      Program contains two main subprogram: CROSSROT and TRFUN.

 

C                """"""""""""""""""""
C                "     MOLREP       "
C                "                  "
C                """"""""""""""""""""
C              ------                        --------
C             ( Fobs )                      ( Model  )
C              ------                        --------
C                .                              .
C                v                              v
C                .          +----------+        .
C                .-->-------. CROSSROT .---<----.
C                .          +----------+        .
C                v               .              .
C                .               v              .
C                .         ---------------      .
C       .-------------->--( List of peaks )     .
C       .        .         ---------------      .
C       .        .               .              .
C       .        v               V              v
C       .        .          +----------+        .
C       .        .-->-------.   TRFUN  .---<----.
C       ^                   +----------+        
C       .                         .              
C       .                         v
C       .                         .
C       .                      -----------
C       .                     ( new model )
C       .                      -----------
C       .                         .
C       .                         .
C       .                         .
C       .                         v
C       ^                +-----------------------+
C       .                . Rigid body refinement .
C       .                +-----------------------+
C       .                         .
C       .                         .
C       .     next peak           .
C       .------<------------<-----.
C                                 .
C                                 v
C                          ------------
C                         ( best model )
C                          ------------
C 
C


  CROSSROT flowchart


    Subprogram  CROSSROT - cross-rotation function.

C
C               """""""""""""""""""""
C               "     CROSSROT      "
C               "                   "
C               """""""""""""""""""""
C                      ------------
C                     (Coor.crd-mod) /model structure/
C                      ------------
C                           .
C                           v
C                +-------------------------------------+
C                . GENDEN . for P1 , A,B,C > 2*DIM-mod .
C                +-------------------------------------+
C                            .
C                            v
C                       +-------+
C                       .  RFT  .
C                       +-------+
C                        .     .
C                        v     v
C     -------        -------   ------
C    ( F-obs )     ( F-mod ) (PH-mod)
C     -------        -------   ------
C        .             .
C        v             v
C    +--------+   +--------+
C    . RFCOEF .   . RFCOEF .
C    +--------+   +--------+
C       .             .   /RAD,RESMIN,RESMAX as for F-obs/
C       v             v
C    --------      --------
C   (Almn-obs)    (Almn-mod)
C    --------      --------
C        .          .
C        v          v
C       +------------+
C       .    RFRES   .
C       +------------+
C            .
C            v
C          ------              ------------
C         (  RI  )            (Coor.crd-mod)
C          ------              ------------
C            .                      .
C            v                      v
C       +------------+              .
C       . PEAKSRCH   .              .
C       +------------+              .
C             .                     .
C             .                     .
C             .                     v
C             .   maximal peak   +-------+
C             -----------------> . TRANS .
C                    Alpha       +-------+
C                    Beta          .
C                    Gamma         v
C                            -------------
C                           ( Coor.crd-mod)  /rotated/
C                            -------------
C
C


  TRFUN flowchart

   Subprogram  TRFUN  - trunslation-packing function.

C
C               """"""""""""""""""""""""""""""""
C               "   TRANSLATION  FUNCTION      "
C               "                              "
C               """"""""""""""""""""""""""""""""
C                      ------------
C                     (Coor.crd-mod) /orient model/
C                      ------------
C                           .
C                           v
C                 +-----------------------+
C                 . Rigid body refinement .
C                 +-----------------------+
C                           .
C                           v
C                      ------------
C                     (Coor.crd-ref) /refined model/
C                      ------------
C                           .
C                           .
C                           v
C                +-------------------------------------+
C                . GENDEN . for P1 , cell as for F-obs .
C                +-------------------------------------+
C                       .
C                       v
C                    +-------+
C                    .  RFFT .
C                    +-------+
C                     .     .
C                     v     v
C      -------    -------   ------
C     ( F-obs )  ( F-mod ) (PH-mod)
C      -------    -------   ------
C         .         .        .
C         v         v        v
C       +------------------------+
C       . TRPACK . Tm - function .      
C       +------------------------+
C             .  
C             v
C         --------
C        (  Coef  )
C         --------
C             .
C             v
C         +--------+
C         .   FFT  .  / for P1 /
C         +--------+
C            .
C            v
C          ------              ------------
C         (  RI  )            (Coor.crd-mod)
C          ------              ------------
C            .                       .
C            v                       v
C      +----------+  maximal peak  +-------+
C      . PEAKSRCH . -------------> . TRANS .
C      +----------+   Delta X      +-------+
C                     Delta Y         .
C                     Delta Z         v
C                              -------------
C                             ( Coor.crd-mod)  / correct/
C                              -------------   /  model /
C
C ==========================================================================


Appendix C.


       A. Example of CIfile of amplitudes:

         data_structure_9ins
         _cell.length_a      100.000
         _cell_length_b      100.000
         _cell.length_c      100.000
         _cell.angle_alpha    90.000
         _cell.angle_beta     90.000
         _cell.angle_gamma    90.000
         _symmetry.space_group_name_H-M  'P 1 21 1'
         loop_
         _refln.index_h
         _refln.index_k
         _refln.index_l
         _refln.F_meas_au
         _refln.F_meas_sigma_au
            2  3   4    12.3   1.2
           -2 -3  -4    11.4   1.1
          . . . . . . . . . . . . .


          For intensities use:

         _refln.intensity_meas 
         _refln.intensity_sigma 

       B. Example of CIfile of amplitudes with phases:

         data_9ins
         _cell.length_a      100.000
         _cell_length_b      100.000
         _cell.length_c      100.000
         _cell.angle_alpha    90.000
         _cell.angle_beta     90.000
         _cell.angle_gamma    90.000
         _symmetry.space_group_name_H-M  'P 1 21 1'
         loop_
         _refln.index_h
         _refln.index_k
         _refln.index_l
         _refln.F_meas_au
         _refln.F_meas_au_sigma
         _refln.phase_calc
         _refln.fom
            1   0   0    3468.4934   138.7397    0.746  1.000 
            2   0   0     618.4012    24.7360   11.948  1.000 
          . . . . . . . . . . . . . . . . . . . . . . . . . . . 


          Phases are in degrees.

 
       C. Example of PDB file of amplitudes:

       HEADER   R2SARSF   15-JAN-91
       COMPND   RIBONUCLEASE SA (E.C.3.1.4.8) COMPLEX WITH 3'-*GUANYLIC ACID 
       SOURCE   (STREPTOMYCES $AUREOFACIENS)
       AUTHOR   J.SEVCIK,E.J.DODSON,G.G.DODSON
       CRYST1  64.900   78.320   38.790  90.00  90.00  90.00 P 21 21 21    8
       CONTNT   H,K,L,S,FOBS,SIGMA(FOBS)
       FORMAT   (2(I3,2I4,2F7.0,F6.0,9X))
       COORDS   2SAR
       REMARK  1 TWO REFLECTIONS PER RECORD.
       REMARK  2 DMIN=1.85, DMAX=16.28
       CHKSUM  1 MIN H=0,MAX H=34,MIN K=0,MAX K=41,MIN L=0,MAX L=20
       CHKSUM  2 TOTAL NUMBER OF REFLECTIONS=17346
       CHKSUM  3 TOTAL NUMBER OF REFLECTION RECORDS=8673
       CHKSUM  4 SUM OF FOBS=0.235499E+07
         0   0   3     60      9    16           0   0   4    106    307    25
         0   0   5    166     23    20           0   0   6    239    657    52
         0   0   7    326      0    38           0   0   8    425    511    40
       . . . . . . . . . . . . . . . . . . . . . .

       D. Example of simple formatted file of amplitudes:
          In this case the assumption is that order of data is H,K,L,F,sig(F)
                   
            2  3   4    12.3   1.2
           -2 -3  -4    11.4   1.1
           . . . . . . . . . . . . .

               or 

            2  3   4    12.3  
           -2 -3  -4    11.4  
           . . . . . . . . . 

      The length of file records must not exceed 80 characters.
      The format of the records is free, e.g. data must be separeted by
      blancs. ( be careful - some PDB files do not satisfy this rule)  
      Program uses the information about cell parameters and space
      group from PDB coordinate file.

C ==========================================================================

Apendix D.

     Optical resolution

     Optical resolution is defined as an expected minimum distance
     between two resolved peaks in the electron density map. It is
     computed from the width of the Patterson origin peak.

     A.A.Vaguine, J.Richelle, S.J.Wodak. SFCHECK: a unified set of 
     procedure for evaluating the quality of macromolecular structure-factor
     data and their agreement with atomic model.
     Acta Cryst.(1999). D55, 191-205

C ==========================================================================


Appendix E.


 BATCH file example:


# --------------------------------
/usr/in23/people/alexei/blanc/exe/molrep <<stop
# --------------------------------
#
_DOC  Y
#
_FILE_F fobs.dat
_FILE_M mm1.crd
#
#
_NP   8
_RAD 27
_LMAX 30
_ANISO C
_sim   .1
_compl .5
_END
stop

 BATCH file example of Self Rotation function:


# --------------------------------
/usr/in23/people/alexei/blanc/exe/molrep <<stop
# --------------------------------
#
_DOC  Y
#
_FILE_F fobs.dat
_FILE_M 
#
#
_RAD 27
_END
stop


 BATCH example with MTZ file:


# --------------------------------
/usr/in23/people/alexei/blanc/molrep/bin/molrep <<stop
# --------------------------------
#
_DOC  Y
#
_FILE_F p1.mtz
#
_F  FO
_SIGF  SDFO
_END    <--- end of MTZ block
#
_FILE_M p1_pdb.cds
#
#
_NP   8
_ANISO C
_sim   .1
_compl .5
_END
stop

 BATCH example with MTZ file for searching in the Electron Density map
 some model (usual Rotation Function will be used):


# --------------------------------
/usr/in23/people/alexei/blanc/molrep/bin/molrep <<stop
# --------------------------------
#
_DOC  Y
#
_FILE_F p1.mtz
#
_F  FO
_SIGF  SDFO
_PH    PH_FO
_END    <--- end of MTZ block
#
_FILE_M mod.pdb
#
#
_NP    8
_PHASE +
_END
stop


 BATCH file example of fitting two models:


# --------------------------------
/usr/in23/people/alexei/blanc/exe/molrep <<stop
# --------------------------------
#
_DOC  Y
#
_FILE_F 
_FILE_M mod1.pdb
#
_MODEL_2 mod2.pdb
_END
stop

C ==========================================================================


Appendix F.

  Memory control parameters ( in main_molrep.f or main_molrep_mtz.f):
 
C         PARAMETER ( MEMORY  = 900000)
C         PARAMETER ( NCRDMAX = 32000 )
C         REAL      POOL(MEMORY)
C -
C         IPRSYM - maximal number of symmetry operators
C         PARAMETER ( IPRSYM=48    )
C         INTEGER*2 ISYM(5,3,IPRSYM)
C 
C         ISYM    - integer*2 array for cryst.symmetry operators 
C         IPRSYM  - dimension of integer*2 array ISYM(5,3,IPRSYM)
C                   maximal number of cryst.symmetry operators.
C         NCRDMAX - maximal number of atoms.
C         POOL    - real array POOL(MEMORY)
C         MEMORY  - dimension array POOL. 
C
C -------------------------------------------------------


  Independence on operating system:


       There are only 2 subroutine depended on operating system
       in the file:  molrep_unix.f 

     DISPL_BL - write message to terminal and stop cursor at the end of line.
     CLOCK    - get date to --> array IH(). 

       (both are not very important for calculations)

       You need to uncomment corresponding operators in this subroutines.
       For example:

C
C              SUBROUTINE DISPL_BL(LINE)
C        C
C        C -P- DISPL - write message to terminal and stop cursor 
C        C             at the end of line.
C        C         
C              CHARACTER LINE*(*)
C              INTEGER*4 NL
C              CALL LENSTR_BL(LINE,NL)
C              IF(NL.GT.79) NL=79
C        CVX   WRITE(*,'(''$'',A)')   LINE(1:NL)
C        CDP   WRITE(*,'('' '',A,$)') LINE(1:NL)
C        CMS   WRITE(*,'('' '',A,\)') LINE(1:NL)
C        CLN   WRITE(*,'('' '',A,$)') LINE(1:NL)
C              RETURN
C              END
C
C      CVX - for VMS VAX 
C      CDP - for unix system
C      CMS - for MS-DOS
C      CLN - for Linux 
C
C
C      SUBROUTINE CLOCK(IH)
C
C -P- CLOCK - get date to --> array IH()
C
C    IH(2),IH(3),IH(4),    IH(5),IH(6),IH(7)
C     sec   min  hour      day   month year
C
C     INTEGER*4 IH(7)
C ******
CMS   INTEGER*2 IHR,IMN,ISEC,I100H,IYR,IMON,IDAY
CVX   CHARACTER STR*8
CDP   INTEGER*4 ID(3)
CLN   INTEGER*4 ID(3)
C --------------------------------
C
CVX   CALL IDATE(I1,I2,I3)
CVX   IH(5)=I2
CVX   IH(6)=I1
CVX   IT1  =I3+1900
CVX   IH(7)=IT
CVX   CALL TIME(STR)
CVX   READ(STR,'(I2,1X,I2,1X,I2)') IH(4),IH(3),IH(2)
CVX   IH(1)=0
C
C
CMS   CALL GETTIM(IHR,IMN,ISEC,I100H)
CMS   CALL GETDAT(IYR,IMON,IDAY)
CMS   IH(4)=IHR
CMS   IH(3)=IMN
CMS   IH(2)=ISEC
CMS   IH(5)=IDAY
CMS   IH(6)=IMON
CMS   IH(7)=IYR
CMS   IH(1)=I100H/2
C
CDP
CDP   CALL ITIME(ID)
CDP   IH(4)=ID(1)
CDP   IH(3)=ID(2)
CDP   IH(2)=ID(3)
CDP   CALL IDATE(IMON,IDAY,IYR)
CDP   IYR=IYR+1900
CDP   IH(5)=IDAY
CDP   IH(6)=IMON
CDP   IH(7)=IYR
CDP   IH(1)=0
CDP 
C
C
CLN
CLN   CALL ITIME(ID)
CLN   IH(4)=ID(1)
CLN   IH(3)=ID(2)
CLN   IH(2)=ID(3)
CLN   CALL IDATE(IMON,IDAY,IYR)
CLN   IYR=IYR+1900
CLN   IH(5)=IDAY
CLN   IH(6)=IMON
CLN   IH(7)=IYR
CLN   IH(1)=0
CLN 
C  
C
C     RETURN
C     END
C ==========================================================================
