Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
cfd_dem_coupling.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2021-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_cfd_dem_coupling_h
5#define lethe_cfd_dem_coupling_h
6
8
10#include <dem/data_containers.h>
11#include <dem/dem.h>
19
20#include <deal.II/base/work_stream.h>
21
22
23
24using namespace dealii;
25
26/**
27 * @brief Solver class for coupled Computational Fluid Dynamics and Discrete Element Method (CFD-DEM) simulations.
28 *
29 * This class implements a two-way coupled CFD-DEM solver that combines the
30 * Volume-averaged Navier-Stokes (VANS) equations for fluid flow with the
31 * soft-sphere Discrete Element Method for particle dynamics. The solver
32 * enables simulation of fluid-particle interactions in systems containing
33 * dense particle suspensions.
34 *
35 * The CFD component uses Galerkin Least Squares (GLS) stabilization for
36 * the VANS equations, while the DEM component handles particle-particle
37 * and particle-wall collisions using the soft-sphere contact model.
38 *
39 * @tparam dim Spatial dimension of the simulation (2 or 3)
40 * @tparam PropertiesIndex Index of the properties used within the
41 * ParticleHandler
42 *
43 * @ingroup solvers
44 */
45template <int dim, typename PropertiesIndex>
46class CFDDEMSolver : public FluidDynamicsVANS<dim, PropertiesIndex>
47{
48public:
49 /**
50 * @brief Constructor for the CFD-DEM solver.
51 *
52 * @param[in] nsparam Simulation parameters containing all CFD-DEM
53 * configuration options
54 */
56
57 /**
58 * @brief Destructor for the CFD-DEM solver.
59 */
60 ~CFDDEMSolver() override;
61
62 /**
63 * @brief Engine of the CFD-DEM solver. Calls all the necessary functions to
64 * set parameters, solve the simulation, and finish the simulation.
65 */
66 virtual void
67 solve() override;
68
69 // The members below are protected rather than private so that the unit tests
70 // of the tests/fem-dem folder can derive from this class to drive the
71 // restart and the load balance of the solver directly, as is done for the
72 // other solvers.
73protected:
74 /**
75 * @brief Set up the various parameters related to the DEM simulation.
76 *
77 * Initializes DEM-specific parameters including contact detection methods,
78 * integration schemes, and material properties based on the simulation
79 * parameters provided during construction.
80 */
81 void
83
84 /**
85 * @brief Initialize the particle size distribution and related parameters.
86 *
87 * Sets up the particle size distribution type for the simulation and
88 * calculates the maximum particle diameter and neighborhood threshold
89 * squared values required for contact detection algorithms.
90 */
91 void
93
94 /**
95 * @brief Set up the time integration method for particle motion.
96 *
97 * Creates and configures the appropriate integration scheme for solving
98 * particle equations of motion (e.g., velocity Verlet, explicit Euler).
99 *
100 * @return Shared pointer to the configured integration object
101 */
102 std::shared_ptr<Integrator<dim, PropertiesIndex>>
104
105 /**
106 * @brief Initialize fundamental DEM simulation parameters.
107 *
108 * Sets up basic DEM parameters including time stepping, contact detection
109 * frequency, and other core simulation settings.
110 */
111 void
113
114 /**
115 * @brief Read DEM restart files from a previous simulation.
116 *
117 * Loads particle data, contact information, and other DEM state variables
118 * from checkpoint files to continue a previously interrupted simulation.
119 */
120 void
121 read_dem() override;
122
123 /**
124 * @brief Set the initial condition. The version in this class does not output
125 * the solution, since the void fraction is not initialized yet.
126 *
127 * @param[in] initial_condition_type Type of method used to impose initial
128 * condition.
129 *
130 * @param[in] restart Indicator if the simulation is being restarted or not.
131 *
132 **/
133
134 void
136 const Parameters::FluidDynamicsInitialConditionType initial_condition_type,
137 const bool restart = false) override
138 {
139 unsigned int ref_iter = 0;
140 do
141 {
142 if (ref_iter > 0)
143 this->refine_mesh();
144
145 this->set_initial_condition_fd(initial_condition_type, restart);
146 if (!restart)
147 {
148 this->multiphysics->set_initial_conditions();
149 }
150 ref_iter++;
151 }
152 while (
153 ref_iter <
154 (this->simulation_parameters.mesh_adaptation.initial_refinement + 1) &&
155 restart == false);
156 }
157
158 /**
159 * @brief Gather TableHandler objects for serialization during checkpointing.
160 *
161 * Collects all TableHandler objects that need to be serialized and
162 * deserialized during checkpoint operations, including their associated
163 * file names for proper storage and retrieval.
164 *
165 * @return Vector of OutputStructTableHandler containing references to
166 * TableHandler objects and their corresponding file names
167 */
168 std::vector<OutputStructTableHandler>
169 gather_tables() override;
170
171 /**
172 * @brief Write CFD-DEM simulation checkpoint files.
173 *
174 * Saves the complete state of the CFD-DEM simulation including fluid
175 * variables, particle data, and auxiliary information to enable
176 * simulation restart from the current time step.
177 */
178 void
179 write_checkpoint() override;
180
181 /**
182 * @brief Read CFD-DEM simulation checkpoint files.
183 *
184 * Loads the complete simulation state from previously written checkpoint
185 * files to restart a CFD-DEM simulation from a specific time step.
186 */
187 void
188 read_checkpoint() override;
189
190 /**
191 * @brief Check if contact detection is required and execute it if necessary.
192 *
193 * Determines whether a contact detection step should be performed based on
194 * the contact detection frequency and executes the appropriate contact
195 * detection algorithm.
196 *
197 * @param[in] counter Current DEM iteration number
198 */
199 void
200 check_contact_detection_method(unsigned int counter);
201
202 /**
203 * @brief Check if load balancing is required and perform it if necessary.
204 *
205 * Evaluates the current load distribution across MPI processes and
206 * performs load balancing to maintain computational efficiency when
207 * particle distribution becomes uneven.
208 */
209 void
210 load_balance();
211
212 /**
213 * @brief Check if particles need to be inserted and perform insertion.
214 *
215 * Determines if new particles should be inserted into the simulation
216 * domain based on the insertion parameters and executes particle
217 * insertion using the configured insertion method.
218 */
219 void
221
222
223 /**
224 * @brief Calculate and add fluid-particle interaction forces.
225 *
226 * Computes the hydrodynamic forces acting on particles due to fluid motion
227 * and adds them to the particle force container for use in DEM integration.
228 */
229 void
231
232 /**
233 * @brief Calculate and add fluid-particle interaction torques.
234 *
235 * Computes the hydrodynamic torques acting on particles due to fluid motion
236 * and adds them to the particle torque container for use in DEM integration.
237 */
238 void
240
241 /**
242 * @brief Calculate contact forces between particles and walls.
243 *
244 * Computes collision forces and torques resulting from particle-wall
245 * interactions using the soft-sphere contact model.
246 */
247 void
249
250 /**
251 * @brief Write DEM simulation results to output files.
252 *
253 * Generates visualization output files containing particle positions,
254 * velocities, forces, and other relevant DEM variables in parallel
255 * VTU format for post-processing.
256 */
257 void
259
260 /**
261 * @brief Calculate and report particle statistics to the terminal.
262 *
263 * Computes and displays comprehensive statistics about particle behavior
264 * including minimum, maximum, and average values for linear velocity,
265 * angular velocity, kinetic energies, and contact search performance
266 * metrics.
267 */
268 void
270
271 /**
272 * @brief Print final summary of particle simulation results.
273 *
274 * Outputs a comprehensive summary of the particle simulation including
275 * final particle positions, velocities, and other relevant information
276 * at the end of the simulation.
277 */
278 void
280
281 /**
282 * @brief Perform fluid dynamics post-processing after each iteration.
283 *
284 * Executes post-processing operations specific to the fluid dynamics
285 * component including output writing and monitoring.
286 *
287 * @param[in] first_iteration Flag indicating if this is the first iteration
288 */
289 void
290 postprocess_fd(bool first_iteration) override;
291
292 /**
293 * @brief Perform CFD-DEM coupled post-processing after each iteration.
294 *
295 * Executes post-processing operations specific to the coupled CFD-DEM
296 * simulation including coupled field analysis and specialized output
297 * generation.
298 */
299 void
301
302 /**
303 * @brief Calculate dynamic flow control accounting for void fraction.
304 *
305 * Performs dynamic flow control calculations that incorporate the local
306 * void fraction (porosity) field in the average velocity computation,
307 * enabling proper flow control in particle-laden flows.
308 */
309 void
310 dynamic_flow_control() override;
311
312 /**
313 * @brief Sort particles into subdomains and cells for efficient processing.
314 *
315 * Redistributes particles among computational subdomains and associates
316 * them with their containing cells, then reinitialize containers that
317 * depend on local particle identifiers.
318 */
319 void
321
322 /**
323 * @brief Execute a complete DEM iteration step.
324 *
325 * Performs a full DEM time step including particle-particle and
326 * particle-wall contact force calculations, time integration of
327 * particle motion, and updates the particles positions and velocities.
328 *
329 */
330 void
331 dem_iterator();
332
333 /**
334 * @brief Carry out the closing half velocity step of a staggered integration
335 * scheme at the end of the DEM sub-iterations of a CFD time step.
336 *
337 * The contact and the fluid-particle interaction forces are re-evaluated at
338 * the final position of the particles so that their velocities can be
339 * synchronized with their positions. Consequently, n + 1 integration
340 * operations are carried out to complete the n DEM sub-iterations, and the
341 * CFD-DEM coupling of the next CFD time step sees synchronized velocities.
342 */
343 void
345
346 /**
347 * @brief Reports the ratio between the DEM time step and the Rayleigh time
348 *
349 */
350 void
352 {
353 Assert(
354 dem_simulation_control.use_count() > 0,
355 ExcMessage(
356 "You are trying to use the DEMSubSimulationControl when it has not been allocated yet."));
357
358 const double time_step_rayleigh_ratio =
360 this->pcout << "DEM time step is " << time_step_rayleigh_ratio * 100
361 << "% of Rayleigh time step" << std::endl;
362 }
363
364 /**
365 * @brief Perform contact detection and build contact lists.
366 *
367 * Checks if a contact search should be performed based on the contact
368 * detection frequency and executes the appropriate contact detection
369 * algorithm to identify particle-particle and particle-wall contacts.
370 *
371 */
372 void
374
375 /// Sub simulation control object used to control the DEM sub iterations for
376 /// each CFD time step.
377 std::shared_ptr<SubSimulationControlDEM> dem_simulation_control;
378
379 /// Gravitational acceleration vector
380 Tensor<1, 3> g;
381
382 /// Container for particle interaction outcomes (forces and torques)
384
385 /// Reference to torque vector from contact outcomes
386 std::vector<Tensor<1, 3>> &torque = contact_outcome.torque;
387
388 /// Reference to force vector from contact outcomes
389 std::vector<Tensor<1, 3>> &force = contact_outcome.force;
390
391 /// Displacement vector for particle motion calculations
392 std::vector<double> displacement;
393
394 /// Moment of inertia values for all particles
395 std::vector<double> MOI;
396
397 /// Squared threshold distance for neighborhood particle detection
399
400 /// Container for particle size distribution objects
401 std::vector<std::shared_ptr<Distribution>> size_distribution_object_container;
402
403 /// Maximum diameter among all particles in the simulation
405
406 /// Smallest criterion used for contact search algorithms
408
409 /**
410 * @brief Object to store ongoing collision information.
411 *
412 * Stores particle ID, boundary ID, velocity tensor, angular velocity
413 * tensor, and collision time for collisions currently in progress.
414 */
416
417 /**
418 * @brief Object to store completed collision events.
419 *
420 * Stores complete collision event data including start and end information
421 * for post-processing and analysis purposes.
422 */
424
425 /// Manager for particle-particle and particle-wall contact detection and
426 /// handling
428
429 /// Load balancing handler for distributing particles across MPI processes
431
432 /// Handler for point and line contact forces between particles
435
436 /// Time integration scheme for particle motion equations
437 std::shared_ptr<Integrator<dim, PropertiesIndex>> integrator_object;
438
439 /// Particle insertion method handler
440 std::shared_ptr<Insertion<dim, PropertiesIndex>> insertion_object;
441
442 /// Contact force model for particle-particle interactions
443 std::shared_ptr<ParticleParticleContactForceBase<dim, PropertiesIndex>>
445
446 /// Contact force model for particle-wall interactions
447 std::shared_ptr<ParticleWallContactForceBase<dim, PropertiesIndex>>
449
450 /// Visualization handler for DEM output generation
452
453 /// Information about boundary cells for contact detection
455
456 /// Mesh information for solid surfaces in contact with particles
459
460 /// Updated boundary points and their corresponding normal vectors
463
464 /// Force information stored on boundary elements
467
468 /// Torque information stored on boundary elements
471
472 /// Information about cells involved in periodic boundary conditions
475
476 /// Handler for periodic boundary condition manipulations
478
479 /// Object for handling adaptive sparse contact detection algorithms
481
482 /// Counter for contact searches performed in the current CFD iteration
484
485 /// Total number of contact searches since simulation start
487
488 /// Statistics container for timing and contact list information
490
491 /// Particle properties handler for DEM simulation
493
494 /// PVD handler for grid visualization output
496
497 /// PVD handler for particle visualization output
499
500 /// DEM simulation parameters container
502
503 /// Rayleigh time step
505
506 /// Current MPI process identifier
507 const unsigned int this_mpi_process;
508
509 /// Total number of MPI processes
510 const unsigned int n_mpi_processes;
511
512 /// TableHandler for post-processing phase volume calculations
513 /// Stores total fluid volume and total particle volume data
515
516 /// Pointer to DEM action manager for handling DEM-specific operations
518};
519#endif
Mechanism that disables contacts computation through mobility status of cells based on granular tempe...
Finds all the boundary cells and faces in the triangulation, for each cell the boundary face is speci...
dem_data_structures< dim >::vector_on_boundary torques_boundary_information
Torque information stored on boundary elements.
double maximum_particle_diameter
Maximum diameter among all particles in the simulation.
void add_fluid_particle_interaction_force()
Calculate and add fluid-particle interaction forces.
ParticleInteractionOutcomes< PropertiesIndex > contact_outcome
Container for particle interaction outcomes (forces and torques).
DEM::dem_data_structures< dim >::periodic_boundaries_cells_info periodic_boundaries_cells_information
Information about cells involved in periodic boundary conditions.
void dem_contact_build()
Perform contact detection and build contact lists.
std::vector< OutputStructTableHandler > gather_tables() override
Gather TableHandler objects for serialization during checkpointing.
std::vector< std::shared_ptr< Distribution > > size_distribution_object_container
Container for particle size distribution objects.
dem_data_structures< dim >::vector_on_boundary forces_boundary_information
Force information stored on boundary elements.
void add_fluid_particle_interaction_torque()
Calculate and add fluid-particle interaction torques.
virtual void solve() override
Engine of the CFD-DEM solver. Calls all the necessary functions to set parameters,...
dem_data_structures< dim >::boundary_points_and_normal_vectors updated_boundary_points_and_normal_vectors
Updated boundary points and their corresponding normal vectors.
void report_rayleigh_time_ratio()
Reports the ratio between the DEM time step and the Rayleigh time.
double rayleigh_time_step
Rayleigh time step.
DEM::ParticleProperties< dim, PropertiesIndex > properties_class
Particle properties handler for DEM simulation.
AdaptiveSparseContacts< dim, PropertiesIndex > sparse_contacts_object
Object for handling adaptive sparse contact detection algorithms.
unsigned int contact_search_total_number
Total number of contact searches since simulation start.
std::shared_ptr< Integrator< dim, PropertiesIndex > > integrator_object
Time integration scheme for particle motion equations.
void print_particles_summary()
Print final summary of particle simulation results.
dem_data_structures< dim >::solid_surfaces_mesh_information solid_surfaces_mesh_info
Mesh information for solid surfaces in contact with particles.
std::shared_ptr< ParticleWallContactForceBase< dim, PropertiesIndex > > particle_wall_contact_force_object
Contact force model for particle-wall interactions.
TableHandler table_phase_volumes
void postprocess_fd(bool first_iteration) override
Perform fluid dynamics post-processing after each iteration.
DEMSolverParameters< dim > dem_parameters
DEM simulation parameters container.
void read_checkpoint() override
Read CFD-DEM simulation checkpoint files.
std::shared_ptr< Integrator< dim, PropertiesIndex > > set_integrator_type()
Set up the time integration method for particle motion.
void report_particle_statistics()
Calculate and report particle statistics to the terminal.
const unsigned int n_mpi_processes
Total number of MPI processes.
std::vector< Tensor< 1, 3 > > & force
Reference to force vector from contact outcomes.
void check_contact_detection_method(unsigned int counter)
Check if contact detection is required and execute it if necessary.
void set_initial_condition(const Parameters::FluidDynamicsInitialConditionType initial_condition_type, const bool restart=false) override
Set the initial condition. The version in this class does not output the solution,...
unsigned int contact_search_counter
Counter for contact searches performed in the current CFD iteration.
CompletedCollisionLog< dim > collision_event_log
Object to store completed collision events.
const unsigned int this_mpi_process
Current MPI process identifier.
BoundaryCellsInformation< dim > boundary_cell_object
Information about boundary cells for contact detection.
std::vector< Tensor< 1, 3 > > & torque
Reference to torque vector from contact outcomes.
void dynamic_flow_control() override
Calculate dynamic flow control accounting for void fraction.
void particle_wall_contact_force()
Calculate contact forces between particles and walls.
PVDHandler grid_pvdhandler
PVD handler for grid visualization output.
std::shared_ptr< ParticleParticleContactForceBase< dim, PropertiesIndex > > particle_particle_contact_force_object
Contact force model for particle-particle interactions.
Tensor< 1, 3 > g
Gravitational acceleration vector.
void setup_distribution_type()
Initialize the particle size distribution and related parameters.
statistics contact_list
Statistics container for timing and contact list information.
void sort_particles_into_subdomains_and_cells()
Sort particles into subdomains and cells for efficient processing.
void synchronize_particle_velocities()
Carry out the closing half velocity step of a staggered integration scheme at the end of the DEM sub-...
void dem_setup_parameters()
Set up the various parameters related to the DEM simulation.
LagrangianLoadBalancing< dim, PropertiesIndex > load_balancing
Load balancing handler for distributing particles across MPI processes.
~CFDDEMSolver() override
Destructor for the CFD-DEM solver.
PeriodicBoundariesManipulator< dim > periodic_boundaries_object
Handler for periodic boundary condition manipulations.
DEMActionManager * dem_action_manager
Pointer to DEM action manager for handling DEM-specific operations.
void dem_iterator()
Execute a complete DEM iteration step.
std::shared_ptr< SubSimulationControlDEM > dem_simulation_control
void read_dem() override
Read DEM restart files from a previous simulation.
double neighborhood_threshold_squared
Squared threshold distance for neighborhood particle detection.
DEMContactManager< dim, PropertiesIndex > contact_manager
void initialize_dem_parameters()
Initialize fundamental DEM simulation parameters.
std::vector< double > displacement
Displacement vector for particle motion calculations.
OngoingCollisionLog< dim > ongoing_collision_log
Object to store ongoing collision information.
double smallest_contact_search_criterion
Smallest criterion used for contact search algorithms.
void postprocess_cfd_dem()
Perform CFD-DEM coupled post-processing after each iteration.
PVDHandler particles_pvdhandler
PVD handler for particle visualization output.
Visualization< dim, PropertiesIndex > visualization_object
Visualization handler for DEM output generation.
void write_dem_output_results()
Write DEM simulation results to output files.
void write_checkpoint() override
Write CFD-DEM simulation checkpoint files.
ParticlePointLineForce< dim, PropertiesIndex > particle_point_line_contact_force_object
Handler for point and line contact forces between particles.
CFDDEMSolver(CFDDEMSimulationParameters< dim > &nsparam)
Constructor for the CFD-DEM solver.
std::shared_ptr< Insertion< dim, PropertiesIndex > > insertion_object
Particle insertion method handler.
void insert_particles()
Check if particles need to be inserted and perform insertion.
void load_balance()
Check if load balancing is required and perform it if necessary.
std::vector< double > MOI
Moment of inertia values for all particles.
Class that stores all the completed collision events.
Manage the actions to be performed in the DEM solver and on the DEM part of the coupling CFD-DEM solv...
Manage the numerous of contact detection search operations in the DEM.
Handles all the parameters declared in the parameter handler file.
Controls the name of output variables for the vtu.
virtual void set_initial_condition_fd(Parameters::FluidDynamicsInitialConditionType initial_condition_type, bool restart=false) override
Sets the initial condition for the solver.
FluidDynamicsVANS(CFDDEMSimulationParameters< dim > &nsparam)
Constructor for the VANS solver.
Manages the load balancing (repartitioning), of the domain according to the computational load of the...
std::shared_ptr< MultiphysicsInterface< dim > > multiphysics
Class managing the ongoing collisions.
The PVDHandler class manages the storage of the information required to write pvd file....
Definition pvd_handler.h:17
Class where the outcomes of particle-particle interactions are stored.
Calculate the non-linear particle-point and particle-line contact force using the information obtaine...
Building patches of particle properties for visualization. This function is taken from Aspect and dea...
A simple container for storing basic statistical values.
Definition utilities.h:56
std::vector< std::vector< std::pair< typename Triangulation< dim >::active_cell_iterator, typename Triangulation< dim - 1, dim >::active_cell_iterator > > > solid_surfaces_mesh_information
ankerl::unordered_dense::map< unsigned int, std::map< types::boundary_id, Tensor< 1, 3 > > > vector_on_boundary
ankerl::unordered_dense::map< global_face_id, std::pair< Tensor< 1, 3 >, Point< 3 > > > boundary_points_and_normal_vectors
std::unordered_multimap< types::global_cell_index, periodic_boundaries_cells_info_struct< dim > > periodic_boundaries_cells_info