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