EDEM API 4000 Particle Replacement

This tutorial describes how to add an existing API model to a simulation which includes Bonded Particles. The API model replaces large spheres with clumps of smaller spheres.

Objective

The objective of this tutorial is to:
  • Use the Bonded Particle Model V2
  • Load a Particle Body Force
  • Load a Custom Factory
  • Post-process the customized simulation
  • Introduce CUDA GPU-API

This tutorial uses a library file compiled with Visual Studio 2019 and a simulation already set up using EDEM version 2024.1. It also uses the Particle Replacement API and has been written for CPU and CUDA GPU.

Figure 1. (1) Solid spheres are created and allowed to settle. (2) The large particles are replaced with bonded Meta-Particles. (3) The bonded Meta-Particles are damaged in the mill, and (4) eventually break up.


Important: Copy the following tutorial files into your working directory before running the simulation:
  • ParticleReplacement.dll
  • Particle_Replacement_prefs.txt
  • Particle_Cluster_Data.txt
  • ReplacementTutorial.dem
  • ReplacementTutorial.dfg
  • The ReplacementTutorial_data folder

EDEM API Functions

The following key API files are included with this tutorial in the src folder:
  • CRemoval.cpp is the CPU Particle Body Force Physics model.
  • ParticleReplacementBreakage_v3_7_0.cu – Is the CUDA GPU Physics model. This API file is used in the initial development of the CUDA code but when compiled the contents are copied into the CRemoval.cpp file under GPU_SOURCE and is no longer used.
  • To replace particles, one type of particle is removed and its position is stored and passed to the CReplacementFactory function for creation of new particles in the same position.
  • EDEM Factories run on CPU only. To avoid passing information from a GPU to a CPU (a complex and computationally slow process), a processParticleOfInterest() function has been implemented in the code. This function runs only on CPU, allowing efficient data transfer between CPU and GPU.

During simulation, the models perform the following:

Particle Body Force
  1. Loading: Reading in Preference .txt Data
    1. When loading the library file into EDEM the Particle_Replacement_prefs.txt file is read using the Setup function detailed in CRemoval.cpp.
    2. This library file contains the name of the particle to replace (Whole) and the Type to replace it with (Fraction).
    3. The StartBondingTime (0.4 s) is also read from the text file.
  2. Running: Removing and storing Particle data
    1. At the StartBondingTime, the code tags the Whole particles as ‘Particles of Interest’ using the externalForce function. Both the CPU and GPU can tag Particles of Interest.
    2. At the end of the Time Step, the processParticleofInterest function is called for the CPU only.
      1. The Size (scale), position, and velocity are written to an array called ParticleList, and stored in the CPU memory.
      2. The Whole particle is removed using the markForRemoval function.
Custom Factory
  1. Loading: Reading in Preference .txt Data
    1. When loading the library file, the Particle_Cluster_Data.txt file is read and stored in an array.
  2. Running: Creating Particles
    1. The factory always runs first in the process loop (Factory > Contact Model > Particle Body Force. However, the factory is not activated until the ParticleList contains data. This process occurs after the bonding time has been reached.
    2. If the ParticleList contains data (particles), then the factory will create new particles.
      1. The ParticleList contains the position of the original Whole particle.
      2. This position is used to create multiple Fraction particles in the same area.
      3. The factory loop runs until all the particles in the list have been processed and replaced with the Fraction particles.
    3. When creating the particles, a Custom Property called CREATIONTIME (Bond Creation Time) is assigned to the particles. This property has a value of the current simulation time.
EDEM Bonded Model V2
  1. The built-in Bonded model utilizes the CREATIONTIME custom property.
  2. Any particles in contact which fulfil the following two conditions are bonded together:
    1. Both particles have the same CREATIONTIME value.
    2. The CREATIONTIME value is equal to the current simulation time.

    This is an example of a custom API model integrating with an internal EDEM model. The API configures the conditions which triggers the internal model to bond the particles.