Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
periodic_boundaries_manipulator.cc
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2022-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
5
7
8#include <deal.II/base/quadrature_lib.h>
9
10#include <deal.II/distributed/tria.h>
11
12#include <deal.II/fe/fe_q.h>
13#include <deal.II/fe/fe_values.h>
14
15#include <algorithm>
16#include <array>
17#include <ranges>
18#include <unordered_map>
19
20using namespace dealii;
21
22template <int dim>
26
27template <int dim>
28void
31{
32 // If this function is reached and the map is not empty
33 if (periodic_boundaries.empty())
34 return;
35
36 // compute_periodic_offset_per_direction() sums every periodic boundary
37 // pair's offset directly into a single std::array<double, dim>, one
38 // component per direction. This requires at most one periodic boundary
39 // pair per direction: two pairs sharing a direction would silently add
40 // into the same component.
41 std::array<bool, dim> direction_is_used{};
42 for (const auto &[id, boundary] : periodic_boundaries)
43 {
44 AssertThrow(std::cmp_less(boundary.direction, dim),
45 ExcMessage(
46 "PeriodicBoundariesManipulator: periodic direction " +
47 std::to_string(boundary.direction) +
48 " configured for boundary id " + std::to_string(id) +
49 " is out of range for a " + std::to_string(dim) +
50 "D simulation."));
51 AssertThrow(
52 !direction_is_used[boundary.direction],
53 ExcMessage(
54 "PeriodicBoundariesManipulator: more than one periodic boundary "
55 "pair is configured for direction " +
56 std::to_string(boundary.direction) +
57 ". At most one periodic boundary pair per direction is "
58 "supported."));
59 direction_is_used[boundary.direction] = true;
60 }
61
63
64 // Communicate to the action manager that there are periodic boundaries
66
67 this->periodic_boundaries = periodic_boundaries;
68
69 // Initialize offset map
70 this->periodic_offsets.clear();
71}
72
73template <int dim>
74void
76 typename Triangulation<dim>::cell_iterator cell,
77 const unsigned int face_id,
78 periodic_boundaries_cells_info_struct<dim> &boundaries_information)
79{
80 // Initialize a simple quadrature for the system. This will be used to
81 // obtain a single sample point on the boundaries faces.
82 const FE_Q<dim> fe(1);
83 QGauss<dim - 1> face_quadrature_formula(1);
84 FEFaceValues<dim> fe_face_values(fe,
85 face_quadrature_formula,
86 update_values | update_quadrature_points |
87 update_normal_vectors);
88 Tensor<1, dim> normal_vector;
89 Point<dim> quad_point;
90
91 // Store information of the cell
92 boundaries_information.cell = cell;
93 boundaries_information.boundary_id = cell->face(face_id)->boundary_id();
94
95 // Store information of the periodic cell
96 boundaries_information.periodic_cell = cell->periodic_neighbor(face_id);
97
98 // Find the normal vector of the boundary face and point
99 fe_face_values.reinit(cell, face_id);
100 boundaries_information.normal_vector = fe_face_values.normal_vector(0);
101 boundaries_information.point_on_face = fe_face_values.quadrature_point(0);
102
103 // Find the normal vector of the corresponding periodic boundary face and
104 // point with the reinit FE face values
105 fe_face_values.reinit(boundaries_information.periodic_cell,
106 cell->periodic_neighbor_face_no(face_id));
107 normal_vector = fe_face_values.normal_vector(0);
108 quad_point = fe_face_values.quadrature_point(0);
109 boundaries_information.periodic_normal_vector = normal_vector;
110 boundaries_information.point_on_periodic_face = quad_point;
111}
112
113template <int dim>
114void
116 const parallel::distributed::Triangulation<dim> &triangulation,
118 &periodic_boundaries_cells_information)
119{
121 return;
122
123 periodic_boundaries_cells_information.clear();
124 periodic_offsets.clear();
125
126 // Temp storage to calculate offsets only once per ID
127 std::map<types::boundary_id, bool> offset_calculated;
128 for (const auto &primary_mesh_id : periodic_boundaries | std::views::keys)
129 offset_calculated[primary_mesh_id] = false;
130
131 // Iterating over the active cells in the triangulation
132 for (const auto &cell : triangulation.active_cell_iterators())
133 {
134 if (cell->is_locally_owned() || cell->is_ghost())
135 {
136 if (cell->at_boundary())
137 {
138 // Iterating over cell faces
139 for (const auto &face : cell->face_iterators())
140 {
141 const types::boundary_id face_boundary_id =
142 face->boundary_id();
143
144 // Check if the face matches any of the principal PB IDs
145 auto it = periodic_boundaries.find(face_boundary_id);
146 if (it != periodic_boundaries.end())
147 {
148 // Get direction corresponding to this periodic boundary
149 const unsigned int current_direction =
150 it->second.direction;
151
153 boundaries_information;
154 unsigned int face_id = cell->face_iterator_to_index(face);
155
157 face_id,
158 boundaries_information);
159
160 // Insert into multimap
161 // One entry per boundary found
162 periodic_boundaries_cells_information.insert(
163 {boundaries_information.cell
164 ->global_active_cell_index(),
165 boundaries_information});
166
167 // Calculate offset if it has not yet been done for this
168 // periodic boundary id
169 if (!offset_calculated[face_boundary_id])
170 {
171 Tensor<1, dim> offset;
172 offset[current_direction] =
173 boundaries_information
174 .point_on_periodic_face[current_direction] -
175 boundaries_information
176 .point_on_face[current_direction];
177
178 periodic_offsets[face_boundary_id] = offset;
179 offset_calculated[face_boundary_id] = true;
180 }
181 }
182 }
183 }
184 }
185 }
186
187 // Once periodic offsets are calculated, combine them into a single
188 // per-direction array
190}
191
192template <int dim>
193void
195 const periodic_boundaries_cells_info_struct<dim> &boundaries_cells_content,
196 const bool &particles_in_pb0_cell,
197 typename Particles::ParticleHandler<dim>::particle_iterator_range
198 &particles_in_cell,
199 bool &particle_has_been_moved)
200{
201 // Retrieve the correct offset for this specific boundary interaction.
202 // boundaries_cells_content contains a single cell on a periodic boundary
203 // and its associated periodic cell. The offset between these cells is
204 // obtained from periodic_offsets to displace particles across these cells.
205 // relevant_offset is a vector pointing from pb0 to pb1, so we check on which
206 // side the current particles are and offset their positions accordingly
207 // (either +offset or -offset).
208
209 Tensor<1, dim> relevant_offset;
210
211 // boundaries_cells_content.boundary_id corresponds to the face on the
212 // "main" side (pb0)
213 auto offset_it = periodic_offsets.find(boundaries_cells_content.boundary_id);
214 if (offset_it != periodic_offsets.end())
215 {
216 relevant_offset = offset_it->second;
217 }
218 else
219 {
220 // Fallback/error, map_periodic_cells should populate this
221 // return;
222 AssertThrow(false,
223 ExcMessage(
224 "PeriodicBoundariesManipulator: no periodic offset found "
225 "for boundary id " +
226 std::to_string(boundaries_cells_content.boundary_id) +
227 ". This means map_periodic_cells() did not populate "
228 "periodic_offsets for this boundary."));
229 }
230
231 for (auto particle = particles_in_cell.begin();
232 particle != particles_in_cell.end();
233 ++particle)
234 {
235 // Get the current particle location
236 Point<dim> particle_position = particle->get_location();
237
238 // Initialize points and normal vector related of the cell that contains
239 // the particle
240 Point<dim> point_on_face;
241 Tensor<1, dim> normal_vector, distance_between_faces;
242
243 if (particles_in_pb0_cell)
244 {
245 point_on_face = boundaries_cells_content.point_on_face;
246 normal_vector = boundaries_cells_content.normal_vector;
247 distance_between_faces = relevant_offset;
248 }
249 else
250 {
251 point_on_face = boundaries_cells_content.point_on_periodic_face;
252 normal_vector = boundaries_cells_content.periodic_normal_vector;
253 distance_between_faces = -relevant_offset;
254 }
255
256 // Calculate distance between particle position and the face of
257 // boundary cell d = n•(pt_particle - pt_face)
258 double distance_with_face =
259 scalar_product(particle_position - point_on_face, normal_vector);
260
261 // If distance >= 0, particle is outside of cell (or on face).
262 // If so, particle location is modified to get moved into the periodic
263 // cell.
264 if (distance_with_face >= 0.0)
265 {
266 // Move particle outside the current cell to the periodic cell.
267 particle_position += distance_between_faces;
268 particle->set_location(particle_position);
269
270 // Update flag to indicate that particle has been moved
271 particle_has_been_moved = true;
272 }
273 }
274}
275
276template <int dim>
277void
279{
280 std::array<double, dim> offset_per_direction{};
281
282 // Since Lethe only supports PBC that are aligned with the cartesian
283 // coordinates (x,y,z), each entry of periodic_offsets is nonzero in exactly
284 // one component (the direction of the associated periodic boundary pair).
285 // Further more, Lethe does not support multiple PBC in the same direction.
286 // Instead of storing the entire Tensor<1,dim>, we only store the norm of that
287 // tensor, which is equivalent to the distance between linked periodic
288 // boundaries, or period of the domain for a given direction. Since the PBC
289 // can be declare in any order (not necessarily x first, y second and z last)
290 // we use the += instead of .norm()
291 for (auto const &[id, offset] : this->periodic_offsets)
292 for (int d = 0; d < dim; ++d)
293 offset_per_direction[d] += offset[d];
294
295 this->periodic_offset_per_direction = offset_per_direction;
296}
297
298template <int dim>
299bool
301 const Particles::ParticleHandler<dim> &particle_handler,
303 &periodic_boundaries_cells_information)
304{
306 return false;
307
308 bool particle_has_been_moved = false;
309
310 if (!periodic_boundaries_cells_information.empty())
311 {
312 // Iterate over all entries. Multimap correctly handles periodic corner
313 // cells in higher dimensions. In 2D, a periodic corner cell would be
314 // iterated over twice: once for x-boundary, once for y-boundary.
315 for (auto boundaries_cells_information_iterator =
316 periodic_boundaries_cells_information.begin();
317 boundaries_cells_information_iterator !=
318 periodic_boundaries_cells_information.end();
319 ++boundaries_cells_information_iterator)
320 {
321 // Get the cell and periodic cell from map
322 auto boundaries_cells_content =
323 boundaries_cells_information_iterator->second;
324 auto cell = boundaries_cells_content.cell;
325 auto periodic_cell = boundaries_cells_content.periodic_cell;
326
327 // Check and execute displacement of particles crossing a periodic
328 // wall.
329 // Case when particle goes from periodic boundary 0 to 1
330 if (cell->is_locally_owned())
331 {
332 typename Particles::ParticleHandler<dim>::particle_iterator_range
333 particles_in_cell = particle_handler.particles_in_cell(cell);
334 const bool particles_exist_in_main_cell =
335 !particles_in_cell.empty();
336
337 if (particles_exist_in_main_cell)
338 {
339 bool particles_in_pb0_cell = true;
340 check_and_move_particles(boundaries_cells_content,
341 particles_in_pb0_cell,
342 particles_in_cell,
343 particle_has_been_moved);
344 }
345 }
346
347 // Case when particle goes from periodic boundary 1 to 0
348 if (periodic_cell->is_locally_owned())
349 {
350 typename Particles::ParticleHandler<dim>::particle_iterator_range
351 particles_in_periodic_cell =
352 particle_handler.particles_in_cell(periodic_cell);
353 const bool particles_exist_in_periodic_cell =
354 !particles_in_periodic_cell.empty();
355
356 if (particles_exist_in_periodic_cell)
357 {
358 bool particles_in_pb0_cell = false;
359 check_and_move_particles(boundaries_cells_content,
360 particles_in_pb0_cell,
361 particles_in_periodic_cell,
362 particle_has_been_moved);
363 }
364 }
365 }
366 }
367
368 return particle_has_been_moved;
369}
370
static DEMActionManager * get_action_manager()
Getter of the unique instance of the DEMActionManager.
void set_periodic_boundaries_enabled()
Flag that there are periodic boundary in the simulation.
std::array< double, dim > periodic_offset_per_direction
Signed periodic distance associated with each periodic boundary pairs. The component d of this array ...
void compute_periodic_offset_per_direction()
Compute the signed periodic offset for every direction and store it in periodic_offset_per_direction.
bool periodic_boundaries_enabled
Flag for periodic boundary conditions in simulation. Useful to exit function when there are no period...
std::unordered_map< types::boundary_id, Tensor< 1, dim > > periodic_offsets
Map storing offset distance between periodic boundaries, keyed by the boundary ID (pb0)....
Parameters::PeriodicBoundaries periodic_boundaries
Periodic boundary pairs of the simulation. Each entry carries the neighbor boundary id of the pair an...
void get_periodic_boundaries_info(typename Triangulation< dim >::cell_iterator cell, const unsigned int face_id, periodic_boundaries_cells_info_struct< dim > &boundaries_information)
Get boundary information related to a face at a periodic boundary and store it in a periodic_boundari...
void map_periodic_cells(const parallel::distributed::Triangulation< dim > &triangulation, typename DEM::dem_data_structures< dim >::periodic_boundaries_cells_info &periodic_boundaries_cells_information)
Execute the mapping of the cells on periodic boundaries and store information in periodic_boundaries_...
void set_periodic_boundaries_information(const Parameters::PeriodicBoundaries &periodic_boundaries)
Sets the periodic boundaries parameters.
void check_and_move_particles(const periodic_boundaries_cells_info_struct< dim > &boundaries_cells_content, const bool &particles_in_pb0_cell, typename Particles::ParticleHandler< dim >::particle_iterator_range &particles_in_cell, bool &particle_has_been_moved)
Check if particle is outside the cell, if so, modify the location of the particle using the relevant ...
bool execute_particles_displacement(const Particles::ParticleHandler< dim > &particle_handler, const typename DEM::dem_data_structures< dim >::periodic_boundaries_cells_info &periodic_boundaries_cells_information)
Moves particles crossing periodic boundaries (any side) particle_handler doesn't allow automated part...
std::map< dealii::types::boundary_id, PeriodicBoundary > PeriodicBoundaries
The periodic boundary pairs of a simulation, keyed by the principal (first) boundary id of each pair.
std::unordered_multimap< types::global_cell_index, periodic_boundaries_cells_info_struct< dim > > periodic_boundaries_cells_info
Handle the information related to the periodic boundary cells which will be used for particle-wall co...
Triangulation< dim >::active_cell_iterator periodic_cell
Triangulation< dim >::active_cell_iterator cell