Commit 1834e030 authored by lheinz's avatar lheinz
Browse files

initial commit as published by original authors

parents
Installation of g_permute
-------------------------
*********************
PREREQUISITES: installing GROMACS-3.3.1
From the parent directory, where you unpacked g_permute-1.1.tar.gz run "sh g_permute/instGMX331.sh" to install GROMACS-3.3.1
*********************
g_permute consists of two parts, the 'lap' library in 'g_permute/liblap' and the tool
itself, 'g_permute' in 'g_permute/src.
Both parts rely on the GROMACS MD package for some functions.
The code has been tested with and requires GROMACS Version 3.3.1.
A - quick version, no editing of Makefiles required
---------------------------------------------------
when using the above mentioned install script, a mere
cd liblap
make
make install
cd ../src
make
make install
will install g_permute in ../g_permute-1.1 with the directories 'lib' 'include' and 'bin';
Make sure LD_LIBRARY_PATH is afterwards set to include the path of the '../g_permute-1.1/lib' directory otherwise g_permute will report a shared library error.
B - advanced version, adjust Makefiles to your GROMACS-3.3.1 (compiled with shared library support)
------------------------------------------------------
1) cd into 'liblap' and edit the Makefile
- set PREFIX to the directory you want the final library to go
(leaving the recommended default in Version A will install liblap.so in
../g_permute-1.1/lib
Make sure the path you enter here is in your LD_LIBRARY_PATH when running g_permute
- specifiy GMXDIR, GMXLIB and GMXINC to point to your Gromacs
installation
make sure you have compiled gromacs with shared libraries enabled
(i.e. with 'configure --enable-shared')
[alternatively, issuing the follwing command in
gromacs-x.x.x/src may suffice 'ln -s libgmx/.libs/libgmx.a libgmx/libgmx.a']
in liblap/, type 'make', then 'make install'
2) cd into 'src' and edit the Makefile as in liblap
type 'make' followed by 'make install'
leaving the default setting for PREFIX will install g_permute to ../g_permute-1.1/lib
Have fun !
User Manual Version 1.1
#######################
1. What is g_permute ?
======================
g_permute is a tool to relabel the solvent molecules in a molecular
dynamics trajectory such that their distance to a reference position
becomes minimal. The result is a new trajectory, where the solvent
molecules are centered around their reference positions, rather than
exploiting the full configuration space as in the original trajectory.
This renders established entropy estimation methods applicable and makes
diffusive systems accessible to improved fit functions. For further details
see the publications cited on the webpage mentioned below.
g_permute was written in the computational biophysics group (Helmut Grubmuller)
at the MPI for biophysical chemistry in Goettingen (Germany)
and is available under the download section
http://www.mpibpc.mpg.de/home/grubmueller/
Feel free to contact juergenhaas@gmx.net for further information.
2. Installation
===============
The prerequisite GROMACS package and its dependencies can be installed
automatically with a supplied script.
Please consult the ./INSTALL file for details!
3. Usage
========
3.1 Input arguments
-------------------
g_permute takes as input arguments
three filenames
-f the input trajectory
-n an index file
-r the reference structure
and one numerical argument
-m the size of the solvent molecules
its output goes into a file specified by
-o the output trajectory
-f can be in any Gromacs-readable format
-r specifies the reference structure. In the course of g_permute, the
solvent molecules will be relabeled in each frame of the input trajectory
such that the distance to the solvent of this reference structure
becomes minimal.
The reference structure thus has to contain the same topology as any
frame of the input trajectory. Again, any Gromacs-readable format is
possible.
If none given the positions in the first frame are used as reference frame.
-n is an index file. It has to contain
1) one index group specifying all solvent atoms. The atom indices have to
be grouped into molecules. e.g, for TIP4P water (four atoms, one oxygen,
two hydrogens and a dummy atom), the first molecule corresponds to
indices 1-4, the second to 5-8, ...
2) one index group specifying one key atom in each solvent molecule.
The distance to the reference structure is computed as
the total distance of these key atoms to their positions
in the reference structure
The user is responsible to make sure that each solvent
molecule of group 1 contains only one key atom of group 2
--- example for TIP4P water ---
[ oxygen_atoms ]
1 5 9 13 etc.
[ solvent_atoms ]
1 2 3 4 5 6 etc.
In the case of relabeling TIP4P water, the first
group contains the indices of all O atoms of the water molecules. The
second group contains the indices of all atoms.
-m The size of a molecule (e.g., 4 for TIP4P water). The solvent group
is internally split into blocks of size 'm', which explains the
grouping condition mentioned above.
After startup, g_permute will ask you to choose from your index file
- the group for the distance calculation
(i.e., group 2) from above, for TIP4P water: the oxygens)
- the solvent group (group 1 from above)
3.2 optional switches
---------------------
g_permute takes up to 5 optional switches, where the switches -b and -e are to be used for frames selection, while -com and -rm_pbc affect the distance calculation itself. The switch -dt reduces the number of frames to include only those where time t modulo the timestep of the trajectory dt is equal the time indicated.
-com center of mass (COM) mode instead of default picking of first atom (oxygen in case of water as solvent)
-rm_pbc calculate distance using periodic boundary conditions, default is off
-b Begin at the specified frame in ps
-e End at the specified frame in ps
-dt Only consider frames when time t MOD dt == first time (ps), otherwise disregard frame.
3.3 Data output
---------------
Output is written to a file specified by -o, there are two optional output files containing COM coordinates, either permuted or in original order.
-o the output trajectory
-oref trajectory containing COM coordinates in original order (optional)
-orefp trajectory containing the permuted COM coordinates (optional)
4. Example run
==============
The simplest command to permute TIP4P water molecules (4 atoms per molecule) in a
GROMACS based trajectory is:
g permute -m 4 -s start_struc.pdb -f traj.xtc -o permute.xtc -n index.ndx
g permute then reads in the topologies of the system from start struc.pdb
and the trajectory from traj.xtc, referring to the groups listed on index.ndx. The
first group will be used for the determining the distances and the second one for the solvent group.
The permuted trajectory will be written to permute.xtc. Note that the output
trajectory can also be written directly to a multi-model pdb file.
5. Hints and practicalities
===========================
5.1 Composing index files
-------------------------
Since we cannot do without an index file, we recommend to use the GROMACS
tool make_ndx. A call to make_ndx requires a structure file in 'pdb' or
a run input file in the GROMACS 'tpr' format.
make_ndx -f start_struc.pdb
On a box filled exclusively with tip4p water molecules make_ndx will give
the following options:
There are: 216 OTHER residues
There are: 0 PROTEIN residues
There are: 0 DNA residues
Analysing Other...
0 System : 864 atoms
1 SOL : 864 atoms
nr : group ! 'name' nr name 'splitch' nr Enter: list groups
'a': atom & 'del' nr 'splitres' nr 'l': list residues
't': atom type | 'keep' nr 'splitat' nr 'h': help
'r': residue 'res' nr 'chain' char
"name": group 'case': case sensitive 'q': save and quit
Choose now all oxygen atoms:
>a OW
Found 216 atoms with name OW
2 OW : 216 atoms
press the <ENTER_KEY> to list the groups
0 System : 864 atoms
1 SOL : 864 atoms
2 OW : 216 atoms
nr : group ! 'name' nr name 'splitch' nr Enter: list groups
'a': atom & 'del' nr 'splitres' nr 'l': list residues
't': atom type | 'keep' nr 'splitat' nr 'h': help
'r': residue 'res' nr 'chain' char
"name": group 'case': case sensitive 'q': save and quit
Choose to save to 'index.ndx' and quit.
>q
You now should have the newly created index.ndx.
5.2 Visualisation of trajectories to investigate effect of permutation
----------------------------------------------------------------------
>>>visualise with vmd:
vmd start_struc.pdb permute.xtc
select graphical representations
Enter into Selection field 'resname OW and resid 1 to 10'
Draw Style > drawing method > VdW
Draw Style > colouring > resid
Trajectory > Draw multiple frames > 0:100
>>>repeat this for the unpermuted trajectory:
vmd start_struc.pdb traj.xtc
In the window 'VMD Main' click on the 'D' to de/active the display of that
individual trajectory to compare the two trajectories. In the permuted trajectory
the oxygen atoms will be centered around a reference position and thus cover a
smaller area than in the original trajectory.
5.3 Memory issues
-----------------
The number of solvent molecules contained in these groups is limited by
the available system memory (RAM), so if you encounter messages like not
enough memory, play with the number of molecules in the solvent group
(SOL) in the case of water.
5.4 dash / sh compatibility issues
----------------------------------
On ubuntu systems you might encounter shell errors, which can be overcome by explicitely running 'bash g_permute/instgmx331.sh' or 'g_permute/instgmx331.sh'.
/************************************************************************
*
* gnrl.h
version 1.0 - 21 june 1996
author Roy Jonker, MagicLogic Optimization Inc.
header file for general stuff
*
**************************************************************************/
/*************** CONSTANTS *******************/
#if !defined TRUE
#define TRUE 1
#endif
#if !defined FALSE
#define FALSE 0
#endif
/*************** DATA TYPES *******************/
typedef int boolean;
/*
* This file contains some functions to simplify memory handling
* of matrices and vectors. It was taken from
* the Jonker / Volgenant LAP code and adapted slightly
* see http://www.magiclogic.com/assignment.html for details
*/
#include <memory.h>
#include "lap.h"
#include <stdio.h>
#include <stdlib.h>
void terminate(void);
int *alloc_ints(int len);
void free_ints(int *ints);
cost *alloc_costs(int len);
void free_costs(cost *costs);
cost **alloc_costmatrix(int width, int height);
void free_costmatrix(cost **cmat, int width, int height);
/************************************************************************
*
* lap.h
version 1.0 - 21 june 1996
author Roy Jonker, MagicLogic Optimization Inc.
header file for LAP
*
**************************************************************************/
#include <typedefs.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#ifndef __LAP_H
#define __LAP_H
#ifdef CPP
#define EXPORT extern "C"
#endif
#ifndef CPP
#define EXPORT extern
#endif
/*************** CONSTANTS *******************/
#define BIG 100000
/*************** TYPES *******************/
typedef int row;
typedef int col;
typedef double cost;
/*************** FUNCTIONS *******************/
EXPORT cost lap(int dim, cost **assigncost, int *rowsol, int *colsol, cost *u, cost *v);
EXPORT void checklap(int dim, cost **assigncost, int *rowsol, int *colsol, cost *u, cost *v);
#endif /* __LAP_H */
#!/bin/bash
#This script will unpack, compile first FFTW and then GROMACS and install GROMACS in ./gromacs afterwards.
#this is intended to be bundled with g_permute-1.1 and higher
#and should be started from a directory above its location:
#after unpacking just type
#cd .. and
#bash g_permute/instGMX331.sh
#
#by juergen haas < juergenhaas@gmx.net >
VER=3.3.1
GMXFILE=gromacs-$VER.tar.gz
FFTWFILE=fftw-3.1.2.tar.gz
GCCFILE=gcc-4.0.2.tar.bz2
echo
echo
echo ============= HINTS FOR INSTALLATION ==========
echo If you wish to compile and subsequently use gcc-4.0.2 set the switch compileGCC=1 in this install script
echo
echo If you wish to use change the number of processors used during compilation set the switch compileParallel=1 and modify ParArgs to the number desired in this install script
echo ==================================================
echo
compileGCC=0
compileParallel=1
ParArgs="-j `cat /proc/cpuinfo|grep proc -c`"
#nothing should be changed by the user below this line*************************
echo CHECKING prerequisites...
echo
echo Checking current path: `pwd`
if [ $(basename `pwd`) == "g_permute" ];then
echo
echo It seems you are in the g_permute source directory
echo
echo default target directory for GROMACS-$VER installation: `pwd`/../gromacs
echo please change to different directory and call `pwd`/$0
echo exiting ...
exit -1
fi
echo ============= STARTING INSTALLATION NOW ==========
echo We need
echo $GMXFILE
echo $FFTWFILE
if [ $compileGCC -eq 1 ];then echo $GCCFILE;fi
echo
if [ $compileGCC -ne 0 ];then
if [ -f $GCCFILE ]; then
echo found $GCCFILE
elif [ $compileGCC -eq 1 ];then
echo trying:
echo wget ftp://ftp.mirrorservice.org/sites/sourceware.org/pub/gcc/releases/gcc-4.0.2/$GCCFILE
wget ftp://ftp.mirrorservice.org/sites/sourceware.org/pub/gcc/releases/gcc-4.0.2/$GCCFILE
echo SKIPPING - Finished Download
echo
echo
if [ ! -f $GCCFILE ];then
echo $GCCFILE not found please supply $GCCFILE from www.gromacs.org
echo aborting..
echo
exit -1
fi
fi
fi
if [ -f $GMXFILE ]; then
echo found $GMXFILE
else
echo trying:
echo wget ftp://ftp.gromacs.org/pub/gromacs/$GMXFILE
wget ftp://ftp.gromacs.org/pub/gromacs/$GMXFILE
echo Finished Download
echo
echo
if [ ! -f $GMXFILE ];then
echo $GMXFILE not found please supply $GMXFILE from www.gromacs.org
echo aborting..
echo
exit -1
fi
fi
if [ -f $FFTWFILE ]; then
echo found $FFTWFILE
else
echo trying:
echo wget ftp://ftp.fftw.org/pub/fftw/$FFTWFILE
wget http://www.fftw.org/$FFTWFILE
echo Finished Download
echo
echo
if [ ! -f $FFTWFILE ];then
echo $FFTWFILE not found please supply $FFTWFILE from www.fftw.org
echo aborting..
echo
exit -2
fi
fi
#Above all gcc-3.3.6
#echo
#echo Installing ${GCCFILE%*.tar*}
#echo
#tar -xvjf $GCCFILE &> lam.log
#cd `ls -d */|grep gcc-|sed 's/\///g'`
#pwd
#sleep 1
#configure --prefix=/usr/local/gcc-3.3.6 --enable-languages=c,c++,g77 >& confi_.log
#./configure --prefix=../gcc336 --enable-languages=c,c++,g77 &> confi_.log
#make bootstrap
#make install
#export CC=../gcc336/bin/gcc
#export F77=../gcc336/bin/g77
#export PATH=../gcc336/bin:$PATH
#cd ..
#Above all gcc-4.0.2 if specified.
if [ $compileGCC -eq 1 ];then
echo
echo Installing ${GCCFILE%*.tar*}
echo
tar -xvjf $GCCFILE &> gcc.log
relPath=`ls -d */|grep gcc-|sed 's/\///g'`
relInstPath=`echo $relPath|sed 's/[-\.]//g'`
echo $relInstPath $relPath
InstPath=`pwd`/$relInstPath
mkdir "objdir_"$relPath
cd "objdir_"$relPath
pwd
sleep 1
../$relPath/configure --prefix=$InstPath --enable-languages=c,c++,f95 &> confi_.log
make $ParArgs bootstrap >& make.log
make $ParArgs install >& makeInst.log
export CC=$InstPath/bin/gcc
export F77=$InstPath/bin/gfortran
export CXX=$InstPath/bin/g++
#export DSSP=$InstPath/../dssp
export PATH=$InstPath/bin:$PATH
cd ..
else
echo make sure you have f77,g77 or gfortran installed and set the environment variables F77,CC and CXX
echo also make sure that \$PATH contains the directories of the compilers needed.
echo "example: export F77=/usr/bin/gfortran"
fi
#1 we care for the fftw libraries
echo
echo Installing ${FFTWFILE%*.tar*}
echo
tar -xvzf $FFTWFILE &>fftw.log
cd ${FFTWFILE%.tar.gz}
pwd
sleep 1
./configure --prefix=`pwd`/../fftw --enable-type-prefix --enable-float >& confi_FFTW.log
make $ParArgs clean >& makeFFTW.log
make $ParArgs >& makeFFTW.log
if [ $? -ne 0 ];then echo exiting, due to error encountered;exit -128;fi
make install >& makeInstFFTW.log
cd ..
#3 we install gromacs
echo
echo Now installing ${GMXFILE%*.tar*}
echo
tar -xvzf $GMXFILE &>gromacs.log
cd gromacs-$VER
pwd
sleep 1
echo
echo making non-parallel gromacs
export LDFLAGS="-L`pwd`/../fftw/lib"
export CFLAGS="-I`pwd`/../fftw/include "
export PATH=$PATH:`pwd`/../lam/bin
./configure --prefix=`pwd`/../gromacs --disable-x --without-x >& confi_SERIAL_GMX.log
make $ParArgs >& makeSERIAL_GMX.log
if [ $? -ne 0 ];then echo exiting, due to error encountered;exit -128;fi
make install >& makeInstSERIAL_GMX.log
cd ..
#
echo Reached end of install script for GROMACS-$VER
echo
echo
echo please issue \"make\" followed by \"make install\" first in g_permute/liblap and then g_permute/src/.
echo NOTE: in case you want to recompile it is usually safer to issue \"make clean\" before \"make\"
Licensing information for liblap
--------------------------------
This library is an implementation of an algorithm proposed in
R. Jonker and A. Volgenant (University of Amsterdam)
"A Shortest Augmenting Path Algorithm for Dense and Sparse Linear Assignment Problems", Computing 38, 325-340 (1987)
The implementation distributed with g_permute is a slightly changed
version of the original implementation of the authors which can be found at
http://www.magiclogic.com/assignment.html
Note that the code is *not* distributed under GPL. Instead, it is
licensed as follows:
"The code is Copyright 2003 MagicLogic Systems Inc., Canada.
These codes are made available in the hope that they will be useful,
but without any warranty. Also, we [the authors] cannot accept any
responsibility for their use.
The codes are available only for non-commercial use. Please contact
MagicLogic for commercial application."
With permission of the authors, this code has been slightly changed
for use with g_permute.
#!/bin/sh
#
# This is a Gromacs 3.0 template makefile for your own utility programs.
#
# Copy this file to whatever directory you are using for your own
# software and add more targets like the template one below.
#
# If you are using gmake it is relatively straightforward to add
# an include based on environment variables (like previous Gromacs versions)
# to select compiler flags and stuff automatically, but below it is static:
#
SHELL=/bin/sh
# this is where executable and libraries will go - we recommend to
# leave PREFIX to the default
# PREFIX must match the PREFIX later used in the ../src/Makefile
#
# note that PREFIX/lib has to be in your LD_LIBRARYPATH to run the program.
PREFIX = ../../g_permute-1.1
EXEC_PREFIX = $(PREFIX)
BINDIR = $(EXEC_PREFIX)/bin
LIBDIR = $(EXEC_PREFIX)/lib
INCDIR = $(EXEC_PREFIX)/include
# pointer to your Gromacs installation - please adjust
GMXDIR = ../../gromacs
GMXLIB = $(GMXDIR)/src/gmxlib
GMXINC = $(GMXDIR)/include/gromacs
# Source of the installation. No need to change this
SRCDIR = ..
CC = cc
LDFLAGS = -L$(GMXLIB) -lm
INCFLAGS = -I$(SRCDIR)/include -I$(GMXINC)
LDSOFLAGS = -shared -Wl,-soname,
#for compilation on 64bit systems uncomment the following line
#CFLAGS = -O0 -fomit-frame-pointer -finline-functions -Wall -Wno-unused -fPIC -DPIC -funroll-all-loops -ggdb
#for compilation on 32bit systems uncomment the following line
CFLAGS = -O0 -fomit-frame-pointer -finline-functions -Wall -Wno-unused -malign-double -funroll-all-loops -ggdb
OBJS = lap.o memory.o
EXE = liblap.so
tvar := $(shell if (test -h $(LIBDIR)/$(EXE).1);then echo 1;else echo 0;fi)
# pattern rule to compile object files from C files
# might not work with make programs other than GNU make
%.o : %.c Makefile
$(CC) $(INCFLAGS) $(CFLAGS) -c $< -o $@
all: $(EXE)