Plugins and input files (tutorial)


your first simulation

This page describes the usage of plugin

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 granoo executable with the -d option as it follows.

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

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

$ granoo -d -f PlugIn -c 
    + [PlugIn] 
      _ApplyTorque, _ClearLoad, _ConvertElementPairToBeam, _ConductHeat, _ConductHeatWithFS, _SphUpdateLocalDensity, _Convert, _SetLinearVelocity, _EnergyBalance, _UpdateVoronoiDomain, _ApplyBrittleFracture, _DeleteUnbondedElement, _RecordExpression, _WriteSensorData, _ReadDomain, _IntegrateAcceleration, _BuildNeighbourElementPair, _NewGround, _ThermalExpansion, _SetOverallMass, _ImposeOrientation, _ApplyBondLoad, _SphUpdatePressure, _ConvertElementPairToPlasticBeam, _NewTimeStep, _BuildDelaunayElementPair, _NewExpression, _SaveDomain, _ConvertBondToElementPair, _NewVariable, _SetDensity, _InitElectricalProperties, _DisplayInfo, _Translate, _NewVector, _InitThermalProperties, _ConductCurrent, _DiscreteDomainToVoronoiDomain, _ComputeVirialStress, _ManageCollision, _NewPoint, _ApplyGravity, _SetOfOperator, _SetElasticProperty, _AddVoltageSource, _ExportToPVD, _SphApplyPressureForce, _ReleaseElPowerAsHeat, _Rotate, _SetContinuousDensity, _Delete, _ImposeRotation, _UpdateSupportShape, _NewSupportShape, _NewQuaternion, _ImposeDisplacement, _BuildGridDomain, _MonitorItemNumber, _PutInContact, _NewFrame, _NewTool, _ConvertElementPairToSpring, _ImposeTemperature, _ComputeOptimalTimeStep, _SphApplyViscousForce, _SphClearInteraction, _Check, _SphUpdateInteraction, _ApplyForce, BuildFacet, _ComputeBondStress

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 prefixed by an underscore. In the following example, only the AddElement plugin is a custom one.

    <!-- Make the rain -->
    <PlugIn Id="AddElement" xMaxPos=".5" yPos="0." zMaxPos=".5" rMax="0.02" 
	    MaxNumber="2000" IterLoop="100"/> 

    <PlugIn Id="_ClearLoad"/>
    <PlugIn Id="_ApplyGravity" X="0." Y="-10." Z="0."/>

    <!-- Manage collision between discrete element and support shape -->
    <PlugIn Id="_ManageCollision" .../>
    <!-- Manage collision between discrete elements -->
    <PlugIn Id="_ManageCollision" .../>

    <PlugIn Id="_IntegrateAcceleration" Linear="Yes" Angular="Yes"/>

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 _SaveDomain plugin (that stores the current state of simulation in files) just each n iteration. In such case, you can use the common IterLoop option.

For example, the following line will trigger the _SaveDomain plugin each 50 iterations.

 <PlugIn Id="_SaveDomain" IterLoop="50" />

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

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