How to …

Below is a list of common tasks and hints on how to perform them. Find how to …

… set the model domain

The model domain is an axis-aligned box that defines the domain in which the PFC model lies. The user must specify the domain extent and boundary conditions prior to creating any instance of a model component. This step is performed with the model domain command, which accepts two keywords: extent and condition. The extent keyword is used to specify the extent of the model domain, independently in each global coordinate system direction. The domain extent is fixed, unless it is further modified by the user. It does not expand automatically when model components disperse. Instead, it dictates the behavior model components should follow when they reach the domain boundaries; they can either be destroyed, stopped, reflected, or periodically reinserted in the model at the opposite domain boundary. This behavior is set with the condition keyword.

Note that the stop or reflect model domain boundary conditions should not be confused with mechanical boundary conditions. They do not apply any mechanical conditions on the model components but instead constrain their kinematics to conform to given constraints. For instance, if a ball settling under gravity loading reaches a domain boundary with the stop condition activated, it will be effectively stopped but will never reach mechanical equilibrium, as the one and only force it is subjected to is its own weight. It is therefore generally recommended that physical boundary conditions (see the item below) are used within the model domain, except when periodic boundary conditions are intended.

back to top

… clean the model, and when it can be useful

We refer to a “clean” model as a PFC model where pieces mapping into the cell space, contacts between pieces, contacts activity status, and derived properties are up to date. The model clean command is a global command that can be given at any time, before or inside a cycle sequence, to ensure that the model is in a clean state. There are three main reasons why a user may want to use this command:

  1. Prior to cycling, during model creation: When model components are created, they may not be automatically mapped into the cell space, and contacts are not automatically created. Instead, these steps are enforced for the first time at the very beginning of the first cycle sequence. Later on, each piece may be remapped in the cell space, and its contact list updated, based on its accumulated displacement. Decoupling contact detection from model creation allows for a much faster and more interactive user experience. Depending on the model being designed, however, it may be necessary that pieces are mapped in the cell space, and contacts created prior to cycling. For instance, if the initial locations of the model components are such that active contacts should already exist, and if there is an interest in modifying the default contact properties (for instance bond select contacts), then the model must be cleaned in the first place. Other operations, such as spatial searching using the ball.inbox or clump.inbox functions, also rely on the pieces mapping into the cell space being up to date.
  2. After restoring a model state: Right after a model state has been restored, pieces are not remapped in the cell space to ensure that the contact lists (including inactive contacts) exactly correspond to the ones that were in use when the model state was saved. For the reasons discussed above, certain operations (those that require up-to-date contact lists or pieces mapping into the cell space) should be preceded by a model clean command.
  3. During cycling: The cycle sequence in PFC is designed to maintain the model in a clean state at each point of the calculation cycle. However, the openness and the generality of PFC implies that some user operations may put the model data into an inconsistent state. For instance, modifying the domain extent or the size of a model component during the calculation sequence are operations that fall in this category, because they may affect the contact list. If such operations are performed between the update of the contact list and the update of the contact forces, the results may differ from user’s expectations. In such cases, it is recommended to use the model clean command to put the model back in a clean state.

back to top

… create particle assemblies

Generating the initial assembly is a crucial step of the DEM modeling procedure. There is indeed an infinite number of ways one can pack particles into a connected network, and the characteristics of the produced packing, as well as its forthcoming rheology, are intimately tied to the construction history. Great care should therefore be devoted to building an initial state that corresponds to the requirements and specifications of the problem being investigated.

Except for regular (cubic or hexagonal) geometries, PFC does not provide built-in tools to automatically create connected assemblies of particles. What it provides is a set of primitive commands that can be used to derive advanced algorithms suited to the problem being studied:

  • The ball create, clump create, and clump replicate commands can be used to create a single ball or a single clump. Note that users are encouraged to use clump replicate and refer to a preexisting clump template (see the clump template create command) when creating clumps.
  • The ball generate and clump generate commands can be used to generate, at once, a specified number of balls or clumps without overlap as follows. PFC will attempt to generate the specified number of balls/clumps in a given number of tries. For each ball/clump to be generated, a random size and position (and orientation for clumps only) is chosen given the user’s input, and the prospective ball/clump is tested for overlap with previously created balls/clumps. If it is found to not overlap existing balls/clumps, then it is created; otherwise it is rejected and another try is performed. The process ceases when the specified number of balls/clumps to be generated is reached or when the specified number of tries is reached. In the latter situation, a warning is issued stating the number of balls/clumps that were actually generated.
  • The ball distribute and clump distribute commands can be used to distribute balls or clumps within a given volume to achieve a specified solid fraction without testing for overlap as follows. For each ball/clump to be distributed, a random size and position (and orientation for clumps only) is chosen given the user’s input, and the prospective ball/clump is added until the specified solid fraction is reached. Since the algorithm does not prevent overlaps, the generated assembly is out of equilibrium, and the large overlaps will give rise to large forces during the first steps, which will result in high kinetic energy that needs to be removed from the system. Also, note that the clump distribute command should be used with care, because initial overlaps between clumps may result in clumps being interlocked.

Note that FISH utilities can also be used to create or modify balls or clumps, as well as walls.

back to top

… setup and control boundary conditions

There are typically three ways of applying boundary conditions to a PFC model:

  1. Using walls as boundaries: Walls do not obey to Newton’s laws of motion in PFC. In some cases, they can be devoid of any motion and act, for instance, as a fixed container. However, in other cases, the user will need to impose their kinematics. For instance, a cutting tool may be modeled as a wall driven at constant velocity through a particle assembly, or the blades of a mixer can be modeled as rigid walls with an imposed rotational velocity, while the outer stator is modeled as a fixed, rigid wall container. The reaction force exercised by the particle assembly onto a wall can also be monitored and used to design advanced servo-control algorithms in order to adjust the wall’s motion to maintain a prescribed stress-boundary condition. An example of servo-control algorithm is described in the example application “Probing a Granular Specimen.”
  2. Using particles as boundaries: It is possible to identify select particles in the model and either control their velocity or apply an external force to them. Impedance match boundaries can, for instance, be modeled by applying forces to boundary particles as illustrated in the example “Wave Propagation in Particle Assemblies.”
  3. Using periodic boundaries: If the model domain is set to be periodic (see the item above) in one or multiple directions, then this condition will apply.

back to top

… control initial conditions

The initial conditions in a granular assembly are generally inherited from its packing history and applied boundary conditions. For instance, it is often desirable to adjust the boundary conditions to install a relevant initial stress state. Depending on the contact models in use (see the next topic), the user may also have the ability to initialize the forces and properties in the contacts to achieve a desired initial stress state.

back to top

… select appropriate contact model(s)

Particles interact with other particles and with walls through the forces that develop at contacts. Contact mechanics is embodied in particle-interaction laws that employ a soft-contact approach, for which all deformation occurs at the contacts between the rigid bodies. The particle-interaction laws are referred to as contact models; each contact is assigned a single contact model.

Although a particle assembly may exhibit complex nonlinear constitutive behavior, this behavior is generally achieved through the use of relatively simple contact models. Several contact models are provided with PFC, and other contact models maybe encoded using the C++ Plugins additionnal feature (Refer to “Contact Models” for more details).

The Contact Model Assignment Table (CMAT) has been introduced in PFC to ease the process of selecting contact models. This tool is powerful enough to allow the creation of complex models, for instance, using several contact models and with heterogeneous distributions of mechanical properties. The user is encouraged to look at the tutorial example “Using the CMAT” for a thorough discussion on this subject.

back to top

… calibrate material behavior

As discussed in the topic “… create particle assemblies” above, the macroscopic mechanical behavior of an assembly of discrete bodies is intimately tied to the fabric of the assembly, thus to its packing history. However, the mechanical behavior of a given packing obviously also emerges from the selection of the micro-parameters of the model. PFC separates micro-parameters into two categories, attributes and properties, as follows:

  • Attributes are intrinsic characteristics of model components, such as position, velocity, size, etc. Bodies (balls, clumps, and walls), pieces (balls, clumps, pebbles, and wall facets) and contacts may have attributes. An example of body/piece attributes are the clump and pebble positions; even though the pebble is part of a clump, its position is a distinct attribute. The list of attributes is unchanging (see the ball attribute, clump attribute, and wall attribute commands).
  • Properties, on the other hand, apply exclusively to contacts and pieces. The properties of a contact depend on the contact model being used; each contact model defines a set of properties that control its constitutive behavior. Contact properties may be assigned or modified with the contact property and contact method commands. The CMAT can also be used to assign contact models and contact model properties to newly created contacts (see the previous topic). Piece properties are lists of string/value pairs specified by the user with the ball property, clump property, and wall property commands. These string/value pairs represent the surface conditions of the pieces. Pieces are devoid of properties by default. Contact models may use the piece properties to determine the resulting interaction through property inheritance. For instance, if the physical specimen to be modeled is composed of both hard and soft balls, the balls could be given different properties. The distinction between attributes and properties is demonstrated in the “Attributes and Properties” tutorial, and usage of the property inheritance mechanism is illustrated in the tutorial example “Using the CMAT.”

Although it is relatively easy to assign chosen attributes and properties to a PFC model, it is often difficult to choose such parameters so that they represent a real material. For codes that model continua (e.g., finite-element or finite-difference programs), the input parameters (such as moduli and strengths) can be derived directly from measurements on laboratory samples. However, PFC works at a more basic level; it “synthesizes” material behavior from the micro-components (equivalent grains and interfaces) that make up the material. If the mechanical properties and geometry of these micro-components are known, then they can be used directly as input to PFC. This approach is referred to as “direct modeling.” But if we are trying to simulate a solid, such as rock, we may not know the mechanical properties of the microscopic constituents. In this case, we must use “inverse modeling” (i.e., perform a number of tests on samples with assumed parameters and compare the results with the desired response of the real intact material). When a match has been found, the corresponding set of parameters may be used in the full simulation.

back to top

… monitor a simulation

It is often useful to understand the evolution of relevant quantities during the course of a simulation and not only analyze the final state that is produced. Before performing simulation steps, the user is encouraged to identify quantities that are relevant for the specific situation being investigated and activate mechanisms to record their time evolution. Several mechanisms may be used in PFC:

  • Histories: The history mechanism allows one to record the value of a variable periodically during cycling (at a specified step interval). PFC provides a large set of built-in variables that can be monitored using this mechanism. CS:down the line: build a “list of commands in pfc that can create histories” list, put it on the main “history” page, then put a link to that list in the preceding line. Additionally, it is possible to monitor the value of a FISH variable or the return value of a FISH function, or a value computed with the measure logic (see below).
  • Measurement regions: The measure logic can be used to compute average quantities over {circular (2D); spherical (3D)} regions of the model. These quantities include porosity, stress and strain-rate tensors, coordination number, and particle size distribution. They can be sampled at periodic intervals using the history mechanism discussed above. Any number of measurement regions may be placed in the model.
  • Particle traces: Particle traces may be activated to record the positions and velocities of model components at periodic step intervals. The user can then plot the recorded particle traces, which show the trajectories of the objects being tracked colored by velocity magnitude.
  • SAV files: The user may periodically save intermediate state of the model into SAV files, using the model save command. These saved states can be restored (with the model restore command) when the simulation is completed in order to analyse intermediate states of the system. SAV files contain the entire model data, and the state being restored can be used as a starting point for further calculation (for sequential modeling or parameter sensitivity analysis, for instance). However, because SAV files contain the entire model data, they are generally heavy and saving a large amount of intermediate states may considerably use up memory. The model result files discussed below may constitute an interesting alternative when only select information about the model needs to be recorded periodically.
  • Model result files: The model result logic allows users to decide on select information attached to balls, walls, or clumps that should be periodically recorded during the simulation. Information can be stored in program memory or in the form of several binary files (the latter preventing heavy usage of RAM). The ball results, wall results, and clump results commands can be used to activate the logic independently for balls, walls, and clumps, respectively. Please consult the description of these commands for a detailed discussion of the logic. The example “Fragmentation Analysis during a Uniaxial Compression with Crack Tracking Using Fractures” illustrates how the ball result logic can be used to record ball fragment ID during a compression test. Note that prior to performing simulation steps, the model result logic must be activated and relevant quantities to be recorded must be selected.

back to top

… solve to a target termination criterion

Two commands can be used to perform simulation cycles: the model cycle and model solve commands. The model cycle command is used to perform a given number of simulation steps. Although this can be useful in many situations, it is often preferable to execute a cycle sequence until a relevant criterion is met, for instance, a target equilibrium condition or a target physical time (remember that since PFC uses an adaptive timestep, which may change during the cycle sequence). The model solve command is more elaborate and accepts one or several ending criteria. The user can also implement a custom FISH function to assess if the calculation should continue or stop and invoke it with the fish-halt keyword. Please refer to the model solve command description for further details.

back to top

… perform sequential modeling

PFC is flexible in the way it handles sequential events; almost anything can be changed at any stage. For example, particles may be deleted to simulate excavation. Particles may also be added to simulate construction or filling of an opening, but there are some precautions. First, if a newly introduced particle overlaps any existing particles, then normal forces, which may disturb the existing system, may be generated at subsequent cycles (depending on the contact model being used). A similar caution applies if walls are added to the system. Second, if a newly compacted assembly is required, the compaction procedure should be done in a way that minimizes disturbance to the existing particles. For example, the existing particles may be fixed (with zero velocities), while the new particles are being expanded to fit into an opening. When equilibrium is obtained, the fix condition on the rest of the particles may be released (and further cycling done to restore equilibrium again).

All model data is saved to a binary file with the model save command. The data can then be restored at any time using the model restore command. After a state has been restored, alteration of the model and additional cycles can be performed to conduct another modeling stage or to perform a sensitivity analysis, for example.

back to top

… insert custom operations in the calculation cycle

A PFC simulation consists of performing a sequence of cycles until a target termination criterion is met. Each cycle consists of a series of operations executed in a given order, as detailed in the “PFC Model Formulation” section. The user has the ability to insert custom computation at specific points in the calculation cycle, using FISH callbacks. The tutorial example “Using FISH Callbacks” discusses this capability in detail.

back to top