initial commit as published by original authors

INSTALL

+
+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

+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'.
+
+

include/gnrl.h

+/************************************************************************
+*
+*  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;
+

include/gp_memory.h

+/*
+ * 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);
+

include/lap.h

+/************************************************************************
+*
+*  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 */

instGMX331.sh

+#!/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\"
+
+
+
+
+
+

liblap/LICENSE

+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. 
+

liblap/Makefile

+#!/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 $@
+