ball tractions command


ball tractions keyword ... <range>

Primary keywords:

angular-tolerance    boundary-group    contact-active    contact-create    constant    direction-x    extra    layered    overburden    periodicity    polydisperse    ratio    update-area    update-position    update-volume

Compute tractions at ball-ball and ball-facet contacts consistent with a prescribed stress state.

A constant stress tensor or gravitational stress may be specified. A Voronoi tessellation of the ball positions is computed to both provide the volume of the cell enclosing each ball and the enclosing surface area. By default, the ball volumes and positions are modified, consistent with the zero-porosity packing represented by the Voronoi tessellation. Ball-ball and ball-facet contacts may be created between pieces in adjacent cells. The area of each Voronoi face, corresponding to a specific contact, can be used to set the user_area contact model property. Contact forces are nulled for all inactive contacts. If the contacts are not bonded, or the reference gap is not specified, then the contacts may become inactive upon the first cycle after this operation. Also, if the normal force computation mode is not set to incremental, large forces might develop upon the first cycle after this operation. The Voronoi tessellation is computed using the Voro++ libraries ( All contacts identified as between adjacent cells are activated. If gravity is specified and a constant stress tensor is not specified, tractions including gravitation are computed; the direction of gravity must coincide with one of the global axes. Use the layered keyword to compute the gravitational overburden for cases with non-uniform densities or non-uniform upper boundaries. The balls are assumed to fall within an axis-aligned box. Note that one may specify a stress tensor with all 0 components in order to just simply introduce the Voronoi contact connectivity and null all contact forces. Note that if the contact model supports a reference gap it is computed so that when the compressive force goes to 0 the sum of the contact gap and reference gap goes to 0 as well.

angular-tolerance f

Specify the angular tolerance for ball-facet identification. If the ball-facet contact normal is within f degrees of the Voronoi cell normal with the boundary, the contact area is set. By default the angular tolerance is 10 degrees.

boundary-group s <slot slot > ...

Specify that balls with contacts with the boundaries of the Voronoi region 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. This can be useful for identifying model boundaries.

contact-active b

Specify whether or not forces are set for inactive contacts. If true (the default), then forces are set for only active contacts. If false, forces are set for all contacts and inactive contacts may be activated.

contact-create b

Specify ball-ball and ball-facet contact creation in cases where there is no piece overlap but pieces are in adjacent Voronoi cells. By default contacts are not created.

constant f1 f2 f3 f4 f5 f6 (only 3 components in 2D)

Set the components of a constant stress tensor. All components must be specified. In 3D, six parameters must be specified in the order stress-xx, stress-yy, stress-zz, stress-xy, stress-sxz, stress-syz. In 2D, three parameters must be specified in the order stress-xx, stress-yy, stress-xy. All components can be 0, in which case the contact forces are nulled and the contact connectivity and areas are set accordingly.

direction-x v (3D ONLY)

If two parameters are given for the ratio keyword, then this keyword can be used to specify the local \(x\)-direction the system should use. The \(y\)-direction is determined automatically using the \(x\)-direction and the direction of gravity to create an orthonormal system. The \(x'\)-direction may be adjusted to make it normal to the direction of gravity. By default the \(x\)-direction is (1,0,0). This keyword cannot be given with the constant keyword.

extra i

Assign the stress based on the tensor stored at extra index i.

layered b

Compute the overburden based on integrating the density of balls above this current contact location. This keyword cannot be used with the constant keyword. By default the model is not assumed to be layered.

overburden f

Specifies an overburden stress added to the calculation, assuming the vertical boundary of the model does not represent the surface. This value defaults to 0.0. Remember that compressive stresses are negative, so this value will typically be negative. This keyword cannot be be given with the constant keyword.

periodicity bx by bz (`z`-component is 3D ONLY)

Specify whether or not periodic boundary conditions should be assumed in each direction during the tessellation.

polydisperse b

Specify if a radical Voronoi tessellation (or Laguerre tessellation) is computed versus a standard Voronoi tessellation. By default the radical tessellation is computed. The radical tessellation produces Voronoi cells that are weighted by the ball radii, making them more closely represent the ball size distribution.

ratio f <fy > (3D ONLY)

Determine the vertical to horizontal stress ratio. Both horizontal stresses are set to the vertical stresses times this value. If the optional second parameter fy is given, then a different ratio is used in the local \(x\) and \(y\)-directions. Note that the direction-x keyword is used in this case to distinguish these local directions. This keyword cannot be given with the constant keyword.

update-area b

Specify if the contact areas are updated in the contact models, if areas are supported. Currently the user_area contact model property will be set. By default the contact areas are updated.

update-position b

Specify if the ball positions are updated to coincide with the Voronoi cell centroids. By default the ball positions are updated.

update-volume b

Specify if the ball volumes are updated to coincide with the Voronoi cell volumes. By default the ball volumes are updated.