Data extractors

Data extractors are probes evaluated during a computation. They write plain text files that can be plotted directly, and they avoid the usual alternative of saving hundreds of conf-files only to post-process a single scalar afterwards.

The file dataExtractors.txt

The extractors are declared in a file named dataExtractors.txt, placed in the folder where the computation runs. The file is read once, at start-up, right after the driving system. Each entry starts with the name of an extractor, followed by its own parameters:

dataExtractors.txt

# one line per extractor
MeanVelocity     meanVelocity.txt 100
TrackBody     12 body12.txt       100
dnStat           dn.txt           500

A token starting with /, # or ! discards the rest of the line.

Note

The extractors are not saved into the conf-files. The file is re-read from the running folder every time a computation is started, so restarting from conf27 keeps the same probes, and editing the file between two runs is enough to change them.

Warning

The extractors are ignored when the conf-file is opened by an interactive tool (see, seer, conftovtk, postpro). Only rockable evaluates them.

Common parameters

Every extractor ends its parameter list with the same two entries:

Parameter	Description
<filename>	Name of the text file to write. It is opened at start-up and flushed after each record, so it can be plotted while the computation runs.
<nrec>	Number of time steps between two records. This is a step count, not a duration: with dt 1e-6, nrec 1000 records every millisecond of simulated time.

The first column of every output file is the time \(t\).

Tip

A file named extractedDataDoc.txt is generated at start-up whenever at least one extractor is declared. It documents, extractor by extractor, what each column of each output file contains. It is the authoritative reference when a column ordering is not obvious.

Available extractors

MeanVelocity (string) filename (int) nrec

Mean of the velocity magnitude \(\Vert \underline{v} \Vert\) over all the bodies, driven ones included.

Columns: t, mean velocity.

TrackBody (int) ibody (string) filename (int) nrec

Full kinematics and loading of a single body.

Columns: t, then pos (3), vel (3), Q (4, as w x y z), vrot (3), the resultant force (3) and the resultant moment (3).

Note

When a component of the body is driven in force, the imposed force is subtracted from the recorded resultant, so that the column holds the force actually carried by the contacts.

TrackRockfall (int) ibody (double) vStop (double) wStop (string) filename (int) nrec

Same columns as TrackBody, but it also stops the computation when the tracked block has come to rest, which is what a rockfall study needs: there is no point integrating a block that has stopped.

The run is stopped as soon as \(\Vert \underline{v} \Vert < v_\text{stop}\) and \(\Vert \underline{\omega} \Vert < w_\text{stop}\), or as soon as the block leaves the bounding box of the driven bodies.

Note

The stop test is inhibited before \(t_\text{min} = v_\text{stop}/g\) with \(g = 9.81\). This grace period is computed automatically, and prevents a block released at rest from stopping the computation at the very first step, before gravity has had time to accelerate it.

ClusterAABB (int) icluster (string) filename (int) nrec

Axis-aligned bounding box of one cluster, useful to follow the swelling or the spreading of a fragmenting body.

Columns: t, aabb.min (3), aabb.max (3).

dnStat (string) filename (int) nrec

Statistics of the normal distances \(d_n\) over all the interactions. It is the quickest way to check that a simulation is not over-compressed and that the time step is small enough.

Columns: t, dnMin, dnMax, dnMean, the mean over the negative values only, the mean over the positive values only, the count of negative values, the count of positive values, and the position (3) where dnMin occurs.

DuoBalance (int) i (int) j (string) filename (int) nrec

Composition of the interaction between two given bodies, by sub-interaction type.

Columns: t, number of vertex-vertex, vertex-edge, vertex-face and edge-edge sub-interactions, then their sum weighted by the contact partnership.

TrackDamage (string) filename (int) nrec

Damage of the sample, defined as the broken interface area divided by the interface area present initially.

Columns: t, damage in \([0, 1]\).

Note

Only meaningful with a force law that breaks interfaces (StickedLinks, BCM) and once the interfaces have been created by a sticking pre-processing command.

Declaring an extractor inside a conf-file

A DataExtractor keyword is also accepted inside a conf-file:

DataExtractor MeanVelocity meanVelocity.txt 100

Warning

This form is kept for backward compatibility only, and it emits a warning. It has a real drawback: the line is not written back into the conf-files that the computation saves, so restarting from a dump silently loses the extractor. Use dataExtractors.txt instead.

Plotting the results

The output files are column-formatted text, directly usable by gnuplot:

plot 'meanVelocity.txt' u 1:2 w l t 'mean velocity'
plot 'body12.txt' u 1:3 w l t 'height of body 12'

The same holds for the three files that rockable always writes (perf.txt, kineticEnergy.txt and staticBalance.txt); the generated script checkplots.txt plots them in one go:

gnuplot checkplots.txt