Command line and build options

rockable

rockable [conf-file] [options]

The positional argument is the conf-file to load; it defaults to conf0. Everything happens in the current folder: the companion files are looked up there, and the dumps are written there.

Option	Description
-j, --nbThreads (int)	Number of OpenMP threads, 1 by default. The parallel strategy itself is a conf-file keyword, parallel_mode.
-v, --verbose (int)	Verbosity, from 0 to 6: off, critical, err, warn, info (the default), debug, trace.
-c, --clean	Delete conf*, kineticEnergy.txt, perf.txt, staticBalance.txt and checkplots.txt from the current folder, then exit.
-b, --banner	Print the banner, which lists the version, the git tag and the compilation options actually used, then exit.
-n (string) -r (string)	Non-regression check. After the run, compare the conf-file given by -n with the reference given by -r, from their Particles section onwards, and exit with an error if they differ beyond the tolerance. The numbers are compared with a relative tolerance, and the interactions are matched by their key, since their order in the file is not reproducible (test/README.md details the comparison).
-t, --tolerance (double)	Relative tolerance of the comparison between the -n and -r files, 1e-5 by default.
-h, --help	The usual help.
--version	The git tag the binary was built from.

rockable input.txt -j 8 -v 5

Warning

rockable -c deletes files without asking for a confirmation. Run it in the folder of the simulation you really mean to clean.

Tip

Any dump is a valid input file, so rockable conf27 -j 8 resumes the computation from configuration 27. The companion files are re-read from the folder, which is how a loading can be changed mid-course.

The other executables

Command	Description
see [conf-file]	The OpenGL viewer. -t <file> loads a trajectory file, -v <int> sets the verbosity of the core. See Visualisation tools.
seer	Dear My Seer, the Dear ImGui viewer that supersedes see.
shape [shapeFile]	Dear My Shape, the Dear ImGui browser of shape libraries. See Visualisation tools.
conftovtk	Convert every conf* of the folder into VTK files for ParaView.
postpro <commandFile>	Run a post-processor over a range of dumps. See Post-processing (postpro).
generator <commandFile>	Build shape files, input files and packings. See the generator page.
shapeSurvey <shapeFile>	Inspect and pre-compute a shape library. See Application shapeSurvey.
shapeSurvey <f.shp> -P <f.shp>	Pre-compute the shapes of a library, in place, without window.
sweepable [script]	Generate a tree of input files for a parameter sweep.
stl2shape -r <R> <f.stl>	Convert a binary STL file into a shape. See Converters.
stl2blocks <commandFile>	Cut a closed STL mesh into blocks (shapes and particles). See Converters.

Building

git clone https://github.com/richefeu/rockable.git
cd rockable
sh install_rockable.sh

The build happens in BUILD and the binaries are installed into INSTALL. Depending on the system, a few packages may be needed beforehand: glfw3, opengl, freeglut, and optionally libpng for PNG screenshots.

To change the options:

cd BUILD
ccmake .
# set the options, then c, then e, then g
cmake ..
make -j
make install

To make the binaries reachable from the shell:

source add_install_to_path.sh

Important

The script must be sourced, not executed. A script run in a subshell cannot change the PATH of the shell that launched it.

Compilation options

Options that change the physics, or the set of keywords understood. ROCKABLE_ENABLE_PERIODIC and ROCKABLE_ENABLE_SOFT_PARTICLES default to ON, so that a default build, and the continuous integration, compiles and tests them; the others default to OFF. Each enabled feature has a small cost even when a computation does not use it, so disable the ones you do not need.

Option	Effect
ROCKABLE_ENABLE_PERIODIC	Tri-periodic cell: the usePeriodicCell, h, vh, ah, mh, dh keywords and the PeriodicLoading drivings. See Periodic boundary conditions.
ROCKABLE_ENABLE_SOFT_PARTICLES	Homogeneous deformation of the particles (DCEM), keywords useSoftParticles, defineElasticParticles, useViscousTime… See Deformable particles (DCEM).
ROCKABLE_ENABLE_BOUNDARY	The special boundary shapes, Ball and Cylinder.
ROCKABLE_USE_FT_CORR	Objectivity correction of the tangential forces under large rotations.
ROCKABLE_ENABLE_PROFILING	Time profiling of the main routines with MATools (fetched by CMake), which reports the timers at the end of the run. The file perf.txt is written in any case.

Warning

ROCKABLE_ENABLE_BOUNDARY is not usable yet. With this option, the current sources do not compile (InteractionBoundary is used in Rockable.hpp without being declared), and the read methods of the Ball and Cylinder boundaries are still empty stubs. Keep it OFF.

Options that select what gets compiled:

Option	Default	Builds
ROCKABLE_COMPILE_SEE	ON	see
ROCKABLE_COMPILE_SEER	OFF	seer (Dear My Seer) and shape (Dear My Shape)
ROCKABLE_COMPILE_CONF2VTK	ON	conftovtk
ROCKABLE_COMPILE_POSTPRO	ON	postpro
ROCKABLE_COMPILE_PREPRO	ON	the pre-processing tools
ROCKABLE_USE_TESTING	OFF	the regression tests

Tip

rockable -b prints which of these were actually enabled. It is the quickest way to explain a keyword that appears to do nothing.

Files of a simulation folder

mySimulation/
  input.txt              # the conf-file you write
  shapes.txt             # shape library, named by shapeFile
  shapes.rmsh            # optional skin meshes, used by see
  drivingSystem.txt      # optional driving and servo
  dataExtractors.txt     # optional measurements
  see.json               # optional view settings
  probe.txt              # optional measurement box
  ------------ produced by the run ------------
  conf0 conf1 conf2 ...  # the dumps
  extractedDataDoc.txt   # what each extractor column holds
  perf.txt               # time, efficiency, profiling
  kineticEnergy.txt      # time, translational and rotational energy
  staticBalance.txt      # time, equilibrium indicators
  checkplots.txt         # gnuplot script for the three files above

Tip

gnuplot checkplots.txt plots the performance, the kinetic energy and the static balance in one go. Watching the kinetic energy fall is the usual way of deciding that a sample has reached equilibrium.