Clump templates¶
The mfix-clump-design tool designs clump templates: it fills a grain, given as an STL surface, a
superellipsoid or a list of spheres, with overlapping member spheres, computes the grain’s drag data,
and writes each template as a template file ([template_name].tpl) for the solver’s
dem.templates.[template_name].file (see Templates). A template is designed once;
runs and restarts read its file.
The tool is built with MFIX-Exa by CMake (cmake --build . --target mfix-clump-design, in
tools/ of the build directory), or with GNU make by running make in tools/clump-design
(mfix-clump-design3d.gnu.ex). It runs serially and reads an inputs file in the same format as the
solver’s, with command-line overrides:
mfix-clump-design templates.inp [key=value ...]
Every key in the inputs must be one the tool reads, so the tool’s inputs belong in their own file.
The following inputs are defined with the prefix dem:
Description |
Type |
Default |
|
|---|---|---|---|
templates |
Names of the templates to design. |
Strings |
None |
templates.write_dir |
Directory the files are written to. |
String |
. |
The following inputs define each template and are defined with the prefix dem.templates.[template_name]:
Description |
Type |
Default |
|
|---|---|---|---|
geometry |
How the grain is given. Options:
|
String |
stl |
geometry.file |
The STL file, or the sphere list for |
String |
None |
scale |
Length unit of the files, in meters. |
Real |
1 |
superellipsoid |
Semi-axes a b c and exponents m n of the superellipsoid, all positive (see the shape below). |
Reals<5> |
None |
d_eq |
Volume-equivalent diameter the grain is designed at; 0 keeps the size of the file. Initial conditions scale the template to the diameters they ask for. |
Real |
0 |
method |
How the members are placed. Options:
|
String |
overlap |
n_spheres |
Number of members for |
Int |
20 |
spill |
|
String |
auto |
grid |
|
Ints<3> |
5 5 2 |
grid_frame |
Options:
|
String |
principal |
small_sphere_ratio |
|
Real |
0 |
max_removal_fraction |
|
Real |
0 |
spheres_file |
|
String |
None |
resolution |
Voxels across the grain’s d_eq used to design it, 8 to 256. |
Int |
64 |
envelope |
Fill closed cavities and drop loose fragments of the grain (1) or not (0). |
Int |
1 |
stokes |
Creeping-flow resistance of the grain and of the members’ union. Options:
|
String |
ellipsoid |
K |
Creeping-flow resistance factors K1 K2 K3 along the body axes, over the
equal-volume sphere’s, in place of |
Reals<3> |
None |
view_resolution |
Voxels across d_eq of the surface written for drawing the grain, 8 to 128; 0 writes none. |
Int |
32 |
raster |
Resolution of the projections the drag tables are computed from. |
Int |
512 |
coverage |
|
Real |
1 |
min_radius_ratio |
|
Real |
0.05 |
spill_weight |
|
Real |
1 |
grow |
|
Real |
1.6 |
closing |
|
Real |
0 |
wall_extend |
|
Real |
0.001 |
A superellipsoid with semi-axes \(a, b, c\) and exponents \(m, n\) is the set of points with
Below is an example of a template designed from a superellipsoid.
dem.templates = flake
dem.templates.flake.geometry = superellipsoid
dem.templates.flake.superellipsoid = 1.0 1.0 0.5 2 2
dem.templates.flake.method = grid
dem.templates.flake.grid = 3 3 2
Drag data¶
Each template file holds two sets of drag data, one for the grain and one for the union of its
member spheres; dem.templates.[template_name].drag in the solver chooses between them. For a grain
given as a list of spheres, the grain is the union of the spheres given. Each set is
the volume-equivalent diameter and the sphericity,
the creeping-flow resistance along the body axes from the body’s equivalent ellipsoid, unless
stokes = none, andthe crosswise and lengthwise sphericities of Hölzer and Sommerfeld over 37 x 72 flow directions in the body frame, from the body’s projected areas on a
rasterxrastergrid.
Files written¶
For each template, the tool writes to write_dir:
[template_name].tpl- the template file, for the solver;[template_name]_spheres.csv- the members in the body frame, and[template_name]_spheres_file.csvin the frame and units of the file the grain was given in, to lay over it;[template_name]_spheres.vtp- the members, for ParaView (glyph by sphere, scaled by diameter);[template_name]_surface.stland[template_name]_view.stl- the grain’s surface and a light surface for drawing it, in the body frame;[template_name]_bonds.csv- the touching pairs of alatticetemplate;
and a summary of all templates (shapes.txt) with an index (shapes.csv).
The template file is text. Its lengths are in units of the grain’s volume-equivalent diameter, in the
body frame: the origin at the members’ center of mass, the axes along their principal axes. It gives
the grain’s volume and sphericity, the grain’s designed diameter and the rotation from the body frame
to the axes of the file the grain was given in (for orientation = file in initial conditions), the
members as lines of x y z r, and the two drag sets. The inputs the template was designed from are
copied into it as comments.