VERSIONS 0.11.1

MercuryDPM 0.11.1 was released on 1st October.

You can find the download instructions here: http://mercurydpm.org-> Downloads -> 0.11

To upgrade a 0.11 version, that was checkout using svn simple type: 'svn switch ^/Release/0.11.1'

REQUIRED DRIVER CHANGES (to update from MercuryDPM 0.11)

No driver changes are required if you have previously used Mercury 0.11.

KNOWN ISSUES

- If you are using the gcc compiler you will get compiler warnings that the deprecated keyword is unknown. You can ignore these warnings, or turn them off using -Wnoattributes

NEW FEATURES IN 0.11.1

The following bug fixes have been applied:

1) SelfTests now work with both python2 and python3.

2) A mistake in the computation of the Hertz normal force has been patched: In the old version , the force was computed as f=4/3 E^* sqrt(2 R^* delta) delta, this has been corrected to f=4/3 E^* sqrt(R^* delta) delta

3) CubeInsertionBoundary has been patched: before the velocity was incorrectly set.

The following changes have been made:

1) Improved xballs parameters for Tutorial9.

2) HertzianViscoelasticSlidingFrictionSpecies has been defined as a new template species.

3) The script file loadstatistics.m has been added to Drivers/MercuryCG to plot results of MercuryCG in Matlab.

4) One new demo have been added and second update to explain how to use MercuryCG: MercurySimpleDemos/FiveParticles.cpp and MercurySimpleDemos/LeesEdwardsSelfTest.cpp

VERSION 0.11(BETA)

MercuryDPM 0.11 (Beta) was released on August 12th, 2016. It does not yet include the full feature list planned for MercuryDPM 1.0, but is a fully functional C++ package for performing discrete particle simulations.

REQUIRED DRIVER CHANGES (to update from MercuryDPM 0.10)

Directory structure has changed a lot, so files will have to be moved, see below.

The following few functions, changed their name (the line starting with a minus is the old version, the line starting with + is the new version)

-getWallHandler()

+wallHandler

-getParticleHandler()

+particleHandler

- set/get_Position

+set/getPosition

-set/get_Velocity

+set/getVelocity

-set/get_name

+set/getName

-set/get_{xmin, xmax, ymin, ymax, zmin, zmax}

+set/get{XMin, XMax, YMin, YMax, ZMin, ZMax}

-set/get_Radius

+set/getRadius

-set/get_species

+set/getSpecies

- setNormalStiffnessAndDissipation() to

+ setStiffnessAndDissipation(), to be compatible with the setStiffness() and setDissipation functions

Note that this list might not be complete; Most of the functions in 0.10 which have an underscore in between the names have been modified such that they adhere to the new coding guidelines. If you find your code required more changes than listed here, please let us know. Also please look in Drivers/Tutorials for examples.

Additionally, several functions have been deprecated (i.e., will soon disappear or take a much nicer form in later versions), and should be replaced by different syntax. When compiling with functions which are deprecated, you will receive warnings which shall soon disappear in later versions.

The most important deprecated functions are:

(i) Walls should not be initialised by a normal vector and a scalar (representing the scaled distance from the origin) anymore. Use a vector position (point on the wall) instead.

E.g. In order to declare a wall on the right of your domain, replace the following line:

InfiniteWall w;

Vec3D normal=Vec3D(1,0,0);

- w.set(normal, getXMax())

+ w.set(normal,Vec3D(getXMax(),0,0));

KNOWN ISSUES

- If you are using the gcc compiler you will get compiler warnings that the deprecated keyword is unknown. You can ignore these warnings, or turn them off using -Wnoattributes

- If you are using the gcc compiler, make sure that your compiler is up-to-date (version 4.8 or higher). Even though version 4.7 of gcc claims to have all C++11 features, the implementation is incomplete and MercuryDPM will not work under this version.

- Sometimes the selftest with .data fail on MAC due to an issue with python scripts. If you get this problems please report all information about your setup as the main development team is having a hard time creating this error.

NEW FEATURES IN 0.11

1. A complete documentation of MercuryDPM’s core directory (Kernel/), previously known as src/, available at docs.mercurydpm.org

2. Most importantly, new tests have been added to check if all the new features work.

3. MercuryDPM now supports Paraview. All your particle data can be viewed both in Paraview and XBalls. Please look into our documentation for further details http://docs.mercurydpm.org/Beta/d1/d6b/analysing.html

4. New tutorials have been added to showcase the features of our code, see Drivers/Tutorials. We are working on many more new tutorials for a comprehensive understanding of MercuryDPM.

5. A fully reorganised directory structure:

At the top level of the source directory you will find six main subdirectories:

• Drivers/ This is the only directory you need to create new application codes or modify existing ones; all other directories contain either documentation or files required as input files in the codes contained in this directory.
  It has a series of subdirectories, for example Tutorials/, that contain a series of demo codes illustrating how to write applications in MercuryDPM.

• Kernel/
  Contains the heart of the code. Users should not change the Kernel files. Instead, the classes and functions defined here are should be used (and possibly modified) in the Driver files.

• Scripts/ Contains a script used by make test, and make fullTest to check if two output files are equal.

• Tools/ Contains the source files required to use paraview.

• Documentation/
  Contains the raw .dox files for creating documentation pages, like the one you are reading right now, as well as the images used in the documentation.

• Configuration/
  These files specify how the documentation and the code is configured.

6. All source files now have the license prepended.

7. New Features

a) Complex wall geometries are now possible such as axisymmetric walls (cones, cylinders, ...), screws, coils, and many more.

b) Support for periodic boundaries, angled periodic boundaries (periodic boundaries in angular direction in a cylindrical geometry), circular periodic boundaries, Lees-Edwards boundaries (periodic boxes with shear). Also introduced a deletion and insertion boundary.

c) Multiple new types of interactions varying from elastic to adhesive to frictional, e.g. Hertzian visco-elastic, linear plastic-visco-elastic, linear visco-elastic, liquid bridges (Willet's model), reversible adhesive, sliding friction. For each of these interactions, species are defined that store the contact properties.

8. In addition to the wallHandler and particleHandler, additional handlers have been introduced, please refer to the documentation

boundaryHandler

interactionHandler

speciesHandler

9. A new class Files has been introduced to read and write files. The files can be accesses by the following variables:

restartFile

dataFile

fstatFile

statFile

eneFile

10. New coding guidelines have been adopted. Please check the link http://mercurydpm.org/development/coding-style-of-the-kernel. As a result we have changed function names, such that they adhere to the new guidelines.

MercuryDPM 0.10 (Beta) was released February 18, 2014. It does not yet include the full feature list planned for MercuryDPM, but is a fully functional C++ package for performing discrete particle simulations.

REQUIRED DRIVER CHANGES (TO UPDATE FROM MERCURYDPM 0.9)

When you update from MercuryDPM 0.9 to MercuryDPM 0.10, you DRIVER codes have to be updated. Here is a list of the required changes:

A) Name changes

The following functions changed their name (the line starting with a minus is the old version, the line starting with + is the new version)

- get_WallHandler()

+ getWallHandler()

- get_ParticleHandler()

+ getParticleHandler()

- Particle p0;

+ BaseParticle p0;

Note: If you are using friction, you have to define your particles as TangentialSpringParticle, not BaseParticle

If you are using the plastic force model, you have to define your particles as DeltaMaxsParticle, not BaseParticle

- cout, endl, stringstream, string

+ std::cout, std::endl, std::stringstream, std::string

Note: Removed "using namespace std", and inserted all the necessary std::

- set_HGRID_sphere_to_cell_ratio(1.2);

- set_UpdateEachTimeStep(false);

+ setHGridCellOverSizeRatio(1.2);

+ setHGridUpdateEachTimeStep(false);

Use set_Position and set_Velocity when setting positions and velocities

Note that this list might not be complete; if you find your code required more changes than listed here, please let us know.

B) CMake

We now use cmake to compile code. For more detail, see the installation instructions on the MercuryDPM website.

C) Downloading

MercuryDPM is now available from our public svn server both version 0.9 and the new 0.10 (Beta).

KNOWN ISSUES

- The balls option "-scala 4" does not work on the mac operating system

- The restarting feature does not save the first time step after restart

NEW FEATURES IN 0.10

CMake

CMake is now used to compile MercuryDPM code. For more details, see installation instructions on the website.

HGridOptimiser

The cell sizes used in the HGrid neighbourhood search routine are now set automatically by the HGridOptimiser. The optimal placement of the cell sizes is based on the particle size distribution. Currently, two distributions are considered.

• Linear (the maximum number of levels are linearly distributed between minimum and maximum particle size)

• Exponential (the maximum number of levels are linearly distributed between minimum and maximum particle size)

• (In progress) Constant number of particles per cell

• (In progress) Optimal

Further Changes:

• It now allows for top-down and bottom-up approaches

• The CELL_TO_CELL_RATIO parameter has been removed

• Changed how sizes (and inverse size) of level are stored to vectors

• The SPHERE_TO_CELL_RATIO parameter has been renamed to cellOverSizeRatio and is used to make sure that particles fit more comfortably in each cell, such that their HGrid positions don't need to be updated each time step

• Added new test HGrid_demo.cpp which test different HGrid options with a larger particle size distribution then free cooling

Adhesive Forces:

• It is now possible to simulate short-range non-contact forces. These are typically adhesive forces, such as van-der-Waals forces or liquid bridges, but potential applications include short-range potential forces like Lennard-Jones or SPH interactions. Currently, only a linear reversible and a linear irreversible adhesive force is implemented. The new code is tested by the two driver codes UnitTests/adhesiveForce and MercurySimpleDemos/free_fall_adhesive.

Reorganisation of the source files

• Added the constant specifier to a lot of functions in CParticle most notably get_Position() and get_Velocity() return a const Vec3D now

• Split the CParticle and the ParticleHandler into header and implementation files

• Split the HGRID from HGRID_base and created header and implementation files

• Added the functionality to get en set X,Y,Z components of a Vec3D by index

• Added the directory Boundaries where baseBoundary and all its derivatives should move too

• Created an insertionBoundary which allows you to insert particles at random in a Domain, it does not yet use the HGRID and needs some more improvements

• Added Simple_MD/insertionBoundaryTest.cpp to test the insertionBoundary

• Removed the obsolete CWall.h

Changes to the ParticleHandler

• Changed the ParticleHandler such that it extends from the BaseHandler

Major changes:

• All objects designed for Handlers have a index, id and pointer to their handler

• All objects designed for Handlers have the required set functions

• All objects designed for Handlers have a moveInHandler function, which is called when a Object is moved to a new position in a vector. This is for example used for tangential springs

• The baseHandler now stores the maximum number of objects in the handler and the id for the next object

Note: If you are using friction, you have to define your particles as TangentialSpringParticle, not BaseParticle

Walls

• - Walls can now have a species and velocity. For most walls the definition of velocity is simple. Only for the FiniteAxisSymmetricWall a more complex definition was implemented

• Prismatic polyhedral walls can now be added using the function FiniteWall::create_prism_walls

Misc

• Added the functionality to MD to follow a single particle and output integration and collisions to the screen. This is useful for anlyzing selftests going wrong.

• Change the default of getInfo to be the species number

• Added local angular momentum, local angular momentum flux and couple Stress to the Statistics

• Compatibility issues: In order to get consistent selftest results for different compilers, the self tests have been revised to take into account differences between compiler implementations.

• Removed "using namespace std", and inserted all the necessary std::

• Many extra example DRIVER codes were added

• Many other small bugs have been fixed

MAIN FEATURES

• Particle contact models: The default contact model in Mercury DPM is described in [2]. It can model elasticity, viscosity, plasticity and cohesivity as well as sliding, rolling and torsion friction. The elastic springs can be chosen either linear or Hertzian. Additionally, the kernel is flexible enough to allow the implementation of other contact models. Time integration of the force laws is performed using the Velocity Verlet algorithm.

• Particles: Spherical particles (circular in 2D) can be modelled. Particles can be of different species, which can have different contact behaviour or material parameters.

• Walls: In addition to praticles, multiple wall types can be modelled. This includes (i) flat, infinitely large walls, (ii) polyhedral walls, and (iii) axisymmetric shapes such as cylinders, cones, or funnels. Additionally, the code is general enough to allow the implementation of complex walls such as screws or drills.

• Neighbourhood search algorithm: MercuryDPM uses the hGrid neighbourhood search algorithm [1] to effectively compute interaction forces, even for polydispersed particles.

• Output: MercuryDPM has four different output files that it can output at selected timesteps: (i) data files, storing the particle information (position, velocity, radius, ...), (ii) fstat files, storing the contact information (contact partners, interaction force, overlap, ...), (iii) ene files, storing general information about the system (kinetic energy, elastic energy, center of mass, ...) and (iv) restart files, containing all information about the current system state, so the code can be restarted. Scripts are available to visualize the system in Visual Molecular Dynamics or in the in-house visualization tool xballs which is included in MercuryDPM.

• Input: The code is designed such that a simulation is defined in a single cpp file (the DRIVER file). However, other modes of defining/changing a simulation are possible: a system can be restarted from a restart file, and a system can be modified using command line arguments. Further, parameter studies can be created using the auto_number tool, whereas the system.

[1] Vitaliy Ogarko and Stefan Luding, A fast multilevel algorithm for contact detection of arbitrarily polydisperse objects,

Computer Physics Communications, 183 (2012), pp 932-936. [2] Stefan Luding, Cohesive, frictional powders: contact models for tension,

Granular Matter 14 (2008), vol 4, pp 235-246.

KNOWN BUGS

1. The new restarting feature does not save the first time step after restart

UPDATE FROM OCT 17, 2013

1. Two files (check_statistics.cpp, check_statistics2.cpp) were erroneously included in the tarball and have been removed. 2013

2. The Doxyfile in the tarball has been corrected.

FUTURE UPDATES

1. Extra feature will be added to new public release over the coming months.

2. Full version 1.0 release anticipated in August

GENERAL

We have moved a new web address, www.MercuryDPM.org.

A tarball of version 0.9 is available there.

A public svn repository for the code will come online soon.