clump generate command


clump generate keyword ... <range>

Primary keywords:

azimuth    box    diameter    density    elevation    fish-distribution    fish-size    gauss    group    id    number    size    templates    tilt    tries

Generate non-overlapping clumps. The process ceases when the target number of clumps are created or when the number of attempts to place clumps without overlap is achieved. By default, the clump positions and sizes are drawn from uniform distributions throughout the model domain. As a result, the set of clumps generated is affected by the state of the random-number generator (see model random). The clump size can also be drawn from a Gaussian distribution via the gauss keyword. A number of clump templates can be used during a single clump generate command. The optional range is applied to each clump upon generation and, if the clump does not fall within the range, it is not added to the model and does not affect the stopping criteria. This command contrasts with the clump distribute command where clumps are distributed without regard for overlap until a target porosity is achieved.


  • A model domain must be specified prior to clump generation.
  • While cycling, clumps can only be created before cycle point 0 (i.e., when the timestep is calculated).
azimuth fazlow fazhi

Range of azimuths to rotate the clump template randomly about. An azimuthal rotation is a right-hand rotation about the {out of plane direction in 2D; \(z\)-axis in 3D} in degrees.

box fxmin fxmax fymin fymax fzmin fzmax (`z`-components are 3D ONLY)

Clumps will fully fall within this box, such that they will not overlap the box faces or edges. By default, the box is the model domain.


Specify that the linear size used to scale the clumps is the volume equivalent diameter of a {disk in 2D; sphere in 3D}.

density fdens

The clump density that is 1 by default.

elevation fellow felhi (3D ONLY)

Range of elevations to rotate the clump template randomly about. An elevating rotation is a right-hand rotation about the \(y\)-axis in degrees.

fish-distribution fdist

The clump sizes are drawn from the distribution represented by the FISH function fdist. Function arguments can be specified as though no function arguments are required. The FISH function must return a floating point value that is the clump size. A FISH distribution cannot be specified with the gauss or size keywords.

fish-size fsize

The size used to scale the clumps while generating can be specified by the FISH function with name fsize. The return value of the FISH function should be a linear measure of the clump size and the function should take one argument that is a clump pointer.

gauss <fcutoff >

Specify that the clump sizes are chosen from a Gaussian distribution with mean value (fsizelow + fsizehi)/2 and standard deviation (fsizehi - fsizelow)/2. The optional fcutoff (default 0.1), multiplied by fsizelow, constitutes the minimum size allowed.

group s <slot slot > <pebble> ...

Specify that generated clumps or pebbles are given group name s at slot slot. If the slot keyword is not specified, then the group name is assigned to the slot Default. The optional pebble keyword specifies that the group is assigned to the pebbles and not to the clump.

id idlow <idhi >

The ID of the first clump generated is set to idlow that, by default, is the next available ID. idhi, if specified, is used to calculate the number of clumps to generate. Clump IDs are chosen sequentially.

number inum

Specify the number of clumps to be generated.

size fsizelow <fsizehi >

Specify the size range to be used during generation. If fsizehi is not specified, then fsizehi = fsizelow. By default, fsizehi = fsizelow = 1.0. Cannot be given with the fish-distribution keyword.

templates inum stname <f > ...

Specify the number inum of clump template pairs to be entered followed by the pairs. The pairs are composed of the clump template name and the relative proportion of the clump template to be used during generation. The relative proportions are divided by the sum of the proportions to yield a percentage. If no percentages are specified, then clump templates are drawn equally from those given. If no templates are specified, then they are randomly selected from all clump templates.

tilt ftiltlow ftilthi (3D ONLY)

Range of tilts to rotate the clump template randomly about. A tilting rotation is a right-hand rotation about the \(x\)-axis in degrees.

tries itries

Number of tries to fill the specified region with the number of clumps. By default, itries = 20,000.

Usage Example

clump generate size 1 2 number 200 template 1 'rock1' 1.0

clump generate size 9 18 number 100 range fish testInclude

clump generate diameter size 1.5 number 25          ...
            box -5.0 5.0 -5.0 5.0 0.0 5.0           ...
            templates 2                             ...
            'dyad' 0.3 'dolos' 0.7                  ...
            azimuth 45.0 45.0                       ...
            tilt 90.0 90.0                          ...
            elevation 45.0 45.0                     ...
            group 'top1'

from “clumps_in_a_box.dat” in Clumps in a Box