Balls in a Box

  Tutorial Resources
Data Files Project: Open {“CMLinearSimple.p2prj” in PFC2D; “CMLinearSimple.p3prj” in PFC3D} [1]

Introduction

This simple example models 30 balls interacting in a box. Gravity is activated, and the system is cycled to a target age limit twice:

  1. once with no energy dissipation, and
  2. once with energy dissipation via frictional slip and viscous damping at the contacts.

This example demonstrates basic usage of the ball generate, ball attribute, and contact cmat default commands and makes use of the linear contact model. A similar tutorial demonstrating the creation of clumps in a box is given in the “Clumps in a Box” section.

Numerical Model

The complete data file (3D) for this example is “cmlinear_simple.p3dat”. Select lines of this file are discussed below. Since the command structure is identical for PFC3D and PFC2D, this data file will operate with the latter as well (only the number of balls generated will differ).

The first two lines of the file (we ignore lines starting with a semicolon ( ; )—these are treated as comments and ignored for command/FISH processing) call the model new command and set the job title for this project:

model new
model title 'Balls in a box'

These two lines are not mandatory. Issuing a model new command clears the entire model and is useful if you run the file multiple times or where previous operations have been performed. The job title is empty by default. Note that the job title may also be set using the General Options dialog under the Tools —> Options… menu.

Next, the extent of the domain is specified using the model domain command:

model domain extent -10.0 10.0

It is necessary to define the domain extent before any model components can be created. PFC uses this information for geometric calculations and contact detection (see the “Domain” section for details). This command sets the domain extent to be a cubic box with a side length of 20.0 units centered on the origin of the model (always at (0.0,0.0,0.0)). This is achieved by specifying the edges of the extent in the x-direction only. If the extent edges in the y- and/or z-direction(s) are not specified, then the extent edges of the preceding direction are used. Also note that domain conditions (i.e., conditions to be applied when a model component reaches the domain boundaries) can be specified with the model domain command. The stop condition is the default, and the translational and angular velocities are set to 0.

Next, the contact cmat default command is used to select the default mechanical contact model to be installed by PFC whenever a new contact is created. Here the linear contact model is selected. One can also specify contact model properties with the property keyword. In this case, the normal stiffness of 1.0e6 stiffness units is specified.

contact cmat default model linear property kn 1.0e6

This command operates on the Contact Model Assignment Table (CMAT), a new utility in PFC. Contact detection occurs while cycling, and the list of contacts is updated based on the proximity of pieces to one another (refer to the “Cycling” section for a detailed description of the cycle sequence). The contact detection scheme also deletes contacts if the pieces move far enough from one another that they no longer interact. Whenever a contact is created, the CMAT is queried to select the appropriate contact model to install. At program start-up, the CMAT contains default slots for each contact type (e.g., ball-ball, ball-facet, etc.) that are filled with the Null contact model. This means that, by default, bodies will not interact or “see” each other. The contact cmat default command is used to modify these default slots; if no contact type is specified, then all default slots are modified. Note that the CMAT may contain additional entries (each associated with a specific range), which easily permits building complex mechanical behaviors into the system. Please refer to “contact cmat commands” for further details.

The next three lines are used to generate 30 balls in a cubic box composed of wall facets:

wall generate box -5.0 5.0 one-wall
model random 10001
ball generate radius 1.0 1.4 box -5.0 5.0 number 30

The wall generate command creates a cubic box with sides of length 10.0 units centered about the origin of the model. The syntax for repetition of extent edges is similar to the domain specification described above. The one-wall keyword is given to force all generated facets to belong to the same wall, as opposed to creating one wall for each face of the box. Other predefined shapes (e.g., cylinders, spheres, etc.) may be generated with the wall generate command. A wall is always a collection {of line segments in 2D; triangular facets in 3D}. It is also possible to create a wall and its facets using the wall create command or to import a wall from an existing STL or DXF file in 3D, or from a geometry object in 2D or 3D.

Balls are generated using the ball generate command: 30 balls with radii ranging from 1.0 to 1.4 units are created in a box the size of the wall. Notice that there are no initial overlaps since the ball generate command generates balls that fall completely within the specified box. The ball centroids are positioned randomly within the box and the radii are chosen randomly from a uniform distribution by default. The ball generate command produces a specimen where balls do not overlap. Note that other commands may be used to create balls (such as the ball create command, which creates a single ball, or the ball distribute command, which produces a specimen with a target porosity without regard to overlap).

The next line uses the ball attribute command to assign the density of the balls:

ball attribute density 100.0

PFC requires balls to have a nonzero density in order to resolve the ball equations of motion. An error occurs at the beginning of a cycle sequence if a ball with zero density exists. The ball attribute command can be used to set all attributes of the balls. Note that the term attribute has a very specific meaning in PFC and is fundamentally different from a property. This distinction is discussed in the tutorial example “Attributes and Properties.”

Gravity is set with the model gravity command:

model gravity 10.0

Using the syntax above, gravity will be assumed to act in the {minus y-direction in 2D; minus z-direction in 3D}. Note that gravity can be oriented arbitrarily if all components of the gravity vector are specified (see model gravity for details).

At this stage, the model is ready to be solved. Before proceeding, the model save command is used to save the current state of the system to “initial-state.p3sav”:

model save 'initial-state'

Note that the model state (SAV) file extension {“.p2sav” in 2D; “.p3sav” in 3D} is automatically appended to the file name if no extension is specified by the user.

The system is then cycled with the model solve command with a target time limit of 10.0 time units, and the resulting state is saved:

model solve time 10.0
model save 'caseA-nodamping'

The model solve command is used to initiate and continue cycling until a target limit criterion is reached. Alternatively, the model cycle command can be used to perform a given number of cycles.

As no energy dissipation mechanisms were introduced in the model, the total energy initially present in the form of potential energy is conserved and distributed into potential, kinetic, and elastic strain energy partitions. Figure 1 shows the state of the system with balls colored by velocity magnitude. As one can see, a high level of agitation remains in the system. This response would not be observed, by default, in PFC 4.0 due to the default local damping coefficient of 0.7. In PFC 6.0, though, there is no local damping by default (one can set the local damping coefficients with the ball attribute damp and clump attribute damp commands).

../../../../../../../_images/p3d-cmlinear-simple-nodamp.png

Figure 1: The system after cycling (case A - no dissipation).

The initial system is then restored with the model restore command:

model restore 'initial-state'

Similar to the model save command, a SAV file extension {“.p2sav” in 2D; “.p3sav” in 3D} is automatically appended if no extension is specified by the user.

The CMAT is modified to introduce dissipation into the system:

contact cmat default model linear ...
                     property kn 1.0e6 ks 1.0e6 fric 0.25 dp_nratio 0.1

The linear contact model continues to be used as the default model, though the properties are changed to activate friction and viscous damping in the normal direction. Please refer to the linear contact model description for details of the model and the contact model properties.

Note that modifying the CMAT does not alter existing contacts since their contact models have already been assigned. Contacts created after the CMAT modification will be affected. To modify existing contacts, the contact cmat apply command is used:

contact cmat apply

This command forces the CMAT to be queried for all existing contacts and can reassign the contact model if necessary. Using this command results in the deletion of all information previously stored in the contact model; it should be used with care.

Finally, the system is solved to the target time limit and a new SAV file is created:

model solve time 10.0
model save 'caseB-damping'

Figure 2 shows the state of the system: balls have settled on the floor of the box.

../../../../../../../_images/p3d-cmlinear-simple-damp.png

Figure 2: The system after cycling (case B - dissipation activated).

Discussion

This tutorial introduces the main steps required to build a simple PFC model. They can be summarized as follows:

  1. define the domain extent;
  2. define the CMAT;
  3. generate the initial state;
  4. perform alterations and solve the system; and possibly
  5. repeat step 4 to conduct sensitivity analyses.

Important PFC features, concepts, and commands have been discussed for each step. The user is encouraged to visit the detailed descriptions of these topics in the corresponding sections of the documentation.

Endnote

[1]These may be found in PFC3D under the “tutorials/balls_in_a_box” folder in the Examples dialog (Help —> Examples on the menu). If this entry does not appear, please copy the application data to a new directory. (Use the menu commands Tools —> Copy App Data …. See the “Copy Application Data” section for details.)