Contact Model Plug-ins

Introduction

The methodology of writing a contact model in C++ for operation in PFC is described in this section. This includes descriptions of the base class, how to create a Visual Studio project, loading the resulting DLL, and how PFC data are accessed.

Creating Contact Model DLLs from the MSVS Project Template

We provide a “Project Template” that is the only supported way to create FISH intrinsic projects in MSVS 2017. The template presumes that PFC is installed in the default directory (i.e., C:Program FilesItascaPFC600). If not, you will need to edit some project settings to point directly to your installation location. Follow the steps below:

1. Assuming PFC, Qt 5.12 and MSVS 2017 are already installed, find file “model.zip” in the pluginfilestemplatefiles directory inside the PFC installation directory.
2. Place this zip file in your DocumentsVisual Studio 2017TemplatesProjectTemplates folder.
3. Launch MSVS and select File -> New -> Project from the menu.
4. Select the “Visual C++” category select the “model” project.
5. Assign a name for the new project. You may also choose a new location in which to place the new project and solution.
6. A project will be created for you using some simple example functions as a source. This project can be freely modified to match your specific desired behavior.
7. Choose the {Release2D; Release} solution configuration for use with {PFC2D; PFC3D}, respectively. If one loads a DLL built for PFC2D into PFC3D, unexpected results may occur, including code crashes.

It is important to note that there are both 2D and 3D targets for contact models. In general, all contact models are written in a generic way to operate in both 2D and 3D. The main difference between 2D and 3D, besides the DLL names, are the preprocessor definitions {DIM=2 in 2D; DIM=3 in 3D}. There are generic vector (:pfc:`DVect <DVect>`) and angular vector (:pfc:`DAVect <DAVect>`) type definitions that change depending on the value of DIM. Occasionally there is a need for 2D and/or 3D specific code sections; the macro definition :pfc:`THREED <THREED>` or checking explicitly for the value of DIM are handy in these circumstances.

If the plug-in DLL has been placed in the {“exe64\plugins\contactmodelmechanical2D” in 2D; “exe64\plugins\contactmodelmechanical3D” in 3D} directory, then it will be loaded automatically at GUI start-up. Otherwise, the plug-in may be loaded explicitly by using the program load contactmodelmechanical command. The following directories are searched automatically when attempting to load a plug-in, in order:

• The directory in the “dir” registry entry, if present, and all sub-directories. The user must set this in registry location “HKEY CURRENT USER\Software\Itasca\pfc2d600” or “HKEY CURRENT USER\Software\Itasca\pfc3d600”.
• The directory where the PFC executable resides and all sub-directories.
• The current directory and all sub-directories.

Note that model state (SAV) files created with custom contact models loaded require that these contact models be present upon restore. PFC will attempt to automatically find and load these contact models during restore; this process will fail if the corresponding DLL is not in one of the locations PFC automatically searches.

Contact Model Implementations

The easiest way to implement a custom contact model is to familiarize oneself with the implementations of the PFC built-in contact models. These are provided below.

• Adhesive Rolling Resistance Linear Model
• Burger’s Contact Model Implementation
• Flat-Joint Model Implementation
• Hertz Model Implementation
• Hysteretic Model Implementation
• Linear Contact Model Implementation
• Linear Contact Bond Model Implementation
• Linear Parallel Bond Model Implementation
• Null Contact Model Implementation
• Rolling Resistance Linear Contact Model Implementation
• Smooth-Joint Model Implementation
• Soft-Bond Model Implementation

Note the following points:

• The null implementation demonstrates the minimal set of member functions that must be implemented for a contact model to operate. One may exclude energies, methods, callback events, custom plotting (the :pfc:`getSphereList <itascaxd::IContactModel::getSphereList>`, :pfc:`getDiskList <itascaxd::IContactModel::getDiskList>`, and :pfc:`getCylinderList <itascaxd::IContactModel::getCylinderList>` methods), and archiving methods. These methods have default implementations.
• In order for the contact model to save and restore, the :pfc:`archive <cmodelsxd::ContactModel::archive>` method must be implemented.
• The :pfc:`getIndex <itascaxd::IContactModel::getIndex>` and :pfc:`setIndex <itascaxd::IContactModel::setIndex>` functions should use a static index value. When a contact model is registered, it is assigned an index for easy lookup without use of the string name.
• The :pfc:`getName <itascaxd::IContactModel::getName>` return value is the keyword with which one references the contact model using commands and FISH.
• In order to use the contact model with facet contacts utilizing the full resolution mode (see the wall resolution command), one must implement the :pfc:`setNonForcePropsFrom <itascaxd::IContactModel::setNonForcePropsFrom>` and :pfc:`propagateStateInformation <itascaxd::IContactModelMechanical::propagateStateInformation>` methods. The former is used when defining proximity contacts; it allows one to basically copy all properties but the force-related properties to a new contact. The :pfc:`propagateStateInformation <itascaxd::IContactModelMechanical::propagateStateInformation>` method, on the other hand, is used to transfer forces from one contact to another (i.e., when a contact between a flat, faceted wall and a ball migrates from one facet to another).

Was this topic helpful? Let us know...