

------------------------------
Membrane ANM
02/06/2012
------------------------------

These files can be used to investigate the effects of the 
membrane on ANM results.  


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

1. Installation
2. File descriptions
3. Examples

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

1. Installation

For full functionality, it is best to install the LAPACK and BLAS 
libraries.  These will significantly speed up the eigendecomposition 
of the Hessian matrix.  If you have some other method of decomposing 
the Hessian matrix, then feel free to use that.  Matlab scripts that 
serve this purpose may be obtained from the ANM website.  

In the (near) future, all decomposition routines will be included in the
imanm software, so that the intermediate steps of decomposing the block 
Hessian and projecting it into the full-residue space will be eliminated.

To compile, unpack the tarball, change to the 'membranm' directory and type:

$ make all

To clean up, type
$ make clean

The executable created generates a Hessian matrix using 
the RTB approximation and a modified ANM potential in the 
x- and y- directions.  


================================================================
2. File descriptions

-----------------
Source code
-----------------
block2full_free.c -- Projects RTB eigenvectors into space of all residues
deigsrt.c -- Numerical Recipes routine for sorting double-precision eigenvectors
dpythag.c -- Numerical Recipes routine 
dsvdcmp.c -- Numerical Recipes routine for double-precision SVD
imanm.c -- imANM 
lapdecomp_free.c -- Driver for lapsolve
lapsolve.c -- LAPACK-based code for decomposing symmetric matrices
membranmutil.c -- Utilities for membrane ANM
nrutil.c -- Numerical Recipes utilities

-----------------
Example files
-----------------
2nwl.blk
2nwl-mem.pdb


----------------------------------------------------------------
blockfiles
----------------------------------------------------------------

The input to imANM is referred to as a 'blockfile', which describes 
the rigid blocks that are to be used.   The first 6 characters in
each row of the blockfile are a header that indicate the type of data in 
the row (similar to a PDB file).  There are currently 3 types of 
headers, all of which are required:

PDB	Indicates the name (including path) of the PDB file to be 
	used in the calculation.

BLOCK	Defines a block.  Each line contains 7 columns, separated 
	by whitespace:

	1. Integer identifier of the block.
	2. Three-letter code for first residue in block.
	3. Chain ID of first residue in block.
	4. Sequential number of first residue in block.
	5. Three-letter code for last residue in block.
	6. Chain ID of last residue in block.
	7. Sequential number of last residue in block.

	Blocks do not have to appear in order, and several blocks
	assigned to the same block ID will be grouped together in
	the calculation.  Blocks of single residues are allowed, 
	and are treated as point particles.  Blocks of two residues
	are separated into two one-residue blocks.

END	Indicates the end of the BLOCK definitions and the file.


In addition to these fields, the blockfile may specify some values
for the calculation that would otherwise be entered on the command-line.
These are: 
	mlo=	Sets the lower z-bound of the membrane (like -b flag)
	mhi=	Sets the upper z-bound of the membrane (like -b flag)
	cut=	Sets the cutoff distance (like -c flag)
	mscl=	Sets the membrane scaling factor  (like -s flag)

The values set in a blockfile override the default values used by the 
program, and values provided on the command line override any values
set in the blockfile.  

Rows beginning with '#' are considered comments.



====================================================================
3. Example
--------------------------------------------------------------------
As an example, the blockfile '2nwl.blk' is provided, along with its 
associated PDB file '2nwl-mem.pdb'.

To view the command-line options of imANM, simply run the program without 
an input file:

$ imanm

To generate a RTB Hessian from the blocks:
$ imanm 2nwl.blk >2nwl.hessian

The program reads the block definitions and the PDB file, calculates
the ANM Hessian in terms of the rigid blocks, and prints it to 
standard output (here redirected to '2nwl.hessian').

The Hessian matrix must then be decomposed.  This can be done with the
provided 'lapdecomp_free' program, which requires the LAPACK and BLAS libraries:
$ lapdecomp 2nwl.hessian 50

The files '2nwl.val' and '2nwl.vec' contain the first 50 eigenvalues and
eigenvectors of the block Hessian.  The block eigenvectors are projected
back into the space of all residues using the 'block2full_free' program provided.
This program needs to know the relationship between the rigid blocks and the
individual nodes of the molecule, and it gets this information from a projection
matrix that maps the block space to the all-residue space.  The projection
matrix '2nwl.prj' is generated with the imANM program with the command:

$ imanm 2nwl.blk -p >2nwl.prj

Now the block eigenvectors can be projected into the space of all residues:
$ block2full_free 2nwl.prj 2nwl.vec >2nwl_full.vec

The eigenvectors in 2nwl_full.vec contain 3582 components, corresponding to 
x-, y- and z-components for each of the 1194 residues.  


