Building compact discrete domains (tutorial)

Tutorials

basic
your first simulation
advanced

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.

First, you need to go into an empty dir.

$ cd /tmp
$ mkdir test
$ cd test

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

$ granoo-cooker -w
** Welcome to the granoo-cooker program ! **
...

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

.
└── CookingBook.inp

You can run the granoo-cooker program with this input file.

$ granoo-cooker ./CookingBook.inp
** Welcome to the granoo-cooker program ! **
...

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

.
├── CookingBook.inp
└── TEST
    ├── Back_up
    ├── CompactDomain.agdd
    ├── CompactDomain.gdd
    ├── CompactDomain.lgdd
    └── info.out

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 granoo-viewer program.

$ granoo-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.

$ cp CookingBook.inp my-cookbook.inp

Now, you can edit this 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

<PlugIn Id="_NewSupportShape" 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.

<PlugIn Id="_NewSupportShape" 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 :

<PlugIn Id="_NewSupportShape" Type="Cylinder" Radius="0.5" Length="2." ID="Boundary"/>

Or a cone :

<PlugIn Id="_NewSupportShape" 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.

$ cp somewhere/2.0/Tool/Cooker/off/cube-and-cylinder.off ./

And set the right option for polyhedron :

<PlugIn Id="_NewSupportShape" Type="Polyhedron" File="./cube-and-cylinder.off" 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

<PlugIn Id="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

<PlugIn Id="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.

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

The following line stop filling if the compacity reach 0.63

<PlugIn Id="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

<PlugIn Id="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.

<PlugIn Id="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.

<PlugIn Id="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.

<PlugIn Id="_BuildNeighbourElementPair" 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 _BuildNeighbourElementPair by _BuildDelaunayElementPair plugin as it follows

<PlugIn Id="_BuildDelaunayElementPair"/>

The following image shows the difference between the two strategies. Note that the BuildDelaunayElementPair 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