lammps/doc/fix_imd.txt

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

fix imd command :h3

[Syntax:]

fix ID group-ID imd trate port keyword values ... :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l
imd = style name of this fix command :l
port = port number on which the fix listens for an IMD client :l
keyword = {unwrap} or {fscale} or {trate} :l
  {unwrap} arg = {on} or {off}
    off = coordinates are wrapped back into the principal unit cell (default)
    on = "unwrapped" coordinates using the image flags used
  {fscale} arg = factor
    factor = floating point number to scale IMD forces (default: 1.0)
  {trate} arg = transmission rate of coordinate data sets (default: 1)
  {nowait} arg = {on} or {off}
    off = LAMMPS waits to be connected to an IMD client before continuing (default)
    on = LAMMPS listens for an IMD client, but continues with the run :pre
:ule

[Examples:]

fix vmd all imd 5678 
fix comm all imd 8888 trate 5 unwrap on fscale 10.0 :pre

[Description:]

This fix implements the "Interactive MD" (IMD) protocol which allows
realtime visualization and manipulation of MD simulations through the
IMD protocol, as initially implemented in VMD and NAMD.  Specifically
it allows LAMMPS to connect an IMD client, for example the "VMD
visualization program"_VMD, so that it can monitor the progress of the
simulation and interactively apply forces to selected atoms.

If LAMMPS is compiled with the preprocessor flag -DLAMMPS_ASYNC_IMD
then fix imd will use posix threads to spawn a thread on MPI rank 0 in
order to offload data reading and writing from the main execution
thread and potentiall lower the inferred latencies for slow
communication links.  This feature has only been tested under linux.

There are example scripts for using this package with LAMMPS in
examples/USER/imd. Additional examples and a driver for use with the
Novint Falcon game controller as haptic device can be found at:
http://sites.google.com/site/akohlmey/software/vrpn-icms.

The source code for this fix includes code developed by the
Theoretical and Computational Biophysics Group in the Beckman
Institute for Advanced Science and Technology at the University of
Illinois at Urbana-Champaign.  We thank them for providing a software
interface that allows codes like LAMMPS to hook to "VMD"_VMD.

Upon initialization of the fix, it will open a communication port on
the node with MPI task 0 and wait for an incoming connection.  As soon
as an IMD client is connected, the simulation will continue and the
fix will send the current coordinates of the fix's group to the IMD
client at every trate MD step. When using r-RESPA, trate applies to
the steps of the outmost RESPA level.  During a run with an active IMD
connection also the IMD client can request to apply forces to selected
atoms of the fix group.

The port number selected must be an available network port number.  On
many machines, port numbers < 1024 are reserved for accounts with
system manager privilege and specific applications. If multiple imd
fixes would be active at the same time, each needs to use a different
port number.

The {nowait} keyword controls the behavior of the fix when no IMD
client is connected. With the default setting of {off}, LAMMPS will
wait until a connection is made before continuing with the
execution. Setting {nowait} to {on} will have the LAMMPS code be ready
to connect to a client, but continue with the simulation. This can for
example be used to monitor the progress of an ongoing calculation
without the need to be permanently connected or having to download a
trajectory file.

The {trate} keyword allows to select how often the coordinate data is
sent to the IMD client. It can also be changed on request of the IMD
client through an IMD protocol message.  The {unwrap} keyword allows
to send "unwrapped" coordinates to the IMD client that undo the
wrapping back of coordinates into the principle unit cell, as done by
default in LAMMPS.  The {fscale} keyword allows to apply a scaling
factor to forces transmitted by the IMD client. The IMD protocols
stipulates that forces are transferred in kcal/mol/angstrom under the
assumption that coordinates are given in angstrom. For LAMMPS runs
with different units or as a measure to tweak the forces generated by
the manipulation of the IMD client, this option allows to make
adjustments.

To connect VMD to a listening LAMMPS simulation on the same machine
with fix imd enabled, one needs to start VMD and load a coordinate or
topology file that matches the fix group.  When the VMD command
prompts appears, one types the command line:

imd connect localhost 5678 :pre

This assumes that {fix imd} was started with 5678 as a port 
number for the IMD protocol.

The steps to do interactive manipulation of a running simulation in
VMD are the following:

In the Mouse menu of the VMD Main window, select "Mouse -> Force ->
Atom".  You may alternately select "Residue", or "Fragment" to apply
forces to whole residues or fragments. Your mouse can now be used to
apply forces to your simulation. Click on an atom, residue, or
fragment and drag to apply a force. Click quickly without moving the
mouse to turn the force off. You can also use a variety of 3D position
trackers to apply forces to your simulation. Game controllers or haptic
devices with force-feedback such as the Novint Falcon or Sensable 
PHANTOM allow you to feel the resistance due to inertia or interactions
with neighbors that the atoms experience you are trying to move, as if 
they were real objects. See the "VMD IMD Homepage"_imdvmd and the 
"VRPN-ICMS Homepage"_vrpnicms for more details.

If IMD control messages are received, a line of text describing the
message and its effect will be printed to the LAMMPS output screen, if
screen output is active.

:link(VMD,http://www.ks.uiuc.edu/Research/vmd)x
:link(imdvmd,http://www.ks.uiuc.edu/Research/vmd/imd/) 
:link(vrpnicms,http://sites.google.com/site/akohlmey/software/vrpn-icms) 

[Restart, fix_modify, output, run start/stop, minimize info:]

No information about this fix is written to "binary restart
files"_restart.html.  None of the "fix_modify"_fix_modify.html options
are relevant to this fix.  No global scalar or vector or per-atom
quantities are stored by this fix for access by various "output
commands"_Section_howto.html#4_15.  No parameter of this fix can be
used with the {start/stop} keywords of the "run"_run.html command.
This fix is not invoked during "energy minimization"_minimize.html.

[Restrictions:]

This fix is part of the "user-misc" package.  It is only enabled if
LAMMPS was built with that package.  See the "Making
LAMMPS"_Section_start.html#2_3 section for more info.

On platforms that support multi-threading, this fix can be compiled in
a way that the coordinate transfers to the IMD client can be handled
from a separate thread, when LAMMPS is compiled with the
-DLAMMPS_ASYNC_IMD preprocessor flag. This should to keep MD loop
times low and transfer rates high, especially for systems with many
atoms and for slow connections.

When used in combination with VMD, a topology or coordinate file has
to be loaded, which matches (in number and ordering of atoms) the
group the fix is applied to. The fix internally sorts atom IDs by
ascending integer value; in VMD (and thus the IMD protocol) those will
be assigned 0-based consecutive index numbers.

When using multiple active IMD connections at the same time, each
needs to use a different port number.

[Related commands:] none

[Default:] none