		ProteinNM
	Computing the normal modes of a protein structure 

1. Background
================

This package includes one program, ProteinNM, designed to compute
the normal modes of a protein represented with a coarse grained
potential on an elastic network.
It performs the following task:
(a) Read the protein structure (PDB and CIF format accepted)
(b) Generate the elastic network for the protein
	If requested, filter this elastic network using rigidity theory
(c) Build the Hessian of the coarse grained potential on the elastic network
	Two different potentials are considered, the Elastic potential
	of Tirion, or a GO like potential
(d) Computes the normal modes associated with the potential
	Two options:
		- Use full diagonalization for small system
		- Use an iterative Chebyshev Jacobi Davidson method
		  for large system
(e) Report eigenvalues and computed B-factors

2. The Program: Installation
=============================

I distribute the source code for the whole program, including all
subroutines, under the LGPL licensing code. Please read the text of
the license (License.LGPLV3 provided with the distribution). 
Basically, you are allowed to use and modify this code freely. 
You are also allowed to distribute it, provided that you include
the source code for all functions involded in ProteinNM.

The Makefile provided with the distribution are intentionally kept
simple. It is very likely that you will have to tweak it for
your own system (the program is written in C++ and compatible
with any version above C++14. The only package used that is not standard
is the Gnu Multiple Precision (GMP) library. This library is installed
by default on Linux system. On MacOSX, you will have to install it,
for example with 
brew install gmp

To install the program, just unzip the archive, go to the main directory,
and type
make

Note that this will use the standard g++ compiler
that should be installed by default on your Linux / Unix / MacOS X
install. 

Again, you may have to tweak the Makefile for your system

3. Running the Program
======================

The name of the executable is ProteinNM; it is located in the bin
subdirectory. Here I define:
- the inputs needed by the program
- typical commands to run the program

I will assume you are in the examples directory

3.a. Input parameters
=====================

If you just type
../bin/ProteinNM
you will see:


     ============================================================================================
     ============================================================================================
     =                                                                                          =
     =                                     ProteinNM                                            =
     =                                                                                          =
     =     This program computes some eigenpairs of the Hessian of the ENM of a protein         =
     =     Usage is:                                                                            =
     =                 ProteinNM                                                                =
     =                    -i  <input file for protein> (in PDB / CIF format)                    =
     =                    -o  <basename for output files>                                       =
     =                    -a  <atoms to include (0) CA, (1) all> (Default: 0)                   =
     =                    -g  <(0) Tirion or (1) Go potential>   (Default: 0)                   =
     =                    -e  <(1) cutoff or (2) Delaunay ENM>   (Default: 1)                   =
     =                    -f  <(0) no filter, (1), rigidity filter> (Default: 0)                =
     =                    -cm <(0) no ordering, (1), reverse cuHill-McKee ordering (Default: 0) =
     =                    -k  <K-constant for springs>  (Default: 1)                            =
     =                    -c  <cutoff value>  (Default: 15)                                     =
     =                    -as <dimension of the active space  (Default 400)                     =
     =                    -cf <order of Chebishev filter)         (Default 60)                  =
     =                    -b  <block size> (only for ChebDav)     (Default 16)                  =
     =                    -ne <approx. number of eigenpairs>     (Default: 100)                 =
     =                    -m  <eigen method>   (Default: 0)                                     =
     =                        0: full diagonalization (only for small systems, no GPU!)         =
     =                        1: Chebyschev Jacobi Davidson                                     =
     =                    -p  <# of threads> (if on CPU)                                        =
     =                    -t  <input file for target> (in PDB / CIF  format) (default: none)    =
     ============================================================================================
     ============================================================================================

Some explanations for each option, assuming:

-i	Provide the name of the input file containing the protein structure
	It can be in PDB format, or CIF format

-o	Basename for all output files
	If the basename is for example "test1", then the program will create:
		- a file test1.pml, a pymol script to be used to visualize the elastic network
		- a file test1.bfact, the atomic B factors (both experimental and computed)
		- a file test1.bfact2, For each normal mode index i, the correlations between 
					experimental B-factors and computed B-factors when
					all normal modes from 7 to i are included
		- (optional): a file test1.over: For each normal mode index i, the overlap
					between the displacement of two conformations
					(the one provided with -i and the one provided with -t)
					and the normal modes, when all normal modes from 7 to i 
					are included

-a	Which atoms are considered. Most computations should be done with a = 0 (the default
				value) as we are dealing with coarse grained representation

-g	Potential considered, Tirion, or G0-like

-e	Type of elastic network considered, cutoff-based, or Delaunay

-f	Apply rigidity-based filtering or not

-cm	Reordering of the Hessian matrix with reverse cuHill-McKee ordering. 
	It is there for historical reason and does not really help

-k	Force constant associated with the springs for the Tirion model

-c	cutoff for the cutoff-based elastic network. I would adive 14 or 15.

-as	(only for Chebyshev Jacobi Davidson method). Size of active space.
	Should be at least 2x the number of eigenvalues to be computed.
	400 (default) is a good value when computing 100 eigenvalues

-cf	(only for Chebyshev Jacobi Davidson method).
	Order of the Chebyshev filtering. 60 to 80 are good values

-b	(only for Chebyshev Jacobi Davidson method).
	Block size. Efficient when set to be the number of threads assigned to the program

-ne	Number of eigenvalues to be computed

-m	diagonalization method:
		0 : full diagonalization (great for systems with < 3000 atoms)
		1 : Chebyschev Jacobi Davidson (should handle systems up to 1 million atoms)

-p	Number of threads used by the program (by default, should use all available;
        sometimes finicky on Linux, so set it explicitly)

-t	(optional): Input file for a different conformation of the protein considered.
		If provided, the program will compute the overlap between the displacement
		between the two conformations, and the normal modes. Results are in
		file "test1".over, where test1 is the name you provided with option -o


3.b. Typical runs
=================

A typical run on the small PDB structure 1A29.pdb (calmodulin)
(available in the directory examples) would be:

../bin/ProteinNM -i 1A29.pdb -o test1 -a 0 -e 1 -g 1 -c 14 -ne 100 -f 1 -m 0

with:
	-a 0	: only consider CAs
	-e 1	: cutoff based elastic network
	-g 1	: Tirion potential
	-c 14	: cutoff value
	-ne 100	: 100 normal modes considered
	-f 1	: apply filter
	-m 0	: full diagonalisation

A typical run on the large PDB structure 3J6T.pdb (dengue, serotype 3)
(available in the directory examples) would be:

../bin/ProteinNM -i 3j6t.pdb -o test2 -a 0 -e 1 -g 1 -c 14 -ne 100 -f 1 -m 1

with:
	-a 0	: only consider CAs
	-e 1	: cutoff based elastic network
	-g 1	: Tirion potential
	-c 14	: cutoff value
	-ne 100	: 100 normal modes considered
	-f 1	: apply filter
	-m 1	: iterative Chebyshev Jacobi Davidson diagonalization

4. Disclaimer
==============

The program is provided "as is". Contact koehl@cs.ucdavis.edu
if you have any problems.
