=-=-=-=-=-=-=-=-=-=-=-=-=-= WELCOME =-=-=-=-=-=-=-=-=-=-=-=-=-= Membrainy is a membrane analysis tool designed to work with GROMACS xtc/trr/tpr/cpt/gro/pdb files. Membrainy has a wide range of features, including: Gel/Fluid percentages - Area per lipid - Bilayer thickness - Lipid Order Parameters - Headgroup Orientations - Surface 2D maps - Thickness 2D maps - Annular Shell analysis - Voltage against Time - Lipid Demixing entropy. Membrainy has been hard coded with force-field parameters for various common lipids in the CHARMM36, GROMOS53a6/Berger and Martini force fields. The main aim of Membrainy is to provide a unified membrane analysis tool that can interpret almost every membrane without the need for complex index or topology files. There is no complicated setup required, Membrainy should "just work". My philosophy in writing software is "The coders should do all the coding, the scientists should do all the science". However all too often, scientists are having to battle with the software, negotiating horrendous c++ installations and setting up complicated configuration files. Mistakes are all too easy to make, and headaches are all too common. This shouldn't be the case. With a bit of extra coding, and using a pre-compiled language such as java, software can do all the hard bits internally so the scientist doesn't have to. That way the scientist can spend more time making discoveries and less time banging his/her head off the wall. Membrainy hopes to provide a user friendly and simplistic experience. The interface is nearly identical to GROMACS and uses similar commands such as '-f' for input files and '-s' for the system information file. If you come from a GROMACS background, Membrainy should be intuitive. I hope that you find Membrainy a pleasure to use. Happy analyzing! =-=-=-=-=-=-=-=-=-=-=-=-=-= DEVELOPMENT =-=-=-=-=-=-=-=-=-=-=-=-=-= If you encounter a bug, or if there is a lipid type/force field you wish to be implemented, please contact me at: support@membrainy.net I will be more than happy to assist you. Sometimes I miss emails amongst the sea of spam, so feel free to hassle me again and again if you need to. =-=-=-=-=-=-=-=-=-=-=-=-=-= PREREQUISITES =-=-=-=-=-=-=-=-=-=-=-=-=-= In order to use certain features such as reading in GROMACS xtc/tpr/trr/cpt files, there must be a working version of GROMACS installed and located in the classpath. Membrainy requires use of the GROMACS programs 'editconf' and 'gmxdump' to convert the binary files into readable format. It is my assumption that anyone using Membrainy will already have this prerequisite, but if you don't, please visit http://www.gromacs.org/ to obtain a copy. Membrainy was originally tested with GROMACS v4.6.5 and then later v2020, but it should work with all future versions. In order to run voltage vs time calculations, Membrainy requires the use of the GROMACS 'g_potential' program. If you have used a suffix in your GROMACS binaries (e.g. editconf_mpi) then please use the option "-g_suffix _mpi" with your Membrainy arguments, replacing _mpi with whatever suffix you use. =-=-=-=-=-=-=-=-=-=-=-=-=-= INSTALLATION INSTRUCTIONS =-=-=-=-=-=-=-=-=-=-=-=-=-= Membrainy is written in Java, so there is no installation required. All you need is Java v1.6 or later. You may find it handy to place a bash script in your classpath to make running Membrainy easier. To run Membrainy, simply type java -jar Membrainy.jar A suitable bash script would look something like this: #!/bin/bash java -jar /path/to/Membrainy.jar "$@" =-=-=-=-=-=-=-=-=-=-=-=-=-= ARGUMENTS =-=-=-=-=-=-=-=-=-=-=-=-=-= The arguments for Membrainy have been designed to be extremely similar to those of GROMACS. To see the available arguments, simply run: java -jar Membrainy.jar -h Which brings up the following: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Membrainy: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Input: -f (xtc,trr,tpr,cpt,gro,pdb,mbr) TPR: -s (tpr,gro,cpt,mbr) ForceField: -ff auto (CHARMM,GROMOS,Martini) External Library: -l (file) Threads: -nt 8 Verbose: -v false (bool) Start: -b 0.0 (ps) End: -e 0.0 (ps) Time Step: -dt 0.0 (ps) Options: Double bilayer: -[no]db auto (bool) Leaflet Update dt: -leafletdt 0.0 (off) (ps) Leaflet Detection Method: -ldm simple (simple,vector,index) Headgroup Angles: -angles false (bool) Angle Type: -angles_type lateral (lateral,axial) Angles vs Time: -angles_vs_time false (bool) Area Per Lipid: -apl false (bool) Entropy: -entropy false (bool) Gel Formation: -gel false (bool) Gel Tolerance: -gel_tol 0.9 Order Parameters: -order false (bool) OP Histograms: -hist false (bool) Thickness: -thickness false (bool) =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Annular Shells: Enable Shells: -shell false (bool) Use Control Grp: -[no]control false (bool) Control Type: -control_type shell (full,shell,#) Ignore Hydrogens: -ignh false (bool) No Gel in Control: -nogel false (bool) Scan Type: -scan full (full,headgroups,tails) Scan Radius: -rad 4.0 (Angstroms) Output Shell Traj: -traj false (bool) Output Control Traj: -ctraj false (bool) Shell Analysis: -analysis false (bool) Choosen Peptide(s): -peptide all (integer(s)) =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2D Surface Maps: Enable Surface Maps: -smap false (bool) # of Iterations: -iterations 100 Resolution: -res 400 Enable graphics: -[no]graphics true (bool) =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Voltage vs Time: Enable VVT: -vvt false (bool) Slices: -sl 1000 (int) =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Notes on the arguments: - For most simulations, the -db argument can be ignored, as double bilayers are detected automatically. This option exists for heavily undulated systems where Membrainy might have a hard time distinguishing the undulations from double bilayers. You can use -db and -nodb if needed. - leafletdt determines the interval in which Membrainy will scan the leaflets for changes, such as lipid swapping. A value of 0.0 performs this calculation every frame. You may get a small speed increase (but not substantial) by setting this value to something higher if you know there is no lipid swapping in your system. However there is no harm leaving it set to 0. - gel_tol is a value (between 0-1) which is converted to a percentage. This percentage is used to monitor the lipid tails and determine if a lipid is in a gel or fluid state. The length of the lipid tails is calculated within the trajectory and compared with the tail length defined by the force field. If this tail length is above the tolerance, the lipid is counted as gel. Using a smaller tolerance will result in more lipids being counted as gel lipids. - the -control_type option defines how much sampling goes into the control group when comparing with annular shelled lipids. Setting this as 'full' will use every lipid outside of the shell in the control group. 'shell' will use exactly the same number of lipids in the control group as found in the shell, randomly selected each frame. The number of shelled lipids likely varies from frame to frame and will produce the most appropriate comparison. Typing in a number will limit the control group to a fixed number of lipids, randomly selected on each frame. We suggest you leave this as 'shell'. - nogel should be used when looking at peptides or proteins that have inserted into fluid regions (and your membrane contains gel lipids). There is probably no harm in using this option with fully fluid membranes also. This option uses the value from -gel_tol, so this may also need to be set. - traj and ctraj are there as a sanity check, to output the lipids in the shell and in the control group to a trajectory file. You can then view these in VMD. - The -analysis option provides detailed output files for information about the shelled lipids. - peptide can be set to all, one, or several peptides. For example, if you had 4 peptides in your system, and peptides 2 and 4 had inserted and you wanted to analyse their shells, you would type '-peptide 2 4'. This will produce averages of the two shells. - iterations and resolution can be modified depending on the membrane size. A membrane of size 10nm x 10nm works best with a resolution of around 400 and 100 iterations of the guass-seidel algorithm. If you are using smaller membranes, you may want to lower the resolution, and smaller resolutions may work better with smaller iterations (but try with 100 first). It is best to play around with these values to achieve the best quality images. - slices defines how many slices the box can be split up in the z-axis, used to calculate the electrostatic potential. The option is identical to the one used in g_potential. 1000 is a good number for double bilayers with height ~20nm. =-=-=-=-=-=-=-=-=-=-=-=-=-= RUNNING MEMBRAINY =-=-=-=-=-=-=-=-=-=-=-=-=-= A running example of executing an analysis would be: java -jar Membrainy.jar -f input.xtc -s input.gro -apl -gel -dt 1000 This would load the system information from input.gro and then run an area per lipid and gel percentage calculation on input.xtc, only sampling every 1000ps =-=-=-=-=-=-=-=-=-=-=-=-=-= Lipids and Force Fields =-=-=-=-=-=-=-=-=-=-=-=-=-= The following is a list of what lipids are currently implemented for each force field. CHARMM: Headgroups: PA, PC, PE, PG, PS, CHL1 (cholesterol) Tails: DA, DL, DM, DO, DP, DS, LL, LP, OS, PL, PO, SA, CHL1 (cholesterol) GROMOS/Berger: DLPC, DMPC, DOPC, DPPC, POPC, POPE, LPOPG, DPOPG Martini: Headgroups: PA, PC, PE, PG, PS, CHOL (cholesterol) Tails: DA, DL, DP, DO, DS, DU, PO, CHOL (cholesterol) =-=-=-=-=-=-=-=-=-=-=-=-=-= External Library =-=-=-=-=-=-=-=-=-=-=-=-=-= For lipids not found on the above list, Membrainy can import new lipids using an external library file. This file can also be used to implement new force fields. An example file can be found in the tutorial, which contains a template of the various flags needed to load in the new lipid information. I highly recommend following Tutorial 4 to learn how to use these flags. Also note that you can override the internal library by using the external library, which may be useful if your system does not follow the usual naming convention for a given force field. The naming convention of hydrogen atoms is still calculated using the standard naming convention for each force field and cannot be specified in an external library. For most cases, you should always try to use the standard naming conventions to avoid problems. Here are some of the values that can be specified in the external library file: [ FF ] - Used to specify a new force field FFName = CHARMM - The force field name FFType = UnsatHydrogenSuffixChain1 = R S - Used to specify the naming convention suffix found on the hydrogens connected to unsaturated carbons for tail 1 UnsatHydrogenSuffixChain2 = X Y - Used to specify the naming convention suffix found on the hydrogens connected to unsaturated carbons for tail 2 C-CLength = 1.53 - The length of a C-C bond C=CLength = 1.34 - The length of a C=C bond C-C=CLength = 1.502 - The length of a C-C=C bond C-C-CAngle = 113.6 - The angle of a C-C-C bond C-C=CAngle = 123.5 - The angle of a C-C=C bond WaterBondAngle = 104.45 - The angle of an H-O-H bond WaterBondLength = 0.9584 - The length of an H-O-H bond WaterOxygenAtomType = OW - The atom type of oxygen in water WaterHydrogenAtomType1 = HW1 - The atom type of hydrogen1 in water WaterHydrogenAtomType2 = HW2 - The atom type of hydrogen2 in water WaterResName = SOL - The residue name of water AnionAtomType = CL - The atom type of the anion AnionResName = CL - The residue name of the anion CationAtomType = K - The atom type of the cation CationResName = K - The residue name of the cation [ Residue ] - Anything listed under this flag will be recognised as a residue [ Water ] - Anything listed under this flag will be recognised as a water [ Ion ] - Anything listed under this flag will be recognised as an ion [ Cholesterol ] - Anything listed under this flag will be recognised as a cholesterol [ Lipid ] - Anything listed under this flag will be recognised as a lipid [ LipidTail ] - Used to specify a lipid tail group Name = PO - The identifier of the tail group FF = CHARMM - The force field of the tail group (used for generating the hydrogen atom types from the standard naming convention for that force field) TailChain1 = C21 C22 C23 C24 C25 C26 C27 C28 C29 C210 C211 C212 C213 C214 C215 C216 C217 C218 - The carbons in tail 1 UnsatChain1 = C28 C29 C210 C211 - The unsaturated carbons in tail 1 (always list four atoms, C-C=C-C) TailChain2 = C31 C32 C33 C34 C35 C36 C37 C38 C39 C310 C311 C312 C313 C314 C315 C316 - The carbons in tail 2 UnsatChain2 = - The unsaturated carbons in tail 2 (leave blank if no unsaturated carbons) - Some lipids use a unique number or letter as a suffix on the atom type for unsaturated hydrogens. This is usually the first element of the force field's 'UnsatHydrogenSuffixChain' parameter, however certain lipids such as POPC (for CHARMM) break this naming convention by using '1' instead of 'R'. UnsatSuffix = 1 [ LipidHead ] - Used to specify the lipid head group Name = PE - The identifier of the head group FF = CHARMM - The force field of the head group HeadgroupAtoms = N C12 C11 O12 O13 O14 O11 P - The atom types found in the headgroup (used for the annular shell analysis). You may include hydrogens if you want ReferenceAtoms = P N - The two reference atoms used in calculating headgroup orientations =-=-=-=-=-=-=-=-=-=-=-=-=-= Notes =-=-=-=-=-=-=-=-=-=-=-=-=-= Some important things to note: - Membrainy only works with planar membranes. It will not work with spherical membranes, and it may have problems with very heavily undulated membranes. This is because most calculations use the z-axis as a reference. If you are having problems with heavily undulated membranes, consider using an index file to specify the leaflets, with -ldm index -n index.ndx. When doing so, ensure the leaflet groups have the word 'leaflet' in the index file, i.e. Leaflet1, Leaflet2. - Currently all membranes must have their membrane normal in the z-direction. I can implement other directions if needed, but I don't know why anyone would want to do this... - Multiple analytical techniques can be run simultaneously. For multi-cored machines, you will likely not observe any speed reduction in doing this, as each analytical technique is run in parallel. - The "-dt" option works exactly like the GROMACS option. But it is worth noting that analytical techniques such as order parameters or headgroup angles work best with maximum sampling. So we advise you don't use -dt with these. - Membrainy will treat cholesterol as a lipid. However it will disclude cholesterol from calculations of order parameters and gel percentages. As a note, I haven't done much work with cholesterol so if you encounter any issues, let me know. - Gel percentage is very much an approximation based on the levels of linearity in the lipid tails. It may be required to look at the membrane using the surface maps (-smap) and judge for yourself the quantity of gel, then adjust the -gel_tol accordingly. I find a value of -gel_tol 0.9 seems to give fairly accurate results. - The scale assigned to the surface maps is very much an approximation. As far as I can tell, there is no clean way of assigning a scale to the product of a gauss-seidel algorithm. Membrainy selects the highest atom in the system, determines its corresponding value from the gauss-seidel algorithm, and scales it according to that height. =-=-=-=-=-=-=-=-=-=-=-=-=-= Contact =-=-=-=-=-=-=-=-=-=-=-=-=-= Questions, comments, suggestions, bug reports? Please email me at: support@membrainy.net Enjoy!