A computation is described through input *.inp files. GranOO uses the PlugIn concept to describe and manage a computation through input files. Each plugin is dedicated to one single task. This design allows for user to build a simulation such as a Lego structure where plugin are such basic bricks. Users are able to put plugin in any place and any order for customizing their simulations.

Listing of all standard plugin

In the GranOO terminology, a standard plugin is a plugin that comes from the GranOO distribution. You probably want to know which plugin exists. A first solution is to use the online listing available here.

Another solution is to use the self documentation of GranOO. To get the full list of available standard plugins, you can run granoo3 executable with the -d option as it follows.

:prompt: granoo3 -d
# Table of content 
+  [`[DEM::Tool] : Box`](#demtool-box)
+  [`[DEM::Tool] : Sphere`](#demtool-sphere)
...

The given output displays the documentation in the popular markdown format. To display it in a more comfortable format, you can use pandoc to convert it in html format.

:prompt: granoo3 -d | pandoc > doc.html

Now you can use any web browser to open the generated doc.html file that contains plugin documentation. Note that the online version of the documentation was auto-generated with this process.

GranOO embeds some useful tools that help you for filtering and sort documentation. For example, the following line displays the full list of plugin in a single condensed line.

:prompt: granoo3 -d -f PlugIn -c 
    + [PlugIn] 
  ADD-VOLTAGE-SOURCE, APPLY-ANGULAR-VELOCITY, APPLY-BOND-LOAD, APPLY-BOND-SURFACE-IT, APPLY-DENSITY, APPLY-DISPLACEMENT, APPLY-FE-DISPLACEMENT, APPLY-FE-LOAD, APPLY-FE-MATERIAL, APPLY-FORCE, APPLY-FRACTURE, APPLY-GRAVITY, APPLY-LINEAR-VELOCITY, APPLY-ORIENTATION, APPLY-PERIODIC-CONDITION, APPLY-ROTATION, APPLY-TEMPERATURE, APPLY-THERMAL-EXPANSION, APPLY-TORQUE, APPLY-TRANSLATION, BOUNDARY-BOX, BUILD-DELAUNAY-ELEMENT-PAIR, BUILD-ELEMENT-PAIR-SET-FROM-ELEMENT-SET, BUILD-GRID-DOMAIN, BUILD-NEIGHBOUR-ELEMENT-PAIR, BUILD-VORONOI-DOMAIN, CHECK, CLEAR-LOAD, COMPUTE-BOND-SURFACE-IT, COMPUTE-OPTIMAL-TIME-STEP, COMPUTE-VOLUME-FRACTION, CONDUCT-CURRENT, CONDUCT-HEAT, CONDUCT-HEAT-WITH-FS, CONVERT, CONVERT-BOND-TO-ELEMENT-PAIR, CONVERT-ELEMENT-PAIR-TO-BEAM, CONVERT-ELEMENT-PAIR-TO-FLAT-BOND, CONVERT-ELEMENT-PAIR-TO-HERTZSPRING, CONVERT-ELEMENT-PAIR-TO-KRATOS-FLAT-BOND, CONVERT-ELEMENT-PAIR-TO-PLASTIC-BEAM, CONVERT-ELEMENT-PAIR-TO-PLASTIC-BEAM-IT, CONVERT-ELEMENT-PAIR-TO-SPRING, CONVERT-ELEMENT-PAIR-TO-XBEAM, DEFORM-PERIODIC-BOX, DELETE, DELETE-INCONSISTENT-VORONOI-BOND, DELETE-UNBONDED-ELEMENT, DISPLAY-INFO, ENERGY-BALANCE, EXPORT-TO-PVD, INIT-ELECTRICAL-PROPERTIES, INIT-PERIODIC-BOND, INIT-THERMAL-PROPERTIES, INTEGRATE-ACCELERATION, INTERACTION-HISTOGRAM, MANAGE-COLLISION, MONITOR-EXPRESSION, MONITOR-ITEM-NUMBER, MONITOR-STRAIN, NEW-EXPRESSION, NEW-FRAME, NEW-GROUND, NEW-MATERIAL, NEW-MATERIAL-COUPLE, NEW-POINT, NEW-QUATERNION, NEW-SUPPORT-SHAPE, NEW-TIME-STEP, NEW-TOOL, NEW-VARIABLE, NEW-VECTOR, PUT-IN-CONTACT, READ-DOMAIN, RELEASE-EL-POWER-AS-HEAT, SAVE-DOMAIN, SETOF-OPERATOR, SOLVER-CD, SPH-APPLY-PRESSURE-FORCE, SPH-APPLY-VISCOUS-FORCE, SPH-CLEAR-INTERACTION, SPH-UPDATE-INTERACTION, SPH-UPDATE-LOCAL-DENSITY, SPH-UPDATE-PRESSURE, STATIC-SOLVE, STEP, UPDATE-BOND-STRAIN, UPDATE-BOND-STRESS, UPDATE-BOND-VECTOR-STRESS, UPDATE-STRAIN, UPDATE-STRESS, UPDATE-SUPPORT-SHAPE, UPDATE-VORONOI-DOMAIN, VELOCITY-VERLET-STEP1, VELOCITY-VERLET-STEP2, WRITE-SENSOR-DATA

Standard plugin VS custom plugin

If you don’t find a standard plugin that matches your expectation, you probably want to build your own custom plugin. Some tools facilitate this process. It will be described in detail later in this tutorial. Note that writing plugins requires C++ or Python basic knowledge and a good understanding of the GranOO API.

In order to recognize standard plugins from custom plugins, standard plugins are written in capital letters whereas custom plugins are written in lowercase. In the following example (which is extracted from the 00104_{dem}{mechanical}{granular}_SPHERICAL-RAIN example), the AddElement plugin is a custom one whereas the APPLY-GRAVITY is a standard one.

...
    <AddElement xMaxPos=".4" yPos="0." zMaxPos=".4" rMax="0.02" MaxNumber="2000" EveryIter="100"/>
    <APPLY-GRAVITY X="0." Y="-10." Z="0."/>
...

Common options for plugins

A common requirement for plugins is to launch them only if a given condition is reached. For example, you can choose to trigger the SAVE-DOMAIN plugin (that stores the current state of simulation in files) just each n iteration. In such case, you can use the common EveryIter option.

For example, the following line will trigger the SAVE-DOMAIN plugin each 50 iterations.

 <SAVE-DOMAIN EveryIter="50" />

A more advanced common option is the TriggerIf. This option accepts symbolic expressions. For example, the following line will trigger the SAVE-DOMAIN each 200 iterations if the current iteration number is higher than 1,000.

 <SAVE-DOMAIN TriggerIf="(it > 1000) and (it%200 == 0)" />

Note that you can use in symbolic expressions the following symbols :

• it that corresponds to the current iteration number,
• t that corresponds to the current simulated time,
• dt that corresponds to the current time step.

Practical work

Run the default 00104_{dem}{mechanical}{granular}_SPHERICAL-RAIN example and modify the input file in order to :

• change the box size of the container (plugin NEW-GROUND)
• change the gravity direction (plugin APPLY-GRAVITY)
• trigger a domain saving each 100 iteration ((plugin SAVE-DOMAIN)

And see the results with the granoo3-viewer tool. A more advanced modification is to change the shape of the container (plugin NEW-GROUND)… good luck !