*************************************************************************
*                                                                       *
*                           The ECEPP Package                           *
*                                                                       *
*************************************************************************

Note:
    This is the file "$ECEPP_ROOT/README".
    The information and explanation of the program contained in this
    README file is correct and accurate as of Thu Jan  2 10:28:23 EST 1997.

What the Package Does
---------------------
The program performs the following calculations:
  1) Single Energy Evaluation.
  2) Single Energy Minimization
  3) Energy evaluation of Multiple Input Conformations
  4) Energy Minimization of Multiple Input Conformations
  5) Monte Carlo Search using a generalized MCM (EDMC) algorithm.
  6) PRODUCE an energy map for a pair of dihedral angles.
  7) Carry out an rms deviations analysis.
  8) Variable Target Function Procedure for structure determination.

Getting Started
---------------
The program requires a well defined setup. Some files must be
located in the correct directory for the program to run. Also, 
a few environmental variables need to be defined properly. We
recommend you follow the next instructions step by step.

1) The files "cshrc.eceppak" and "bashrc.eceppak" are provided in this
   directory to help you get started. 
   (a) Specify the environment variable ECEPP_ARCH by uncommenting 
       the proper line.
   (b) Specify the environment variable ECEPP_ROOT (should point to the 
       directory where the program is located).

2) Source the appropriate rc file in the eceppak directory. 

   Example: source /usr/daniel/eceppak/cshrc.eceppak

   You may want to make some changes to your own rc files so that your
   eceppak environment is setup automatically every time you login.
   This is usually convenient, but not necessary.

Compiling the Eceppak Package
-----------------------------
1) Change your current directory to eceppak/Source

2) There will be a file called "Makefile" in this directory. It is actually 
   a symbolic link to one of several different architecture dependent 
   Makefiles. If "Makefile" is not pointing to the correct Makefile for your 
   target platform, you should remove the link and reset it properly. 
   Note: when compiling the version for pH calculations, the file
   sims_01_pbl.f may not compile properly with high optimization levels. 
   Compile the file separately using lower level of optimization.
  For example, on the IBM SP2 use:
    mpxlf -c -O2 -g -qcheck -qsigtrap -IInclude -bmaxdata:500000000 -bmaxstack:500000000 sims_01_pbl.f

3) To generate the executable:
    Type "gmake". This will take a bit of time. 
    If the package fails to compile properly, please send a bug report. 
    See the file Doc/BUGS/Reporting.Bugs for details.

4) Check to see that the executable is correctly installed in your 
   eceppak/bin directory. 

5) Change directory to eceppak/Test, and then run the script "test_eceppak.sh".
   This will run the executable you produced in step 3 on each of the 
   sample input files in the Test directory hierarchy and compare the output 
   to a set of reference files using the "diff" utility. See the file 
   Test/README for more details.

How To Run The Eceppak Program
------------------------------
 - The script to run the program is called: recepp.s.  Actually, this is
   an alias that points to the proper script, which is architecture dependent
   and located in $ECEPP_ROOT/bin. The alias is set after you source the 
   cshrc.eceppak (or bashrc.eceppak) file.

   To run the program you should give a set of arguments, the number of
   arguments depends on the architecture. You will get precise information 
   about the arguments that should be used by typing, 
                 recepp.s 

   IMPORTANT: If "recepp.s" is not recognized, you need to source your 
              *rc.eceppak file. If the command does not execute properly, 
              then, check your rc file. It may have been set up incorrectly.  
              Look at previous point "To Start" to do this setup.

What's New
----------
* The old set of ECEPP Input files has been replaced by a more flexible 
    file structure.
* The main input file contains now a series of cards that define the type 
    of run and parameters.

* Residue Data file has been enhanced.
    This file contains the ECEPP/3 residues and other non-standard ones.
    There are 74 residues (including N-methyl residues), and new end groups 
    defined.
    The file is found under subdirectory eceppak/Data/Residue.

    Among the changes introduced in rsdata are:
    (a) Data on loop closing pairs was added. The program uses a general 
        treatment for these pairs (introduced by A.Liwo).
    (b) It includes N-methyl residues.
    (c) Hydration atom types were added in the description of atoms 
        (old hrs.data).
    (d) Description of 1-4 interactions is included in a more general format.
    (e) C' was replaced by C, NP in PRO and HPRO was replaced by N to increase 
        compatibility with PDB format.
    (f) Atom type of protons in COOH groups ( ASP, GLU, meASP, meGLU and 
        Carboxyl-End terminal) changed to type 1, (as in ECEPP/3, no H-bonding 
        allowed).

* Hydration parameters for different surface-solvation models are provided under
    the subdirectory eceppak/data/Hydration_files. The SRFOPT set (srfopt.set) 
    of parameters is defined as the default. Other sets can be used by 
    modifying the recepp.s script (eceppak/bin/recepp.s).
    The volume-solvation model developed by Joe Augspurger is also available
    as an option. 
    
Examples
--------
   The Input files provided as examples (directory eceppak/Test)
   will give you an idea of the calculations the program is able to do.
   See the file Test/README for more details.
    
    
FILE(S)                       EXPLANATION
-------                       -----------

enk_sol.inp       Calculation of surface solvation energy.
                  To execute type:
                  "recepp.s ENERGY enk_sol ENK_sol dummy dummy"

enk_checkgrad.inp Checking Gradient calculation.
                  "recepp.s CHECKGRAD enk_checkgrad ENKGRAD  dummy dummy"

enk_sp.inp           Calculate energy using a soft-sphere potential.
                  "recepp.s ENERGY enk_sp ENKSP dummy dummy"

enk.inp           EDMC run.
                  "recepp.s EDMC enk enk_out dummy dummy"

mebmt.inp         Minimization (with output from minimizer).
                  "recepp.s MINIMIZE mpa1ot MPA1OT dummy dummy"

avian.inp         ECEPP/3 and solvation energy.
                  "recepp.s ENERGY avian AVIAN dummy dummy"

cala6.inp         Cyclic peptide and solvation energy.
                  "recepp.s ENERGY cala6 CALA6 dummy dummy"

hisp1.inp         EDMC run with two possible states for PRO (UP and DOWN).
                  and HIS (HID and HIE) residues.
                  "recepp.s EDMC hisp1 HISP1 dummy dummy"

cys1.inp          Input sequence with 1-letter code.
                  "recepp.s ENERGY cys1 CYS1 dummy dummy"

three_let.inp     Input sequence with 3-letters code.
                  "recepp.s ENERGY three_let THREE_LET dummy dummy"

CPEP.inp          Energy minimization of multiple input conformations.
outo.CPEP         set of conformations to be minimized.
                  "recepp.s MINIMIZE CPEP CPEPout CPEP dummy"

ala_map.inp       Energy map.

ala_rms1.inp      RMS deviation analysis; generation of a reference
                  conformation.
ala_HELIX.pdb     Input for reference conformation generation in PDB format
outo.ala_rms      Input conformations for comparison in ECEPP format.
                  To execute type:
                  "recepp.s RMS_FIT ala_rms1 ala_rms1 ala_HELIX ala_rms"
                  As a result you get, among others, a file xray.ala_HELIX
                  that could be save for future use.

ala_rms2.inp      RMS deviation analysis; comparison of a conformation
                  (file in pdb format) with the reference one.
ala_HELIX.pdb     Input conformation for comparison in PDB format.
                  To execute type:
                  "recepp.s RMS_FIT ala_rms2 ala_rms2 HELIX ala_HELIX"

timbck.inp        Calculate upper and lower bounds for distance constraints
tim.pdb           runs from a pdb file.
                  "recepp.s BOUNDS timbck TIMBCK tim"

vtf_tim.inp       Example of a run using the Variable Target Function procedure.
outo.vtf_tim      Usually constraints come from NMR experiments
bounds.timbck      " recepp.s VTF vtf_tim VTFOUT dummy  timbck"


tim_sp.inp        Example of a Monte Carlo run combining distance constraints
bounds.timbck     and a soft-sphere potential  (NMR refinement).

NOTE: We have noticed that large differences can occur between EDMC runs
in different architectures. This appears to be related to machine precision. 
In general, a single energy calculation will tell you if the ECEPP/3 energy
function is working correctly. For EDMC runs, check if the program leads
to a sequence of improved energies.
