Application generator

generator reads commands from a text file and produces Rockable configuration files (shape files, input files, packings). It is the standard pre-processing tool for setting up simulations.

generator <command-file>

Note

Leave at least one blank line at the end of the command file to avoid parsing issues.

Example

The following script generates a shape file and a full Rockable input file with a random close packing of cuboids:

# --- shapes ---
open shapes.txt
generateShape:cuboid Cuboid 0.0005 0.03 0.01 0.01
generateShape:xyz_walls 0.25 0.25 0.25 0.0005
close

# --- input file ---
open input.txt
print Rockable 21-08-2022
print #### time #############################
print t 0
print tmax 2.0
print dt 5e-6
print interVerlet 0.001
print interConf 0.01
print
print #### options ##########################
print forceLaw Default
print Integrator Beeman
print
print #### proximity of the particles #######
print DVerlet 0.005
print dVerlet 0.0025
print
print #### properties for particles #########
print density 0 2700
print density 1 2700
print
print #### interaction parameters ###########
print knContact 0 1 1e6
print en2Contact 0 1 0.02
print ktContact 0 1 1e6
print muContact 0 1 0.6
print krContact 0 1 0.0
print murContact 0 1 0.0
print
print #### the system #######################
print iconf 0
print shapeFile shapes.txt
print nDriven 0
Particles:placeHolder

generatePacking:RandomClosePacking
Cuboid
CUBOID Y
0.2 0.2 0.3
0.03 0.01 0.01
1.0 1.0
2000
0.9
0
0

close

Command Reference

File output

open <filename>

Open filename for output. All subsequent print, compute, and packing commands write to this file until close is called. If no file is open, output goes to the console.

close

Close the current output file. If Particles:placeHolder was used, the final particle count is written back into the file at that position before closing.

Printing and arithmetic

print <text>

Write text to the current output, trimming leading and trailing spaces, and append a newline. Useful for writing raw lines into shape or configuration files.

print> <text>

Same as print but without the trailing newline. The next output statement continues on the same line.

Example — writing a computed contact stiffness on one line:

print> knContact 0 0
<compute 500000 * 2

produces: knContact 0 0 1000000

compute <label> <expression>

Evaluate a mathematical expression and write label result to the output.

Example: compute Particles 5^3 + 6 produces Particles 131

<compute <expression>

Evaluate an expression and write only the result (preceded by a space), without a label. Intended to be combined with print> on the previous line (see example above).

Particle counting

Particles:placeHolder

Reserve a slot in the output file where the total particle count will be written when close is called. The count is updated automatically by every packing command.

incrementNoParticles <n>

Manually increase the tracked particle count by the integer n. Use this when adding particles through print rather than through a packing command.

Transformations

A global transformation is maintained throughout script execution and applied by packing commands when placing particles.

Note

The first versions of generator spelt these commands tranformation:..., without the first s. This spelling is still accepted, so that the old command files keep working.

transformation:add_translation <x> <y> <z>

Add a translation to the current transformation.

transformation:add_rotation <x> <y> <z> <angle_deg>

Add a rotation around the axis (x, y, z) by angle_deg degrees.

Note

The last command written is applied first. To turn a packing about its centre and then move it, write the translation before the rotation, with the packing centred on the origin:

transformation:add_translation 0 0.056 0
transformation:add_rotation -1 0 1 54.7356

The rotation also turns each particle, but only the last add_rotation does: the orientations are not composed, so a packing that needs two rotations should be given a single equivalent one.

transformation:reset

Reset the transformation to identity (clears both translation and rotation).

transformation:reset_translation

Reset only the translation component.

transformation:reset_rotation

Reset only the rotation component.

Shape Generation

generateShape:sphere <name> <radius>

Generate a spherical shape.

generateShape:cube <name> <radius> <sideSize>

Generate a cubic shape of side length sideSize with corner radius radius.

generateShape:cuboid <name> <radius> <sx> <sy> <sz>

Generate a cuboid shape with side lengths (sx, sy, sz) and corner radius radius.

generateShape:pyramid3 <name> <radius> <sideSize>

Generate a triangular pyramid shape.

generateShape:thin_cylinder <name> <Rin> <Rout> <H> <nbSectors>

Generate a thin cylindrical shell with inner radius Rin, outer radius Rout, height H, and nbSectors angular sectors.

generateShape:cuboid_container <name> <radius> <sx> <sy> <sz> <hasTop> <hasBottom>

Generate an open or closed cuboid container. hasTop and hasBottom are integers (0 = absent, 1 = present).

generateShape:rectangle_xz <name> <radius> <side_x> <side_z>

Generate a rectangular plate in the xz plane.

generateShape:rectangle_xy <name> <radius> <side_x> <side_y>

Generate a rectangular plate in the xy plane.

generateShape:rhombicuboctahedron <name> <radius> <sx> <sy> <sz>

Generate a rhombicuboctahedron shape.

generateShape:xyz_walls <sx> <sy> <sz> <Rw>

Generate three flat wall shapes (one per axis) sized (sx, sy, sz) with corner radius Rw.

Packing Generation

addParticle <name> <group> <cluster> <homothety> <px> <py> <pz> <qs> <qx> <qy> <qz>

Place a single particle at position (px, py, pz) with quaternion orientation (qs, qx, qy, qz), homothety scale homothety, assigned to group and cluster.

generatePacking:wallBox <group> <LX> <LY> <LZ> <Rw>

Generate six flat wall particles forming a closed box of dimensions LX × LY × LZ with wall corner radius Rw, all assigned to group.

generatePacking:grid <name> <ox> <oy> <oz> <bx> <by> <bz> <nx> <ny> <nz> <group> <cluster> <homothety> <randQ>

Fill a box of size (bx, by, bz) starting at origin (ox, oy, oz) with a regular nx × ny × nz grid of particles of shape name. Set randQ to 1 for random orientations. Each particle gets its own cluster, numbered from cluster upwards, so that the gluing commands (stickVerticesInClusters, stickBCM…) do not glue them together.

generatePacking:grid_clust <name> <ox> <oy> <oz> <bx> <by> <bz> <nx> <ny> <nz> <group> <cluster> <homothety> <randQ>

Same as generatePacking:grid, but all the particles get the same cluster cluster: they form one body once glued. See examples/fragmentation.

generatePacking:grid_inside <shapeFile> <cutter> <cutterHomothety> <name> <ox> <oy> <oz> <bx> <by> <bz> <nx> <ny> <nz> <group> <cluster> <homothety> <randQ>

Same as generatePacking:grid, but a shape is used as a cookie cutter: only the positions of the grid that are inside the shape cutter of the file shapeFile are kept. The cutter is placed at the origin, in the frame of its shape file, and scaled by cutterHomothety; the grid is given in the same frame, and the transformation, if any, is applied afterwards to the positions kept. The faces of the cutter must form a closed surface (its radius is not taken into account). A position is inside when rays cast from it cross the faces an odd number of times.

# cubes of 1 cm filling a bunny of homothety 2
generatePacking:grid_inside shapes.txt Bunny 2  Cell  -0.12 -0.06 -0.09  0.22 0.14 0.19  22 14 19  1 0 1 0

generatePacking:grid_clust_inside <...>

Same arguments, but all the particles get the same cluster, as with generatePacking:grid_clust: once glued, they form one body with the shape of the cutter. See examples/bunnyFun/bunnyShot.

generatePacking:OBBs <shapeFile> <names> <container> <mode> <axis> <ox> <oy> <oz> <bx> <by> <bz> <hmin> <hmax> <nb> <solidFraction> <group> <cluster> <seed>

Pack particles of any shape in a container, without overlap, so that a computation starts from a rather dense state. The oriented bounding boxes (OBB) of the particles are placed one by one, with a random orientation, until they overlap no other box; each box is then replaced by the particle it bounds. The packing still has to be stabilised by a computation (under gravity, or by moving the walls).

Parameter	Description
shapeFile	The shape file where the OBB of each shape is read (obb.extent, obb.center, obb.e1, obb.e2, obb.e3). The shapes must be pre-computed (preCompDone y): run shapeSurvey first (see Application shapeSurvey).
names	The name of a shape, or several names separated by commas, without spaces (Bunny,Cube): each particle is then given one of them at random.
container	CUBOID, or CYLINDER along axis (an elliptic one if its two transverse sizes differ).
mode	RANDOM: each box is put anywhere in the container, the largest first (random sequential addition, as TubePacker). STACK: each box is tried 20 times, with a random orientation and a random transverse position, and goes down along axis to the lowest place where it overlaps no other box; the lowest trial is kept. The boxes are stacked from the bottom of the container.
axis	X, Y or Z: the axis of the cylinder, the direction of stacking, and the order of the particles in the output (bottom first).
ox oy oz, bx by bz	The corner and the sizes of the container (of the bounding box of the cylinder). A size 0 along axis means a container without top: with RANDOM, its height is computed so that the nb boxes reach solidFraction; with STACK, the nb boxes are stacked as high as needed.
hmin hmax	The homothety of each particle is drawn uniformly in this range.
nb	Number of particles wanted.
solidFraction	The packing also stops when the volume of the boxes reaches this fraction of the container.
group cluster	The group of all the particles, and the cluster of the first one: each particle gets its own cluster, numbered from cluster upwards, as with generatePacking:grid.
seed	Seed of the random draws: the same seed gives the same packing.

The packing also stops when a box finds no place: the container is full. generator then prints the number of particles, the height reached, and the solid fraction of the boxes and of the particles.

generatePacking:OBBs shapes.txt Bunny CUBOID STACK Y  -0.1 0 -0.1  0.2 0.6 0.2  0.4 0.6  400 0.6  0 6  0

Note

A packing of boxes is loose: about 0.25 to 0.3 of the volume with RANDOM (the boxes jam), a little more with STACK. The solid fraction of the particles is lower still, by the ratio of the volume of a particle to the volume of its box (close to 1 for a cube, 0.52 for a sphere, 0.23 for the Stanford bunny). The OBB of a shape is not necessarily centred on its mass centre nor aligned with its principal axes: the particles are placed so that their boxes are where they were packed.

generatePacking:RandomClosePacking <name> <boxShape> <direction> <bx> <by> <bz> <xOBB> <yOBB> <zOBB> <hmin> <hmax> <nbTarget> <solidFraction> <group> <cluster>

The former form of generatePacking:OBBs, with the mode RANDOM, a container whose corner is the origin, and the sizes of the box of the shape given by hand instead of being read in a shape file. The box is supposed to be centred on the particle and aligned with its axes, and all the particles get the same cluster.

Parameter	Description
boxShape	Container geometry: CUBOID or CYLINDER
direction	Axis of the cylinder, and order of the output: X, Y, or Z
xOBB yOBB zOBB	Bounding box dimensions of the particle shape, at homothety 1
hmin hmax	Homothety range (size scatter)
nbTarget	Target number of particles
solidFraction	Target solid fraction (0–1)
group cluster	Group and cluster indices assigned to all particles