Introduction and Installation

This documentation describes the software for the Fast Stokesian Dynamics (FSD) algorithm implemented on GPUs as a plugin for the molecular dynamics package HOOMD-blue. The algorithm is described in detail in the following manuscript: Fiore, Andrew M. and Swan, James W. Fast Stokesian Dynamics, J. Fluid Mech.

The FSD algorithm performs over-damped simulations of hydrodynamically interacting monodisperse suspensions of colloidal particles in periodic geometries. The hydrodynamic interactions are represented using the Stokesian Dynamics approximation, which includes a far-field many-body mobility computed using the multipole expansion (truncated after the force dipole) plus near-field pair-wise lubrication interactions.

Functionality is included in the software to apply linear shear to the suspension. The flow, gradient, and vorticity directions are the cartesian directions x, y, and z, respectively. Shear options include steady shear, oscillatory (sinusoidal) shear, and

Software Requirements

The FSD plugin requires the following software:
  • HOOMD, compiled with CUDA (tested with version 2.4)
  • CUDA (tested with version 9.2)
  • LAPACKE (tested with version 3.6.1)
  • CBLAS (tested with version 3.6.1)

CUDA can be installed manually after downloading the source code from NVIDIA and following the instructions presented by them.

LAPACKE and CBLAS can be installed manually after downloading the source code from netlib and openblas or from repositories. In Ubuntu, the simplest method is via repository:

sudo apt-get install liblapack3 liblapack-dev liblapacke liblapacke-dev
sudo apt-get install libblas3 libblas-dev libopenblas-dev libatlas-base-dev

Installing HOOMD-blue

For use with plugins, HOOMD-blue needs to be compiled from source (not installed using anaconda packages). The documentation for HOOMD-blue provides directions on installation. Those directions can be followed with the exception that the cmake command needs a particular set of flags, i.e.

export HOOMD_ROOT=/path/to/prefix

git clone --recursive https://bitbucket.org/glotzer/hoomd-blue

mkdir build

cd build

cmake ../ -DCMAKE_INSTALL_PREFIX=${HOOMD_ROOT}/lib/python -DCOPY_HEADERS=ON -DENABLE_CUDA=ON -DSINGLE_PRECISION=ON

make -j6

make install

A sample installation location is:

export HOOMD_ROOT=/home/your_user_name/hoomd-blue-install

An alternative to the cmake command is:

cmake ../
ccmake .

with the following ccmake options:

CMAKE_INSTALL_PREFIX    /path/to/prefix
COPY_HEADERS            ON
ENABLE_CUDA             ON
SINGLE_PRECISION        ON

after which you can hit “c” to configure cmake and “g” to generate the configuration. The installation can be tested with:

make test

Finally, HOOMD has to be added to the python path:

export PYTHONPATH=$PYTHONPATH:${HOOMD_ROOT}/lib/python

Installing the FSD Plugin

The FSD plugin itself can be installed using the following commands from the plugin directory:

make plugin_build

cd plugin_build

cmake ../ -DHOOMD_ROOT=${HOOMD_ROOT}/lib/python/hoomd

make -j6

make install

By default, make install will install the plugin into:

${HOOMD_ROOT}/lib/python/hoomd/PSEv3

Using the Plugin

A detailed description of a python script to set up and ran a simulation is given in Running a Simulation, but with a proper script, the simulation can be run with the command:

python3 run.py