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


MDX Notes
version 1.0.0
-------------

David J. Hardy
25 September 2005


Overview
--------

MDX is a collection of C libraries to enable the development of methods
for molecular dynamics of biomolecules.  The target audience is anyone
(computer scientist or physicist) interested in using and extending these
libraries for the purpose of methods development and experimentation.

MDX provides a modular approach to developing molecular dynamics
software.  The goal is to develop reusable modules with well-defined
interfaces towards the implementation of a sequential molecular dynamics
program and related tools.  The priority is to create MD codes that are
easy to understand and modify, enabling straightforward design and
testing of new methods.  Flexible software libraries will provide tools
for taking care of common tasks, allowing more rapid development of
revolutionary techniques.

Two major methods currently being developed are multilevel summation
method (MSM) for the fast evaluation of electrostatic forces and MDAPI,
a high-performance interfacing of a front end with an MD engine, intended
for use in a future release of NAMD.

MSM provides a fast method for computing electrostatics.  It produces
smooth potential energy and continuous forces for both nonperiodic and
periodic boundary conditions.  The approximation utilizes a repeated
smooth splitting of the interaction potential into a short-range part
evaluated directly and a slowly varying long-range part which is
interpolated to a lattice.  Repeated use of this idea gives rise to a
hierarchical method for which, under reasonable assumptions, the
computational cost is linear in the number of atoms.  The original paper
detailing this method for nonperiodic systems is:

  R. D. Skeel, I. Tezcan, D. J. Hardy, "Multiple Grid Methods for
  Classical Molecular Dynamics," J. Comp. Chem., 23, 673-684, 2002.
  http://bionum.cs.uiuc.edu/SkTH02.pdf

Further analysis, improvements, and the extension of the method to
periodic boundaries are presented in the author's dissertation, which
should be available shortly.

The MDAPI (MD application programming interface) is a core technology
demonstrated by MDX.  The design is to separate an MD code into a front
end and a computational engine.  The front end handles file reading and
writing, initializing the molecular system and categorizing results,
and interfacing with the user.  The engine performs the computational
tasks required for each simulation step.  The MDAPI provides a flexible
interface to both sides without sacrificing performance and specifies
basic guidlines to facilitate interoperability between any front end and
engine.  The MDAPI is intended to become a part of the third generation
NAMD architecture.  One possible vision is for VMD to serve as a front
end controlling a NAMD computational engine connected through the MDAPI,
where the interface layer would make transparent the remote communication
between, say, a graphics workstation running VMD and a remote parallel
cluster running NAMD.


MDSim Program
-------------

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


Libraries
---------

force - Evaluates bonded potentials, cutoff nonbonded potentials, 
  nonbonded exclusions, and certain boundary constraints.  Supports
  orthogonal cells that may be periodic in 0, 1, 2, or 3 dimensions.
  The different force types can be enabled individually or collectively.

mgrid - MSM restricted to cubic cells that are either nonperiodic or
  fully periodic.

step - Performs leapfrog (velocity Verlet) time integration.  Can also
  initialize velocities from a desired temperature distribution and
  calculate kinetic energy and temperature reductions.

random - Generates random numbers.  Used by the step library.

mdapi - Interfaces a front end with an MD engine.  This version is
  single-threaded, considered to be the reference implementation of
  the MDAPI specification.

mdio - Molecular dynamics I/O classes.  Reads NAMD-style configuration
  files, X-Plor force field parameter files, and X-Plor PSF topology
  files.  Reads and writes coordinate PDB files and NAMD-style binary
  restart files.  Writes DCD files (less than 2 GB).

adt - Container classes used by MDIO and MDAPI.

deven - MD engine that utilizes force, mgrid, and step libraries.

simen - Simple MD engine that utilizes force library.


Caveats
-------

For a scientist interested in using these codes for methods development,
it is not necessary, and probably not desirable, to comprehend the MDAPI.
The other major libraries (step, force, mgrid, and mdio) are much more
accessible and can lend themselves more quickly to methods development,
plus they contain all of the starting pieces needed for MD codes.
One thing to note is that all of these libraries depend on the molecular
and force field data types defined in the src/mdapi/mdtypes.h header file,
which is well-commented.  Reading Chapter 2 of the MDAPI Specification
(doc/mdapi.pdf), in which these data types are discussed, might also be
helpful.

This code base is under active development.  Even a more mature module,
such as the MDAPI, is subject to experience some changes to its interface
as some design issues are resolved.


Future Plans
------------

List of planned MSM library enhancements:
- Optimization for "sparse" nonperiodic domains to cut away corners from
  cube where atoms do not exist.
- Extend nonperiodic systems to rectangles.
- Permit grid sizes for periodic domains to be different sized powers of 2
  between dimensions or non-powers of 2 (e.g. allow a factor of 3 or 5).
- Add support for semi-periodic cells.
- Extend periodicity to rectangles.
- Extend periodicity to parallelepipeds.
- Perform fast reinitialization of constants for domain dimension updates
  (needed for flexible cells for constant pressure simulation).

Other plans to extend MDX include:
- Incorporation of Wei Wang's polarizability code.
- Implementation of multiple time stepping.
- Computation of "shadow" Hamiltonians.

Updates to the documentation:
- MDAPI needs to be "doxygen-ated", particularly to move the reference
  section of the MDAPI Specification so that it is maintained directly
  within the header files.


Directory Structure
-------------------

The top level directories serve the following purposes:

arch/  - Contains makefile definitions for each supported architecture.
build/  - Stores object files, libraries, and executables within
  subdirectories identified by the intended architecture.
demo/  - Provides a quick demonstration for MDSim.
doc/  - Contains documentation for the various modules.
src/  - Contains the source code for the modules, with each module
  located within its own subdirectory.  Each module may generate a
  binary executable, library, or plugin (i.e. dynamically loadable).

The following list presents the modules:

src/adt    - Container library (ADT = abstract data type).
src/debug  - Special header file with macros to assist debugging.
src/deven  - The "development engine" for MD.
src/force  - Force evaluation library.
src/mdapi  - MDAPI library.
src/mdio   - MD file I/O library.
src/mdsim  - Front end (a.k.a. "NAMD-lite") to deven.
src/mgrid  - MSM solver for electrostatics.
src/random - Random number library.
src/simen  - The "simple engine" for MD.
src/step   - Time integration library.


Documentation
-------------

doc/mdsim.txt  - Configuration options supported by MDSim and its
  compatibility with NAMD.

doc/html/index.html  - Documentation for all of the major modules
  (excluding MDAPI, deven, simen, and mdsim) generated by doxygen.
  
doc/mdapi.pdf  - Extensive documentation of the MDAPI specification.
  Of particular importance is Chapter 2 regarding the molecular and
  force field data types.  These are used (through the inclusion of
  mdapi/mdtypes.h) by many of the MDX libraries.

doc/mdapidev.txt  - Details regarding this implementation of the MDAPI
  specification.


Compilation
-----------

The codes have been successfully tested and should compile and run on
Linux, Solaris, and Darwin (Mac OS X).  Compiling the software requires
the GNU version of make.

Quick build instructions:

$ make config
$ make
$ make install             # default install into $HOME/bin, $HOME/lib, etc.
$ cd demo
$ mdsim alanin.config      # assuming $HOME/bin is in your path

  OR

$ make config INSTALL=no   # test libraries in place without installing
$ make
$ cd demo
$ ../build/Linux_generic/bin/mdsim alanin.config  # assuming Linux build

To build a version that tests the libraries in place, rather than
installing them to a different location, perform one of the following
at the command prompt:

$ make config INSTALL=no ARCH=debug  # compile with debugging support
$ make config INSTALL=no             # compile with optimizations

This will show the resulting build configuration.  Then build the
indicated modules by performing:

$ make

Other build options include:

$ make doc          # build PDF documents
$ make clean        # remove objects (for this architecture)
$ make cleandoc     # remove generated documents
$ make veryclean    # remove all objects and build configurations


Demonstration
-------------

Change your current working directory to demo/ and run the a very short
decalanine simulation by performing the following:

$ ../build/Linux_debug/bin/mdsim alanin.config

(replacing "Linux_debug" with your particular build).  The simulation
configuration file is almost identical to that for NAMD except for the
last few lines:

  # simulation results
  results         energy
  results         temp
  results         ke
  results         pe

that tell MDSim which simulation results to display.  Also perform this
brief simulation with NAMD to verify the correct answer:

$ namd2 alanin.namd.config

From this example, it should be obvious that MDSim has "borrowed" the
random number generator and velocity initialization code from NAMD.
The only other code taken from NAMD is that which computes dihedral
and improper interactions.  The rest has been written from scratch.

After running the examples, remove the output files in demo/ with:

$ make clean


Copyright and License
---------------------

All work included in this distribution is copyrighted by David J. Hardy,
except where noted within specific source files.  Terms of the license
are presented in the file LICENSE.