MercuryDPM  0.9
Reference documentation of Mercury - MD

# News

MercuryDPM is a code for performing discrete particle simulations. It is currently available on request (a.r.t.nosp@m.horn.nosp@m.ton@u.nosp@m.twen.nosp@m.te.nl or t.wei.nosp@m.nhar.nosp@m.t@utw.nosp@m.ente.nosp@m..nl), but will soon be released as an open-source code.

Update Apr 16, 2013: In a recent article we have described the code as being publicly available already. Unfortunately, version 1.0 is still begin alpha tested and the new website is being built. We apologise to the readers of this article; however, an alpha version 0.9 is currently available as a tar ball. Version 1.0 , a new website and public svn access to the code will all become available very shortly. We are sorry for the delay; however, if you have any problem with the alpha release we will provide support; do not hesitate to contact us.

Simulation of granular flow through a contraction with 400,000 particles. Two shocks are generated on either side of the contraction and there is interaction where the two shocks meet. The colour of the particles indicates the flow height.

Mercury is a code for discrete particle simulations. That is, it simulates the motion of particles, or atoms, by applying forces and torques that stem either from external body forces, (e.g. gravity, magnetic fields, etc...) or from particle interaction laws (e.g. Lennard-Jones). For granular particles, these are typically contact forces (elastic, plastic, viscous, frictional), while for molecular simulations, forces typically stem from interaction potentials (e.g. Lennard-Jones). The code has been developed extensively for granular applications, but could be adapted to include long-range interactions as well.

It was started by Anthony Thornton and Thomas Weinhart, and is currently actively developed by Thomas Weinhart, Anthony Thornton and Dinant Krijgsman with input from Stefan Luding and Onno Bokhove.

Mercury is a very versatile, object-orientated C++ code which is easily understandable. It has been tested for several Linux distributions and Mac OS. The user specifies the particulars of their simulation (initial positions, inflow, outflow, walls, interaction parameters) in a single driver file, which calls the kernel to do the simulations. All kernel functions are documented here, and there are several driver samples available. To avoid breaking already existing code a suite of self-tests have been developed testing pre-existing features of the code.

Among other developments, it contains the hGrid neighbourhood search algorithm to effectively compute interaction forces, even for polydispersed particles. It has an in-built statistics package to extract fields such as density, velocity, and stresses, during computation or for post-processing. Many contact force models are implemented, including elastic or dissipative normal forces and tangential friction; flat or polyhedral walls are modelled, as well as fixed-particle walls; particles can be grouped into species with different parameters; inflow through a hopper is implemented; codes can be restarted from the output files, if the simulation has been aborted.

# Installation (Internal svn access only)

1. Before you start, type 'svn' and 'doxygen' into your terminal to see if these programs are installed. Install svn and Doxygen if needed.
2. Check if you can connect to the svn server here: type :
svn list https://www2.msm.ctw.utwente.nl/svn/repos/THORNTON/Code
Finite_volume_code/
MD/
SPH/
scripts/
If the user name on your current system is not the same as your user name on the svn repository, you will need to add  –username=<yourusername>  to the end of the command.
3. Now you need to check out the MD/ and the scripts/ directories. You should have been given a branchname like 'BRANCHES/yourname'. First create a directory for the code with
mkdir <yourcodedir>
then type
svn checkout https://www2.msm.ctw.utwente.nl/svn/repos/THORNTON/Code/scripts <yourcodedir>/scripts
svn checkout https://www2.msm.ctw.utwente.nl/svn/repos/THORNTON/Code/MD/<branchname>/  <yourcodedir>/MD/

4. Once you have got the code, cd into the MD/DRIVERS/ directory and type
make doc
You should get lots of output.
5. Now go to MD/Documentation/html/ and load index.html into your web browser, by typing
firefox index.html
or otherwise. This will give you this documentation, which you are currently reading, it is not complete, as we are not fully ready to go open source, but there is some description of what is in each directory, including the scripts, which you may find useful. The main reason for doing this is it gives you the a local update version of the documentation. Please now swap to folling the instructions in this version.

## Getting a feel for the code

1. Go to MD/DRIVERS/ and type
make selftest
This will run the tests. If any fail let me know then there is a problem on your computer.
2. Go to the directory MD/DRIVERS/Simple_MD/run/ then type
sc/quick_run free_fall
This will run a simulation of a single particle falling under gravity. The output from this code will appear in a directory called free_fall.
3. To visualise the results of the code, type
./free_fall/free_fall.disp
This should launch Stefan Luding's MD visualisation program. You may get an error message here if so when me know and I will get you a version for your operating system.
4. To compile, run, and visualise another problem, type
sc/quick_run free_cooling
./free_cooling/free_cooling_hgrid.disp 
This will display a short animations of 100 particles moving under gravity bouncing off a wall and interacting inelastically.

You should notice this code runs twice, once using the HGRID and once not. The use of the HGRID should be a lot faster, this is the third party code I said that is used to make the code go faster. I would base any code you write on the HGRID version of this code. Have a look at free_cooling.cpp. Gravity defaults to 9.8 in the z-direction can this can changed my setting the gravity vector see documentation.

# Mailing List

There is a mailing list for the users of MERCURY; if you would like to join please send an email to:

listserv[AT]lists[dot]utwente[dot]nl,

with

Subject: subscribe
Body: subscribe MERCURY-USER <your full name>

As a member of the list you will receive information about updates to the code, new features and bug fixes. Please note, if you require technical support or just have general questions about the code join the mailing list and send your e-mail to the list [Note, this will not be distributed to all list members, just the developers].

# The Current Development Team

• Thomas Weinhart
• Project manager
• Developer
• Technical Support
• Anthony Thornton
• Project manager
• Developer
• Technical Support
• Dinant Krijsman
• Developer
• Stefan Luding
• Onno Bokhove

# Using the code

The code is currently not publically available, but a public release is anticipated in the coming weeks.

When released you will be free to use the code under the GNU public license.

# Publications from the code

This code uses the hierarchical grid (fast multilevel algorithm), of Ogarko and Luding (2012), for neighbourhood search. Currently there is no paper describing this code; however, the authors have several publications using the same code. Therefore, we kindly request if you use this code, you refer to the following publications.

1. Ogarko and Luding. A fast multilevel algorithm for contact detection of arbitrarily polydisperse objects. Computer Physics Communications, 183 (2012) p932-936.
2. Weinhart, Thornton, Luding and Bokhove, Closure Relations for Shallow Granular Flows from Particle Simulations. Granular Matter, 14 (2012) p531-552. Download: http://eprints.eemcs.utwente.nl/20425/
3. Thornton, Weinhart, Luding and Bokhove, Friction dependence of shallow granular flows from discrete particle simulations. EPJ E, submitted 2011. Download: http://eprints.eemcs.utwente.nl/20679/
4. Weinhart, Thornton, Luding and Bokhove, From discrete particles to continuum ﬁelds near a boundary. Granular Matter, special volume for Goldhirsch, 14-2 (2012) p289-294. Download: http://eprints.eemcs.utwente.nl/20426/
5. Thornton, Weinhart, Luding and Bokhove, Modeling of particle size segregation: Calibration using the discrete particle method . Modern Physics C, in press. http://eprints.eemcs.utwente.nl/20702/

These represent the applications for which the code was originally developed and details of the used contact detection algorithm.

Publications using the code:

1. Weinhart, Thornton, Luding and Bokhove, Closure Relations for Shallow Granular Flows from Particle Simulations. Granular Matter, 14 (2012) p531-552.
2. Thornton, Weinhart, Luding and Bokhove, Modeling of particle size segregation: Calibration using the discrete particle method. Modern Physics C, in press. http://eprints.eemcs.utwente.nl/20702/
3. Weinhart, Thornton, Luding and Bokhove, From discrete particles to continuum ﬁelds near a boundary. Granular Matter, special volume for Goldhirsch, 14-2 (2012) p289-294. Download: http://eprints.eemcs.utwente.nl/20426/
4. Thornton, Weinhart, Luding and Bokhove, Friction dependence of shallow granular flows from discrete particle simulations. EPL, submitted 2011. Download: http://eprints.eemcs.utwente.nl/20679/