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 a custom Contact Model as a User Defined Library (UDL) written in C/C++.

To create a new Contact Model:
  1. Create a directory in which you want to save the new Contact Model project.
  2. Copy the following header files into the directory that you have created:
    • IPlug-inContactModel.h
    • Plug-inContactModelCore.h
    • IPlug-inContactModelV3_9_0.h
    • Plug-inConstants.h
  3. If required, copy the following optional header files:
    • CGenericFileReader.h
    • Helpers.h
  4. Create a new class (CNewContactModel) derived from the Contact Model interface you want to use (for example, IPlug-inContactModelV3_9_0).
  5. Save the class declaration to a header file (for example, CNewContactModel.h).
    This file must consist of declarations of the methods in the selected interface, any extra methods required, and any variables.
  6. Implement all the methods defined in your header file.
  7. Save the file as a .cpp file (for example, CNewContactModel.cpp).
  8. Create a new .cpp file with implementations of the methods in Plug-inContactModelCore.h. For example, save this file as NewContactModel.cpp.
  9. Compile all your src files and link them together into .dll (Windows) or .so (Linux) library files.
  10. Ensure that the library and optional preferences file are saved in the Plug-in folder (as specified in Tools > Options > File Locations), or in the same folder as thesimulation_name.dem file (only applicable for EDEM versions 2025.1 and higher).
  11. Start EDEM and then select the required Contact Model category from the Interaction dropdown list in the Physics section.
  12. Click the + dropdown list and then select the new Contact Model.
    The following methods are available in the Contact Model interface IPlug-inContactModelV3_9_0:
    Method Description Type
    getPreferenceFileName Retrieves the name of the config file used by the UDL. Setup
    setApiParametersTemplate Allows you to set up the plug-in parameter values. They can be modified from the UI. Setup
    getModelType Indicates the model type of the plug-in. This is a mandatory method for every model. Setup
    getExecutionChainPosition Indicates the position in the Contact-Model chain for the plug-in to be executed. This is a mandatory method for every model. Setup
    setFilePath Called inside the starting() method to provide the plug-in with the full simulation path (including the simulation file name). Setup
    getGpuFileName Initializes the GPU plug-in by accepting the file name without an extension. If empty, the model will not be supported on the GPU solver. Setup
    getGpuSourceSize You must set the size of the char array, which contains the CUDA source code, if libraryProvidesGpuSource is enabled. Setup
    getGpuSource You must set the char array with the CUDA source code, if libraryProvidesGpuSource is enabled. Setup
    setup Initializes the plug-in by reading any config files, opening temporary files, generating data structures, or other setup tasks. Setup
    starting Called once at the start of a simulation to indicate that 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 that processing is complete and the model should free any temporary storage and close/release file/api/socket handles. Simulation
    calculateForce This function is called when two elements are in contact with each other. These elements can either be two spheres, or a sphere and a Geometry element. For two spheres, the function is called when their contact radii cross. For a sphere and a Geometry, the function is called when the contact radius of the sphere touches the Geometry. Element 1 is always a sphere, and element 2 can be either another sphere or a Geometry element. 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 conflict with the existing properties. Setup
    configForTimeStep Called during processing, at the start of each Time Step. Simulation
    This must be empty for CUDA solvers and implemented in the CUDA file instead.
    getParticleParameterData Retrieves particle parameter data in buffer format. Setup
    getSimulationParameterData Retrieves simulation parameter data in buffer format. Setup
    getPartPartContactParameterData Retrieves Particle-Particle contact parameter data in buffer format. Setup
    getPartGeomContactParameterData Retrieves Particle-Geometry contact parameter data in buffer format. Setup
    getDetailsForCounterProperty Functions are provided in IContactManagerApi_X_X (CPU) and CApiContact (CUDA) to add values to counter properties. This can be done by treating the data as a 1D histogram spanning the range [minVal,maxVal], or by specifying the bin index.

    This method allows you to use the counter properties as a histogram or a general array of counters.

    		 Setup
    calculateTriangleDeformation Calculates deformation for triangular elements and returns parameters for the updated mesh element. Simulation
    getDeformationTransformSpace Defines the Global or Local reference frame for triangle deformation. Simulation
    setApiManager This is called once during the loading of the API to set the apiManager. Setup
    Note: The methods of type 'Setup' are called once at the start of the simulation, whereas, those of type 'Simulation' are called during the simulation. For more information about how the methods are called, see the Help included in the EDEM installation folder..