Overview

What is it?

HOOMD-blue is a general-purpose particle simulation toolkit. It scales from a single CPU core to thousands of GPUs.
You define particle initial conditions and interactions in a high-level python script. Then tell HOOMD-blue how you want to execute the job and it takes care of the rest. Python job scripts give you unlimited flexibility to create custom initialization routines, control simulation parameters, and perform in situ analysis.

How does it work?

The core of Hoomd is written in C++, which is how it is able to utilize GPU hardware in a seamless way. But it also has an API written in Python that plugs into the C++ backend, enabling simpler programs and making the learning curve shallower.

On the main Hoomd-blue website (link above), an example using the Python API is given:

import hoomd, hoomd.md
hoomd.context.initialize()
unitcell=hoomd.lattice.sc(a=2.0, type_name='A')
hoomd.init.create_lattice(unitcell=unitcell, n=10)
nl = hoomd.md.nlist.cell()
lj = hoomd.md.pair.lj(r_cut=3.0, nlist=nl)
lj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
all = hoomd.group.all();
hoomd.md.integrate.mode_standard(dt=0.005)
hoomd.md.integrate.langevin(group=all, kT=1.2, seed=4)
hoomd.run(10e3)

This can be run in any manner of ways:

Serial (single processing unit):

$ hoomd run.py --mode=cpu    # run on a single cpu
$ hoomd run.py --mode=gpu    # run on a single gpu

Parallel (multiple processing units):

$ mpirun -n 256 hoomd run.py --mode=cpu    # run on 256 cpus
$ mpirun -n 64 hoomd run.py --mode=gpu    # run on 64 gpus

Building Hoomd

To build:

Clone copy of repository locally
Make a build directory
Move into the build directory
Run the cmake command and point it to the repository directory

Also see glotzports repo: https://bitbucket.org/glotzer/glotzports/src/f947d3842169?at=master

Running Examples

Source:

https://github.com/joaander/hoomd-examples

Live notebooks:

https://nbviewer.jupyter.org/github/joaander/hoomd-examples/blob/master/index.ipynb

Exploring the Source

Main Directory

The main directory of hoomd-blue contains mostly infrastructure stuff: building, compiling, documentation, testing, etc.

https://bitbucket.org/glotzer/hoomd-blue/src/5007cf262c48aa72210bf93266aa175898ebb254?at=maint

The actual source code of hoomd is in the hoomd folder.

The main directory contains the following components:

circleci - directory with circle continuous integration configuration files (testing)
jenkins - directory with Jenkins configuration (deployment)
cmake - configuration directory/files (cmake is the build system used by hoomd)
conda-recipe - directory for scripts for building hoomd via conda
doc - directory containing Doxygen documentation build files
sphinx-doc - directory containing documentation files for sphinx documentation (main documentation style for Python projects)
hoomd - directory containing source code for hoomd

Hoomd Source

The hoomd source is in the hoomd folder of the repository:

https://bitbucket.org/glotzer/hoomd-blue/src/5007cf262c48aa72210bf93266aa175898ebb254/hoomd/?at=maint

List of modules:

cgcmm
dem
extern - links into modules for external linear solvers
hpmc - hard particle monte carlo
md - molecular dynamics
metal - dynamics simulations for metal atoms
test - tests

Molecular Dynamics (md) Module

In the hoomd source, the md folder contains code for solving molecular dynamics equations on a lattice.

https://bitbucket.org/glotzer/hoomd-blue/src/5007cf262c48aa72210bf93266aa175898ebb254/hoomd/md/?at=maint

Brownian vs Langevin Dynamics

The principal difference between Brownian and Langevin dynamics is that Langevin dynamics are a more general case of Brownian dynamics.

Specifically, Brownian dynamics ignores the inertia of a particle, and neglects a particle acceleration term. This is equivalent to treating a molecular dynamics simulation as a big force balance where the sum of forces on each particle should be zero. The Brownian dynamics equation of motion (Brownian equation) is a first-order differential equation (first order with respect to particle location), because there is no particle acceleration term and therefore no second derivatives of particle location.

Contrast that with the Langevin equation, which is the more general of the two cases. The Langevin equation includes an additional acceleration term in the equation of motion for each particle in the system, and this results in a second order (with respect to particle location) differential equation.

Often in the literature, Brownian dynamics and Langevin dynamics are treated as interchangeable. From the standpoint of a physicist dealing with governing equations, this is understandable, because it's a matter of including or excluding a single term (or setting the force balance equal to 0 or equal to ma).

Numerically, though, first and second order differential equations can require totally different strategies, so it's important for computational tools and mathematicians to differentiate between the two cases.

Brownian dynamics: https://en.wikipedia.org/wiki/Brownian_dynamics

Langevin dynamics: https://en.wikipedia.org/wiki/Langevin_dynamics