Building compact discrete domains (tutorial)


your first simulation

This page describes how to build new compact discrete domain with the granoo-cooker tool

Generally a preliminary step consists in building an initial discrete domain. GranOO embeds a specific tool for this task named granoo-cooker. The cooker program uses DEM computation with an improved algorithm for building compact discrete domain with controlled parameters.

In this tutorial you are going to build your first compact domain. First, you need to go into an empty dir.

:prompt: cd /tmp
:prompt: mkdir test
:prompt: cd test

As many granoo programs granoo3-cooker needs an input file to be executed. granoo3-cooker embeds its own input file. To write it in the current directory simply run it with the -w option.

:prompt: granoo3-cooker -w
** Welcome to the granoo-cooker program ! **

Now, the current directory contains the default input file named CookingBook.inp.

├── CookingBook.inp
└── CookingBook_Periodic.inp

Note that the current directory contains also a file named CookingBook_Periodic.inp. This second input file allows for building full 3D periodic compacted domains. However, we will not focus on periodic condition and we will focus only on the the CookingBook.inp. Note that the usage is quite similar between free boundaries and periodic boundaries.

Ok, now, you can run the granoo3-cooker program with the CookingBook.inp input file.

:prompt: granoo3-cooker ./CookingBook.inp
** Welcome to the granoo-cooker program ! **

Wait until the simulation is ending. Now, your directory must look like this.

├── CookingBook.inp
├── CookingBook_Periodic.inp
└── TEST
    ├── backup
    │   └── CookingBook.inp
    ├── CompactDomain.agdd
    ├── CompactDomain.gdd
    └── CompactDomain.lgdd

A new directory named TEST is created. In this directory, the files CompactDomain.* are discrete domain files. Note that granoo uses several kind of files. Each file format have its own advantages and disadvantages. You will learn it in detail later. Now, you can take a look to these files thanks to the granoo3-viewer program.

:prompt: granoo3-viewer ./TEST

You should see something like this. a cubic compact discrete domain

Changing the shape of the discrete domain

To change the discrete domain, you must edit the input file. First, make a copy of the original one and name it my-cookbook.inp.

:prompt: cp CookingBook.inp my-cookbook.inp

Now, you can edit this new input file in order to change the discrete domain shape. The bounding shape of the discrete domain is defined in the input file by the following line

<NEW-SUPPORT-SHAPE Type="Box" DimX="2" DimY="2" DimZ="2" ID="Boundary"/>

Here, you can change the length DimX, DimY and DimZ of the bounding box. You can also change the Type of the shape. You can change it by Sphere, Cylinder, Cone or Polyhedron keywords. For example, the following line gives a sphere of 0.5 radius.

<NEW-SUPPORT-SHAPE Type="Sphere" Radius="0.5" ID="Boundary"/>

With this new settings, you must obtain something like this : a spherical compact discrete domain

If you want a cylinder :

<NEW-SUPPORT-SHAPE Type="Cylinder" Radius="0.5" Length="2." ID="Boundary"/>

Or a cone :

<NEW-SUPPORT-SHAPE Type="Cone" Radius="0.5" Length="2." ID="Boundary"/>

Now, if you want a polyhedron, you need an off file. You can get one from the granoo repository.

:prompt: cp somewhere/3.0/Tool/Cooker/off/ ./

And set the right option for polyhedron :

<NEW-SUPPORT-SHAPE Type="Polyhedron" File="./" ID="Boundary" />

You must obtain something like this. a polyhedral compact discrete domain

Changing the number of discrete element

In order to change the number of discrete element contained, you should find the line

<InitProblem TotalDeNumber="1500" BoundarySupportShapeID="Boundary"/>

and simply change the value of the TotalDeNumber Xml attribute.

PART 2 : advanced Usage

The next part may be useful if you want to get finest control of the cooker algorithm.

Changing the stop filling criterion

The stop filling criterion is set through the StopFill plugin

<StopFill Criterion="Cardinality" Value="6.2"/>

The default value corresponds to a cardinal (or coordination) number of 6.2 that corresponds to a random close packing. Note that you can replace this default value. In addition, you can change the Criterion. Allowed criterion are : Cardinality, Compacity or ElementNumber. You can use these three criteria to stop filling. The following line stop filling when the total discrete element number reach 5,000.

<StopFill Criterion="ElementNumber" Value="5000"/>

The following line stop filling if the compacity reach 0.63

<StopFill Criterion="Compacity" Value="63%"/>

Speed up the cooking algorithm

At the end of the cooker algorithm, discrete domains are highly interpenetrated. So a last step, named Relax, consists in decreasing the interpenetration to a small acceptable value. Note that this step is very time consuming ! Depending on further usage, this step is not mandatory. You can disable it by replacing the Process xml tag by the No value

<Relax Process="No" WallStiffDecreaseCoeff="0.9"/>

Another way to speed-up the computation is to increase the PacketSize number. This value corresponds to the number of discrete element added to the domain in one iteration step. Note that many iteration steps are processed to stabilize domain after adding a packet of n elements.

<Fill RandomRange="25%" MaxLoopTry="10000" PacketSize="10" RepeatWhileFreePlace="Yes"/>

Managing radius distribution

By default, a uniform distribution law is used to randomly choose discrete element radii. The range of this distribution is 25% of the average radius. You can change it by editing the RandomRange xml tag.

<Fill RandomRange="25%" MaxLoopTry="10000" PacketSize="10" RepeatWhileFreePlace="Yes"/>

Managing element pair construction

The last step of the cooker algorithm is dedicated to the element pair construction. An element pair is simply a connection between two discrete elements. It allows to build a discrete element network that may be used later for continuous modeling with GranOO thanks to the beam cohesive model. You can control the value of the average coordination number of this network with the WantedCardinalityValue xml tag. This plugin simply involve a dichotomy process that virtualy increases/decreases the discrete element radii while the WantedCardinalityValue is not reached.

<BUILD-NEIGHBOUR-ELEMENT-PAIR ForceCardinality="Yes" WantedCardinalityValue="6.2" BoundarySet="WallShell"/>

Another strategy to build the network is to involve a Delaunay triangulation tessellation between the center of the discrete elements. So you can replace the BUILD-NEIGHBOUR-ELEMENT-PAIR by <BUILD-DELAUNAY-ELEMENT-PAIR plugin as it follows


The following image shows the difference between the two strategies. Note that the BUILD-DELAUNAY-ELEMENT-PAIR gives higher coordination number close to 13.6 Obtained discrete element network

In conclusion

Many strategy can be used with the cooker algorithm. If you want a complete description of the algorithm you can take a look into this book. granoo book