Quick-start guid

What is Rockable?

Rockable is a DEM code written in C++11 (tend to become C++17). The two main specificities of the code are (i) to hold sphero-polyhedral shapes, (ii) to manage breakable interfaces. This technique has been developed in another code named DEMbox which was designed to do more things, with a higher degree of abstraction. Also, it is designed and developed for an academic usage.

Compilation with cmake

The preferred method for building the project is by using CMake, a widely-used build system. Follow these steps to compile the project:

  1. Create a new directory called build (you can choose any name) in the project’s root directory:

mkdir build

  1. Navigate into the build directory:

cd build

  1. Run CMake configuration command from within the build directory. This command sets up the build environment and generates the necessary build files based on the CMake configuration files present in the project:

cmake ..

If you wish to disable the compilation of the see application, you can pass the -DROCKABLE_COMPILE_SEE=OFF option to CMake during the configuration step:

cmake .. -DROCKABLE_COMPILE_SEE=OFF

To enable the installation with profiling tools, you can use the -DROCKABLE_ENABLE_PROFILING=ON option during the CMake configuration step:

cmake .. -DROCKABLE_ENABLE_PROFILING=ON

These options will set up the CMake build system accordingly to either include or exclude the see feature and enable or disable the profiling tools during the build process. After configuring CMake with the desired options, you can proceed with the usual build process (e.g., using make or your preferred build command) to compile the project with the chosen settings.

All the options are listed below:

  • ROCKABLE_USE_FT_CORR (default is OFF): add objectivity correction to tangent forces.

  • ROCKABLE_ENABLE_PROFILING (default is ON): enable time profiling.

  • ROCKABLE_ENABLE_BOUNDARY (default is OFF): enable the special boundaries like Ball or Cylinder.

  • ROCKABLE_ENABLE_SOFT_PARTICLES` (default is OFF): enable straining of particles.

  • ROCKABLE_ENABLE_PERIODIC (default is OFF): enable full periodic boundary conditions.

  • ROCKABLE_COMPILE_SEE (default is ON): compile the application to visualize the conf-files.

  • ROCKABLE_COMPILE_SEE3 (default is OFF): compile the application to edit graphically the input files.

Compilation with Makefile

The compilation is managed with a classic Makefile. Some options can be set at compile time: FT_CORR, and COMPONENTWISE_NUM_DAMPING. To disable an option it is advised to rename it by adding a letter ‘n’ at the beginning.

  • FT_CORR: with this option, the tangential force is corrected to account for the rotation of the local framework

  • COMPONENTWISE_NUM_DAMPING: it activates the component-wise numerical damping (so called Cundall damping)

  • ROCKABLE_ENABLE_PROFILING: enable the use of MATools for performance profiling

Depending on the computer you use (Apple or PC with Linux) CXX, CXXFLAGS and GLLINK have to be set in the right section for setting, respectively, the compiler name, the options of compilation, and the options of linkage with openGL. The rest of the file should normally not be changed. Finally, the applications run and see can be compiled with the following command:

make

It is sometimes necessary to remove all object files (.o) together with the compiled applications. this can be made with:

make clean

Running a simulation

To run a simulation, a configuration file has to be written. The format of such a file is described in the section Syntax for conf-files. We show here a simple example simulating a sphere bouncing on a plan.

input.txt
Rockable 20-02-2017
t 0
tmax 0.06
dt 1e-6
interVerlet 0.01
interConf 0.01

DVerlet 0.08
dVerlet 0.02
density 0 2700
density 1 2700

forceLaw Avalanches
knContact 0 1 1e6
en2Contact 0 1 0.05
ktContact 0 1 1e7
muContact 0 1 0.4
krContact 0 1 1e7
murContact 0 1 0.0

iconf 0
nDriven 1
shapeFile SphereAndPlan.shp
Particles 2
Plan 0 0 1 0 -0.05 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0
Sphere 1 0 1 -0.5 0.5 0 3.69 -3.29 0 0 0 0 0.707 0 0.707 0 0 0 -50.52 0 0 0

The shape-file as described in the section Syntax for shape-files is a file named SphereAndPlan.shp with the following content:

SphereAndPlan.sph
<
name Plan
radius 0.05
preCompDone y
nv 4
2 0 0.5
2 0 -0.5
-2 0 -0.5
-2 0 0.5
ne 4
0 1
1 2
2 3
3 0
nf 1
4 0 1 2 3
obb.extent 2.0 0.05 0.5
obb.e1 1 0 0
obb.e2 0 1 0
obb.e3 0 0 1
obb.center 0 0 0
volume 1
I/m 1 1 1
>

<
name Sphere
radius 0.08
preCompDone y
nv 1
0 0 0
ne 0
nf 0
obb.extent 1 1 1
obb.e1 1 0 0
obb.e2 0 1 0
obb.e3 0 0 1
obb.center 0 0 0
volume 0.004021
I/m 0.00493333 0.00493333 0.0032
>

Supposing that the executable named rockable stands in the same folder as the configuration and shape files, the simulation is launched that way:

./rockable bouncingSphere.txt

If the executable has been compiled with openMP abilities, the number of threads can be set with the option -j, for example:

./rockable bouncingSphere.txt -j 24

In this particular example, it is clearly not a good idea to use so much threads because the number of particles is to small and the computation duration will be worst.

The verbosity of logs is set with a number that way:

./rockable bouncingSphere.txt -v 6

Highest number corresponds highest verbosity: trace = 6, debug = 5, info = 4, warn = 3, err = 2, critical = 1, off = 0

If the files produced by a computation (conf*, kineticEnergy.txt, perf.txt, and staticBalance.txt) have to be deleted, rockable can do the job.

./rockable -c

Visualising the simulations

Normally, the application see has been built as the same time than rockable. The application see needs freeglut, the simplest way to use openMP and display 3D things.