Particle Body Force 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 particle body forces as a User Defined Library (UDL) written in C/C++.

To create a Particle Body Force UDL:
  1. Create a directory in which you want to save the new Particle Body Force project.
  2. Copy the following header files into the directory that you have created:
    • IPlug-inParticleBodyForce.h
    • Plug-inParticleBodyForceCore.h
    • IPlug-inParticleBodyForceV3_9_0.h
    • Plug-inConstants.h
    • Helpers.h
  3. Create a new class (CNewParticleBodyForce) derived from the Particle Body Force interface you want to use (for example, IPlug-inParticleBodyForceV3_9_0).
  4. Save the class declaration to a header file (for example, CNewParticleBodyForce.h).
  5. Implement all the methods defined in your header file and save as a .cpp file (for example, CNewParticleBodyForce.cpp).
  6. Create a new .cpp file with implementations of the methods in Plug-inParticleBodyForceCore.h.
  7. Save this file as NewParticleBodyForce.cpp.
  8. Create a new .cpp file with implementations of the methods in Plug-inParticleBodyForceCore.h.
  9. Save this file as NewParticleBodyForce.cpp.
  10. Use command line or create a makefile (or equivalent) to build and compile .dll (Windows) or .so (Linux) library files.
  11. Ensure that the library and optional preferences file are saved in the Plug-in model folder (as specified in Tools > Options > File Locations), or in the same folder as the simulation_name.dem file (only applicable for EDEM versions 2025.1 and higher).
  12. Start EDEM and then select the required Particle Body Force Model category from the Interaction dropdown list in the Physics section.
  13. Click the + dropdown list and then select the new Particle Body Force Model .
    The following methods are available in the Particle Body Force Model interface IPlug-inParticleBodyForceV3_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
    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
    externalForce Used to add particle body forces (such as electromagnetic or drag forces) to particles. This function is called every single time step for every single particle. Simulation
    configForTimeStep Called during processing, at the start of each Time Step. Not used for CUDA solvers, but must be implemented in the 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 conflict with the existing properties. Setup
    getParticleParameterData Retrieves particle parameter data in buffer format. Setup
    getSimulationParameterData Retrieves simulation parameter data in buffer format. Setup
    setApiManager Called once during the loading of the API to set the apiManager. Setup
    processParticleOfInterest Processes particles that were marked for additional processing in the externalForce call. Particle modifications are not allowed. 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.