A ball is a rigid {disk with unit thickness in 2D; sphere in 3D}. The surface is defined by the sphere radius (\(R\)). A ball has a single set of surface properties. Balls can translate and rotate (defined by \(\{\mathbf{v},\mathbf{w}\}\), the generalized velocity and angular velocity or spin). Ball motion obeys the equations of motion. This requires that mass properties, loading conditions, and velocity conditions exist. Mass properties are mass, centroid position, and inertia tensor (\(\{m,\mathbf{x},\mathbf{I}\}\)). Mass properties are defined by the density (\(\rho\)) and radius. Loading conditions are defined by: the force and moment resulting from interactions with other pieces; gravity (defined by \(\mathbf{g}\), the gravitational acceleration vector); and, an externally applied force and moment (defined by \(\mathbf{F_A}\) and \(\mathbf{M_A}\)). Velocity conditions are defined by velocity-fixities \(V_f\) with {3 values in 2D; 6 values in 3D}.

Balls are inserted into the domain (see the model domain command) in three ways: by creating balls one at a time (using ball create), by generating non-overlapping sets of balls (using ball generate), or by distributing overlapping balls to match a specified size distribution (using ball distribute).

The ball attribute and ball property commands are used to specify ball attributes and properties as discussed in the “Model Components” section. The entire attribute/property lists can be listed with the ball list attribute and ball list property commands along with the values of specific attributes/properties.