Introduction to the Code

Information for users of this application

General Information

This code is written in C++ and does make use of both templates and the object oriented nature of C++. This basic architecture is to have a core kernel code (located in scr) that is general and flexible and then very small driver codes (located in DRIVERS) that pick out the parts of the kernel required to solve specific problems.

Directory Structure

At the top level you will find six main directories
Configuration/
Documentation/
Drivers/
Kernel/
Scripts/
Tools/
XBalls/
In the Documentation directory is located the documentation, i.e. this file. Please note, if you find no documentation there it can be generated by going into the DRIVERS/ direction and typing "make doc". If the documentation becomes corrupt the following will force it to regenerate "make docClean; make doc"

The Kernel direction contains the heart of the code and as a users you should not need to known much about it.

The Drivers directory has a series of subdirectories for example Tutorials/ that each contain a series of demo codes illustrating how to use the main src code. Typing "make fulltest" in the top level of drivers would perform checks on all parts of the code to confirm everything is functioning as intended.

Finally running a code will (in general) generate four files called some_name.data, some_name.xballs, some_name.stat. and some_name.ene. The files with .data extension contain all the position and velocity information for every particles. The .stat extension, contains macroscopic statistics about the problem (the information contained is semi-driver dependent). The .ene file contain some basic bulk information about the system i.e. centre of mass, total kinetic energy, total potential energy, etc. Finally .xballs extension is an a script file that to run to plot for .data output file using xballs.

The Scripts

The directory contains a full scripts that are used by the selftest suite of MercuryDPM. You need worry about the contains of this directory at all; however, for the interested reader

  • fpdiff.py : Calculated the floating point different between number in text file. This is part of the internal working of the selftest routine. This original version of this code was created for the oomph-lib project at the University of Manchester.
  • self_test : Makes calls to fpdiff.py passing the locations of newly create data and existing golddata. If writes error logs if something is different between the new data file and the golddata.

Creating your own DRIVERS directory for your code

It you look in the DRIVERS directory you will see several subdirectories. These subdirectories contain collections of similar codes and, as a new user, you probably want to create a new directory for your own driver codes. To do this copy the TEMPLATE direction to you YOUR_DIR_NAME (if your are a developer and have access to svn repository it is advisable to svn copy to create your new DRIVERS directory)

Variables and Equations

  1. global parameters: for details refer to MD class documentation.
    • time domain \([0,t_{\mbox{max}}]\),
    • spatial domain \([x_{\mbox{min}},x_{\mbox{max}}] \times [y_{\mbox{min}},y_{\mbox{max}}] \times [z_{\mbox{min}},z_{\mbox{max}}]\),
    • number of particles \( N \),
    • number of (regular) walls \( N_{wall}\),
    • number of periodic walls \( N_{wall,periodic}\)
    • gravitational acceleration \( \vec{g}\),
    • Walls are defined by outward unit normal \( \vec{n}_{\mbox{w}}\) and position \( p_{\mbox{w}}\): \( \mbox{w} = \{\vec{x}:\ \vec{n}_{\mbox{w}} \cdot \vec{x} = p_{\mbox{w}} \}\)
  2. global variables: for details refer to MD class documentation.
    • time \( t \),
  3. parameters for particle \( \mbox{P}_i \) : for details refer to CParticle class documentation
    • radius \( a_i \),
    • mass \( m_i = \frac{4}{3} \pi a_i^3 \),
    • inertia \( I_i = \frac{2}{5} m_i \),
    • normal spring constant \( k \) (globally set)
    • normal dissipation coefficient \( \gamma \),
    • tangential dissipation coefficient \( \gamma^t \),
    • Coulomb friction coefficient \( \mu \)
  4. variables for particle \( \mbox{P}_i \): for details refer to CParticle class documentation
    • position \( \vec{r}_i(t)\),
    • velocity \( \vec{v}_i(t)\),
    • angle \( \vec{\alpha}_i(t)\),
    • angular velocity \( \vec{\omega}_i(t)\).
  5. initial values:
    • position \( \vec{r}_i(0) = \vec{r}_i^0 \),
    • velocity \( \vec{v}_i(0) = \vec{v}_i^0 \),
    • angle \( \vec{\alpha}_i(0)=\vec{0} \),
    • angular velocity \( \vec{\omega}_i(0) = \vec{\omega}_i^0 \).
  6. variables for each collision between particles \(\mbox{P}_i\) and \(\mbox{P}_j\):
    • relative position \( \vec{r}_{ij} = \vec{r}_i - \vec{r}_j \),
    • normal direction \( \vec{n}_{ij} = \frac{\vec{r}_{ij}}{\|\vec{r}_{ij}\|}\),
    • overlap \( \delta_{ij} = (\vec{a}_i - \vec{a}_j) - \vec{r}_{ij}\),
    • relative velocity \( \vec{v}_{ij}=\vec{v}_i-\vec{v}_j + (a_i-\frac{\delta_{ij}}{2}) \vec{n}_{ij} \times \vec{\omega}_i + (a_j-\frac{\delta_{ij}}{2}) \vec{n}_{ij} \times \vec{\omega}_j \)
    • relative normal velocity \( v_{ij}^n = - \vec{v}_{ij} \cdot \vec{n}_{ij}$ ($= \dot{\delta}_{ij} \)),
    • normal force (spring-dashpot model) \( f_{ij}^n = k \delta_{ij} + \gamma v_{ij}^n \),
    • relative tangential velocity \( \vec{v}_{ij}^t = \vec{v}_{ij} - v_{ij}^n \vec{n}_{ij} \),
    • tangential direction \( \vec{t}_{ij} = \frac{\vec{v}_{ij}^t}{\|\vec{v}_{ij}^t\|}\),
    • tangential force (sliding friction model) \( f_{ij}^t = - \max( \gamma^t v_{ij}^t,\ \mu f_{ij}^n)\),
    • collision force \( \vec{f}_{ij} = f_{ij}^n \vec{n}_{ij} + f_{ij}^t \vec{t}_{ij},\ \mbox{if } \delta_{ij}\leq 0,\ 0\ \mbox{else} \),
  7. Variables for collisions between particle \( \mbox{P}_i \) and wall \( \mbox{w}_j \):
    • normal direction \( \vec{n}_{ij}^{wall} = - \vec{n}_{\mbox{w}_j}\),
    • overlap \( \delta_{ij}^{wall} = \vec{a}_i - (p_{\mbox{w}_j} - n_{\mbox{w}_j} \cdot x)\),
    • relative velocity \( \vec{v}_{ij}^{wall}=\vec{v}_i + (a_i-\frac{\delta_{ij}}{2}) \vec{n}_{ij} \times \vec{\omega}_i \),
    • all else is the same as for particle collisions
  8. Force and torque calculations

    \[ \vec{f}_i = m_i \vec{g} + \sum_{j=1}^N \vec{f}_{ij} + \sum_{j=1}^{N_{wall}} \vec{f}_{ij}^{wall}, \]

    \[ \vec{t}_i = \sum_{j=1}^N (a_i-\frac{\delta_{ij}}{2}) \vec{n}_{ij} \times \vec{f}_{ij} + \sum_{j=1}^{N_{wall}} (a_i-\frac{\delta_{ij}^{wall}}{2}) \vec{n}_{ij}^{wall} \times \vec{f}_{ij}^{wall}. \]

  9. Time integration

    \[ \vec{\dot{r}}_i = \vec{v}_i,\ m_i \vec{\dot{v}}_i = \vec{f}_i,\quad \vec{\dot{\alpha}}_i = \vec{\omega}_i,\ I_i \vec{\dot{\omega}}_i = \vec{t}_i \]

Implementation

Time Stepping

Verlet integration for \( \vec{r}_i \), forward Euler for \( \vec{\alpha}_i \), \( \vec{\omega}_i \), fixed time step \( dt \).