Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
adaptive_sparse_contacts.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2024-2025 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_adaptive_sparse_contacts_h
5#define lethe_adaptive_sparse_contacts_h
6
7
10
11#include <deal.II/base/tensor.h>
12
13#include <deal.II/dofs/dof_handler.h>
14
15#include <deal.II/lac/affine_constraints.h>
16#include <deal.II/lac/la_parallel_vector.h>
17#include <deal.II/lac/la_parallel_vector.templates.h>
18
19#include <deal.II/particles/particle_handler.h>
20
21#include <vector>
22
23using namespace dealii;
24
25// Special template instance for this class.
26// Unsigned integer would have been a better choice, but is not working
27// with the Vector class (error because of calling of abs() function)
28template class LinearAlgebra::distributed::Vector<int>;
29
30/**
31 * @brief Mechanism that disables contacts computation through mobility status
32 * of cells based on granular temperature.
33 *
34 * The general idea behind the algorithm:
35 *
36 * It uses the granular temperature to determinate if particles in a cell are
37 * sufficiently mobile that the contact forces are worth computation.
38 * A cell having a granular temperature under a threshold (default is 1e-4) will
39 * have an inactive or advected status which makes them rejected in the broad
40 * search step. There is also an extra layer of mobile cells around the current
41 * mobile cells to propagate the motion of particles. Additionally, there is
42 * another layer of cells around those mobile cells that are flagged as
43 * static_active or advected_active cells.
44 *
45 * While the inactive status makes the particles static (no further handling),
46 * the advected status will lead to computation and application of a
47 * cell-averaged advected term. This term is computed from the last average
48 * velocity and acceleration of the particles when the cell had a mobile status,
49 * or at the first DEM time step of a CFD iteration in CFD-DEM (ensures an
50 * update of the hydrodynamic forces). Those forces are reapplied after each
51 * DEM time step.
52 *
53 * Particles in cells with an inactive status results in skipping the fine
54 * contact search, the p-p & p-w forces computation and the velocity and
55 * position update. It reduces the computational cost of the simulation when
56 * particles are not moving.
57 *
58 * Particles in cells with an advected status results in skipping the fine
59 * contact search, the p-p & p-w forces computations, but they do have a
60 * velocity and position update through the advection term. This is critical for
61 * CFD-DEM.
62 *
63 * In summary, cells are flagged using a mobility status:
64 * - mobile (all contacts are calculated, same as if the feature is not enabled)
65 * - static_active (particles with low velocity variance next to mobile
66 * particles)
67 * - advected_active (same as above but particles will be advected)
68 * - inactive (particles next to mobile particles that allow one way contact
69 * forces calculation, not computation of collision pair in the cell)
70 * - advected (same as above, but particles will be advected)
71 *
72 * There are some edge cases that need some attention. In these cases, particles
73 * in cells cannot be deactivated:
74 *
75 * 1. Solid fraction
76 * The solid fraction of the cell is under a value (default = 40%): particles
77 * in the cell are not consolidated (packed) and may move freely.
78 *
79 * 2. Empty cell neighbor
80 * Cell having empty cell neighbor: it means that particles are next to a
81 * floating wall/mesh, and they may have a change of contact forces from it if
82 * the wall moves or disappears.
83 *
84 * 3. Additional mobile cell layer
85 * The cell has at least one cell neighbor flagged as mobile from the 3 criteria
86 * mentioned above (granular temperature, solid fractions or floating walls):
87 * this is because motion is badly propagated to particles to the cell around
88 * without this additional "layer" of mobile cells.
89 *
90 * 4. Active cell layer
91 * The cell has at least one cell neighbor flagged as mobile from the previous
92 * criterion (additional layer of mobile cells): again, this is to allow the
93 * motion propagation, but only the particles in contact with particles
94 * from the mobile cells are considered for the contact force calculation but
95 * their position is not computed at the integration step. Those cells are
96 * flagged as active cells. It works with the assignment and verification of the
97 * mobility status at nodes to check the status of the neighboring cells.
98 *
99 * @tparam dim An integer that denotes the number of spatial dimensions.
100 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
101 */
102template <int dim, typename PropertiesIndex>
104{
105public:
107
108 /**
109 * Mobility status flags used to identify the status at nodes and the status
110 * of the cell:
111 *
112 * inactive (0)
113 * The motion of particles in the cell is considered as negligible,
114 * particles within this cell are not considered in the contact detection
115 * (rejected at the broad search step), so no force calculation or
116 * integration is applied
117 *
118 * static_active (1)
119 * The motion of particles in the cell is considered as negligible, but
120 * there's at least one neighbor cell that is flagged as mobile, meaning that
121 * particles need to be in contact candidates lists at the broad search step,
122 * particles directly in contact with the mobile cell are also considered in
123 * force calculation, but none of the particles in the cell are integrated.
124 *
125 * advected (2)
126 * The variance of the velocity of the particles in cell is low, suggesting
127 * that contact forces are negligible but particles are advected by other
128 * forces. Note that there are currently no mechanisms that distinct active vs
129 * advected status: advection of particles is a user-defined feature. Advected
130 * and active status are detected in the same way, but are not processed the
131 * same at the velocity integration step. For advected particles, the last
132 * computed cell-averaged velocity and acceleration is used to advect the
133 * particles.
134 *
135 * advected_active (3)
136 * Same as (1), but particles are advected by the last computed
137 * cell-averaged velocity and acceleration.
138 *
139 * mobile (4)
140 * The motion of particles in the cell is significant or there is at least
141 * one cell neighbor that is mobile by criteria (see the
142 * identify_mobility_status() description), particles need to be in contact
143 * candidate lists at the broad search step and particles are treated as
144 * usual (force calculation and integration)
145 *
146 * empty (5)
147 * This status is only used for the node-based mobility status identification,
148 * no cells are flagged as empty, only node can be identified as empty.
149 * Without this identification of the empty cells, we cannot identify the cell
150 * that have an empty neighbor cell, which is critical for simulations using
151 * floating walls or mesh.
152 */
153
154 enum mobility_status : unsigned int
155 {
156 inactive = 0, // used for cells
157 static_active = 1, // used for cells and nodes
158 advected = 2, // used for cells and nodes
159 advected_active = 3, // used for cells and nodes
160 mobile = 4, // used for cells and nodes
161 empty = 5 // used for nodes only
162 };
163
164
165 /**
166 * @brief Set the threshold values for the mobile status criteria (granular
167 * temperature and solid fraction) and the flag for the advection of
168 * particles.
169 *
170 * @param[in] granular_temperature The threshold value for the granular
171 * temperature.
172 * @param[in] solid_fraction The threshold value for the volumic solid
173 * fraction.
174 * @param[in] advect_particles The flag for the advection of particles.
175 */
176 inline void
177 set_parameters(const double granular_temperature,
178 const double solid_fraction,
179 const bool advect_particles)
180 {
181 // If the function is reached, the adaptive sparse contacts is enabled.
183
184 // Communicate to the action manager that the sparse contacts is enabled
186
187 granular_temperature_threshold = granular_temperature;
188 solid_fraction_threshold = solid_fraction;
189 advect_particles_enabled = advect_particles;
190 }
191
192 /**
193 * @brief Create or update a set of the active and ghost cells so that
194 * there is no loop over all the cells of the triangulation for the granular
195 * temperature and solid fraction calculation, and during the identification
196 * of the mobility status. This set prevents 4 iteration steps over all the
197 * cells and the verification if the cell is locally owned, ghost or not.
198 * This set is updated at every load balance step since cells are
199 * redistributed among processors.
200 *
201 * @param[in] background_dh The DoFHandler of the background grid.
202 */
203 void
204 update_local_and_ghost_cell_set(const DoFHandler<dim> &background_dh);
205
206 /**
207 * @brief Calculate or update the cell-averaged velocities and accelerations
208 * of the cells. This is used for the advection of particles during
209 * integration and the velocities and accelerations map is fully updated at
210 * least at each CFD time step since the first DEM iteration computes every
211 * contact. This map is also partially updated when cell is mobile in the
212 * Verlet integration (not implemented for other scheme).
213 * Since this step loops over all the particles of mobile cells and new values
214 * of velocities are computed, this helps to have a more accurate value of the
215 * average velocities and accelerations when applied to the particles in
216 * next DEM time steps.
217 *
218 * @param[in] particle_handler The particle handler that contains all the
219 * particles.
220 * @param[in] g The external forces, same for all cells (gravity or other
221 * sources).
222 * @param[in] force The contact or hydrodynamic forces.
223 * @param[in] dt The DEM time step.
224 */
225 void
226 update_average_velocities_acceleration(
227 Particles::ParticleHandler<dim> &particle_handler,
228 const Tensor<1, 3> &g,
229 const std::vector<Tensor<1, 3>> &force,
230 const double dt);
231
232 /**
233 * @brief Identify of the mobility status of each cell through a node-based
234 * identification and check. Only the active and ghost cells are processed.
235 *
236 * The following 4 checks (search loops) are done:
237 *
238 * 1. Check if the cell is empty (n_particle = 0), if so, nodes and cells are
239 * flagged as empty mobility status (5)
240 *
241 * 2. Check if the cell is mobile by criteria (average granular temperature >
242 * threshold, solid fraction < threshold or has at least one empty node from
243 * previous check), if so, nodes are flagged and cells are stored with mobile
244 * mobility status (4)
245 *
246 * 3. Check if the cell is mobile by neighbor (at least a node is flagged as
247 * mobile from previous check), if so, cells are stored in map as mobile
248 * status (4) and nodes that are not mobile are flagged as active (1/3)
249 *
250 * 4. Check if the cell is active (at least a node is flagged as active from
251 * previous check), if so, cells are stored with active status in the map
252 * (1/3)
253 *
254 * The remaining cells are inactive (0)
255 *
256 * @param[in] background_dh The dof handler of the background grid.
257 * @param[in] particle_handler The particle handler that contains all the
258 * particles.
259 * @param[in] n_active_cells The number of active cells in triangulation.
260 * @param[in] mpi_communicator The MPI communicator.
261 */
262 void
263 identify_mobility_status(
264 const DoFHandler<dim> &background_dh,
265 const Particles::ParticleHandler<dim> &particle_handler,
266 const unsigned int n_active_cells,
267 MPI_Comm mpi_communicator);
268
269 /**
270 * @brief Map the periodic nodes pairs of the triangulation using the
271 * constraints. It allows to compare the mobility status of the nodes with the
272 * status of the periodic node.
273 *
274 * Note: this might not be the efficient way to pair the periodic nodes.
275 *
276 * @param constraints[in] The background constraints of triangulation.
277 */
278 inline void
279 map_periodic_nodes(const AffineConstraints<double> &constraints)
280 {
281 periodic_node_ids.clear();
282
283 IndexSet local_lines = constraints.get_local_lines();
284 for (auto i : local_lines)
285 {
286 for (auto j : local_lines)
287 {
288 // Map the values of the periodic nodes (with repetition)
289 if (constraints.are_identity_constrained(i, j))
290 {
291 periodic_node_ids.insert(std::make_pair(i, j));
292 }
293 }
294 }
295 }
296
297 /**
298 * @brief Find the mobility status of a cell.
299 *
300 * @param[in] cell The iterator of the cell that needs mobility evaluation.
301 */
302 inline unsigned int
304 const typename Triangulation<dim>::active_cell_iterator &cell) const
305 {
306 return cell_mobility_status.at(cell->active_cell_index());
307 }
308
309 /**
310 * @brief Convert the map of mobility status to a vector of mobility status
311 * because map cannot be used as is in the pvd post-processing or any data
312 * out, it needs to be converted to a vector of mobility status by active cell
313 * index.
314 *
315 * @param[out] status The initiated vector for the conversion.
316 */
317 void
318 get_mobility_status_vector(Vector<float> &status)
319 {
320 for (auto &cell_to_status : cell_mobility_status)
321 {
322 status[cell_to_status.first] = cell_to_status.second;
323 }
324 }
325
326 /**
327 * @brief Give the map of the mobility status of the cells.
328 */
331 {
333 }
334
335 /**
336 * @brief Give the map of the cell-averaged velocities and accelerations * dt.
337 */
338 std::map<typename Triangulation<dim>::active_cell_iterator,
339 std::pair<Tensor<1, 3>, Tensor<1, 3>>> &
344
345 /**
346 * @brief Give the advected particles flag.
347 */
348 bool
350 {
352 }
353
354private:
355 /**
356 * @brief Calculate the granular temperature and solid fraction approximation
357 * (pcm method). Those values are criteria for cell mobility.
358 *
359 * @param[in] particle_handler The particle handler that contains all the
360 * particles.
361 * @param[in] local_and_ghost_cells_with_particles The set of locally owned
362 * and ghost cells that empty cells were removed from.
363 * @param[out] cell_granular_temperature The empty vector of granular
364 * temperature.
365 * @param[out] cell_solid_fraction The empty vector of solid fraction.
366 */
367 void
368 calculate_granular_temperature_and_solid_fraction(
369 const Particles::ParticleHandler<dim> &particle_handler,
370 const std::set<typename DoFHandler<dim>::active_cell_iterator>
371 &local_and_ghost_cells_with_particles,
372 Vector<double> &cell_granular_temperature,
373 Vector<double> &cell_solid_fraction);
374
375 /**
376 * @brief Assign the mobility status to the cell, its nodes, and its periodic
377 * coinciding nodes from the periodic nodes map. If required, this will
378 * prevent overwriting a node status prevailing over the initial one.
379 * For instance, empty status must not be overwritten by mobile status because
380 * all cells with this node will be part of the additional mobile layer and
381 * will wrongly propagate mobility status to the next cells.
382 *
383 * @param[in] cell_id The current cell index.
384 * @param[in] dof_indices The vector of the DoF indices of the cell.
385 * @param[in] cell_status The mobility status of cell to assign.
386 * @param[in] node_status The current mobility status of the node.
387 */
388 inline void
390 unsigned int cell_id,
391 const std::vector<types::global_dof_index> &dof_indices,
392 const int cell_status,
393 const int node_status)
394 {
395 cell_mobility_status.insert({cell_id, cell_status});
396
397 // Assign mobility status to nodes without overwriting empty or mobile nodes
398 // in regard to the case
399 for (auto node_id : dof_indices)
400 {
401 // Prevailing mobility status of the node and assignation
402 int status_assigned = std::max(node_status, mobility_at_nodes(node_id));
403 mobility_at_nodes(node_id) = status_assigned;
404
405 // Check if node has a periodic node and assign the same mobility status
406 // if prevailing on the one on the periodic node
407 auto it = periodic_node_ids.find(node_id);
408 if (it != periodic_node_ids.end())
409 {
410 mobility_at_nodes(it->second) =
411 std::max(status_assigned, mobility_at_nodes(it->second));
412 }
413 }
414 }
415
416 /**
417 * @brief Assign the mobility status to the cell. No need to update the node
418 * status. Only use for active status assignment since nodes are not evaluated
419 * after this step.
420 *
421 * @param[in] cell_id The current cell index.
422 * @param[in] cell_status The mobility status of cell to assign.
423 */
424 inline void
425 assign_mobility_status(unsigned int cell_id, const int cell_status)
426 {
427 cell_mobility_status.insert({cell_id, cell_status});
428 }
429
430 /**
431 * @brief Set of locally owned and ghost cells: <local/ghost cells>
432 * Used to loop over only the locally owned and ghost cells without looping
433 * over all the cells in the triangulation numerous times.
434 */
435 std::set<typename DoFHandler<dim>::active_cell_iterator>
437
438 /**
439 * @brief Map of cell mobility status: <cell index: mobility status>
440 */
443
444 /**
445 * @brief Vector of mobility status at nodes: [mobility status]
446 * Used to check the value at node to determine the mobility status of the
447 * cell, this type of vector is used to allow update values in parallel.
448 */
449 LinearAlgebra::distributed::Vector<int> mobility_at_nodes;
450
451 /**
452 * @brief Map of periodic nodes: <periodic node index: coinciding node index>
453 */
454 std::unordered_map<unsigned int, unsigned int> periodic_node_ids;
455
456 /**
457 * @brief Map of cell velocities and accelerations * dt:
458 * <cell iterator: <velocity, acceleration * dt>>
459 */
460 std::map<typename Triangulation<dim>::active_cell_iterator,
461 std::pair<Tensor<1, 3>, Tensor<1, 3>>>
463
464 /**
465 * @brief Flag for adaptive sparse contacts enabling. Useful to exit functions.
466 */
468
469 /**
470 * @brief Flag for the advection of particles.
471 */
473
474 /**
475 * @brief Threshold value for granular temperature.
476 */
478
479 /**
480 * @brief Threshold value for solid fraction.
481 */
483};
484
485#endif // lethe_adaptive_sparse_contacts_h
std::unordered_map< unsigned int, unsigned int > periodic_node_ids
Map of periodic nodes: <periodic node index: coinciding node index>.
double solid_fraction_threshold
Threshold value for solid fraction.
bool advect_particles_enabled
Flag for the advection of particles.
double granular_temperature_threshold
Threshold value for granular temperature.
void set_parameters(const double granular_temperature, const double solid_fraction, const bool advect_particles)
Set the threshold values for the mobile status criteria (granular temperature and solid fraction) and...
void assign_mobility_status(unsigned int cell_id, const int cell_status)
Assign the mobility status to the cell. No need to update the node status. Only use for active status...
bool sparse_contacts_enabled
Flag for adaptive sparse contacts enabling. Useful to exit functions.
std::set< typename DoFHandler< dim >::active_cell_iterator > local_and_ghost_cells
Set of locally owned and ghost cells: <local/ghost cells> Used to loop over only the locally owned an...
std::map< typename Triangulation< dim >::active_cell_iterator, std::pair< Tensor< 1, 3 >, Tensor< 1, 3 > > > cell_velocities_accelerations
Map of cell velocities and accelerations * dt: <cell iterator: <velocity, acceleration * dt>>.
LinearAlgebra::distributed::Vector< int > mobility_at_nodes
Vector of mobility status at nodes: [mobility status] Used to check the value at node to determine th...
DEM::dem_data_structures< dim >::cell_index_int_map cell_mobility_status
Map of cell mobility status: <cell index: mobility status>.
void get_mobility_status_vector(Vector< float > &status)
Convert the map of mobility status to a vector of mobility status because map cannot be used as is in...
unsigned int check_cell_mobility(const typename Triangulation< dim >::active_cell_iterator &cell) const
Find the mobility status of a cell.
bool has_advected_particles() const
Give the advected particles flag.
void map_periodic_nodes(const AffineConstraints< double > &constraints)
Map the periodic nodes pairs of the triangulation using the constraints. It allows to compare the mob...
std::map< typename Triangulation< dim >::active_cell_iterator, std::pair< Tensor< 1, 3 >, Tensor< 1, 3 > > > & get_velocities_accelerations()
Give the map of the cell-averaged velocities and accelerations * dt.
DEM::dem_data_structures< dim >::cell_index_int_map & get_mobility_status()
Give the map of the mobility status of the cells.
void assign_mobility_status(unsigned int cell_id, const std::vector< types::global_dof_index > &dof_indices, const int cell_status, const int node_status)
Assign the mobility status to the cell, its nodes, and its periodic coinciding nodes from the periodi...
static DEMActionManager * get_action_manager()
Getter of the unique instance of the DEMActionManager.
void set_sparse_contacts_enabled()
Flag that the ASC is enabled and trigger a mobility status reset to initialize the containers.
ankerl::unordered_dense::map< types::global_cell_index, unsigned int > cell_index_int_map