Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
particle_particle_fine_search.cc
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2020-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
5
6#include <dem/contact_info.h>
7#include <dem/contact_type.h>
10
11#include <deal.II/particles/particle.h>
12
13#include <boost/range/adaptor/map.hpp>
14
15#include <array>
16#include <cmath>
17#include <limits>
18#include <utility>
19
20using namespace dealii;
21
22template <int dim, ContactType contact_type>
23void
26 &particle_container,
29 &contact_pair_candidates,
30 const double neighborhood_threshold,
31 const std::array<double, dim> &periodic_offset_per_direction)
32{
33 // First iterating over adjacent_particles
34 for (auto &&adjacent_particles_list :
35 adjacent_particles | boost::adaptors::map_values)
36 {
37 // List of potential particles
38 auto &second_particles = adjacent_particles_list.second_particles;
39
40 // If the list is empty, we continue.
41 if (second_particles.empty())
42 continue;
43
44 // Gather information about particle 1. The iterator to particle 1 is
45 // shared by all its contacts and stored once in the adjacency value.
46 auto &particle_one = adjacent_particles_list.particle_one;
47 Point<dim, double> particle_one_location = particle_one->get_location();
48
49 // For non-periodic contacts
50 if constexpr (contact_type == local_particle_particle ||
51 contact_type == ghost_particle_particle)
52 {
53 // Iterating over each map which contains the contact information
54 for (auto adjacent_particles_list_iterator = second_particles.begin();
55 adjacent_particles_list_iterator != second_particles.end();)
56 {
57 // Getting contact information and particle 2 as local variables
58 auto &adjacent_pair_information =
59 adjacent_particles_list_iterator->second;
60 auto &particle_two = adjacent_pair_information.particle_two;
61
62 // Finding the properties of the particles in contact
63 Point<dim, double> particle_two_location =
64 particle_two->get_location();
65
66 const double square_distance =
67 particle_one_location.distance_square(particle_two_location);
68 if (square_distance > neighborhood_threshold)
69 {
70 adjacent_particles_list_iterator =
71 second_particles.erase(adjacent_particles_list_iterator);
72 }
73 else
74 {
75 ++adjacent_particles_list_iterator;
76 }
77 }
78 }
79
80 // For periodic contacts
81 if constexpr (contact_type == local_periodic_particle_particle ||
82 contact_type == ghost_periodic_particle_particle ||
84 {
85 // Iterating over each map which contains the contact information
86 for (auto adjacent_particles_list_iterator = second_particles.begin();
87 adjacent_particles_list_iterator != second_particles.end();)
88 {
89 // Getting the contact information and particle 2 as local
90 // variables
91 auto &adjacent_pair_information =
92 adjacent_particles_list_iterator->second;
93 auto &particle_two = adjacent_pair_information.particle_two;
94
95 // Finding the properties of particle 2.
96 Point<dim, double> particle_two_real_location =
97 particle_two->get_location();
98
99 // Reuse the periodic offset found on a previous call: for a
100 // persisting contact this translation practically never
101 // changes between fine search calls. This avoids computing the
102 // minimum periodic offset twice, which is costly.
103 Tensor<1, dim> cached_translation =
104 adjacent_pair_information.periodic_offset;
105 const double cached_square_distance =
106 particle_one_location.distance_square(
107 particle_two_real_location + cached_translation);
108
109 // Using the cached periodic offset, if the shared distance
110 // respects the neighborhood threshold, this means that the
111 // particles stayed on their respective side of the PBC.
112 if (cached_square_distance <= neighborhood_threshold)
113 ++adjacent_particles_list_iterator;
114
115 // If not, either one particle crossed the PBC or both crossed it
116 // or they just moved apart.
117 else
118 {
119 // Cached periodic offset no longer holds. Fall back to the
120 // distance computation using the minimum image convention.
121 // If the distance between the particles is higher than the
122 // neighbor threshold, we erase the potential contact from the
123 // list.
124 // The nearest_translation is the periodic offset.
125 const auto [nearest_translation, found_periodic_translation] =
127 particle_one_location,
128 particle_two_real_location,
129 periodic_offset_per_direction);
130
131 // If a periodic offset was found, the min_square_distance is
132 // computed. Otherwise, we know that the particles are far
133 // apart, thus we impose the min_square_distance to a high
134 // value (max())
135 const double min_square_distance =
136 found_periodic_translation ?
137 particle_one_location.distance_square(
138 particle_two_real_location + nearest_translation) :
139 std::numeric_limits<double>::max();
140
141 // If the min_square_distance does not respect the
142 // neighborhood threshold at this point, this means that the
143 // particle officially moved apart. We can remove the
144 // potential contact from the list.
145 if (min_square_distance > neighborhood_threshold)
146 adjacent_particles_list_iterator =
147 second_particles.erase(adjacent_particles_list_iterator);
148
149 // Otherwise, this means that one or both particle(s) crossed
150 // the PBC. We update the periodic_offset in the periodic
151 // contact_info.
152 else
153 {
154 adjacent_pair_information.periodic_offset =
155 nearest_translation;
156 ++adjacent_particles_list_iterator;
157 }
158 }
159 }
160 }
161 }
162
163 // Now iterating over contact_pair_candidates (maps of pairs), which
164 // is the output of broad search. If a pair is in vicinity (distance <
165 // threshold), it is added to the adjacent_particles
166 for (auto &[particle_one_id, second_particle_container] :
167 contact_pair_candidates)
168 {
169 if (second_particle_container.empty())
170 continue;
171
172 auto particle_one = particle_container.at(particle_one_id);
173 Point<dim, double> particle_one_location = particle_one->get_location();
174
175 for (const types::particle_index &particle_two_id :
176 second_particle_container)
177 {
178 auto particle_two = particle_container.at(particle_two_id);
179
180 // For non-periodic contacts
181 if constexpr (contact_type == local_particle_particle ||
182 contact_type == ghost_particle_particle)
183 {
184 Point<dim, double> particle_two_location =
185 particle_two->get_location();
186
187 const double square_distance =
188 particle_one_location.distance_square(particle_two_location);
189
190 if (square_distance < neighborhood_threshold)
191 {
192 auto &particle_one_contact_list =
193 adjacent_particles[particle_one_id];
194 particle_one_contact_list.particle_one = particle_one;
195
196 particle_one_contact_list.second_particles.emplace(
197 particle_two_id,
199 Tensor<1, 3>(),
200 Tensor<1, 3>()});
201 }
202 }
203
204 // For periodic contacts
205 if constexpr (contact_type == local_periodic_particle_particle ||
206 contact_type == ghost_periodic_particle_particle ||
208 {
209 Point<dim, double> particle_two_real_location =
210 particle_two->get_location();
211
212 // nearest_periodic_translation returns the periodic translation
213 // that brings two particles the closest together. (if they are
214 // close enough)
215 const auto [nearest_translation, found_periodic_translation] =
217 particle_one_location,
218 particle_two_real_location,
219 periodic_offset_per_direction);
220
221 // It is possible that the two particle moved far apart so much
222 // that the round operation in the nearest_periodic_translation
223 // function return a 0. In this case, found_periodic_translation
224 // will be at false. Thus, we need to make sure that this isn't
225 // the case by imposing min_square_distance to max().
226 const double min_square_distance =
227 found_periodic_translation ?
228 particle_one_location.distance_square(
229 particle_two_real_location + nearest_translation) :
230 std::numeric_limits<double>::max();
231
232 // If the neighborhood_threshold is respected, we add particle 2
233 // to particle's 1 potential contact list. Otherwise, we do
234 // nothing.
235 if (min_square_distance < neighborhood_threshold)
236 {
237 auto &particle_one_contact_list =
238 adjacent_particles[particle_one_id];
239 particle_one_contact_list.particle_one = particle_one;
240
241 particle_one_contact_list.second_particles.emplace(
242 particle_two_id,
244 {particle_two, Tensor<1, 3>(), Tensor<1, 3>()},
245 nearest_translation});
246 }
247 }
248 }
249 }
250}
251
252template <int dim>
253std::pair<Tensor<1, dim>, bool>
255 const Point<dim, double> &particle_one_location,
256 const Point<dim, double> &particle_two_real_location,
257 const std::array<double, dim> &periodic_offset_per_direction)
258{
259 Tensor<1, dim> nearest_translation;
260 bool found_periodic_translation = false;
261
262 // Loop on every direction
263 for (int d = 0; d < dim; ++d)
264 {
265 // If the periodic offset associated with this direction is zero,
266 // this means that the direction is not periodic, thus we skip it.
267 // Also, it prevents a division by zero a bit later in the code.
268 if (periodic_offset_per_direction[d] != 0.)
269 {
270 // Real distance between p1 and p2
271 const double delta =
272 particle_one_location[d] - particle_two_real_location[d];
273
274 // If particle 1 (p1) is on one side of the triangulation and p2 is
275 // on the other side and both sides/boundaries are linked through a
276 // PBC, the distance between those two particle should
277 // be around one period (~ 0.9), thus when we round, we get 1.0,
278 // which we then multiply to the actual periodic_offset. When p1 and
279 // p2 and near periodic corner, this method will also work because the
280 // rounding will give 1.0 for more than one direction.
281 nearest_translation[d] =
282 std::round(delta / periodic_offset_per_direction[d]) *
283 periodic_offset_per_direction[d];
284
285 // If the nearest_translation got rounded to 0., this means that
286 // the particles are in the same cell or in a real neighboring cell
287 // or that the current direction is not linking this periodic
288 // contact. (By real neighboring cell, we mean a neighboring cell that
289 // is not periodic neighboring cell)
290 found_periodic_translation |= (nearest_translation[d] != 0.);
291 }
292 }
293 return {nearest_translation, found_periodic_translation};
294}
295
296// 2D templates
297template void
300 &particle_container,
302 &adjacent_particles,
304 &contact_pair_candidates,
305 const double neighborhood_threshold,
306 const std::array<double, 2> &periodic_offset_per_direction);
307
308template void
311 &particle_container,
313 &adjacent_particles,
315 &contact_pair_candidates,
316 const double neighborhood_threshold,
317 const std::array<double, 2> &periodic_offset_per_direction);
318
319template void
322 &particle_container,
324 &adjacent_particles,
326 &contact_pair_candidates,
327 const double neighborhood_threshold,
328 const std::array<double, 2> &periodic_offset_per_direction);
329
330template void
333 &particle_container,
335 &adjacent_particles,
337 &contact_pair_candidates,
338 const double neighborhood_threshold,
339 const std::array<double, 2> &periodic_offset_per_direction);
340
341template void
344 &particle_container,
346 &adjacent_particles,
348 &contact_pair_candidates,
349 const double neighborhood_threshold,
350 const std::array<double, 2> &periodic_offset_per_direction);
351
352
353// 3D templates
354template void
357 &particle_container,
359 &adjacent_particles,
361 &contact_pair_candidates,
362 const double neighborhood_threshold,
363 const std::array<double, 3> &periodic_offset_per_direction);
364
365template void
368 &particle_container,
370 &adjacent_particles,
372 &contact_pair_candidates,
373 const double neighborhood_threshold,
374 const std::array<double, 3> &periodic_offset_per_direction);
375
376template void
379 &particle_container,
381 &adjacent_particles,
383 &contact_pair_candidates,
384 const double neighborhood_threshold,
385 const std::array<double, 3> &periodic_offset_per_direction);
386
387template void
390 &particle_container,
392 &adjacent_particles,
394 &contact_pair_candidates,
395 const double neighborhood_threshold,
396 const std::array<double, 3> &periodic_offset_per_direction);
397
398template void
401 &particle_container,
403 &adjacent_particles,
405 &contact_pair_candidates,
406 const double neighborhood_threshold,
407 const std::array<double, 3> &periodic_offset_per_direction);
Vector< double > delta(unsigned int order, unsigned int n, unsigned int j, const Vector< double > &times)
Recursive function for calculating the order divided differences ( ) that is used for calculating ba...
Definition bdf.cc:63
@ ghost_periodic_particle_particle
@ ghost_particle_particle
@ local_particle_particle
@ ghost_local_periodic_particle_particle
@ local_periodic_particle_particle
DEM particle property definitions and output name management.
template void particle_particle_fine_search< 3, local_particle_particle >(const typename DEM::dem_data_structures< 3 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 3 >::adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 3 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 3 > &periodic_offset_per_direction)
template void particle_particle_fine_search< 2, local_particle_particle >(const typename DEM::dem_data_structures< 2 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 2 >::adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 2 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 2 > &periodic_offset_per_direction)
template void particle_particle_fine_search< 2, ghost_local_periodic_particle_particle >(const typename DEM::dem_data_structures< 2 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 2 >::periodic_adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 2 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 2 > &periodic_offset_per_direction)
template void particle_particle_fine_search< 3, local_periodic_particle_particle >(const typename DEM::dem_data_structures< 3 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 3 >::periodic_adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 3 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 3 > &periodic_offset_per_direction)
void particle_particle_fine_search(const typename DEM::dem_data_structures< dim >::particle_index_iterator_map &particle_container, adjacent_pairs_for_contact_t< dim, contact_type > &adjacent_particles, const typename DEM::dem_data_structures< dim >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, dim > &periodic_offset_per_direction)
Iterates over a vector of maps (pairs_in_contact) to see if the particles which were in contact in th...
template void particle_particle_fine_search< 2, ghost_periodic_particle_particle >(const typename DEM::dem_data_structures< 2 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 2 >::periodic_adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 2 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 2 > &periodic_offset_per_direction)
template void particle_particle_fine_search< 3, ghost_periodic_particle_particle >(const typename DEM::dem_data_structures< 3 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 3 >::periodic_adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 3 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 3 > &periodic_offset_per_direction)
template void particle_particle_fine_search< 2, ghost_particle_particle >(const typename DEM::dem_data_structures< 2 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 2 >::adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 2 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 2 > &periodic_offset_per_direction)
std::pair< Tensor< 1, dim >, bool > nearest_periodic_translation(const Point< dim, double > &particle_one_location, const Point< dim, double > &particle_two_real_location, const std::array< double, dim > &periodic_offset_per_direction)
Find the translation that brings the nearest periodic image of particle two to particle one....
template void particle_particle_fine_search< 3, ghost_particle_particle >(const typename DEM::dem_data_structures< 3 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 3 >::adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 3 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 3 > &periodic_offset_per_direction)
template void particle_particle_fine_search< 2, local_periodic_particle_particle >(const typename DEM::dem_data_structures< 2 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 2 >::periodic_adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 2 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 2 > &periodic_offset_per_direction)
template void particle_particle_fine_search< 3, ghost_local_periodic_particle_particle >(const typename DEM::dem_data_structures< 3 >::particle_index_iterator_map &particle_container, typename DEM::dem_data_structures< 3 >::periodic_adjacent_particle_pairs &adjacent_particles, const typename DEM::dem_data_structures< 3 >::particle_particle_candidates &contact_pair_candidates, const double neighborhood_threshold, const std::array< double, 3 > &periodic_offset_per_direction)
std::conditional_t< contact_type==local_periodic_particle_particle|| contact_type==ghost_periodic_particle_particle|| contact_type==ghost_local_periodic_particle_particle, typename DEM::dem_data_structures< dim >::periodic_adjacent_particle_pairs, typename DEM::dem_data_structures< dim >::adjacent_particle_pairs > adjacent_pairs_for_contact_t
Selects adjacent_particle_pairs or periodic_adjacent_particle_pairs based on the contact_type.
ankerl::unordered_dense::map< types::particle_index, Particles::ParticleIterator< dim > > particle_index_iterator_map
ankerl::unordered_dense::map< types::particle_index, periodic_adjacent_particle_pairs_value > periodic_adjacent_particle_pairs
ankerl::unordered_dense::map< types::particle_index, std::vector< types::particle_index > > particle_particle_candidates
ankerl::unordered_dense::map< types::particle_index, adjacent_particle_pairs_value > adjacent_particle_pairs
Handle the information related to the calculation of the particle-particle contact force....
Derived struct of the base struct particle_particle_contact_info for periodic particle-particle conta...