ParM Documentation

The PARticle Molecular dynamics library


Purpose

The purpose of this library is to provide methods to produce any MD simulation, with any type of integrator, any type of particles, and any type of force in 2D or 3D.

It is currently single-core only, and provides objects for many different integrators, and many different forces, which can be composed together for simulations from a few particles bouncing around in a box to a full protein simulation.

Examples

C++

There are several examples in C++ in the src/bin folder, all with good comments:

• LJatoms.cpp (LJatoms.cpp): a simulation of a Lennard-Jones simulation (2D, or 3D)
• packer.cpp (packer.cpp): Generates packings (2D or 3D)
• hardspheres.cpp (hardspheres.cpp): for a more unconventional example of collision-driven dynamics

Python

See pyparm/examples/LJ.py (LJ.py) for an example of a simple Lennard-Jones simulation, with data analysis included.

See pyparm/packmin.py for an example of how to make a packing.

Basic Concepts

• Vec: this is a "vector" in the physics sense, having either 2 or 3 dimensions.
• Atom: an Atom is the basic unit of the simulation; it represents a particle with mass, position, velocity, etc.
• AtomGroup: an AtomGroup is a set of atoms, grouped together for the sake of utility.
  • Note that AtomVec is a concrete type, and AtomGroup is an abstract class
• Interaction: an Interaction is a definition of a force and energy, such as a Lennard-Jones potential (use NListed<IEpsSigCutAtom, LJAttractRepulsePair>), springs for bonds (BondPairs), etc.
  • Note that the neighbor list has been "abstracted" to work with many potentials; to use it, you create a NeighborList, then use NListed<FooAtom, FooPair> as the Interaction
• Box: a box is either infinite (InfiniteBox) or periodic (OriginBox), and takes care of the boundary conditions
• Collection: a grouping together of a Box, AtomGroup, and Interactions, with an integrator (such as velocity Verlet, CollectionVerlet, or brownian motion, CollectionSol).

Standard Steps

1. Make a Box. OriginBox is a good standard choice for periodic boundary conditions.
2. Make an AtomVec.
3. Set masses, positions and velocities
   1. Positions might be set using box.rand_loc(), for a random point inside the box
   2. Velocities may be set using rand_vec(), which generates a Gaussian distribution, like the expected Boltzmann distribution

1. Make Interactions. For neighborlisted interactions, make NeighborList first, then make interactions.
   1. NListed<EpsSigAtom, LJRepulsivePair> (LJRepulsive in Python) is a repulsive Lennard-Jones Interaction
   2. NListed<EpsSigExpAtom, RepulsionPair> (Repulsion in Python) is a Repulsion or Harmonic Interaction (exponent can be chosen)
   3. Add atoms / pairs to Interaction
2. Make a Collection. Note that the NeighborList has to be added to trackers
   1. CollectionVerlet is a good NVE Collection
3. Run Collection.timestep() many, many times
   1. Use methods such as Collection.kinetic_energy() or Collection.temp() to get statistics
   2. Or use trackers like RsqTracker to track running statistics
4. Write output to files

Dependencies

• STL, the C++ Standard Template Library
• Boost: primarily for random numbers, also a few odds and ends
• (optional) SWIG: for generating Python bindings
• (optional) Python: for generating Python bindings
  • Known to compile for python 3.2-3.4, and probably with 2.6-2.7

On Ubuntu, the following packages should suffice for Python 3:

build-essential
libeigen3-dev
libboost-all-dev
swig
python3-dev
python3-numpy
python3-nose
python3-setuptools 
python3-pip

For Python 2, simply use the same packages but with the python- prefix instead of python3-.

Note that you will need to make sure you include Boost and Eigen in you "include" path. On Ubuntu, Boost will be by default, but you may need to add Eigen:

export CPLUS_INCLUDE_PATH="$CPLUS_INCLUDE_PATH:/usr/include/eigen3"

Note that the attached .travis.yml file are computer-readable instructions for automatically building and testing this module on an Ubuntu machine, so that should always be up to date.

Python

This library includes a sim.i file for use with SWIG for generating Python bindings.

To Generate Python module

• Make sure you have the dependencies and include paths set, as above.
• Run make wraps to generate the SWIG wrappers.
• Run python3 setup.py build_ext --inplace to build it in place, or python3 setup.py install to install.
  • There are many option for Python setup.py files; run python3 setup.py --help to see more options.

Using the Python module

Use import pyparm.d2 as sim or import pyparm.d3 as sim to import the module. Then use it freely.

Other Notes

Lennard-Jones

This module uses the equation \(V\left(r\right)=\varepsilon\left(1-\frac{\sigma^{6}}{r^{6}}\right)^{2}\)

The other standard form is \(V\left(r\right)=4\varepsilon\left(\frac{\sigma^{\prime12}}{r^{12}}-\frac{\sigma^{12}}{r^{6}}\right)\)

To convert, use \(\sigma=2^{\frac{1}{6}}\sigma^{\prime}\).