Particle Body Force User Defined Libraries (UDL)

A Particle Body Force 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 UDL written in C/C++.

Creating a New Particle Body Force UDL

  1. Create a directory to contain the new Particle Body Force project.
  2. Copy the following header files into the directory:
    1. IPluginParticleBodyForce.h
    2. PluginParticleBodyForceCore.h
    3. IPluginParticleBodyForceV3_3_0.h
    4. PluginConstants.h
    5. Helpers.h
  3. Create a new class (CNewParticleBodyForce) derived from the particle body force interface you want to use (for example, IPluginParticleBodyForceV3_3_0).
  4. Save the Class declaration (consisting of declarations of the methods in the chosen interface and any extra methods needed for your functionality and any variables) to a header file (for example, CNewParticleBodyForce.h).
  5. Implement all of 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 PluginParticleBodyForceCore.h. Save as  NewParticleBodyForce.cpp.
  7. Use command line or create a Makefile (or equivalent) to build and compile .dll (Windows) or .so (Linux) library files.
  8. Ensure that the library and optional preferences file are in the particle body force 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).
  9. Start EDEM and then select the required particle body force model category from the Interaction pull-down in the Physics section.
  10. Click the + dropdown and then select the new particle body force model.

Particle Body Force API v3.3.0

The interface IPluginParticleBodyForceV3_3_0 provides these methods:

Method Description Type
getPreferenceFileName Retrieves the name of the config file used by the UDL. Setup
isThreadSafe If the UDL 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.
This has no effect on CUDA solver. 		Setup
usesCustomProperties Indicates whether the UDL wishes to register or receive custom property data. Setup
setFilePath Called inside starting() method to provide the plugin with the full simulation path (including the simulation filename). Setup
getGpuFileName Initializes GPU plugin by accepting cl file name without extension. If empty, the model will not be supported on the GPU solver. Setup
setup Initializes the UDL by giving it a chance to read any config files, open temporary files, generate data structures or any other one off setup work. Setup
starting Called once at the start of the simulation to indicate processing is about to begin and the model should allocate any temporary storage and retrieve any file/api/socket handles it may need. Simulation
stopping Called once at the end of the simulation to indicate processing is finished and that the model should free any temporary storage and close/release file/api/socket handles. Simulation
externalForce Called every single Time Step for every single particle. It allows you to add a particle body forces (for example, electromagnetic force, 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 clash with any existing properties. Setup
configForTimeStep Called during processing, at the start of each Time Step.
This should be empty for CUDA solvers and implemented in the CUDA file instead.		 Simulation
getParticleParameterData Retrieves particle parameter data in a buffer format. Setup
getSimulationParameterData Retrieves simulation parameter data in a buffer format. Setup
processParticleOfInterest Process particles that were marked for additional processing in externalForce call. Simulation

Methods of type 'Setup' are called only once at the start of a 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