git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@1701 f3b2605a-c512-4ea7-a41b-209d697bcdaa

tools/lmp2vmd/README

@@ -1,12 +1,31 @@
-This directory contains utility scripts for using VMD to visualize and
-analyze LAMMPS trajectories (well, right now there is only two
-scripts, but more are to come). 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/
 
-The scripts here are maintained by Axel Kohlmeyer
+This directory contains utility scripts for using VMD to visualize and analyze
-<akohlmey@cmm.chem.upenn.edu>.
+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.
 
 -------------------------
 
@@ -15,95 +34,168 @@ The scripts here are maintained by Axel Kohlmeyer
 
 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.
+   then reads a trajectory with the coordinate information on top of that. The
-   The most common use is the combination of a (CHARMM or X-PLOR style) .psf
+   most common use is the  combination of a (CHARMM  or X-PLOR style) PSF file
-   file and a .dcd file. If the bonding information is not avaiable, VMD uses
+   and  a DCD file  (the latter can be  produced by LAMMPS  directly).  If the
-   a heuristic guess, which does not always work, but can be particularly
+   bonding information is not   available, VMD uses   a heuristic guess  which
-   cumbersome in coarse grained MD or similar systems. The lmpbonds2vmd.tcl
+   works  reasonably  well with  biological  systems, but  can be particularly
-   script provide an option to transfer bonding information from a LAMMPS data
+   cumbersome     in  coarse grained  MD   or    similar model  systems.   The
-   file into VMD.
+   lmpbonds2vmd.tcl script provides an option  to transfer bonding information
+   from a LAMMPS data file into VMD.
 
-1b. Usage 
+1b. Usage.
-   The script defines a new procedure "lmpbondsfromdata". To activate it
+   The script defines a new procedure "lmpbondsfromdata".  To activate it type
-   type at the VMD command prompt:
+   at the VMD command prompt:
 
      source lmpbonds2vmd.tcl
 
-   To then build a .psf file that can be used for subsequent
+   To then build a PSF file for use in subsequent  visualizations you can load
-   visualizations you can load one frame of a native LAMMPS trajectory
+   one just frame of a native LAMMPS trajectory (not binary, not custom!), for
-   (not binary, not custom!), e.g. perusing the output from the
+   example perusing the output from the micelle example.
-   micelle example.
 
      mol new dump.micelle type lammpstrj waitfor all
-   lmpbondsfromdata 0 data.micelle
+     lmpbondsfromdata [molinfo top] data.micelle
 
-   now you should only see the bonds that actually have bonded interactions.
+   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 
+   To  avoid having to run  the script all the time   you can save the bonding
-   information in an (incomplete) .psf file.
+   information in an (incomplete) PSF file.
 
      animate write psf micelle.psf
 
-   and now in the future you can load this psf file first and then 
+   In the future you can now load this PSF file first and then the LAMMPS dump
-   the dump file (or a more compact and faster loading .dcd or .xtc file).
+   file(s) (or a more compact and faster loading DCD or XTC file) with:
-   e.g., with:
 
      vmd micelle.psf -lammpstrj dump.micelle
 
-1c. Problems
+1c. Problems.
-   The data file format is quite flexible and thus not always easy to parse
+   The LAMMPS data file format  is quite flexible and thus  not always easy to
-   independent from context. As a consequence, the lmpbondsfromdata parser
+   parse independently from context.  As a consequence,  the lmpbondsfromdata
-   may be confused by your specific setup.
+   parser may be confused by your specific setup.
 
-1d. History
+1d. History.
-   First version. 2007, axel kohlmeyer <akohlmey@cmm.chem.upenn.edu>
+   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
+2. lmpresid2vmd.tcl - translate residue information from a LAMMPS data file 
-   file into VMD.
+   into VMD.
 
-2a Background.  LAMMPS dump files contain information about the
+2a. Background.  
-   (numerical) atom type, but not a molecule or residue id as it is
+   LAMMPS dump files contain information about  the (numerical) atom type, but
-   typically used in .psf or .pdf files to define subunits of a
+   not a molecule or residue id as it is typically  used in PSF or PDB files
-   system. Adding this information can be very helpful for analysis
+   to define subunits of a system. Adding this information can be very helpful
-   and postprocessing of LAMMPS data in VMD.
+   for analysis and post-processing of LAMMPS data in VMD.
 
-2b Usage.
+2b. Usage.
-   The script defines a new procedure "lmpresidfromdata". To activate it
+   The script defines a new  procedure "lmpresidfromdata". To activate it type
-   type at the VMD command prompt:
+   at the VMD command prompt:
 
      source lmpresid2vmd.tcl
 
-   To then add the residue information to a .psf file, see the steps for from
+   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 0 data.micelle
+     lmpresidfromdata [molinfo top] data.micelle
 
-   to avoid having to run the script all the time you can save the bonding
+   To  avoid having to run  the script all the time  you  can save the residue
-   information in an (incomplete) .psf file.
+   information in an (incomplete) PSF file.
 
      animate write psf micelle2.psf
 
-   and now in the future you can load this psf file first and then
+   In the future you can now load this PSF file first and then the LAMMPS dump
-   the dump file (or a more compact and faster loading .dcd or .xtc file).
+   file(s) (or a more compact and faster loading DCD or XTC file) with:
-   e.g., with:
 
      vmd micelle2.psf -lammpstrj dump.micelle
 
-   now you can use the residue information to "join" the bonds split
+   You can use the residue information to join bonds split across the periodic
-   across the periodic boundaries with:
+   boundaries with:
 
      pbc join residue -all
 
    and then enjoy a nice visualization of the micelle example with VMD. :)
 
-2c. Problems
+2c. Problems.
-   The data file format is quite flexible and thus not always easy to parse
+   The LAMMPS data file  format is quite flexible and  thus not always easy to
-   independent from context. As a consequence, the lmpresidfromdata parser
+   parse  independent from  context.  As a  consequence, the  lmpresidfromdata
-   may be confused by your specific setup.
+   parser may be confused by your specific setup.
 
-2d. History
+2d. History.
-   First version. 2008, axel kohlmeyer <akohlmey@cmm.chem.upenn.edu>
+   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>
 
 

tools/lmp2vmd/lmpbonds2vmd.tcl

@@ -4,6 +4,10 @@
 
 proc lmpbondsfromdata {mol filename} {
     
+    if {"$mol" == "top"} {
+        set mol [molinfo top]
+    }
+
     # create an empty bondlist
     set na [molinfo $mol get numatoms]; # number of atoms
     set nb 0;                           # number of bonds
@@ -31,7 +35,7 @@ proc lmpbondsfromdata {mol filename} {
 
     # skip one line
     gets $fp line
-    # read the bonds file
+    # read the bonds data
     for {set i 0} {$i < $nb} {incr i} {
         gets $fp line
         # grep bond numbers from entry and adjust to VMD numbering style
@@ -39,6 +43,12 @@ proc lmpbondsfromdata {mol filename} {
         incr ba -1
         incr bb -1
 
+        # sanity check
+        if { ($ba > $na) || ($bb > $na) } {
+            puts stderr "number of atoms in VMD molecule ($na) does not match data file"
+            return -1
+        }
+
         set bn [lindex $bl $ba]
         lappend bn $bb
         set bl [lreplace $bl $ba $ba $bn]
@@ -52,5 +62,6 @@ proc lmpbondsfromdata {mol filename} {
     set sel [atomselect $mol all]
     $sel setbonds $bl
     $sel delete
+    return 0
 }
 

tools/lmp2vmd/lmpname2vmd.tcl

@@ -0,0 +1,18 @@
+# small script to assign atom names to type numbers in LAMMPS .
+# (c) 2008 Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>
+
+proc lmptypetoname {mol names} {
+    if {"$mol" == "top"} {
+        set mol [molinfo top]
+    }
+
+    set t 0
+    foreach n $names {
+        incr t
+        set sel [atomselect $mol "type $t"]
+        $sel set name $n
+        $sel delete
+    }
+    return 0
+}
+

tools/lmp2vmd/lmpradius2vmd.tcl

@@ -0,0 +1,18 @@
+# small script to assign a radius by type number in VMD
+# (c) 2008 Axel Kohlmeyer <akohlmey@cmm.chem.upenn.edu>
+
+proc lmptypetoradius {mol rlist} {
+    if {"$mol" == "top"} {
+        set mol [molinfo top]
+    }
+
+    set t 0
+    foreach r $rlist {
+        incr t
+        set sel [atomselect $mol "type $t"]
+        $sel set radius $r
+        $sel delete
+    }
+    return 0
+}
+

tools/lmp2vmd/lmpresid2vmd.tcl

@@ -3,12 +3,16 @@
 
 proc lmpresidfromdata {mol filename} {
 
+    if {"$mol" == "top"} {
+        set mol [molinfo top]
+    }
+
     # create an empty bondlist
     set na [molinfo $mol get numatoms]; # number of atoms of molecule
-    set nb 0;                           # number of atoms in data file
+    set da 0;                           # number of atoms in data file
-    set bl {};                          # resid list
+    set rl {};                          # resid list
     for {set i 0} {$i < $na} {incr i} {
-        lappend bl 0
+        lappend rl 0
     }
 
     # open lammps data file
@@ -19,11 +23,18 @@ proc lmpresidfromdata {mol filename} {
 
     # read file line by line until we hit the Bonds keyword
     while {[gets $fp line] >= 0} {
-        # pick number of bonds
+        # pick number of atoms
-        regexp {^\s*(\d+)\s+atoms} $line dummy nb
+        regexp {^\s*(\d+)\s+atoms} $line dummy da
 
         if { [regexp {^\s*Atoms} $line] } {
-            puts "atoms= $nb\n now reading Atoms section"
+            # sanity check
+            if {$na != $da} {
+                puts stderr \
+                    "number of atoms in VMD molecule ($na) does not match data file ($da)"
+                return -1
+            }
+
+            puts "atoms= $da\nnow reading Atoms section"
             break
         }
     }
@@ -31,17 +42,17 @@ proc lmpresidfromdata {mol filename} {
     # skip one line
     gets $fp line
     # read the Atoms data
-    for {set i 0} {$i < $nb} {incr i} {
+    for {set i 0} {$i < $da} {incr i} {
         gets $fp line
         # grep bond numbers from entry and adjust to VMD numbering style
         regexp {^\s*(\d+)\s+(\d+)\s+\d+.*} $line dummy ba bb
         incr ba -1
-        lset bl $ba $bb
+        lset rl $ba $bb
     }
     close $fp
 
     set sel [atomselect $mol all]
-    $sel set resid $bl
+    $sel set resid $rl
     $sel delete
 }
 

tools/lmp2vmd/mkidx

@@ -0,0 +1,13 @@
+#!/usr/bin/tclsh
+# recreate the tcl index file for on demand loading.
+#
+# Copyright (c) 2003 by <Axel.Kohlmeyer@theochem.ruhr-uni-bochum.de>
+#
+auto_mkindex . *.tcl
+
+############################################################
+# Local Variables:
+# mode: tcl
+# time-stamp-format: "%u %02d.%02m.%y %02H:%02M:%02S %s"
+# End:
+############################################################

tools/lmp2vmd/tclIndex

@@ -0,0 +1,12 @@
+# Tcl autoload index file, version 2.0
+# This file is generated by the "auto_mkindex" command
+# and sourced to set up indexing information for one or
+# more commands.  Typically each line is a command that
+# sets an element in the auto_index array, where the
+# element name is the name of a command and the value is
+# a script that loads the command.
+
+set auto_index(lmptypetoname) [list source [file join $dir lmpname2vmd.tcl]]
+set auto_index(lmpresidfromdata) [list source [file join $dir lmpresid2vmd.tcl]]
+set auto_index(lmpbondsfromdata) [list source [file join $dir lmpbonds2vmd.tcl]]
+set auto_index(lmptypetoradius) [list source [file join $dir lmpradius2vmd.tcl]]