Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
ib_particles_dem.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_ib_particles_dem_h
5#define lethe_ib_particles_dem_h
6
7#include <core/ib_particle.h>
8
11
12#include <deal.II/base/tensor.h>
13
14using namespace dealii;
15
16namespace Parameters
17{
18 template <int dim>
19 class IBParticles;
20 namespace Lagrangian
21 {
22 template <int dim>
23 class FloatingWalls;
24 struct BCDEM;
25 } // namespace Lagrangian
26} // namespace Parameters
27
28/**
29 * @brief A solver class for the DEM used in conjunction with IB particles and
30 * fluid_dynamics_sharp. This class defines and uses some functions of the
31 * DEM class that have been modified and simplified to be compatible with
32 * IB_particles.
33 *
34 * @tparam dim An integer that denotes the dimension of the space in which
35 * the flow is solved
36 *
37 * @ingroup solvers
38 */
39
40template <int dim>
42{
43public:
44 /** @brief Struct that contains history of the contact between two objects. This is the commonly used
45 * constructor since it houses all the information required to perform the
46 * contact calculation.
47 * */
49 {
50 Tensor<1, 3> normal_vector;
51 Point<3> contact_point;
56 std::vector<Tensor<1, 3>>
57 tangential_relative_velocity; // keep each step of RK4 in memory
58 };
59
60 /** @brief Struct is used to reduce the number of parameters passed in the function calculate_force_model.
61 * */
72
73 /**
74 * @brief
75 * Initialize the IBParticlesDEM object with the parameters, the mpi
76 * communicator and the particles.
77 *
78 * @param p_nsparam The parameters for the immersed boundary particles
79 * @param floating_walls_parameters The parameters for the floating walls.
80 * @param boundary_conditions_parameters The parameters for the DEM boundary conditions.
81 * @param mpi_communicator_input The mpi communicator of the simulation.
82 * @param particles The particles vector containing all the IB particles.
83 */
84 void
85 initialize(const std::shared_ptr<Parameters::IBParticles<dim>> &p_nsparam,
88 const std::shared_ptr<Parameters::Lagrangian::BCDEM>
90 const MPI_Comm &mpi_communicator_input,
91 const std::vector<IBParticle<dim>> &particles);
92
93
94 /**
95 * @brief
96 * Updates the boundary cells that are contact candidates for each of the
97 * particles.
98 *
99 * @param particles The particles vector containing all the IB particles.
100 * @param time The current CFD time.
101 */
102 void
103 update_particles(const std::vector<IBParticle<dim>> &particles, double time);
104
105
106 /**
107 * @brief
108 * Integrates the dynamics of the IB_particle taking into account the contact
109 * between particles and between particles and walls.
110 *
111 * @param dt The CFD time step.
112 * @param h_max The gap between the two particle.
113 * @param h_min The minimal gap distance considered in the force calculation to avoid the singularity of the model.
114 * @param rho The fluid density.
115 * @param mu The fluid viscosity.
116 */
117 void
118 integrate_particles_motion(const double dt,
119 const double h_max,
120 const double h_min,
121 const double rho,
122 const double mu);
123
124 /**
125 * @brief Calculates non-linear (Hertzian) particle-particle contact force
126 *
127 * @param dt_dem The sub time stepping time step.
128 * @param contact_force a vector containing the contact force between particles
129 * @param contact_torque a vector containing the contact torques between particles
130 */
131 void
132 calculate_pp_contact_force(const double dt_dem,
133 std::vector<Tensor<1, 3>> &contact_force,
134 std::vector<Tensor<1, 3>> &contact_torque);
135
136 /**
137 * @brief Updates the contact candidates of all the particles
138 */
139 void
141
142
143 /**
144 * @brief Calculates non-linear (Hertzian) particle-wall contact force
145 *
146 * @param dt_dem The sub time stepping time step.
147 * @param contact_force a vector containing the contact force between particles
148 * @param contact_torque a vector containing the contact torques between particles
149 */
150 void
151 calculate_pw_contact_force(const double dt_dem,
152 std::vector<Tensor<1, 3>> &contact_force,
153 std::vector<Tensor<1, 3>> &contact_torque);
154
155
156 /**
157 * @brief Calculates non-linear (Hertzian) force between two objects. Take into input the physical properties and contact state of the two objects.
158 *
159 * @param normal_overlap Contact normal overlap
160 * @param contact_info A container that contains the required information for
161 * calculation of the contact force for a particle pair in contact
162 * @param contact_point The contact point between the two objects
163 * @param contact_normal Contact normal unit vector
164 * @param normal_force Contact normal force
165 * @param tangential_force Contact tangential force
166 * @param rolling_resistance_torque Contact rolling resistance torque
167 * @param particle_one_position the position of particle one
168 * @param particle_one_velocity the velocity of particle one
169 * @param particle_one_omega the angular velocity of particle one
170 * @param particle_one_properties the physical properties of particle one
171 * @param particle_two_position the position of particle two
172 * @param particle_two_velocity the velocity of particle two
173 * @param particle_two_omega the angular velocity of particle two
174 * @param particle_two_properties the physical properties of particle two
175 * @param dt the dem time step.
176 */
177 void
178 calculate_force_model(const double normal_overlap,
179 ContactInfo &contact_info,
180 Point<3> &contact_point,
181 Tensor<1, 3> &contact_normal,
182 Tensor<1, 3> &normal_force,
183 Tensor<1, 3> &tangential_force,
184 Tensor<1, 3> &rolling_resistance_torque,
185 Point<dim> &particle_one_position,
186 Tensor<1, 3> &particle_one_velocity,
187 Tensor<1, 3> &particle_one_omega,
188 const ObjectProperties particle_one_properties,
189 Point<dim> &particle_two_position,
190 Tensor<1, 3> &particle_two_velocity,
191 Tensor<1, 3> &particle_two_omega,
192 const ObjectProperties particle_two_properties,
193 const double dt);
194
195
196 /**
197 * @brief Calculates particle-particle lubrication force. The force is based on the formula from
198 * Microhydrodynamics: Principles and Selected Applications by Kim, Sangtae;
199 * Karrila, Seppo J. ISBN 13: 9780750691734
200 *
201 * @param dt_dem The sub time stepping time step.
202 * @param h_max The gap between the two particle.
203 * @param h_min The minimal gap distance considered in the force calculation to avoid the singularity of the model.
204 * @param mu The fluid viscosity.
205 * @param lubrication_force a vector containing the lubrication force on the particles.
206 * @param lubrication_torque a vector containing the lubrication torques on the particles.
207 */
208 void
209 calculate_pp_lubrication_force(const double dt_dem,
210 const double h_max,
211 const double h_min,
212 const double mu,
213 std::vector<Tensor<1, 3>> &lubrication_force,
214 std::vector<Tensor<1, 3>> &lubrication_torque);
215
216
217 /**
218 * @brief Calculates particle-wall lubrication force
219 *
220 * @param dt_dem The sub time stepping time step.
221 * @param h_max The gap between particle and the wall below which we evaluate the force.
222 * @param h_min The minimal gap distance considered in the force calculation to avoid the singularity of the model.
223 * @param mu The fluid viscosity.
224 * @param lubrication_force a vector containing the lubrication force on the particles.
225 * @param lubrication_torque a vector containing the lubrication torques on the particles.
226 */
227 void
228 calculate_pw_lubrication_force(const double dt_dem,
229 const double h_max,
230 const double h_min,
231 const double mu,
232 std::vector<Tensor<1, 3>> &lubrication_force,
233 std::vector<Tensor<1, 3>> &lubrication_torque);
234
235 /**
236 * @brief Update the boundary cells that are contact candidates for each
237 * particle.
238 *
239 * The wall-contact search relies on the lubrication/contact model described
240 * in Microhydrodynamics: Principles and Selected Applications by Kim,
241 * Sangtae and Karrila, Seppo J. ISBN 13: 9780750691734.
242 *
243 * @param particles The particles vector containing all the IB particles.
244 * @param dof_handler The dof handler of the mesh used for the fluid simulation.
245 * @param face_quadrature_formula The face quadrature formula used in the elements.
246 * @param mapping The FEM mapping of the face element.
247 */
248
249 void
251 std::vector<IBParticle<dim>> &particles,
252 const DoFHandler<dim> &dof_handler,
253 const Quadrature<dim - 1> &face_quadrature_formula,
254 const Mapping<dim> &mapping);
255
256
257 std::vector<IBParticle<dim>> dem_particles;
258
259 /**
260 * @brief Return the particle-particle contact map built for the IB DEM
261 * coupling.
262 */
263 const std::map<unsigned int, std::map<unsigned int, ContactInfo>> &
265 {
266 return pp_contact_map;
267 }
268
269private:
270 /**
271 * @brief Check whether a boundary should be ignored for Sharp-IB particle
272 * wall interactions.
273 *
274 * Outlet and periodic DEM boundaries do not represent colliding walls and
275 * are therefore excluded from the wall-contact search.
276 *
277 * @param boundary_id Boundary id under consideration.
278 * @return `true` if the boundary must be excluded from contact handling.
279 */
280 bool
281 is_boundary_excluded(const types::boundary_id boundary_id) const;
282
283 /**
284 * @brief Get the DEM wall motion prescribed on a boundary.
285 *
286 * This converts the DEM boundary-condition parameters into the translational
287 * and angular wall velocities used by Sharp-IB particle-wall interaction
288 * models.
289 *
290 * @param boundary_id Boundary id under consideration.
291 * @param point_on_boundary Contact point on the boundary.
292 * @param wall_velocity Translational wall velocity.
293 * @param wall_angular_velocity Angular wall velocity.
294 * @param wall_rotation_axis_point Point on the rotation axis used for
295 * rotational wall motion.
296 */
297 void
298 get_wall_motion(const types::boundary_id boundary_id,
299 const Point<dim> &point_on_boundary,
300 Tensor<1, 3> &wall_velocity,
301 Tensor<1, 3> &wall_angular_velocity,
302 Point<dim> &wall_rotation_axis_point) const;
303
304 // A struct to store boundary cells' information
306 {
307 template <class Archive>
308 void
309 serialize(Archive &ar, const unsigned int /*version*/)
310 {
311 for (int i = 0; i < dim; ++i)
312 {
313 ar &normal_vector;
315 ar &boundary_index;
316 }
317 }
318
319 Tensor<1, dim> normal_vector;
321 types::boundary_id boundary_index;
322 };
323
324 // These structs are used to specify the default value of a variable in a map
325 // or set. This is used to find the best particle wall contact candidate.
327 {
328 double value = DBL_MAX;
329 };
330 // This enum defines the lowest index of a floating wall in the particle wall
331 // contact. This prevents a wall floating wall from shearing the same index as
332 // a standard boundary.
337
338 std::shared_ptr<Parameters::IBParticles<dim>> parameters;
339 std::shared_ptr<Parameters::Lagrangian::FloatingWalls<dim>>
341 std::shared_ptr<Parameters::Lagrangian::BCDEM> boundary_conditions_parameters;
344
345 std::vector<std::set<unsigned int>> particles_contact_candidates;
346
347 // Store the previous contact point as initial guess for the next search
348 std::map<unsigned int, std::map<unsigned int, Point<dim>>>
350 std::map<unsigned int, std::map<unsigned int, Point<dim>>>
352
353 // Particles contact history
354 std::map<unsigned int, std::map<unsigned int, ContactInfo>> pp_contact_map;
355 std::map<unsigned int, std::map<types::boundary_id, ContactInfo>>
357
358 // A vector of vectors of candidate cells for each of the particle.
359 std::vector<std::map<types::boundary_id, BoundaryCellsInfo>> boundary_cells;
360
361 double cfd_time;
362};
363
364
365#endif // LETHE_IB_PARTICLES_DEM_H
Handles all the parameters declared in the parameter handler file.
Define the behavior of a specific particle for the sharp interface IB solver.
Definition ib_particle.h:26
A solver class for the DEM used in conjunction with IB particles and fluid_dynamics_sharp....
bool is_boundary_excluded(const types::boundary_id boundary_id) const
Check whether a boundary should be ignored for Sharp-IB particle wall interactions.
void calculate_pw_contact_force(const double dt_dem, std::vector< Tensor< 1, 3 > > &contact_force, std::vector< Tensor< 1, 3 > > &contact_torque)
Calculates non-linear (Hertzian) particle-wall contact force.
std::map< unsigned int, std::map< unsigned int, Point< dim > > > previous_wall_contact_point
void calculate_pw_lubrication_force(const double dt_dem, const double h_max, const double h_min, const double mu, std::vector< Tensor< 1, 3 > > &lubrication_force, std::vector< Tensor< 1, 3 > > &lubrication_torque)
Calculates particle-wall lubrication force.
void calculate_force_model(const double normal_overlap, ContactInfo &contact_info, Point< 3 > &contact_point, Tensor< 1, 3 > &contact_normal, Tensor< 1, 3 > &normal_force, Tensor< 1, 3 > &tangential_force, Tensor< 1, 3 > &rolling_resistance_torque, Point< dim > &particle_one_position, Tensor< 1, 3 > &particle_one_velocity, Tensor< 1, 3 > &particle_one_omega, const ObjectProperties particle_one_properties, Point< dim > &particle_two_position, Tensor< 1, 3 > &particle_two_velocity, Tensor< 1, 3 > &particle_two_omega, const ObjectProperties particle_two_properties, const double dt)
Calculates non-linear (Hertzian) force between two objects. Take into input the physical properties a...
std::map< unsigned int, std::map< unsigned int, Point< dim > > > previous_particle_particle_contact_point
void calculate_pp_lubrication_force(const double dt_dem, const double h_max, const double h_min, const double mu, std::vector< Tensor< 1, 3 > > &lubrication_force, std::vector< Tensor< 1, 3 > > &lubrication_torque)
Calculates particle-particle lubrication force. The force is based on the formula from Microhydrodyna...
std::map< unsigned int, std::map< unsigned int, ContactInfo > > pp_contact_map
std::shared_ptr< Parameters::Lagrangian::BCDEM > boundary_conditions_parameters
std::vector< std::map< types::boundary_id, BoundaryCellsInfo > > boundary_cells
std::shared_ptr< Parameters::Lagrangian::FloatingWalls< dim > > floating_walls_parameters
const std::map< unsigned int, std::map< unsigned int, ContactInfo > > & get_particle_particle_contact_map() const
Return the particle-particle contact map built for the IB DEM coupling.
std::vector< IBParticle< dim > > dem_particles
void update_contact_candidates()
Updates the contact candidates of all the particles.
void update_particles_boundary_contact(std::vector< IBParticle< dim > > &particles, const DoFHandler< dim > &dof_handler, const Quadrature< dim - 1 > &face_quadrature_formula, const Mapping< dim > &mapping)
Update the boundary cells that are contact candidates for each particle.
void calculate_pp_contact_force(const double dt_dem, std::vector< Tensor< 1, 3 > > &contact_force, std::vector< Tensor< 1, 3 > > &contact_torque)
Calculates non-linear (Hertzian) particle-particle contact force.
std::map< unsigned int, std::map< types::boundary_id, ContactInfo > > pw_contact_map
void initialize(const std::shared_ptr< Parameters::IBParticles< dim > > &p_nsparam, const std::shared_ptr< Parameters::Lagrangian::FloatingWalls< dim > > &floating_walls_parameters, const std::shared_ptr< Parameters::Lagrangian::BCDEM > &boundary_conditions_parameters, const MPI_Comm &mpi_communicator_input, const std::vector< IBParticle< dim > > &particles)
Initialize the IBParticlesDEM object with the parameters, the mpi communicator and the particles.
DEMSolverParameters< dim > dem_parameters
void get_wall_motion(const types::boundary_id boundary_id, const Point< dim > &point_on_boundary, Tensor< 1, 3 > &wall_velocity, Tensor< 1, 3 > &wall_angular_velocity, Point< dim > &wall_rotation_axis_point) const
Get the DEM wall motion prescribed on a boundary.
std::vector< std::set< unsigned int > > particles_contact_candidates
std::shared_ptr< Parameters::IBParticles< dim > > parameters
void update_particles(const std::vector< IBParticle< dim > > &particles, double time)
Updates the boundary cells that are contact candidates for each of the particles.
void integrate_particles_motion(const double dt, const double h_max, const double h_min, const double rho, const double mu)
Integrates the dynamics of the IB_particle taking into account the contact between particles and betw...
MPI_Comm mpi_communicator
Parameters for floating walls in DEM simulations.
void serialize(Archive &ar, const unsigned int)
Struct that contains history of the contact between two objects. This is the commonly used constructo...
std::vector< Tensor< 1, 3 > > tangential_relative_velocity
Tensor< 1, 3 > rolling_resistance_spring_torque
Tensor< 1, 3 > tangential_displacement
Struct is used to reduce the number of parameters passed in the function calculate_force_model.
Boundary conditions for DEM simulations.