Add new file

README.md

+-----------------------------------
+Umbrella integration  
+-----------------------------------
+
+Authors: Martin Stroet (University of Queensland)
+         Evelyn Deplazes (Curtin University, University of Queensland) 
+
+
+When using this program please cite the following paper 
+
+	Deplazes E., Stroet M, Passioura T., Chassagnon I., Cristofori-Armstrong B., 
+	Rash LD., King GF., Mark AE., Journal, vol. no. (year) 
+	DOI
+
+Please also cite the GitHub project using the following DOI
+	DOI for GitHub project 
+	http://gitlab.biosci.uq.edu.au/uqedepla/Umbrella-Integration
+
+The calculation of the derivatives, the free energy profile (potential of mean 
+force, PMF) is based on the equations in the following paper by Kästner & Thiel 
+	Kästner J. and Thiel W., J. Chem. Phys. 123, 144104 (2005); 
+        doi: 10.1063/1.2052648 
+The estimates of uncertainties for the PMF are based on equations in 
+the equations in the following paper by Kästner & Thiel 
+	Kästner J. and Thiel W., J. Chem. Phys. 124, 234106 (2006); 
+        doi: 10.1063/1.2206775
+
+
+--------------------
+About the program
+------------------------
+
+PyUI is a set of python script that calculates a potential of mean force (PMF) 
+from the data produced by umbrella sampling simulations (e.g. with the pull 
+code in the GROMACS MD package). The PMF is calculated by integrating the 
+derivative of the free energy with respect to the reaction coordinate (RC) 
+as described by Kästner and Thiel (2005, J. Chem. Phys.).
+
+The idea of this program was to keep the analysis of the PMF independent from 
+the simulation package that was used to run the umbrella sampling simulations. 
+All the required input can easily be extracted and/or calculated by the user 
+from the trajectories or other output files specific to the MD package used.
+
+The program contains the following components 
+- umbrella-integration: calculations of the derivatives and the free energy 
+  profile (PMF) based on data in the user-provided input file
+- convergence check (optional): runs a convergence check on each of the ‘window’ 
+- error analysis (optional): estimates the uncertainties in the free energy 
+  profile 
+
+For a description of how to use the scripts, the required format and content of 
+the input file, a description of the convergence analysis, error analysis and 
+the test data see the separate sections below. 
+
+** IMPORTANT ** 
+The following are things to consider when using PyUI:
+The scripts were developed for the analysis of a few specific systems that we 
+work with. While we tried to make the code applicable to other systems, it is 
+likely that the user has to adapt the script to work with her/his particular 
+system or data. 
+
+Reaction coordinate:
+The program is implemented to work with a reaction coordinate that is a 
+distance between two molecules (or groups of molecules). In the test data 
+provided on GitHub the reaction coordinate is either 
+i) the distance between the center of mass (COM) of a peptide and the COM of 
+a protein
+ii) the distance between the COM of an ion and the COM of a lipid bilayer 
+iii) the distance between the COM of an ion and the COM of a lipid bilayer.
+
+In principle the code can also be used for other geometric reaction coordinates 
+such as angles or dihedrals that produces a continuous distribution of values. 
+But the code will have to be adapted for more complicated reaction coordinates 
+(e.g. number of H-bonds, coordination spheres
+etc).
+
+One-dimensional only:
+The program only works for a one-dimensional PMF ie a single reaction 
+coordinate. The following paper by Kästner describes an extension of umbrella 
+integration for two or more reaction coordinates, which can be used to adapt 
+the program for the analysis of multidimensional PMFs.
+	Kästner J., J. Chem. Phys. 131, 034109 (2009); 
+	http://dx.doi.org/10.1063/1.3175798
+
+Restraining potential: 
+the program assumes the bias potentials applied to the system is in the 
+form of harmonic restraints. The code needs to be adapted for any other
+form of restraining potentials.
+
+
+---------------
+Installation 
+---------------
+
+There is no installation required, simply clone PyUI from GitHub
+
+http://gitlab.biosci.uq.edu.au/uqedepla/Umbrella-Integration
+
+OR 
+
+git clone ssh://git@scmb-gitlab.biosci.uq.edu.au:2023/uqedepla/Umbrella-Integration.git
+
+The umbrella integration code expects the code for the convergence analysis and 
+the error analysis  to be in the same parent folder. 
+
+
+---------------------
+Requirements 
+----------------------
+
+Python 3.1 or higher
+
+The program uses the following packages 
+
+numpy 
+http://www.numpy.org
+
+matplotlib / pyplot
+http://matplotlib.org/index.html
+http://matplotlib.org/api/pyplot_api.html
+
+SciPy 
+https://www.scipy.org/getting-started.html
+
+