
                       B L A N C

    The BLANC program suite is a collection of programs which can be used
    for macromolecular structure determination by X-ray crystallography. The
    suite is designed to provide experienced crystallographers and students 
    with a number of simple tools. Beside set of small programs, the BLANC
    system introduces so-called superprograms which represent larger programs
    composed of several smaller programs. They utilize so-called black-box
    principle requiring minimum preparations or intervention from a user.
    The programs are written in standard Fortran77. They are connected by
    standard BLANC data files. The package has been ported to all the major
    platforms such as Unix, VMS and DOS.

================================================================

   Authors:      A.A.Vagin, G.N.Murshudov, B.V.Strokopytov

   Reference: 

                A. A. Vagin, G. N. Murshudov and B. V. Strokopytov
                BLANC: the program suite for protein crystallography 
                J. Appl. Cryst. (1998). 31, 98 - 102

================================================================

                  HOW TO GET BLANC


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

          After untaring  ( command: tar xvf blanc.tar ) `blanc.tar' ,
          you will get a blanc directory, with ccp4, doc, dic, example, exe,
          for, mappage, mmm, lib, prog, start/unix, start/linux 
          subdirectories and files: sfcheck.tar.gz, molrep.tar.gz,
          makecif.tar.gz, contact.tar.gz, mir.tar.gz, README

       b) Compilation.

            1. go to directory: blanc/start/unix

            2. sh setup.unx 
          
                  or 

               if you want to have CCP4 version of programs
               give command:

               sh setup_ccp4

          For Linux system:
 
              
            1. go to directory: blanc/start/linux

            2. sh setup.unx  

            3. if you want to have CCP4 version for programs
               give command:

               sh setup_ccp4

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

      before running

        Get commands: 1. "setenv BLANC path_name".
                                         Example: "setenv BLANC ~alexei/blanc
                          or put it to your ".personal-cshrc"

                      2.  set path to executable files
                              Example: "set path=($path ~alexei/blanc/exe)"

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

    For details look at BLANC manual in the file: blanc/doc/blanc_descr.txt


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

    Some superprogram have independent from BLANC versions.
 
 SFCHECK  -   pub/alexei/sfcheck.tar.gz
 MOLREP   -   pub/alexei/molrep.tar.gz
 CONTACT  -   pub/alexei/contact.tar.gz

 LIBCHECK !
 MAKECIF  !-  pub/alexei/makecif.tar.gz
 MODCHECK !
 EMIN     !

 MIR      !
 MIR_II   !-  pub/alexei/mir.tar.gz
 TRAHALO  !

 About these programs see below and also README files in these tar files. 

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

    Connection with CCP4.

 1. There are two programs: 

        A) MTZ2CIF which reads MTZ file and writes output
          CIFile. Use program TOBLANC to convert CIFile to BLANC file.

        B) DNS2CCP4 which converts density map( BLANC format) to CCP4 format.

    You can find MTZ2CIF,DNS2CCP4 and makefile in directory: blanc/ccp4

    For compilation give command: make mtz2cif or/and  make dns2ccp4

 2. You can have CCP4 version SFCHECK which can read MTZ file.

    For compilation go to directory: blanc/sfcheck/src
    and give command: make ccp4.
    Name of program will be the same as for ordinary version: sfcheck  

 3. You can have CCP4 version MOLREP which can read MTZ file.

    For compilation go to directory: blanc/molrep/src
    and give command: make ccp4.
    Name of program will be the same as for ordinary version: molrep  
 
 4. You can have CCP4 version MIR which can read MTZ file.

    For compilation go to directory: blanc/mir/src
    and give command: make mir_ccp4.
    Name of program will be : mir  

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

 6. Batch file blanc/start/unix/setup_ccp4 prepares CCP4 version all
    these programs: SFCHECK,MOLREP,MIR,MTZ2CIF,DNS2CCP4.
    Go to directory: blanc/start/unix and give command: sh setup_ccp4 

---------------------------------------------------------------------
======================================================================

    Independent superprograms:

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

      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 with correct position
                 and orientation.
               * 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.

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

    MIR

    There are three super_programs for Isomorphous replacement method:
    MIR, MIR_II, TRAHALO. Main program is MIR. Others may be used
    for semi-automated solution or if you like to play with parameters of 
    program.

       MIR         * performs automated heavy atom search and phasing for
                     one or several derivatives. This program is based on
                     program TRAHALO which used translation function
                     approach for heavy atom solution.
                   * Program supports SAD,SIR,SIRAS,MIR,MIRAS cases.
                   * can use MTZ file as input.
                   * can use the phases from other sources.
                   * can manage pseudo-translation.
                   * can refine phases by density modification 
                     /solvent flattening/

    Other prorams are the auxiliary programs. Their input files have BLANC
    format. You can have these files after program MIR.
   

       TRAHALO       TRAslation function Heavy Atom LOcation.
                   * performs automated heavy atom  search and phasing 
                     for one derivative.  
                   * Program supports SAD,SIR,SIRAS cases.
                   * can use the phases from other sources.
                   * can manage pseudo-translation.
                     / also is the part of MIR /

       MIR_II        performs automated phasing: computes the phases of 
                     native structure factors by using information of several
                     derivatives (structure factors and coordinates). 
                     Can refines phases by  density modification  
                     /solvent flattening/
                     / this program is auxiliary program, just refines
                       heavy atom position, computes ABCD coefficients
                       and combines its. /                                     
---------------------

     MAKECIF -  uses as input CIF or PDB_file and libraries mon_lib.cif,
                ener_lib.cif, symlib.blc and creates files:
                1. with atomic coordinates, symmetry and unit cell
                   parameters. / file extension "crd"/ 
                2. with chemical structure description and atomic
                   scattering structure factors. / file extension "str"/
                3. with restraints: standard values of bonds, angles, 
                   torsion angles, chirality centres, plan groups, its
                   actual values in the structure. / file extension "rst"/
                4. with Van-der-Waals and H_bond restraints: standard values
                   of distanceis and its actual values in the structure. /file
                   extension "vdw"/
    
                Program can read additional library of monomers.
                Program rebuilds missing atoms used information from
                monomer's library.
                If the description of a monomer is absent in the library
                program will try to create library description and write
                it to special file for further inclusion to the library.
                Program creates PostScript files with the pictures of new
                monomers.
                Program can generate hydrogen atoms.
 

     MODCHECK - reads CIFiles of coordinates and restraints,
                gives information about restraints (to DOC_file),
                writes PDB_file or/and CIFile of coordinates.

     LIBCHECK - reads library of monomers, gives information about some
                monomer, creates PostScript file with picture and information
                about bonds, angles, ...
                can read additional library, add two libraries and write to
                a new library file ;
                can create description of new monomer reading coordinates
                from PDB file of CIFile.
                Program can generate hydrogen atoms.
                                  
     EMIN       performs energy minimization or B_factor regularization; 
                minimizes the energy of structure using the restraints
                files from program MAKECIF.
 
                     E_total = E_bond + E_angle + E_tors + E_vdw + E_hb
                                  
                           E_bond  = Sum ( Kb * (Bobs     -Bidl)**2    )
                           E_angle = Sum ( Ka * (ANGLEobs -ANGLEidl)**2)
                           E_tors  = Sum ( Kt * (PHIobs   -PHIidl)**2  )
                           E_vdw   = Lennard-Jones 6-12 potential
                           E_bond  = 10-12 potential

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

     SFCHECK  - A program for assessing the agreement between the atomic 
                model and X-ray data. The program requires one or two input 
                files, with the coordinates of the model (in PDB or CIF or 
                BLANC format) and structure factors (in CIF or PDB or BLANC 
                format), and runs completely automatically.
                gives information about R-factor, correlation, Luzzaty plot,
                Wilson plot, Boverall, ...,local error estimation by residues.
                Can compute omit phases and use its instead phases of model.
                For output information program generates PostScript file.

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

    CONTACT  computes inter or/and intra molecular contacts;
 
             * can compute contacts only for special atoms ( for example
               for potential H-bonds);
             * can generate additional symmetry related atoms (with
               occupancy = 0) which are closed to initial molecule;
               can do it only for water molecules (water structure);
             * checks atoms in special positions and changes multiplicity
               for these atoms.
 
---------------------
======================================================================
