Discovering examples (tutorial)


your first simulation

This tutorial shows how to run your first example in order to check your installation

Suppose that you install GranOO in a somewhere directory. Now, go to the example directory.

:prompt: cd somewhere/granoo/tags/3.0/Example/

Take a look on the content of this directory, you must see something like

├── 00001_{tutorial}_HELLO-WORLD
├── 00002_{tutorial}_SIMPLE-DOMAIN-BUILDER
├── 00003_{tutorial}_SIMPLE-TENSILE-TEST
├── 00010_{lattice}{dem}{mechanical}{elastic}{beam}_TENSILE-TEST
├── 00011_{lattice}{dem}{mechanical}{brittle}{beam}_TENSILE-TEST
├── 00012_{lattice}{dem}{mechanical}{elastic}{flatbond}_TENSILE-TEST
├── 00013_{lattice}{dem}{mechanical}{brittle}{flatbond}_TENSILE-TEST
├── 00014_{lattice}{dem}{mechanical}{brittle}{beam}_BENDING-TEST
├── 00015_{lattice}{dem}{mechanical}{brittle}{beam}_TORSION-TEST
├── 00016_{lattice}{dem}{mechanical}{brittle}{beam-contactbond}_COMPRESSION-TEST
├── 00020_{lattice}{fem}{mechanical}{elastic}{xbeam}_TENSILE-TEST
├── 00021_{lattice}{fem}{mechanical}{elastic}{xbeam}_HOPKINSON-BAR
├── 00031_{lattice}{dem}{mechanical}{elastic}{beam}_BOUNCING-BALL-v0
├── 00032_{lattice}{dem}{mechanical}{elastic}{beam}_BOUNCING-BALL-v1
├── 00033_{lattice}{dem}{mechanical}{elastic}{flatbond}_BOUNCING-BALL-v1
├── 00034_{lattice}{dem}{mechanical}{elastic}{beam}_BRAZILIAN-TEST
├── 00040_{lattice}{thermo-mechanical}{elastic}{beam}_THERMAL-CONDUCTION
├── 00041_{lattice}{thermo-mechanical}{elastic}{flatbond}_THERMAL-CONDUCTION
├── 00042_{lattice}{electrical}{beam}_ELECTRICAL-CONDUCTION
├── 00043_{lattice}{electro-mechanical}{brittle}{beam}_TORSION-TEST
├── 00044_{lattice}{thermo-electrical}{beam}_JOULE-HEATING
├── 00050_{fem}{mechanical}{elastic}_TENSILE-TEST
├── 00051_{fem}{mechanical}{elastic}_IMPACT
├── 00060_{sph}{mechanical}{fluid}_LIQUID-RAIN
├── 00100_{dem}{mechanical}{granular}_BLUE-WAVE
├── 00101_{dem}{mechanical}{granular}_IMPACT
├── 00102_{dem}{mechanical}{granular}_MIXER
├── 00103_{dem}{mechanical}{granular}_SILO
├── 00104_{dem}{mechanical}{granular}_SPHERICAL-RAIN
├── 00105_{dem}{mechanical}{granular}_MULTISHAPE-RAIN

As you can see, there is a lot of examples. The examples begin by a number (00001 for instance) and are followed by keywords which are inside bracket {xxxx}. It allows to find quickly an example of an expected type. For instance, if you are interested for running a lattice/thermo-mechanical problem, you should be interested to take a look into the 00040 and the 00041 examples. Note also the presence of file. This kind of file are often present in the directory structure for giving useful information to users.

Now, let’s take a look on the 00010_{lattice}{dem}{mechanical}{elastic}{beam}_TENSILE-TEST.

:prompt: cd 00010_{lattice}{dem}{mechanical}{elastic}{beam}_TENSILE-TEST

You can see the following directory structure

├── c++
│   ├── CMakeLists.txt
│   ├── Main.cpp
│   ├── PlugIn_InitSensor.cpp
│   └── PlugIn_InitSensor.hpp
├── gdd
│   ├── cube-10000.agdd
│   └── cube-2000.agdd
├── inp
│   └── beam-elastic-tension.inp
├── py
│   └──

Such a structure is quite similar for all examples. It contains :

  • a c++ folder that contains c++ source files
  • a inp folder that contains GranOO input command files (*.inp)
  • a gdd folder that contains the GranOO domain files (*.gdd, *.agdd, *.lgdd *.off)
  • a py folder that contains python script files mainly for post-process results (*.py).
  • a file which contains some human readable information about the current example

Now, we will build and run the 00104 example. First, you must go into this directory

:prompt: cd somewhere/granoo/tags/3.0/Example/00104_{dem}{mechanical}{granular}_SPHERICAL-RAIN

Now, take a look on the directory structure

├── c++
│   ├── CMakeLists.txt
│   ├── Main.cpp
│   ├── PlugIn_AddDiscreteElement.cpp
│   └── PlugIn_AddDiscreteElement.hpp
├── inp
│   └── rain.inp

You can see again the c++ and the inp folders. Note that there is no py and gdd files because these directories are useless for this example. Now, we will compile the C++ source files. First, you must create an empty directory named build

:prompt: mkdir build

Go inside this directory

:prompt: cd build

Now, we will invoke cmake. You must tell cmake where the CMakeLists.txt file is. The CMake file is located into the c++ source directory.

:prompt: cmake ../c++

Now, You can invoke make for compiling the C++ source files. This process will create the executable file named rain.exe (the name is given by the CMakeLists.txt file). Note that you can use the -j option to speed-up the compilation process (multi-core compilation).

:prompt: make -j

If you take a look on the content of the current build directory, you should see the rain.exe files and some other (useless) files.

Now, go to the root directory of the 00104_{dem}{mechanical}{granular}_SPHERICAL-RAIN example

:prompt: cd ../

And run the rain.exe executable. Note that you must specify to the executable the path of the input file rain.inp.

:prompt: ./build/rain.exe ./inp/rain.inp

and wait for simulation ending…

Post-treating simulation

GranOO automatically creates a folder (in this example, this folder is named TEST) which includes the result files of the simulation. In the present case, these result files are simply GranOO Discrete Domain (*.gdd) files. A gdd file is a snapshot of the simulation at a given iteration number. You can use the granoo3-viewer program to visualize such result files.

:prompt: granoo3-viewer ./TEST

Now, you can visualize the results of your simulation with the granoo3-viewer. This tool is quite powerful but not really user friendly. Here, we will give short explanations about this tool.


The granoo3-viewer is built of six main areas :

  • the warping command which can be used for scaling/unscaling the displacements (useful in case of small strain simulations)
  • the 3D viewer is the main window where you can see your simulation in 3D
  • the Player allows you to visualize a simulation like a movies by loading/unloading into the viewer a list of GranOO domain files
  • the Scale view is able to colorize elements and bonds from values (right-click on this zone to see the list)
  • the Structure viewer which highlights the collections of items and objects which are present in the simulation
  • the Console output which gives some information.

Note that the granoo3-viewer has a lot of keybindings. You can get an overview of all these keybindings by typing the h key !.