MDENERGY
-------------
by Jan Saam
saam@ks.uiuc.edu
saam@charite.de

WARNING:
MDEnergy is a bit outdated! Almost all things you can do with mdenergy can
nowadays also be done with NAMD in a more consistent way (see the PairInteraction 
feature in the NAMD users guide). There even exists a simple gui for that called 
namdenergy (found in the extensions menu). So mdenergy is somewhat outdated, but 
it can be useful if you want to play around with the source code as a template 
for your own trajectory analysis tool.


MDEnergy is a programm to calculate energies from DCD or PDB-files. It
is originally derived from Mindy, a simplified version of the NAMD engine,
written by Justin Gullingrud. It can calculate the different bonded and 
nonbonded energies for each atom based on the information from the PSF-file
and the coordinate file that you have to specify. The total energy values
are identical to the NAMD output, except for roundoff errors, in case you 
specify the same cutoff and switch distance same as in the NAMD input file.
You can also compute the energy for a selection of atoms or determine
the interaction energy between two sets of atoms.
MDEnergy is very memory efficient because is processes DCD files frame 
by frame.
The output format is similar to NAMD's output and you can plot it with 
'namdplot' (comes with NAMD).

You can build binaries for different architectures (named mdenergy.Linux,
mdenergy.IRIX, etc.) and the wrapper script 'mdenergy' determines 
automatically which one to use. (For this version I only tested Linux!)
The entire program is command line driven and has defaults for most 
of the parameters that can be given through the command line options.
But the wrapper shell script allows you to use personal default values  
which is especially useful for filenames.
Furthermore there is a TCL script (mdenergy.tcl) that allows to run
MDEnergy conveniently within VMD which simplifies the usage of atom
selections. In a future version an IMD connection to VMD will be 
provided over which the coordinates will be sent to mdenergy. That avoids 
rebuilding the molecule upon every new request.

The TCL-script visual_mdenergy.tcl contains a procedure with the same name that
visualizes the atom based energy values. You must use the mdenergy 
option -a <filename> to dump the atom energies to a file that can be read by
visual_mdenergy.
 

You must specify on the command line or in the wrapper srcipt:
--------------------------------------------------------------
You always need a PDB or DCD file as coordinate input:
-pdb file   and/or  
-dcd file   : You can specify as many files as you want, they will
	      process in order of occurance. They must have the same 
	      number of atoms and MDEnergy assumes that they all belong
	      to the same structure.

And you need parameters and structure information:
-par file   : The parameter file in charmm style.
or
-xplor file : The parameter file in xplor style.

-psf file   : The PSF file (charmm/xplor).

or alternatively
-amber      : AMBER partop file (parm7)
	      (contains parameters and structure)


You must specify one or more of the following options to tell mdforce 
which energies it has to calculate:
---------------------------------------------------------------------
-smooth n : No energies are computed but a trajectory with smoothed
	    coordinates is emitted. See -avg for info how smoothing 
	    works.
-all      : All energies are computed
-bond     : Bond energy
-angl     : Angle energy
-dihe     : Dihedral energy
-impr     : Improper energy
-vdw      : Van der Waals energy
-elec     : Electrostatic energy
-nonb     : Nonbonded energies (elec, vdw)
-conf     : Conformational energy (bond, angl, dihe, impr)
-kin      : Kinetic energy (need velocity dcd file: -vel file)
-hbon     : Computes h-bond energies (angle and distance dependent)
            according to the explicit hydrogen-bond term as is was
	    used in older versions of the CHARMM force field (see
	    X-PLOR manual for a nice description).
	    The H-bond term has the form
	    E = (A/r^6 - B/r^4) * cos^4(theta_A-H-D) * cos^2(theta_AA-A-D)
	    involving atoms AA, A, H, D (acceptor antecedent, acceptor,
	    hydrogen, and donor heavy atom) while
            well depth = -B^2/4A and the optimal distance = (2A/B)^(1/6).

	    WARNING: The energies computed have nothing to do with the
	    ones that are computed in NAMD using a modern force field
	    like CHARMM22 or greater! I.e. the energies are not compliant
	    with these force fields since the latter treat hydrogen bonds
	    implicitely by parametrizing the VDW and electrostatic terms
	    accordingly. Nevertheless the explicit H-bond energies can be
	    useful for visualization purposes, they show a nice angle
	    dependency.

	    If you want the "real" H-bond energies you must compute
	    the sum of the electrostatic and VDW energy between the
	    donor/hydrogen and the acceptor/antecedent pairs.
	    This can be achieved by running MDEnergy once for each
	    H-bond computing the interaction between the donor group and
            the acceptor group.	(See option -sel regarding the definition
	    of groups.

	    The computed H-bond energies can be very nicely visualized
	    in VMD with the script visual_hbonds (in 'hbonds.tcl').
	    See documentation therein.

            You need to have:
            A psf file with populated NBON and NACC fields to tell 
	    MDEnergy about the donors and acceptors in your system.
	    You can generate it using the 'hbondpsf' tool which is 
	    contained in this distribution. With the help of the
            DONOR/ACCEPTOR information in the topology file and an 
            existing psf file it generates a new psf including the
	    required donor/acceptor info.
	    Further you have to specify:
            -hpar <file> : H-bond parameter file
			   A sample file that should be sufficient for 
			   most cases is provided in hbonds/hpar

            Optional:
            -pat <file> : If there residue patches were applied to the
	                  molecule, then you should specify them in a 
			  file. The reason is that the PRES resnames are
			  not stored in the pdb and psf file and we want
			  to lookup the correct donor/acceptor pairs in
			  the topology file.
			  The format is the same as used in 'psfgen', e.g.
			  "patch ACE RH:1" for N-terminal acetylation of
			  protein segment RH.
			

Other options/parameters: 
-------------------------
-xplor      : By default MDEnergy assumes a CHARMM format parameter file. 
              Use this option to tell MDEnergy that you are using xplor
              format.

-beg <n>    : the first frame to process. Default=0
-end <n>    : the last frame to process. you can say 'last' instead of a 
              number, if you just mean the last frame of the dcd file.
              Default='last'

-switch <d> : switch distance for VDW interaction. Default=10
-cutoff <d> : cutoff distance for nonbonded calculation. Default=12
              (switch is the distance at which the switching function for VDW 
              interaction begins, cutoff is where it ends and where the VDW 
              interaction is zero.
              -switch 20 -cutoff 25 starts the switching function at 20A and 
              at 25A it has reached zero.
 	      For the electrostatic interaction switch has no meaning, while
	      cutoff marks the point where the interaction is zero. The 
	      potential function is shifted to obtain this.)

-scale14fac <n> : VDW 1-4 scaling factor in CHARMM style
-sncb <n>       : VDW 1-4 scaling factor in AMBER style.
	          This would be 1/scale14fac. See NAMD manual for details.

-noamberexcl  : Don't read exclusions from parm file but autogenerate
		them.

-sel <file> : File with indices for an atom selection.
              The energy for the selected atoms is computed.
              For the nonbonded energies the interaction of the selection 
              with the environment is included.
              If this option is used twice the nonbonded interaction energy 
              between the two selections is computed.

-self     : If you have specified a selection with -sel and -self is set 
	    then the nonbonded energies are computed only within the selection.
	    Otherwise the interaction with the environment (but not the
    	    self energy of the environment) is included. 

	    Not yet clear?
	    OK, Let's distinguish different types of interaction:
	    1) Interactions of atoms within a selection
	    2) Interactions of atoms from the selection with atoms not 
	       from the selection (the environment)
	    3) Interactions of atoms within the environment (i.e both 
               atoms are not part of the selection)

	    If you specify -self MDEnergy will compute only energy 1), 
	    if you don't specify it, energies 1) and 2) will be computed.

	    If you are interested in 3), you would simply invert the selection 
	    and use -self.

-diel <n> : Dielectric constant. This only makes sense if you want to 
            calculate the interaction between two sets of atoms. You can 
            use it for simple docking experiments between two molecules. 
            If you don't have water between them you could for example 
            specify -diel 80. Note that this is a rather rough method. 
            It assumes the dielectric constant for the entire space 
            between the atoms of the two selections, even if there are 
            other parts of the protein or the selection itself between 
            them.

-a <file> : Dumps energies for all individual selected atoms into a file 
            which can be read by the script 'viz_energy.tcl' to visualize
            the energy contributions per atom in VMD.
            Use one energy type option only!

            File format (entries line by line):
            # header
            1) energy type 
            2) number of atoms
            3) selection text
            4) atom index list of the selection
            # body (for each frame)
            1) frame number
            2) indexes of min and max values for current frame 
            3) min and max energy values for current frame  
            4) A long line containing the energy values for each atom  

-log	  : The energy output will be on logarithmic scale. This can be 
	    useful for visualization.

-avg <n>  : You can get running averages of all output by specifying this
	    option. The width of the symmetric sliding average window is 
	    2n+1. This effects the total energy output on the screen as well
	    as well as the values for the individual atom dumped into a file
	    by '-a file'.
	    By default your output size is reduced by 2n frames, n frames
	    missing at the beginning and the end. This is because the average
	    has to be build up. Use options -pad or -ramp to preserve the
	    number of frames.

-pad      : To be used with -avg. The missing frames at the beginning and 
	    the end are padded with the first averaged frame.

-ramp     : To be used with -avg. The missing frames at the beginning and
            the end are replaced by ramping the average up and down. That 
	    means the averaging window is not symmetric and has not the 
	    same size at the ends but the average is computed from as all
	    available frames. This gives smoother looking results at both 
	    ends.



VMD-PLUGIN
==================================================================

MDENERGY.TCL 
------------
This script is an interface to compute energies conviniently in VMD.
MDEnergy runs as a background process so you can continue with your 
work in VMD. The output is similar to NAMD's output and you can plot 
it with 'namdplot' (a tool which is part of the NAMD distribution).
It also tries to determine which binary of MDEnergy to run. 

Usage: 
mdenergy -bond|-angle|-dihed|-impr|-vdw|-elec|-nonb|-all -sel $sel [$sel2] [options]

!!! SEE THE HEADER OF THE SCRIPT FOR MORE DETAILED DOCUMENTAION !!!



Some emails in which I answered user questions or explained something to them. This might be 
of interest for others, too.

Hi Bora,
I think the problem was that in earlier versions of the CHARMM format one
could not have dihedrals with a multiplicity of more than 4. This was hard
wired into NAMD and thus also in MDEnergy. I changed this from 4 to 6. I
hope it will work now. The updated version is attached.

I'm sorry there no other documentation for MDEnergy, for further
information, I attached an email that I wrote to another user.
In that mail I also point out that nowadays you also do these computations
with NAMD, in which case you can be sure that you will have the same
conditions as in the originall NAMD run. MDEnergy for example does not
take periodic boundaries into account.

Regarding your specific question:
Be aware: Abolute potential energies in MD simulations don't make sense.
You should always compare energies, for example the energy difference
between two different conformation.
If you look at a selection of atoms you can discriminate the following
energies:
1) The interaction energy between the selection and the rest of the system.
2) the energy of the selection itself
3) the self-energy of the environment
4) the total energy
They are related by:
4) = 1) + 2) + 3)

If you want to have 2) you must specify your selection and the option
-self.  Then the interaction with anything outside is suppressed.
See the comment about -self in the README file of MDEnergy.

I hope this helps, good luck,
Jan

---------------------------------------------------------
Dear Ken,

I'm sorry, but there are no tutorials for MDEnergy. It's just a little
thing that I once wrote for myself, but I made it public in case it is
useful for others. All the documentation is in the README file and in the
scripts  hbonds.tcl and mdenergy.tcl. Furthermore there are a few examples
in the folder "test".
You can run mdenergy from the command line, e.g. the script test/electest
shows how to do it. You can also run it through the tcl script mdenergy
which you can run from the tkcon console in VMD. This has the advantage
that  you can specify atomselections easily using -sel. MDEnergy always
needs a pdb, a psf and a parameter file. If you start it through the tcl
script in VMD it will dtermine the pdb and psf from your loaded molecule.
Instead of a pdb you can also have a dcd file.

Example:
set sel1 [atomselect top "resid 1"]
set sel2 [atomselect top "resid 2"]
mdenergy -vdw -sel $sel1 $sel2 -par yourparameterfile
(Computes the VDW energy between selection 1 and 2)

Forget about the hbonds feature. It is test code, more a like a funky
visualization play-feature. The energies computed have nothing to do with
the nes that are computed in NAMD. They are not compliant with the force
field, but they are angle dependent.
If you want the "real" H-bond energies you must compute the sum of the
electrostatic and VDW energy between the donor/hydrogen and the
acceptor/antecedent pairs.

Good luck,
Jan

BTW, did you know that meanwhile you can also postprocess your simulation
files using NAMD? There you can also specify selecctions and compute
interaction energies. It's somewhere in the manual. This is probably more
what you want. MDEnergy is rather aimed to the expert who wants to play
around with the code himself.


-------------------------------------------------------------------

Bora,

The energies that NAMD uotputs are total energies for the system, unless
you do  trajectory postprocessing in which you can specify a selection.
See the NAMD manual for more info.

Also MDEnergy does only a simplified energy calculation, as I mentioned
before, it does not take PBC into account. That means any interacion
between waters that are across the unit cell boundaries is not considered.
Also MDEnergy does not do PME electrostatic calculations. If you want
numbers that match the one from your simulation, use NAMD for the
postprocessing. At the time I wrote MDEnergy this feature didn't exist.
MDEnergy is more for playing with the code itself or getting an idea of
relative energies of smaller selections far from the system boundaries,
i.e. a ligand in the binding pocket of a protein.

Jan

On Mi, Juli 13, 2005 18:57, s.bora erdemli wrote:

>> Hi,
>>
>>
>> I have some problems with the MDenergy output and I think you have idea
>> about the reasons of them.
>>
>> I did a molecular dynamics simulation with a solvated protein. In order
>> to calculate the vdw and electrostatic potential of the only protein
>> without solvent I tried to use both MDenergy and a method mentioned in the
>> NAMD
>> tutorial
>> (http://www.ks.uiuc.edu/Training/Tutorials/namd/namd-tutorial-html/node12
>> .html#SECTION00041500000000000000).
>> However, they both gave different results.
>>
>>
>> The results are as follows:
>>
>>
>> MDenergy --->   vdw ~ 500       elec ~ 5700
>>
>>
>> NAMD tutorial ---> vdw ~ 250    elec~ 1800
>>
>>
>> I used the same cutoff  distance,switch distance ,.psf file, .dcd file
>> and parameter file. What could be the reason? Do you have any opinion?
>>
>> If you have any doubt, I can send you .dcd and .psf file for my protein.
>>
>>
>> Please help me ... I am thinking I missed some points...
>>
>>
>>
>> thank you very much in advance....
>>
>> sincerely
>>
>> Bora
>>
>>
>>

-----------------------------------------------------------------

Hi Jeff,
there is an example in test/hbondpsftest.

mdenergy.Linux -top top_all27_prot_lipid_LYR_noHH.inp \
  -hpar ../hbonds/par_hbond.inp -pat patches.txt -psf rh_protein.psf
  
  par_hbond.inp contains the info about the hbond parameters.
  patches.txt is used to define residue patches that were made in the
  structure because the PRES resnames are not stored in the pdb and psf
  file.
  
  Good luck,
  Jan
  
  BTW: I don 't consider this feature very useful anymore, I was just
  playing around back then. It computes the H-bond energies using the wrong
  potential function. I you want to do serious stuff, you should rather
  compute the sum of VDW and electroststic interaction for the pairs you are
  interested in and write a TCL script to display these interactions if they
  are above a certain threshold.
  
  On Di, Juli 26, 2005 23:36, Jeff Forbes wrote:
  
  >> Jan,
  >>
  >>
  >> I am trying to use the H Bond visualization component of MDenergy.
  >> I am having trouble getting  a psf file populated with donor and
  >> acceptor information.
  >>
  >> Any suggestions would be welcomed.
  >>
  >>
  >>
  >> Jeff
  >>
  >>
  >>
  >>
  >> 
  
  ----------------------------------------------------------------
  
  Dear Jindal,
  
  MDEnergy is relatively simple minded and does not take periodic boundary
  conditions into account. That means any interaction between neighbouring
  cells are ignored. Nevertheless MDEnergy can be useful for the calculation
  of energies between atoms within the unit cell such as the interaction
  between a ligand and its binding pocket in the protein.
  Note that there are examples in the test directory and that there is some
  documentation in the README file and inside the scripts.
  
  Also MDEnergy does not use the PME charge calculation method but calculate
  their interaction explicitely by using the Coulomb formula.
  
  
  If you need numbers that are directly comparable to NAMD's out put you can
  use NAMD's trajectory prostprocessing feature which also lets you compute
  the interaction energies between groups of atoms while it does it exactly
  the same way as in the original simulation. There is no user interface for
  VMD yet, but I heard that they will release one shortly and you can get an
  alpha version on request.
  
  Good luck,
  Jan
  
  
  On Do, 18.08.2005, 16:47, Jindal Shah wrote:
  
  >> Jan,
  >>
  >>
  >> Thank you very much for writing a script that computes the energies of a
  >> selection of atoms. I am trying to use your script on outputs generated by
  >>  NAMD. I noticed that the program does not require the simulation box
  >> parameters (box lengths) to compute the energies. Is that so? Did I miss
  >> something?
  >>
  >> I use the following command
  >>
  >>
  >> mdenergy -all -sel atom.sel -pdb pdb_filename -psf psf_filename -par
  >> parameter_file
  >>
  >> selection file contains one atom 20032 --- the index of the atom in the
  >> pdb file I get vdw energy = 0.0. It is actually an oxygen atom of a water
  >> molecule.
  >>
  >> Please let me know any suggestions/advice you may have. I can send you
  >> the files if you like.
  >>
  >> Thanks
  >> Jindal
  
