Copyright (C) 2007 by David J. Hardy.
All rights reserved.


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

David J. Hardy
1 March 2007


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 (see http://www.ks.uiuc.edu/Research/namd/2.6/ug/ for details):


Options recognized by MDSim:

  cwd                      - input and output
  parameters
  structure
  coordinates
  bincoordinates
  velocities
  binvelocities
  outputname
  binaryoutput
  binaryrestart
  restartname
  restartsave
  restartfreq
  dcdfile
  dcdfreq
  dcdunitcell
  veldcdfile
  veldcdfreq
  outputenergies
  firsttimestep            - what time steps to take
  numsteps


Options recognized by deven:

  timestep                 - basic simulation parameters
  temperature
  COMmotion
  seed
  cutoff
  switchdist
  switching
  exclude
  dielectric
  1-4scaling
  fulldirect
  sphericalBC              - spherical boundary conditions
  sphericalBCcenter
  sphericalBCr1
  sphericalBCk1
  sphericalBCexp1
  sphericalBCr2
  sphericalBCk2
  sphericalBCexp2
  cylindricalBC            - cylindrical boundary conditions
  cylindricalBCaxis
  cylindricalBCcenter
  cylindricalBCr1
  cylindricalBCl1
  cylindricalBCk1
  cylindricalBCexp1
  cylindricalBCr2
  cylindricalBCl2
  cylindricalBCk2
  cylindricalBCexp2
  cellBasisVector1         - define periodic boundaries
  cellBasisVector2
  cellBasisVector2
  cellOrigin
  PME                      - use of PME requires FFTW (see "Issues" below)
  PMETolerance
  PMEInterpOrder
  PMEGridSizeX
  PMEGridSizeY
  PMEGridSizeZ
  OutputMomenta            - some output options
  OutputPressure
  OutputTiming
  constraints              - harmonic constraint parameters
  consexp
  consref
  conskfile
  constraintScaling
  selectConstraints
  selectConstrX
  selectConstrY
  selectConstrZ
  fixedAtoms               - fixed atoms parameters
  fixedAtomsFile             (but does not correct the virial)
  fixedAtomsCol


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
      vol    - volume
      press  - scalar pressure
      vir_x  - "x"-vector component of virial tensor
      vir_y  - "y"-vector component of virial tensor
      vir_z  - "z"-vector component of virial tensor
      linmo  - linear momentum
      shadow4 - 4th order shadow Hamiltonian (need shadow=on)
      shadow8 - 8th order shadow Hamiltonian (need shadow=on)
      shadow12 - 12th order shadow Hamiltonian (need shadow=on)
      shadow16 - 16th order shadow Hamiltonian (need shadow=on)
      shadow20 - 20th order shadow Hamiltonian (need shadow=on)
      shadow24 - 24th order shadow Hamiltonian (need shadow=on)


  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".

  correctLinmo  - Correction for grid-based electrostatics evaluation
    that conserves linear momentum with velocity Verlet.  Must initialize
    system with zero linear momentum (COMmotion=off).

  shadow  - Computes shadow Hamiltonian up to 24th order (much better
    conserved quantity than energy).

  temperatureBath  - (on/off) Weak-coupling to a temperature bath
    (Berendsen, 1984).  Does not produce true NVT ensemble.

  targetTemperature  - Temperature for bath.

  relaxationTime  - Bath coupling parameter, units in femtoseconds.
    Leach prescribes 400 fs value for 1 fs timestep.

  NoseHoover  - (on/off) Explicit, time-reversible integrator for
    Nose-Hoover method.  Produces NVT ensemble provided that the
    center of mass momentum remains zero.  This can be used with
    correctLinmo=on.

  NHtemperature  - Nose-Hoover thermostat temperature, units of K.
    Should be set to a positive value when NoseHoover=on.

  NHtimescale  - Nose-Hoover thermostat timescale, units of fs.
    Controls the strength of the coupling of the system to the thermostat.
    Used to set the thermostat "mass" for the extended Lagrangian,
    Q = N_f k_B T (timescale)^2, where N_f is number of degrees of freedom,
    k_B is Boltzmann constant, and T is the thermostat temperature.
    Defaults to 50 fs, the period of a harmonic oscillator.

  cgmin  - (on/off) Energy minimization using conjugate gradient
    search directions with a golden section line search.

  cgmineval  - Maximum number of force evaluations before giving up.
    Defaults to 50.

  cgmindis  - Maximum bracketing distance.  Defaults to 1 A.

  cgmintol  - Convergence tolerance for line search.  Defaults to 0.01 A.

  buckingham  - (on/off) Replace van der Waals potential with Buckingham
    potential.

  buckparam  - (bks/ttam/fb/glass) Choose silica parameterization, default
    is "fb".  The 2-body "glass" potential does not include the attractive
    dispersion term and uses a modified electrostatic term by default so
    for this you should leave pme=off.

  bucknodispersion  - (on/off) Buckingham potential without the attractive
    dispersion term so there is no artificial well.  Requires buckingham=on.

  bucksafe  - (on/off) Attaches a smooth extension to the Buckingham
    potential to eliminate the artificial well.  This is especially
    important for energy minimization, but is smooth so is safe to use
    with dynamics.


Unsupported simulation parameter values:

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

  binaryresults=yes


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.

Use of periodic boundaries with MSM (mgrid library) restricts domain to
fully periodic cubic cells.  Use of nonperiodic boundaries with MSM
requires domain to be entirely contained within a cube (e.g. set
spherical boundary restraints).  Virial is not yet computed by mgrid.

Use of PME requires FFTW support, but licensing prevents its distribution
with MDX.  Instructions for building FFTW support into MDX:
   - download FFTW version 2.1.5:
      + http://www.fftw.org/fftw-2.1.5.tar.gz
      + ftp://ftp.fftw.org/pub/fftw/fftw-2.1.5.tar.gz
   - copy files from the fftw and rfftw directories into respective
     MDX directories, e.g.:
      + cp fftw-2.1.5/fftw/* mdx/src/fftw
      + cp fftw-2.1.5/rfftw/* mdx/src/rfftw
   - reconfigure MDX for FFTW support and rebuild, e.g.:
      + cd mdx
      + make config HAVE_FFTW=yes
      + make clean ; make

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