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

initial commit as published by original authors

Installation of g_permute
From the parent directory, where you unpacked g_permute-1.1.tar.gz run "sh g_permute/" 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 install
cd ../src
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 in
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
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
Feel free to contact 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
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.
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/' or 'g_permute/'.
* 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
#if !defined FALSE
#define FALSE 0
/*************** 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 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"
#ifndef CPP
#define EXPORT extern
/*************** 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 */
#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/
#by juergen haas < >
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 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 ==================================================
ParArgs="-j `cat /proc/cpuinfo|grep proc -c`"
#nothing should be changed by the user below this line*************************
echo CHECKING prerequisites...
echo Checking current path: `pwd`
if [ $(basename `pwd`) == "g_permute" ];then
echo It seems you are in the g_permute source directory
echo default target directory for GROMACS-$VER installation: `pwd`/../gromacs
echo please change to different directory and call `pwd`/$0
echo exiting ...
exit -1
echo ============= STARTING INSTALLATION NOW ==========
echo We need
if [ $compileGCC -eq 1 ];then echo $GCCFILE;fi
if [ $compileGCC -ne 0 ];then
if [ -f $GCCFILE ]; then
echo found $GCCFILE
elif [ $compileGCC -eq 1 ];then
echo trying:
echo wget$GCCFILE
echo SKIPPING - Finished Download
if [ ! -f $GCCFILE ];then
echo $GCCFILE not found please supply $GCCFILE from
echo aborting..
exit -1
if [ -f $GMXFILE ]; then
echo found $GMXFILE
echo trying:
echo wget$GMXFILE
echo Finished Download
if [ ! -f $GMXFILE ];then
echo $GMXFILE not found please supply $GMXFILE from
echo aborting..
exit -1
if [ -f $FFTWFILE ]; then
echo found $FFTWFILE
echo trying:
echo wget$FFTWFILE
echo Finished Download
if [ ! -f $FFTWFILE ];then
echo $FFTWFILE not found please supply $FFTWFILE from
echo aborting..
exit -2
#Above all gcc-3.3.6
#echo Installing ${GCCFILE%*.tar*}
#tar -xvjf $GCCFILE &> lam.log
#cd `ls -d */|grep gcc-|sed 's/\///g'`
#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 Installing ${GCCFILE%*.tar*}
tar -xvjf $GCCFILE &> gcc.log
relPath=`ls -d */|grep gcc-|sed 's/\///g'`
relInstPath=`echo $relPath|sed 's/[-\.]//g'`
echo $relInstPath $relPath
mkdir "objdir_"$relPath
cd "objdir_"$relPath
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 ..
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"
#1 we care for the fftw libraries
echo Installing ${FFTWFILE%*.tar*}
tar -xvzf $FFTWFILE &>fftw.log
cd ${FFTWFILE%.tar.gz}
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 Now installing ${GMXFILE%*.tar*}
tar -xvzf $GMXFILE &>gromacs.log
cd gromacs-$VER
sleep 1
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 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
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.
# 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:
# 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
# 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
CC = cc
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
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)