Contact Model User Defined Libraries

A Contact Model UDL consists of a shared library file and, optionally, a file containing preferences.

Using the EDEM API, you can write and compile custom contact models as a User Defined Library (UDL) written in C/C++.

Creating a New Contact Model

  1. Create a directory to contain the new contact model project.
  2. Copy the following header files into the directory:
    1. IPluginContactModel.h
    2. PluginContactModelCore.h
    3. IPluginContactModelV3_3_0.h
    4. PluginConstants.h
  3. If required, copy the following optional header files:
    1. CGenericFileReader.h
    2. Helpers.h
  4. Create a new class (CNewContactModel) derived from the contact model interface you want to use (for example, IPluginContactModelV3_3_0).
  5. Save the class declaration to a header file (for example, CNewContactModel.h). This should consist of declarations of the methods in the chosen interface, any extra methods required, and any variables.
  6. Implement all of the methods defined in your Header File and save as a cpp file (for example, CNewContactModel.cpp).
  7. Create a new .cpp file with implementations of the methods in PluginContactModelCore.h. For example, save as NewContactModel.cpp.
  8. Compile all of your src files and link them together into .dll (Windows) or .so (Linux) Library files.
  9. Ensure that the library and optional preferences file are in the contact model folder (as specified with Tools > Options > File Locations) or in the same folder as the simulation_name.dem file (only for versions EDEM 2017 onwards).
  10. Start EDEM then select the required contact model category from the Interaction pull-down in the Physics section.
  11. Click the + dropdown and then select the new contact model.

Contact Model API v3.4.0

The contact model interface IPluginContactModelV3_4_0 provides these methods:

 

Method Description Type
getPreferenceFileName Retrieves the name of the config file used by the UDL. Setup
isThreadSafe If the UDL’s calculateForce() method is thread-safe then this method should return true. Thread safe programming requires a number of conventions and restrictions to be followed. If in doubt set this to return false. Not applicable for CUDA API. Setup
usesCustomProperties Indicates whether the UDL wants to register or receive custom property data. Setup
getModelType     Indicates what model type the plugin is. This is a required method for every model. Setup
getExecutionChainPosition Indicates the position in the contact-model chain for the plugin to be executed. This is a required method for every model. Setup
usesContactFactor Indicates whether the UDL wants to use contact factor. Contact factor is the number of contacts between two particles or between one particle and different mesh elements belonging to the same plane. Setup
setFilePath     Called inside starting() method to provide the plugin with the full simulation path (including the simulation filename). Setup
getGpuFileName    Initializes the GPU plugin by accepting it's file name without extension. If empty, the model will not be supported on the GPU solver. Setup
setup Initializes the plugin by reading any config files, opening temporary files, generating data structures or any other setup work. Setup
starting Called once at the start of a simulation to indicate processing is about to begin and the model should allocate any temporary storage and retrieve any required file/API/socket handles. Simulation
stopping Called once at the end of a simulation to indicate processing is finished and that the model should free any temporary storage and close/release file/api/socket handles. Simulation
calculateForce Called when two elements are in contact with each other. These may be surfaces (in-contact when their contact radii cross), or a surface and a geometry element (when the contact radius of the surface touches the surface geometry). Also used to set contact forces and deltas for custom properties. Not required for CUDA solvers. Simulation
configForTimeStep Called during processing, at the start of each Time Step. Not used for CUDA solvers, should be implemented in CUDA file. Simulation
getNumberOfRequiredProperties Returns the number of custom properties this UDL wants to register with the system. Setup
getDetailsForProperty Retrieves details for a given property. These properties will then be registered with the system if they do not clash with any existing properties. Setup
getGeometryParameterData Retrieves geometry parameter data in a buffer format. Setup
getParticleParameterData Retrieves particle parameter data in a buffer format. Setup
getPartPartContactParameterData Retrieves particle-particle contact parameter data in a buffer format. Setup
getPartGeomContactParameterData Retrieves particle-geometry contact parameter data in a buffer format. Setup
getSimulationParameterData Retrieves simulation parameter data in a buffer format. Setup
calculateTriangleDeformation Calculates deformation for triangle elements and returns parameters for updated mesh element. Simulation
deformationEnabled Enables and disables mesh deformation. Simulation
ignoreZeroForceTriangles Skips geometry deformation call if force acting on geometry element is zero. Simulation
getDeformationTransformSpace Defines Global or Local reference frame for triangle deformation. Simulation

The methods of type "Setup" are called once, at the start of the simulation, whereas those of type "Simulation" are called during the simulation.

See the API documentation for more details.

(c) 2023 Altair Engineering Inc. All Rights Reserved.

Intellectual Property Rights Notice | Technical Support