Rockable - Format of configuration files

The "conf-files" are the files that hold the whole configuration at a given time. They are used (1) for defining the initial configuration and parameters of a simulation, (2) for runing some preprocessing commands, or (3) for saving the history of a simulation. The keywords are defined in the following.

Header

A conf-file always starts with the header: Rockable dd-mm-yyyy (e.g., Rockable 20-02-2017).
Each time a noticeable change is made in the format, the date of this change is also changed in the header of the file. It has to be understood as the version of the format.

Timing

• t (double)value
  Current time

• tmax (double)value
  Maximum time (at the end of a simulation)

• dt (double)value
  Time step increments

Neighbor list (NL)

• interVerlet (double)value
  Elapsed time between each update of the neighbor list

• DVerlet (double)value
  Distance to define if two sphero-polyhedra are neighbors

• dVerlet (double)value
  Distance to define if two sub-elements (sphere for vertices, tubes for edges, or thick 3D polygons for faces), between two sphero-polyhedra, are neighbors

• dynamicUpdateNL 0/1
  If the dynamic update of the neighbor list is activated (set to 1), then an update will be made if the maximum distance of a body, since the last update, becomes larger than dispUpdateNL. An update will also be made when the maximum rotation becomes larger than angleUpdateNL

  Notice that, when the dynamic Update is enabled, the periodic updates are also still enabled (it can actually not be disabled)

• dispUpdateNL (double)distance
  The maximum distance that any body is allowed to move without updating the NL

• angleUpdateNL (double)angleDegree
  The maximum angle that any body is allowed to rotate without updating the NL

Configuration backups

• interConf (double)value
  Elapsed time between each backup of the configuration

• iconf (double)value
  Number of the current configuration

Options

• AddOrRemoveInteractions (string)Option
  where Option can be bruteForce or OBBtree

• UpdateNLStrategy (string)Option
  where Option can be bruteForce or linkCells

Library of particle shapes

• shapeFile (string)path
  Paths of the file that defines the shapes used. The format to define a shape is explained here

Particles

• density (int)groupNumber (double)density Set the density of all particles belonging to the group groupNumber

• Particles (int)numberOfParticles
  REPEAT FOR EACH PARTICLE [
  (string)shapeName (int)group (int)cluster (double)homothety (vec3r)position (vec3r)velocity (vec3r)acceleration (quat)angularPosition (vec3r)angularVelocity (vec3r)angularAcceleration
  ]

Note that different numbers are associated with a given body:

• the body number, which is its position in the con-file (first is 0)
• the group-number, used to set interaction parameters (try to set smallest possible values because a table group-number $\times$ group-number is allocated)
• the cluster-number, used to state whether a glued interface is "inner" (i.e., between bodies belonging to the same cluster) or "outer" (in-between the clusters)

Interactions

• Interactions (int)numberOfInteractions
  • REPEAT FOR EACH INTERACTION [ (int)i (int)j (int)type (int)isub (int)jsub (vec3r)n (double)dn (vec3r)position (vec3r)relativeVelocity (double)fn (vec3r)ft (vec3r)mom (double)viscousDampingValue
  • ]

• type is either 0 for vertex-vertex, 1 for vertex-edge, 2 for vertex-face, or 3 for edge-edge
• relativeVelocity is the velocity of body j relative to body i at the contact point
• n is oriented from j to i

Interfaces

• Interfaces (int)numberOfInterfaces
  • REPEAT FOR EACH INTERFACE [ (int)i (int)j (int)nbBonds
    • IF (ParamsInInterfaces is not 0) [ (double)kn (double)kt (double)kr (double)fn0 (double)ft0 (double)mom0 (double)power ]
    • REPEAT FOR EACH BOND [ (int)type (int)isub (int)jsub ]
  • ]

Force laws

• forceLaw (string)Name
  Select a model for the computation of forces. The detailed description of the available laws is here.
  Quick overview for possible Name:

  1. Avalanches:

     • Normal force: $\Delta f_n = k_n \Delta h_n$ for loading (compression), and $f_n = e_n^2 k_n h_n$ for unloading;
     • Coulomb friction force: $\Delta \mathbf{f}_t = k_t \mathbf{v}_t^{ij} \Delta t$ is an elastic force increment with intensity of $\mathbf{f}_t$ limited at $\pm \mu f_n$;
     • Moment resistance: $\Delta \mathbf{m} = k_r \mathbf{\omega}^{ij} \Delta t$ is an elastic moment increment with intensity of $\mathbf{m}$ limited at $\pm \mu_r R f_n$; $R$ is the minimum distance between the contact point and the current rotation axis passing by the mass centre of the moving particle

  2. StickedLinks:

     • Contacts:
       • Normal force: $f_n = k_n h_n + \nu_n \dot{h}_n$
         with $\nu_n = \frac{-2\log e_n}{\sqrt{\log^2 e_n + \pi^2} } \sqrt{k_n m_{eff}}$ (the input parameter is $e_n^2$);
       • Coulomb friction force: $\Delta \mathbf{f}_t = k_t \vec{v}_t^{ij} \Delta t$ is an elastic force increment with intensity of $\mathbf{f}_t$ limited at $\pm \mu f_n$;
       • Moment resistance: $\Delta \mathbf{m} = k_r \mathbf{\omega}^{ij} \Delta t$ is an elastic moment increment with intensity of $\mathbf{m}$ limited at $\pm \mu_r f_n$ (be careful, the unit of $\mu_r$ is a length);
     • Glued-bonds:
       • Normal force: $f_n = k_n h_n + \nu_n \dot{h}_n$
         like in the case of contact
       • Tangential (incremental) force: $\Delta \mathbf{f}_t = k_t \mathbf{v}_t^{ij} \Delta t$
       • Yield-surface: rupture if $\frac{f_n}{f_n^0} + \left (\frac{|f_t|}{f_t^0} \right )^\alpha - 1 > 0$. The interaction switch then irreversibly to a contact.

By default (if not specified), the model used is Avalanches.

Parameters of force laws

• <PARAMETER_NAME> (int)group1 (int)group2 (double)value
  where <PARAMETER_NAME> is the parameter to be set (see below)

  • For contacts with friction, we can use knContact, en2Contact, ktContact, muContact, krContact and murContact.
  • For bonds inside the same cluster, we can use knInnerBond, ktInnerBond, fn0InnerBond, ft0InnerBondand en2InnerBond.
  • For bonds between the clusters, we can use knOuterBond, ,ktOuterBond, krOuterBond, fn0OuterBond, ft0OuterBond, mom0OuterBond and en2OuterBond.

• ParamsInInterfaces 0/1
  it says whether the parameters are embedded in the interfaces or not.

Loading

nDriven (int)value
The value is the number of bodies, at the beginning of the list, that nDriven first bodies are fixed (all velocities imposed to zero), but if we want to set a velocity or a force/moment, some commands have to be added in a file named drivingSystem.txt.

File drivingSystem.txt

• Control (string)mode (int)bodyNumber (double)value
  where mode is either _x_Vel_, _y_Vel_, _z_Vel_, _xrot_Vel_, _yrot_Vel_, _zrot_Vel_, _x_For_, _y_For_, _z_For_, _xrot_Mom_, _yrot_Mom_, or _zrot_Mom_

This is a simple solution to impose a constant velocity or force/moment to a body. Notice that bodyNumber needs to be lower than nDriven. Also, there can be only one Servo that will act on the degrees of freedom of the driven particles.

• Servo (string)Name PARAMETERS...

Name (with the corresponding PARAMETERS...) can be:

• ramp (string)mode (int)bodyNumber (double)valueIni (double)valueEnd (double)TimeIni (double)TimeEnd
  It makes it possible to impose a time-controlled ramp of velocity or force (depending on mode) to the body number bodyNumber. Before TimeIni, the value is valueIni and after TimeEnd the value is maintained at valueEnd. In-between these two times, the ramp is linear.

• shaker (int)bodyNumber (vec3r)direction (double)Amplitude (double)Frequency
  It will impose sinusoidal oscillations of the body bodyNumber, in a given direction, Amplitude (half the total displacement), and Frequency (cycles/second or Hertz).

• tritriIsostaticCompression (int)idXmin (int)idXmax (int)idYmin (int)idYmax (int)idZmin (int)idZmax (double)pressure 6 plans need to be set as driven particles, and their numbers are set with the idSomething parameters. The parameter pressure is positive for a compression.

• tritriBiaxialCompression (int)idXmin (int)idXmax (int)idYmin (int)idYmax (int)idZmin (int)idZmax (double)pressure (double)velocity 6 plans need to be set as driven particles, and their numbers are set with the idSomething parameters. The parameters pressure and velocity are positive for a compression.

Processing commands

These commands can be used at the end of an input conf-file. They will not be saved in the conf-files generated during a computation.

• stickVerticesInClusters (double)Epsilon
  This command will add glued interfaces between bodies having the same cluster identifier. Only bonds between vertices (spheres) are added when the distance is less than Epsilon.

• stickClusters (double)Epsilon
  This command will add glued interfaces between bodies having different cluster identifiers. Bonds are added when the distance is less than Epsilon.

• randomlyOrientedVelocities (double)velocity

• randomlyOrientedVelocitiesClusters (double)velocity (int)option

• copyParamsToInterfaces (string)isInnerStr

• setVariableStickParams (string)paramName (string)isInnerStr (double)lambda (double)m (int)timeSeeded

Data Extractors

• DataExtractor (string)ExtractorName PARAMETERS...
  The list of PARAMETERS... depends on the ExtractorName. They are listed below.

Actually, it is advised to rather set the DataExtractors in a separated file named dataExtractors.txt.
In this case, the syntax is similar but without the keyword DataExtractor before each extractor.

ExtractorName (with the corresponding PARAMETERS...) can be:

• TrackBody (int)bodyNumber (string)filename (int)stepPeriodRecord
  This data-extractor will create a file named filename holding the data (kinetics and force/moment) of the body bodyNumber. It is organized that way:

Notice that, when a force is imposed on a body, this force is subtracted.

• ClusterAABB (int)clusterID (string)filename (int)stepPeriodRecord
  It will create a file named filename holding the the Axis Aligned Bounding Box (AABB) of the bodies having with cluster = clusterID. It is organized that way: