Format of configuration files (conf-file)

The conf-files are the files that hold the whole configuration at a given time. They are used for the following purposes:

  1. Defining the initial configuration and parameters of a simulation.

  2. Running some preprocessing commands.

  3. Saving periodically the history of a simulation.

Keywords

The conf-files contain specific keywords that define various aspects of the configuration. These keywords are used throughout the file to specify different settings and parameters.

Usage

These conf-files are essential for setting up and managing simulations. They are used for:

  1. Initializing the simulation with specific configurations and parameters.

  2. Executing preprocessing commands to prepare the simulation environment.

  3. Periodically saving simulation history to track its progress over time.

The format of the conf-files allows users to define and control various aspects of the simulation accurately.

Tip

It is crucial to maintain consistency in the format of conf-files and keep track of changes made to the header date whenever modifications are introduced. This practice ensures clarity and compatibility between different versions of the configuration files and the codebase.

Timing

  • t (double) value

    Current time.

  • tmax (double) value

    Maximum time. The simulation will end when time reaches tmax.

  • dt (double) value

    Time step increments.

Neighbor List (NL)

  • interVerlet (double) value

    Elapsed time between each rebuild of the neighbor list.

  • DVerlet (double) value

    Distance used to define if two sphero-polyhedra are neighbors. This length is added to the Object-Bounding Boxes (OBBs) before testing for overlap. In other words, half of this length is added to each side of the OBBs.

  • dVerlet (double) value

    Distance used 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 dynamic update of the neighbor list is activated (set to 1), the list will be updated if the maximum distance a body has moved since the last update becomes larger than dispUpdateNL, or if the maximum rotation becomes larger than angleUpdateNL. These dynamic updates will not affect the regular updates (every interVerlet).

    Additional parameters to be set:

    • dispUpdateNL (double) distance

    • angleUpdateNL (double) angleDegree

Configuration Backups

As mentioned earlier, the “conf-files” store a configuration (i.e., the entire dataset of a simulation state). The format described here can be used as both input and output of a simulation.

  • interConf (double) value

    Elapsed time between each backup of the configuration.

  • iconf (double) value

    Number of the current configuration. This number is used to name the conf-file.

Computation options

  • AddOrRemoveInteractions (string) Option

    Choose the method for handling interactions between particles (sphero-polyhedra).

    • Options: bruteForce (default) or OBBtree

    • Description: The interactions between particles involve different types of interaction,

      such as sphere-sphere, sphere-tube, sphere-polygon, and tube-tube. The best strategy to be used depends on the complexity of the involved shapes.

  • UpdateNLStrategy (string) Option

    Choose the strategy for updating neighbor lists.

    • Options: bruteForce (default) or linkCells

    • Description: In the case of the linkCells strategy, the following additional settings need to be configured:

      • cellMinSizes (double) xmin (double) ymin (double) zmin: Set the minimum size of

        a cell in each direction.

      • boxForLinkCellsOpt (0 | 1): A flag to determine if the first driven bodies are part of the overall

        bounding box, which will be split into cells.

  • Integrator (string) Option

    Choose the time-integration scheme to be used.

    • Options: Euler, velocityVerlet (default), Beeman, or RungeKutta4

    • Description: This option determines the time-integration method for the simulation. For more details,

      see Integration schemes.

Library of Particle Shapes

  • shapeFile (string) path

    Path of the file that defines the shapes used. The format to define a shape is explained here: Format of shape-files

Particles

  • density (int) groupNumber (double) density

    Set the density (in kilograms per cubic meter) for particles belonging to a given group number.

  • Particles (int) numberOfParticles

    The following entries are repeated for each particle: (string)shapeName (int) group (int) cluster (double) homothety (vec3r) position (vec3r) velocity (vec3r) acceleration (quat) angularPosition (vec3r) angularVelocity (vec3r) angularAcceleration

Interactions

  • Interactions (int) numberOfInteractions

    The following numberOfInteractions entries are repeated 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: 0 for vertex-vertex, 1 for vertex-edge, 2 for vertex-face, or 3 for edge-edge.

    • relativeVelocity: The velocity of body j relative to body i at the contact point.

    • n: Vector oriented from j to i.

Force Laws

  • forceLaw (string) Name

    Select a model for the computation of forces. For possible Name, see Force laws.

Time-Integration Scheme

  • Integrator (string) Name

    Select a scheme for time integration. For possible Name, see Integration schemes.

Dissipation

There are several dissipation strategies that can be used (see Global dissipation features).

Loading

  • nDriven (int) Value

    Set the number of bodies, at the beginning of the list, that are not free to move. By default, the 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

    Use mode to set a velocity or force/moment for a specific body.

    Warning

    There are two additional mode keywords for which the single value has to be replaced by three values (a vector of three components): _xyzrot_Vel_ and _xyzrot_Mom_.

  • Servo (string) servoName <PARAMETERS>

    Set the parameter list depending on the selected servo (see Available servo-controllers).

Pre-processing Commands

Rockable provides several commands for performing preprocessing tasks. These commands are typically entered at the end of an input conf-file, after the definition of particles and interactions. For details on these commands, refer to: Pre-processing commands

Data Extractors

  • DataExtractor (string) ExtractorName <PARAMETERS>

    The parameter list depends on the ExtractorName. Details are listed below.