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:

  • stl - an STL surface (geometry.file)

  • superellipsoid - the shape in superellipsoid

  • spheres - a list of spheres (geometry.file, lines of x y z r)

String

stl

geometry.file

The STL file, or the sphere list for geometry = spheres.

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:

  • overlap - overlapping spheres fitted to the grain

  • grid - spheres on a grid along the grain’s axes

  • lattice - touching spheres on a close-packed lattice

  • file - members read from spheres_file, or for geometry = spheres the spheres given

String

overlap

n_spheres

Number of members for overlap and lattice.

Int

20

spill

overlap: the largest fraction of a member allowed outside the grain, or auto to try 0 to 0.05 and keep the best.

String

auto

grid

grid: number of cells along the grain’s long, middle and short axes.

Ints<3>

5 5 2

grid_frame

grid: axes of the grid.

Options:

  • principal - the grain’s principal axes

  • file - the file’s own axes

String

principal

small_sphere_ratio

grid: remove members smaller than this times the largest member’s volume.

Real

0

max_removal_fraction

grid: remove small members only until this fraction of the volume is removed.

Real

0

spheres_file

file: the members, as lines of x y z r.

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:

  • ellipsoid - from each body’s equivalent ellipsoid

  • none - none; the drag uses the sphericities alone

String

ellipsoid

K

Creeping-flow resistance factors K1 K2 K3 along the body axes, over the equal-volume sphere’s, in place of stokes; both drag sets take them.

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

overlap: stop adding members once this fraction of the grain is covered; 1 places all n_spheres.

Real

1

min_radius_ratio

overlap: smallest member radius as a fraction of the largest.

Real

0.05

spill_weight

overlap: cost of the members’ volume outside the grain.

Real

1

grow

overlap: largest member radius as a multiple of the inscribed one.

Real

1.6

closing

overlap: closing radius over d_eq, which fills cracks up to twice its width.

Real

0

wall_extend

grid: the grid’s box widened by this fraction.

Real

0.001

A superellipsoid with semi-axes \(a, b, c\) and exponents \(m, n\) is the set of points with

\[\left( \left|\frac{x}{a}\right|^m + \left|\frac{y}{b}\right|^m \right)^{n/m} + \left|\frac{z}{c}\right|^n \le 1\]

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, and

  • the 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 raster x raster grid.

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.csv in 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.stl and [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 a lattice template;

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.