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:
    • IPluginContactModel.h
    • PluginContactModelCore.h
    • IPluginContactModelV3_3_0.h
    • PluginConstants.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, IPluginContactModelV3_3_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 PluginContactModelCore.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 Contact Model folder (as specified in Tools > Options > File Locations), or in the same folder as thesimulation_name.dem file (only applicable for EDEM versions 2017 and above).
  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 IPluginContactModelV3_4_0:
    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 must 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 the model type of the plugin. This is a mandatory method for every model. Setup
    getExecutionChainPosition Indicates the position in the Contact-Model chain for the plugin to be executed. This is a mandatory 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 the starting() method to provide the plugin with the full simulation path (including the simulation file name). Setup
    getGpuFileName Initializes the GPU plugin by accepting the file name without an 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 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
    externalForce Called at every single Time Step for every single particle and allows you to add particle body forces (for example, electromagnetic force or drag force) to particles.

    This is not used by CUDA solvers and should be left empty.

    		 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
    processParticleOfInterest Processes particles marked for additional processing in the externalForce call. Simulation
    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..