MercuryPBM

MercuryPBM is a free, open source software package for the simulation of population balance models (PBM) and coupling of PBM to the discrete particle method (DPM), also known as discrete element method (DEM). MercuryPBM is an object-oriented C++ library that can be used to simulate a wide range of systems, from colloids to granular materials. The MercuryPBM build system is similar to the popular open source DEM framework MercuryDPM enabling users to easily couple both codes. This will allow to integrate particle dynamics into stochastic PBM simulations in the future.

Bitbucket Repository
Version: 0.1
License: BSD-3-Clause\

Installation

Linux installation guide

Mac installation guide

Windows installation guide

External Dependencies

Miminum requirements:

1. C++ and Fortran compilers: MercuryPBM uses C++20 features and thus requires an up-to-date compiler. We suggest you use at least gcc 9 or higher. To compile our Fortran files, we recommend gfortran.

2. git version 2.2 or higher

3. cmake version 2.8.14 or higher (http://cmake.org/cmake)

4. python version 3 or higher

5. Eigen version 3 or higher

Optional dependencies:

1. doxygen (http://www.doxygen.nl/download.html) and graphviz (dot) (https://graphviz.gitlab.io/download/), used to create a local copy of the documentation

Linux installation

Step 1: Install external dependencies

• Before installing MercuryPBM, you need to install a set of required external dependencies:

On Ubuntu 20.04, you can install the minimum dependencies with the following command:

sudo apt install build-essential g++ gfortran git cmake python3 python3-dev gdb libeigen3-dev

On Ubuntu 20.04, you can install the optional dependencies with the following command:

sudo apt install doxygen graphviz

Step 2: Clone the MercuryPBM repository

• To install MercuryPBM, open the terminal. Create a new directory in which to install MercuryPBM, and enter this directory:

mkdir MercuryPBM
cd MercuryPBM

• There are three options to get the developers version of the code. We list them in order of simplicity:

1. Direct local clone:

   Check out a local clone of the MercuryPBM developers version using the following command:

   git clone https://bitbucket.org/mercurydpm/mercurypbm.git MercurySource
   

   This option is recommended if you simply want to use/test MercuryPBM. You do not need an Atlassian account. However, it does not allow to push back features to Bitbucket.

2. Private fork:

   If you want to develop a (private) feature with MercuryPBM (which we encourage you to push back to us at a later date), create a personalised local repo of MercuryPBM on bitbucket:

   • Goto https://bitbucket.org/mercurydpm/mercurypbm/

   • Create an Atlassian Bitbucket account

   • Establish a secure SSH connection to the Bitbucket cloud.

   • Click the the three dots and select 'Fork this repository'

   Then clone this fork to your computer:

   git clone git@bitbucket.org:<yourBitBucketName>/mercurypbm.git MercurySource
   

3. Main (open) developers branch:

   If you are a member of the MercuryPBM development team, create a public branch of MercuryPBM in the main git repository:

   git clone git@bitbucket.org:mercurydpm/mercurypbm.git MercurySource
   

   Note, you must first establish a secure SSH connection to the Bitbucket cloud.

Step 3: Install MercuryPBM

• Create another directory called "MercuryBuild", and enter the folder by typing

mkdir MercuryBuild
cd MercuryBuild

• Create the Makefiles necessary for compiling MercuryPBM using cmake:

cmake ../MercurySource

Note 1: If you don't want to use the default cmake options, use ccmake instead of cmake. In ccmake, click "c" to configure, then modify the configuration as needed . Then click "c" to configure again. Finally, click "g" to generate the Makefiles.

Note 2: To modify the build options, you can also using cmake's command line interface instead of ccmake. For example, you can change to build in Release mode instead of Debug mode using cmake ../MercurySource -DBUILD=Release

To check if the installation was successful, go to your build directory "MercuryBuild" using the terminal and type

make fullTest

This will compile all MercuryPBM components, and run the selftest suite.

If all the tests have passed, MercuryPBM is successfully installed on your machine.

Mac installation

Step 1: Install external dependencies

• To install an up-to-date c++ compiler we recommend you to install either XCode or the Command Line Tools. XCode provides you with a nice IDE, but is ~10GB in size, whereas the Command line tools is a much lighter package. To install the Command Line Tools, open a terminal and type

xcode-select --install

For more details, see https://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/.

• To install the other dependencies, we recommend you to use a package manager such as brew. Once you have installed brew, you can install the other packages as follows:

brew install --cask cmake
brew install git
brew install python
brew install gcc
brew install eigen

Notes: the "--cask" version of cmake adds the graphical user interface; gcc is installed to get gfortran, you can install any other fortran compiler.

• Similarly, you also can install the optional dependencies, like doxygen:

brew install --cask xquartz
brew install doxygen
brew install graphviz

Step 2: Install MercuryPBM

• Follow the installation instructions for linux to install MercuryPBM, starting with step 2.

Class structure

Contribution guidelines

• Writing tests
• Code review
• Other guidelines

Who do I talk to?

• Repo owner or admin
• Other community or team contact