lammps/tools/lmp2vmd/README

This directory contains utility scripts for using VMD to visualize and analyze
LAMMPS trajectories (hopefully in  the future this will  turn into a plugin or
proper  library).  Below are  short  descriptions and  examples  on how to use
them. Additional information on VMD as well as additional scripts can be found
at:   http://www.ks.uiuc.edu/Research/vmd/  
and:  http://www.theochem.rub.de/go/cpmd-vmd.html

The scripts are maintained by Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>;
please contact him through the LAMMPS mailing list in case of problems.

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

0. Installation.

   The scripts below  define new tcl procedures for  use  with the tcl  script
   interpreter embedded into VMD. To activate them, you can load them by using
   the "source" command. However  it is more convenient  to have VMD load them
   automatically  on demand. To  do this, you need to  modify  your .vmdrc (or
   vmd.rc) file (see the VMD User's Guide for details) and add the and adapted
   version of the following code.

     # add local (auto-loaded) scripts to the interpreter search path
     set auto_path [concat $env(HOME)/lammps/tools/lmp2vmd $auto_path]

   With this change the "source" command lines below are no longer needed.  If
   you add new  files or procedures   to this directory, you  have  to run the
   mkindex script to update the tclIndex file.

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

1. lmpbonds2vmd.tcl - translate bonding information from a LAMMPS data
   file into VMD.

1a. Background.
   With  VMD one typically reads bonding  information from a topology file and
   then reads a trajectory with the coordinate information on top of that. The
   most common use is the  combination of a (CHARMM  or X-PLOR style) PSF file
   and  a DCD file  (the latter can be  produced by LAMMPS  directly).  If the
   bonding information is not   available, VMD uses   a heuristic guess  which
   works  reasonably  well with  biological  systems, but  can be particularly
   cumbersome     in  coarse grained  MD   or    similar model  systems.   The
   lmpbonds2vmd.tcl script provides an option  to transfer bonding information
   from a LAMMPS data file into VMD.

1b. Usage.
   The script defines a new procedure "lmpbondsfromdata".  To activate it type
   at the VMD command prompt:

     source lmpbonds2vmd.tcl

   To then build a PSF file for use in subsequent  visualizations you can load
   one just frame of a native LAMMPS trajectory (not binary, not custom!), for
   example perusing the output from the micelle example.

     mol new dump.micelle type lammpstrj waitfor all
     lmpbondsfromdata [molinfo top] data.micelle

   Now you should only see the bonds that actually have bonded interactions.

   To  avoid having to run  the script all the time   you can save the bonding
   information in an (incomplete) PSF file.

     animate write psf micelle.psf

   In the future you can now load this PSF file first and then the LAMMPS dump
   file(s) (or a more compact and faster loading DCD or XTC file) with:

     vmd micelle.psf -lammpstrj dump.micelle

1c. Problems.
   The LAMMPS data file format  is quite flexible and thus  not always easy to
   parse independently from context.  As a consequence,  the lmpbondsfromdata
   parser may be confused by your specific setup.

1d. History.
   First version. 2007, Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>
   Added a sanity check 03/2008, Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>

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

2. lmpresid2vmd.tcl - translate residue information from a LAMMPS data file 
   into VMD.

2a. Background.  
   LAMMPS dump files contain information about  the (numerical) atom type, but
   not a molecule or residue id as it is typically  used in PSF or PDB files
   to define subunits of a system. Adding this information can be very helpful
   for analysis and post-processing of LAMMPS data in VMD.

2b. Usage.
   The script defines a new  procedure "lmpresidfromdata". To activate it type
   at the VMD command prompt:

     source lmpresid2vmd.tcl

   To then add the residue information to a PSF file, see the steps for from
   item 1 from above and then type into the VMD console.
   
     lmpresidfromdata [molinfo top] data.micelle

   To  avoid having to run  the script all the time  you  can save the residue
   information in an (incomplete) PSF file.

     animate write psf micelle2.psf

   In the future you can now load this PSF file first and then the LAMMPS dump
   file(s) (or a more compact and faster loading DCD or XTC file) with:

     vmd micelle2.psf -lammpstrj dump.micelle

   You can use the residue information to join bonds split across the periodic
   boundaries with:

     pbc join residue -all

   and then enjoy a nice visualization of the micelle example with VMD. :)

2c. Problems.
   The LAMMPS data file  format is quite flexible and  thus not always easy to
   parse  independent from  context.  As a  consequence, the  lmpresidfromdata
   parser may be confused by your specific setup.

2d. History.
   First version. 2008, Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>

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

3. lmpname2vmd.tcl - set atom names based on LAMMPS type in VMD.

3a. Background.  
   LAMMPS dump files contain information about  the (numerical) atom type, but
   not atom names like in PSF or PDB files. The names are used in VMD to guess
   element, radius and (default) coloring. Adding this information can be very
   helpful to set convenient defaults for visualization of LAMMPS data in VMD.

3b. Usage.
   The script defines a new  procedure "lmptypetoname". To activate it type
   at the VMD command prompt:

     source lmpname2vmd.tcl

   To then add atom name information,  e.g., to a PSF  file, see the steps for
   item 1 from above and then type into the VMD console.
   
     lmptypetoname [molinfo top] "SOL HDR TL1 TL2"

   To avoid having to run the script all the time you can save the bonding
   information in an (incomplete) PSF file.

     animate write psf micelle3.psf

   In the future you can now load this PSF file first and then the LAMMPS dump
   file(s) (or a more compact and faster loading DCD or XTC file) with:

     vmd micelle3.psf -lammpstrj dump.micelle

   And you'll see that VMD will assign different colors to the atom types. You
   cat get the previous coloring back by using the "Type" coloring scheme.

3c. Problems.
   This script assumes the data  originates from a LAMMPS  dump file and  thus
   the atoms types are numerical starting from 1. If  those have been modified
   by some means, no name will be assigned.

3d. History.
   First version. 2008, Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>


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

4. lmpradius2vmd.tcl - set VdW radius based on LAMMPS type in VMD.

4a. Background.  
   The radii used for VDW and derived representations in VMD are guessed from 
   the atom names. This script offers a convenient way to reset them (e.g. by
   using the sigma parameters from matching LJ interactions).

4b. Usage.
   The script defines a new  procedure "lmptypetoradius". To activate it type
   at the VMD command prompt:

     source lmpradius2vmd.tcl

   To then add atom radius information, see the steps for
   item 1 from above and then type into the VMD console.
   
     lmptypetoradius [molinfo top] "1.00 1.00 0.75 0.50"

4c. Problems.
   This script assumes the  data originates from  a LAMMPS dump file and  thus
   the atoms types are numerical starting from 1. If  those have been modified
   by some means, no name will be assigned. There is  currently no file format
   that  exports the radius  information,  so  this script/command  has to  be
   added, e.g., to "saved states" and other visualization scripts.
   

4d. History.
   First version. 2008, Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>