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

A “Project Template” is provided as the only supported way to create contact model projects in MSVS 2019. The template presumes that PFC is installed in the default directory (i.e., C:\Program Files\Itasca\PFC700). If not, some project settings will need to be edited to point directly to the installation location.

1. Assuming PFC 7.0 and MSVS 2019 are already installed, find the file “ItascaProjectTemplates.vsix” in the PFC 7.00 installation “PluginFiles” directory.
2. Execute this plugin installation file by double-clicking on it. (Administrator privileges on the computer may be required to do this.) Complete the installation as prompted.
3. Launch Visual Studio 2019, then:
   1. Select “Create a new Project” from the options on the right of the startup dialog.
   2. Type ‘itasca’ in the “Search for project templates” field.
   3. Select the “Itasca Contact Model” option and press “Next”.
   4. Assign a name to the project. You also have the option to choose a new location in which to place the new project and solution. Then press “Create”.
4. A dialog will appear, asking you to name your new contact model. This will be the name of the class, and the name used to refer to the model in the code. This name can be changed later by directly editing the source. If you have more than one compatible version of an Itasca code installed, select the one you are planning on using the contact model with first. Press “Accept and Close”.
5. A project will be created for you, using the source to the internal Linear contact model as a starting point. This can be freely modified by you to match your specific model behavior.
6. You should update the solution to use the latest version of the Windows SDK and runtime libraries. Do this by right-clicking on the solution line in the “Solution Explorer” and selecting “Retarget Projects.”
7. Choose the {“Release2D” (PFC2D)); “Release” (PFC3D)} solution configuration. 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 (DVect <DVect>) and angular vector (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 THREED or checking explicitly for the value of DIM are handy in these circumstances.

If the plug-in DLL has been placed in the directory
{“exe64\plugins\contactmodelmechanical2D” in 2D;
 “exe64\plugins\contactmodelmechanical3D” in 3D},
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\pfc700”.
• The directory where the PFC executable resides and all sub-directories.
• The current directory and all sub-directories.

Note that model state (SAV) files with model data that utilize custom contact model(s) will require that the contact model(s) 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.

• Adhesive Rolling Resistance Linear Model
• Burger’s Contact Model Implementation
• EEPA Model Implementation
• Flat-Joint Model Implementation
• Hertz Model Implementation
• Hysteretic Model Implementation
• JKR 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
• Spring Network 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 getSphereList, getDiskList, and getCylinderList getCylinderList methods), and archiving methods. These methods have default implementations.
• In order for the contact model to save and restore, the archive method must be implemented.
• The getIndex and 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 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 setNonForcePropsFrom and 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 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).