Running examples (tutorial)

Tutorials

basic
your first simulation
advanced

This page describes how to run the provided examples

Suppose that you install GranOO in a somewhere directory. If you go inside the granoo distribution, you will see the following file structure

somewhere/granoo/tags/2.0/
├── Binding   # Python bindings here
├── CMake     # directory where cmake files are installed
├── Example   # the example directory 
├── Lib       # the core of GranOO
├── License
├── readme.md # some useful info are here
└── Tool      # directory that contain sources of the executable tools

Now, go to the Example directory

somewhere/granoo/tags/2.0/Example
├── Continuous
├── Electrical
├── Granular
├── Misc
├── readme.md # some useful info here
├── Sandbox
├── Sph
├── Test
├── Tool
└── Tutorial

You can observe that examples are organized by category. Be careful, some examples are not up-to-date. To get the list of up-to-date examples, you can take a look in the readme.md file. Now, we are going to run the Rain example under the Granular category.

$ cd Granular/Rain/

You will see the following data structure

.
├── CMakeLists.txt                # cmake file for compilation process 
├── Main.cpp                      # C++ source file
├── PlugIn_AddDiscreteElement.cpp # C++ source file
├── PlugIn_AddDiscreteElement.hpp # C++ source file
├── Rain.inp                      # GranOO input file 
└── readme.md                     # some useful info here

You can observe that only source files are present. You must compile them to run the example. The compilation process is assisted by cmake. cmake is a cross-platform compilation tool for C++ programs. A good way to use cmake is to invoke cmake in a temporary empty directory. Generally, this temporary directory is named build.

$ mkdir build

Go inside this new dir

$ cd build

You can check if you are in the right directory with the pwd command

$ pwd
somewhere/granoo/tags/2.0/Example/Granular/Rain/build

Now, you must invoke cmake. cmake needs to locate the path where the CMakeLists.txt file is.

$ cmake ../
-- The C compiler identification is GNU 5.4.0
-- The CXX compiler identification is GNU 5.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
...

Now, you must invoke the make command (or nmake for windows user) to start the compilation process.

$ make 
Scanning dependencies of target rain.exe
[ 33%] Building CXX object CMakeFiles/rain.exe.dir/PlugIn_AddDiscreteElement.cpp.o
...

If you take a look at the current directory structure, you will see

.
├── CMakeCache.txt
├── CMakeFiles
├── cmake_install.cmake
├── Makefile
└── rain.exe # here is the executable file !

Now, we want to run the example. You must return to the upper directory.

cd ../

Run the rain.exe executable file. Note that granoo executable generally needs an input *.inp file. The input file are very important for understanding granoo. You will learn it in detail in further steps of this tutorial.

$ ./build/rain.exe ./Rain.inp
                                
  \    /_ | _ _ ._ _  _  _|_ _ 
   \/\/(/_|(_(_)| | |(/_  |_(_)
                                
  _|_|_|       	       	       	       	  _|_| 	    _|_|   
_|     	  _|  _|_|    _|_|_|  _|_|_|   	_|    _|  _|   	_| 
_|  _|_|  _|_| 	    _| 	  _|  _|    _| 	_|    _|  _|   	_| 
_|    _|  _|   	    _| 	  _|  _|    _| 	_|    _|  _|   	_| 
  _|_|_|  _|   	      _|_|_|  _|    _| 	  _|_| 	    _|_|   

Version 2.0.0
....

Now, if you look at the current directory structure. You must see a new directory named Results. This directory simply contains the result files of the simulation. In this case, result files are simply Granoo Discrete Domain *.gdd files. A gdd file is a snapshot of the simulation at a given iteration number.

GranOO embeds a custom 3D viewer able to read gdd files. The viewer is named granoo-viewer. If your install is ok, you can invoke this tool from anywhere as it follows

$ granoo-viewer ./Results
GddParser, find 101 *.gdd files in "./Results/" directory
....

You should see something like this. granoo-viewer

You can push the play button and observe your simulation.

You can repeat these tutorial steps for any up-to-date example. For some examples, note that input files may be located in a inp directory.