Copyright (C) 2004-2005 by David J. Hardy.
All rights reserved.


MDSim Guide
-----------

David J. Hardy
25 September 2005


Description
-----------

This executable program from MDX performs an MD simulation using a subset
of NAMD configuration options, so can be viewed as "NAMD-lite".  The
mdsim (front end) uses the MDAPI to interface to deven (MD engine),
providing a non-trivial demonstration of the interface.

MDSim can perform constant energy simulation using leapfrog (velocity
Verlet) time integration.  It can simulate nonperiodic or fully periodic
orthogonal cells using a cutoff for electrostatics.  It can also make use
of mgrid (MSM library) to compute long-range electrostatics, but this
feature is restricted to cubic cells.


Usage
-----

MDSim is used from the command line:

$ mdsim config_file

where "config_file" is a NAMD-style configuration file.



Configuration Options
---------------------

The combination of mdsim (front end) with deven (engine) recognizes
several basic NAMD simulation parameters along with most of the same
semantics:


Options recognized by MDSim:

  cwd
  parameters
  structure
  coordinates
  bincoordinates
  velocities
  binvelocities
  outputname
  binaryoutput
  binaryrestart
  restartname
  restartsave
  restartfreq
  dcdfile
  dcdfreq
  dcdunitcell
  veldcdfile
  veldcdfreq
  outputenergies
  firsttimestep
  numsteps


Options recognized by simen and deven:

  timestep
  temperature
  COMmotion
  seed
  cutoff
  switchdist
  switching
  exclude
  dielectric
  1-4scaling
  fulldirect
  sphericalBC
  sphericalBCcenter
  sphericalBCr1
  sphericalBCk1
  sphericalBCexp1
  sphericalBCr2
  sphericalBCk2
  sphericalBCexp2
  cylindricalBC
  cylindricalBCaxis
  cylindricalBCcenter
  cylindricalBCr1
  cylindricalBCl1
  cylindricalBCk1
  cylindricalBCexp1
  cylindricalBCr2
  cylindricalBCl2
  cylindricalBCk2
  cylindricalBCexp2
  cellBasisVector1
  cellBasisVector2
  cellBasisVector2
  cellOrigin


Options recognized by MDSim, but not NAMD:

  engine  - Name of MD engine (not yet supported).

  results  - Indicate desired reduction results to be monitored.  This can
    be used multiple times with any one of the following values:

      energy - total energy
      ke     - kinetic energy
      pe     - potential energy
      bond   - potential due to bonds
      angle  - potential due to angles
      dihed  - potential due to dihedrals
      impr   - potential due to impropers
      elec   - potential due to electrostatic
      vdw    - potential due to van der Waals
      bound  - potential due to boundary restraints (spherical or cylindrical)
      temp   - temperature

  resultsname  - Name of output file for results.

  resultsfreq  - Frequency for results, measured in number of time steps.
    Defaults to 1.

  resultswidth  - Field width for each printed result column.  Defaults to 12.

  resultsheaderfreq  - Frequency with which the results column headers
    get printed, measured in number of reported results.  Defaults to 20.

  binaryresults  - (on/off) Indicates whether the results output file is
    binary.  Defaults to "off".  ("yes" is not yet supported.)


Options recognized by deven, but not NAMD:

  mgrid  - (on/off) Indicates whether to use mgrid.  Default is "off".

  mgridLength  - Length of the cubic cell.

  mgridCutoff  - Cutoff for splitting short-range and long-range
    interactions.  Recommended range:  8 <= mgridCutoff <= 12.
    Accuracy improves with longer cutoff, but it is more costly.

  mgridSpacing  - Lattice spacing for the finest grid level.
    Recommended range:  2.5 <= mgridSpacing <= 3.5.  Should be close
    to the interatomic spacing.  The computational cost is extremely
    sensitive, so adjust with care.

  mgridNspacings  - Number of lattice spacings for the finest grid level
    along each dimension.

  mgridNlevels  - Number of levels in the grid hierarchy.  (The maximum
    value for mgridNlevels will be "discovered" automatically.)

  mgridApprox  - Type of approximation to use.  Choices are:  cubic,
    bspline, quintic1, quintic2, heptic1, heptic3, nonic1, nonic4, hermite.
    Default is "cubic".  Recommended:  for lower accuracy "cubic", for
    medium to high accuracy "quintic1", for greater accuracy use "heptic1"
    or "nonic1".

  mgridSplit  - Type of splitting to use.  Choices are:  taylor1, taylor2,
    taylor3, taylor4, taylor5, taylor6, taylor7, taylor8, errmin3.
    Default is "taylor2".  Recommended:  use "taylor2" with "cubic",
    use "taylor3" with "quintic1", use "taylor4" with "heptic1", use
    "taylor5" with "nonic1".


Unsupported simulation parameter values:

  engine  - Does not do anything (yet), deven is always the engine.

  binaryresults=yes

  cellBasisVector1, cellBasisVector2, cellBasisVector3
    - These must lie along x, y, and z coordinate axes, respectively,
      with nonnegative length.


Issues
------

Unlike NAMD, MDSim does not support scripting.  This means that MDSim
config files should not contain any of the TCL extensions that NAMD
understands (including the use of previously defined variables).  The
MDSim config file syntax is essentially identical to the traditional
NAMD config file syntax:

  KEYWORD = VALUE

where KEYWORD is not case sensitive, but VALUE usually is (particularly
for file names), and the equal-sign ("=") is optional.  For an
explanation of the various keywords (at least the ones that are shared
with NAMD), consult the "NAMD User's Guide" document located at
http://www.ks.uiuc.edu/Research/namd/current/ug/ .

For the displayed "results" file generated by setting "resultsname"
(which can be used directly by gnuplot), future plans are to enable the
feature "binaryresults=yes" to dump all of the available results into a
binary file, and also to provide an external program that supports
reading and processing these binary files.

There is support for only constant energy simulation using the leapfrog
(velocity Verlet) time integration method.  For cutoff electrostatic
simulations, there is support only for orthogonal cells.  However, use
of the MSM library further restricts this to cubic cells.

The DCD file writer does not yet support large ( >= 2 GB) files.
