Fork me on GitHub

This tutorial covers the requirements and compilation/installation of the DynamO simulation package and its tools.

If you've already installed DynamO using the prebuilt packages, you can skip straight to tutorial 2:

Tutorial 2: Introduction to the DynamO workflow: Running a simulation of hard spheres

Step 0: Build requirements

DynamO is only tested on Gnu/Linux based systems (e.g., Ubuntu/Gentoo/RedHat/Suse). Compilation under Mac and windows is under development.

To build DynamO you will need a compiler, CMake, and several other libraries installed. There are also several optional dependencies which, if they're installed, will activate extra features. The minimum requirements are git, cmake, and the boost libraries. For the visualiser to compile, you need freeglut, GLEW, and gtkmm-3. For your convenience, commands to install these packages on Debian, RedHat-based, and OpenSUSE distributions are given below.


On Ubuntu versions 12.04 and above, you can install the minimum dependencies using the following command:

sudo apt-get install git build-essential cmake libboost-all-dev libbz2-dev

And the optional packages with this command:

apt-get install libjudy-dev libgtkmm-3.0-dev freeglut3-dev libavcodec-dev libglew1.6-dev libxmu-dev

Now you can continue to step 1.

CentOS/Red Hat Enterprise Linux (RHEL)/Scientific Linux 6

For older RedHat based distributions (e.g. RHEL 5 or 6), you will need to update to a modern compiler (gcc 4.6+) and you will also need to install an up-to-date version of boost. The instructions have only been tested on CentOS 6.5.

To install the modern compiler, you will need to install the updated developer toolset. For all variants of RedHat, this involves installing the developer tool set. Instructions on how to do this are listed below for the three main distributions:

You can then install the minimum dependencies like so

yum groupinstall "Development Tools"
yum install git cmake bzip2-devel

You will also need to install an up-to-date version of boost by hand, preferably v1.50 or above.

If you are having trouble updating to a modern version of boost, please follow step 1 to download a copy of the DynamO source code, then try the instructions for installing using a local boost.

Red Hat Enterprise/CentOS/Scientific Linux 7/Fedora 21+

To install the minimum dependencies, use the following two commands:

yum groupinstall "Development Tools"
yum install git cmake boost-devel bzip2-devel gcc-c++

If you wish to compile the visualiser, you will need to install the following packages:

yum install glew-devel freeglut-devel gtkmm30-devel libpng-devel libXmu-devel

OpenSUSE (13.1)

These instructions have only been tested on OpenSUSE 13.1. To install the minimum dependencies, use the following command:

sudo zypper install gcc-c++ cmake libbz2-devel git boost-devel

Now you can continue to step 1.

Step 1: Download the code

You must then download a copy of the source code. The recommended method is to use git:

git clone

If this command fails, it could be because you don't have an internet connection or you are behind a proxy. You can also try using the git protocal:

git clone git://

Both of these commands create a folder called DynamO with the full code inside. Change in to this folder to grab the submodules and to build the code.

cd DynamO
git submodule init
git submodule update

Step 2: Compilation

DynamO uses the CMake build system to handle its compilation. You set up the build/compilation in a sub directory like so:

mkdir build-dir
cd build-dir
cmake ..

By default the build type is set to "Release" to ensure DynamO is built with optimisations turned on.

This last step should take a few seconds while cmake checks the setup of your system. If there are any errors, they are typically due to missing build dependencies. If you cannot fix these on your own, please take a look at the support section of the site to find ways of filing a bug report and how to contact the developers.

Once cmake has finished setting up the build, you need to run make to actually compile the code.


Alternative Step 2:Compiling using a local boost installation

Many HPC resources have up-to-date compilers but out-of-date boost installations. In these cases it can be handy to have a way to install boost locally, in your own home directory.

First, download the source of the current release of the boost library from here, and extract it. You can do this using the commands below, provided wget is installed (it is not installed by default on Mac/OSX systems).

cd ~
tar -xf boost_1_56_0.tar.gz

Now change into the boost source directory and build only the libraries that DynamO needs.

cd ~/boost_1_56_0
./ --with-libraries=program_options,system,filesystem,iostreams,test

Now we can compile DynamO using this local boost installation. Change back to the DynamO directory and run the following commands:

#Make the build directory
mkdir -p build-dir
#Set up the build pointing to the local boost installation
cd build-dir
export BOOST_ROOT=~/boost_1_56_0/
export BOOST_LIBRARYDIR=~/boost_1_56_0/stage/lib
cmake ../
#begin the compilation

Step 3: Installation

Once the compilation has completed, you can install DynamO into your system using the following command (you will need to be root).

make install

Alternatively, you may just run the executables from the build directory. Congratulations, you now have a working installation of DynamO and can now move on to the next tutorial:

Tutorial 2: Introduction to the DynamO workflow


DynamO has a test-suite to confirm that the code is functioning as expected. You can run the test suite using the make test command:

make test


This covers how to update using Git, which you might choose to do if you have made changes to the code. Alternatively, you can just redownload the code and start again from the instructions above.

First, you will need to pull any new updates from the git repository:

cd DynamO
git pull
git submodule init
git submodule update

Then you should scrub the old build. This can be done by removing the build-dir:

rm -Rf build-dir

Finally, rebuild the code

mkdir build-dir
cd build-dir 
cmake ../
sudo make install

and you should now have an up-to-date set of executables installed.

Building debugging executables

If you're having some trouble with DynamO, you can build a debug version. This version is slower than the standard version, but contains many extra sanity checks and verbose error reports. To create the debugging version just run the following command in the DynamO directory

cd DynamO
mkdir debug-build-dir
#Create a special build directory for the debug code
cd debug-build-dir
#Set up the build
cmake .. -DCMAKE_BUILD_TYPE="Debug"
#Begin the compilation
sudo make install

Page last modified: Sunday 9th June 2024