Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
periodic_boundaries_manipulator.h
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
4#ifndef lethe_periodic_boundaries_manipulator_h
5#define lethe_periodic_boundaries_manipulator_h
6
8
10#include <dem/data_containers.h>
12
13#include <deal.II/distributed/tria.h>
14
15#include <deal.II/particles/particle_handler.h>
16
17#include <array>
18#include <map>
19#include <unordered_map>
20
21using namespace dealii;
22
23/**
24 * This class corresponds to a manipulator of the particles crossing periodic
25 * cells in DEM. It maps cell information of the pairs of periodic cells
26 * and manipulate the particles' location when they cross periodic boundaries,
27 * i.e. when a particle cross a periodic boundary (0 or 1) its location is
28 * modified with the offset between faces of periodic cells on periodic
29 * boundaries.
30 *
31 * @note Currently the code only supports periodic boundaries that are
32 * parallel and aligned with an axis of the domain (e.g., x axis).
33 */
34
35template <int dim>
37{
38public:
40
41 /**
42 * @brief Sets the periodic boundaries parameters.
43 *
44 * @param[in] periodic_boundaries Periodic boundary pairs of the simulation,
45 * keyed by the principal periodic boundary id (periodic id 0).
46 */
47 void
50
51 /**
52 * @brief Execute the mapping of the cells on periodic boundaries and store
53 * information in periodic_boundaries_cells_information.
54 *
55 * @param[in] triangulation Triangulation.
56 * @param[out] periodic_boundaries_cells_information Map (multimap) of
57 * information of the pair of cells on periodic boundaries.
58 */
59 void
61 const parallel::distributed::Triangulation<dim> &triangulation,
63 &periodic_boundaries_cells_information);
64
65 /**
66 * @brief Moves particles crossing periodic boundaries (any side)
67 * particle_handler doesn't allow automated particle displacement since it is
68 * not linked to triangulation and its periodic mapping.
69 *
70 * @param[in,out] particle_handler Particle handler of particles located in
71 * boundary cells.
72 * @param[in] periodic_boundaries_cells_information Map of information of the
73 * pair of cells on periodic boundaries.
74 *
75 * @return Flag if at least one particle has been moved to the other periodic
76 * cell.
77 */
78 bool
80 const Particles::ParticleHandler<dim> &particle_handler,
82 &periodic_boundaries_cells_information);
83
84 /**
85 * @brief Return the periodic offset distance for a specific pb0 boundary ID.
86 * All pairs of cells on that pair of periodic boundaries are assumed to have
87 * the same offset. If no periodic offset has been identified for the
88 * boundary id, a zero tensor is inserted as a default value.
89 *
90 * @param[in] boundary_id ID of the boundary to query.
91 *
92 * @return Offset distance between periodic boundaries.
93 */
94 inline const Tensor<1, dim> &
95 get_periodic_offset_distance(const types::boundary_id boundary_id)
96 {
97 // If no offset was identified during looping over the cell, a zero
98 // tensor is returned as a default offset.
99 if (!periodic_offsets.contains(boundary_id))
100 {
101 Tensor<1, dim> zero_tensor;
102 periodic_offsets.insert(std::make_pair(boundary_id, zero_tensor));
103 }
104 return periodic_offsets.at(boundary_id);
105 }
106
107 /**
108 * @brief Return the periodic boundary pairs, keyed by the principal periodic
109 * boundary id (periodic id 0).
110 *
111 * @return Map of periodic boundary pairs keyed by principal periodic
112 * boundary id.
113 */
114 inline const Parameters::PeriodicBoundaries &
116 {
117 return periodic_boundaries;
118 }
119
120 /**
121 * @brief Return the signed periodic offset for every direction.
122 *
123 * @return Array whose component d is the signed periodic offsets of the
124 * domain along direction d if d is periodic, or 0 otherwise.
125 */
126 inline const std::array<double, dim> &
131
132private:
133 /**
134 * @brief Get boundary information related to a face at a periodic
135 * boundary and store it in a periodic_boundaries_cells_info_struct
136 * object.
137 *
138 * @param[in] cell Current cell on boundary.
139 * @param[in] face_id Face located on boundary.
140 * @param[out] boundaries_information Reference to the object with periodic
141 * boundary information.
142 */
143 void
145 typename Triangulation<dim>::cell_iterator cell,
146 const unsigned int face_id,
147 periodic_boundaries_cells_info_struct<dim> &boundaries_information);
148
149 /**
150 * @brief Check if particle is outside the cell, if so, modify the
151 * location of the particle using the relevant periodic offset for the
152 * boundary.
153 *
154 * @param[in] boundaries_cells_content Reference to the object with periodic
155 * boundary information.
156 * @param[in] particles_in_pb0_cell If the particles are linked to a cell on
157 * the periodic boundary 0 (true) or the periodic boundary 1 (false).
158 * @param[in,out] particles_in_cell Iterator to the particles in cell.
159 * @param[out] particle_has_been_moved Flag the particle has been moved to
160 * the other periodic cell.
161 */
162 void
164 const periodic_boundaries_cells_info_struct<dim> &boundaries_cells_content,
165 const bool &particles_in_pb0_cell,
166 typename Particles::ParticleHandler<dim>::particle_iterator_range
167 &particles_in_cell,
168 bool &particle_has_been_moved);
169
170 /**
171 * @brief Compute the signed periodic offset for every direction and store it
172 * in periodic_offset_per_direction.
173 */
174 void
176
177 /**
178 * @brief Flag for periodic boundary conditions in simulation. Useful to
179 * exit function when there are no periodic boundaries.
180 */
182
183 /**
184 * @brief Periodic boundary pairs of the simulation. Each entry carries the
185 * neighbor boundary id of the pair and the direction of periodicity, which
186 * is normal to the periodic boundaries. Keys of this map are
187 * the principal periodic boundary ids (periodic id 0).
188 */
190
191 /**
192 * @brief Map storing offset distance between periodic boundaries, keyed by
193 * the boundary ID (pb0). It is calculated from the first pair of cells on
194 * periodic boundaries, so all pairs of cells on a given peridodic boundary
195 * are assumed to have the same offset.
196 */
197 std::unordered_map<types::boundary_id, Tensor<1, dim>> periodic_offsets;
198
199 /**
200 * @brief Signed periodic distance associated with each periodic boundary
201 * pairs. The component d of this array returns the distance, in absolute
202 * value, between the two boundaries facing in that d direction (x,y,z). If
203 * the associated d direction is not periodic, the array returns a 0. This
204 * array is used by the particle-particle fine search to find the nearest
205 * periodic image of a particle.
206 */
207 std::array<double, dim> periodic_offset_per_direction{};
208};
209
210#endif
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)....
const Tensor< 1, dim > & get_periodic_offset_distance(const types::boundary_id boundary_id)
Return the periodic offset distance for a specific pb0 boundary ID. All pairs of cells on that pair o...
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...
const Parameters::PeriodicBoundaries & get_periodic_boundaries() const
Return the periodic boundary pairs, keyed by the principal periodic boundary id (periodic id 0).
const std::array< double, dim > & get_periodic_offset_per_direction() const
Return the signed periodic offset for every direction.
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...