Merge pull request #34 from wiederm/cleanup

Cleanup

README.md

@@ -1,77 +1,43 @@
 Transformato
 ==============================
 [//]: # (Badges)
-[![Travis Build Status](https://travis-ci.org/wiederm/transformato.png)](https://travis-ci.org/wiederm/transformato)
 [![codecov](https://codecov.io/gh/wiederm/transformato/branch/master/graph/badge.svg)](https://codecov.io/gh/wiederm/transformato/branch/master)
 
-Transformato is a package that helps to set up an equilibrium sampling protocol for relative free energy calculations of small molecules with a common core scaffold. The package is designed to be used with output from CHARMM-GUI (www.charmm-gui.org).
+Transformato is a package that helps to set up relative alchemica free energy calculations of small molecules with a common core scaffold, either for solvation free energy or binding free energy estimates. The package is designed to be used with output generated by CHARMM-GUI (www.charmm-gui.org).
 
-### Theory
+## Theory
 
-The thermodynamic cycle used by Transformto is shown below:
+Transformato uses a common core of two molecules to connect the physical endstates of two molecules via two seperate alchemical paths. The common core is defined as the maximum topology mapping between two molecular graphs using elements to identify matching nodes.
+In the example shown below the input are two physical systems (i.e. systems that are parameterized and generated without dummy atoms or unpysical additions to the topology) which are connected via their common core structure.
 
-![drawing-1](https://user-images.githubusercontent.com/31651017/72672192-dc8c4480-3a56-11ea-9906-67bd27810c9e.png)
+![SAI_Intro_v2](https://user-images.githubusercontent.com/31651017/138690737-ebc2cdcd-ee04-459e-b291-ba59b94578f8.png)
 
-The strategy is to turn atoms of two molecules to dummy atoms (shown in green) to obtain a common core (cc) between the two molecules (in this case a CH3 group) and subsequently mutate the common core of molecule 1 (cc1) to the common core of molecule 2 (cc2) to obtain equivalen states. This closes the thermodynamic cycle. 
-In the depicted example the additional step from cc1 to cc2 might not be necessary since both cc1-CH3 and cc2-CH3 might be equivalent in their bonded and non-bonded terms, but this is a special case. For more general mutations the change in bonded and non-bonded terms will be necessary. The mutation strategy used by Transformato can deal with changes in bonded and non-bonded parameters of the common core.   
+This is done by gradually turning the starting topology and parameter set im the common core molecule. For toluene and methane, the common core structure is a CH3-X, with X as a LJ particle with default vdW parameter. The alchemical transformation is performed by first turning off the electorstatics of the molecules that will become dummy atoms (for toluene this is everything that is in the green circle and for methane it is the red highlighted hydrogen). Afterwards the vdw parameters are turned off, again for the molecules in the green circle (this step is only necessary for toluene, since for methane the X hydrogen is turned into a default LJ particle). This is done via the serial atom approach (for details see  Boresch, S.;  Bruckner, S. Avoiding the van der Waals endpoint problem using serial atomic  insertion. Journal of Computational Chemistry 2011,32, 2449–2458).
 
 
-A more in detail description of the mutation strategy used by Transformto will be described using the the following two molecules:
-![bitmap](https://user-images.githubusercontent.com/31651017/68553941-6e5b4e00-0425-11ea-8b81-065e013276c2.png)
+## How to use Transformato for alchemical free energy calculations
 
-The general approach is:
-- find the common maximum (connected) substructure (CMS) based on elements (ignoring bond and atom types)
-  - this defines the commen core (cc) for both small molecules resulting in cc1 and cc2. The commen core can be different in atom types, charges and bonded parameters but has a mapping between the atoms.
-- mutate the atoms that are not in the CMS.
-  - charges are linearly scaled to zero in multiple lambda states.
-  - LJ parameters are set to zero using a mutation strategy called serial atom insertion (SAI). This leads to either LJ fully intact or completly turned off for a single atom outside of the common core. At each LJ lambda protocol step the LJ terms of at least one atom are turned off.
-- linearly scaling of the bonded and non-bonded parameters of the common core.
+A good starting point are the two examples of alchemical free energy calculations given in the notebooks directory.
 
-Using these transformations we obtain the same common core between two different molecules with a common substructure.
+In general, the CHARMM-GUI output for the physical endstates is needed.
+For the `Loeffler`-benchmark set the necessary output is shown here:  https://github.com/wiederm/transformato-systems.
+To run the simulations you also need a config file, examples for these are shown in the notebooks directory.
 
+You also need to have openMM or CHARMM/domdec (CHARMM/openMM) installed, depending which of the two MD engines you want to use for energy/force calculations.
 
-## Common maximum substructure
+## Installation
 
-For our example the maximum common substructure is marked in read on both molecules.
-![bitmap](https://user-images.githubusercontent.com/31651017/68554631-c2683180-0429-11ea-8846-ce303fa933b9.png)
-
-The common core of mol1 and mol2 is different in bonded and non-bonded parameters (mol1 is aromatic, mol2 is not aromatic). The first step is now to define a mutation route to obtain a molecule where only the common core is interacting with the environment.
-
-
-### How to use transformato for binding free energy calculations
-
-## Setting up free energy calculations
-
-For 'endpoints' are needed to run a protein binding free energy simulation. 
-1. Ligand 1 in a waterbox
-2. Ligand 2 in a waterbox
-3. Ligand 1 in complex
-4. Ligand 2 in complex
-
-An example with the ligands shown above is deposited in transformato/data.
-The directory with 2OJ9-e1 has the enol form of the ligand and 2OJ9-e2 the keto form of the ligand.
-
-All these directories are directly taken from CHARMM-GUI. After you solvate either the ligand or the ligand+protein and download the system for openMM you have to run a short minimization using the scripts obtaine from CHARMM-GUI.
-
-To use the Transformato free energy set up the next step is to set up a config file for you run.
-The config file for 2OJ9-e1 and 2OJ9-e2 is shown in transformato/config/2oj9_example.yaml.
-What is important here is that the tree letter code (tlc) used in the psf is the same as in the config file.
-
-
-## Generating equilibrium samples along the alchemical path 
-After this step you should run the transformato/notebooks/example.ipynb notebook to generate the intermediate states connecting the two ligands. There are two variables you want to adapt there: the yaml file that is loaded and where you want to write the intermediate state files to. Both is further explained in the jupyter notebook.
-
-After the notebook has generated all the intermediate states you have to run the simulations script `simulation.sh` that is located in each intermediate state directory. This script will generate equilibrium conformations and save the trajectory.
-## Calculating the free energy difference using MBAR
+You can use `python setup.py install` to directly install the code of the repo. Before doing so please take a look in devtools/conda-envs/test_env.yaml to install the dependencies.
 
 ### Maintainers
 
-- Marcus Wieder <[email protected]> (MSKCC)
+- Marcus Wieder <[email protected]> (University of Vienna)
+- Johannes Karwounopoulos <[email protected]> (University of Vienna)
 
 
 ### Copyright
 
-Copyright (c) 2019, Marcus Wieder
+Copyright (c) 2021, Marcus Wieder, Johannes Karwounopoulos, Stefan Boresch
 
 
 #### Acknowledgements