Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
force_chains_visualization.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2024-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_force_chains_visualization_h
5#define lethe_force_chains_visualization_h
6
7#include <core/pvd_handler.h>
8
9#include <dem/contact_type.h>
10#include <dem/data_containers.h>
14
15#include <boost/range/adaptor/map.hpp>
16
17#include <vector>
18
19using namespace dealii;
20using namespace DEM;
21
22/**
23 * @brief Base class for the particles force chains contact force models.
24 * This class does not implement any of the models, but ensures that
25 * an interface without template specialization is available. Every model
26 * implementation are carried out in the ParticlesForceChains class which is
27 * templated by the contact model type.
28 * @tparam dim An integer that denotes the number of spatial dimensions.
29 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
30 */
31template <int dim, typename PropertiesIndex>
33{
34protected:
35 /**
36 * @brief Use a ParticleParticleContactForce object to calculate normal forces
37 * between particles. Store normal forces and particles position in
38 * vectors.
39 *
40 * @param[in] local_adjacent_particles Container of the contact pair
41 * candidates information for calculation of the local particle-particle
42 * contact forces.
43 * @param[in] ghost_adjacent_particles Container of the contact pair
44 * candidates information for calculation of the local-ghost particle-particle
45 * contact forces.
46 * @param[out] vertices the vector of positions of touching particles.
47 * @param[out] normal_forces_vector the vector of normal forces between each
48 * touching particles.
49 */
50 virtual void
53 &local_adjacent_particles,
55 &ghost_adjacent_particles,
56 std::vector<Point<3>> &vertices,
57 std::vector<double> &normal_forces_vector) = 0;
58
59public:
60 virtual ~ParticlesForceChainsBase() = default;
61 /**
62 * @brief Output the force chains in VTU and PVTU files for each iteration and
63 * a PVD file.
64 *
65 * @param[in] dem_parameters DEM parameters declared in the .prm file
66 * @param[in] pvd_handler a PVDHandler to store the information about the file
67 * name and time associated with it
68 * @param[in] mpi_communicator The mpi communicator
69 * @param[in] folder a string that contains the path where the results are to
70 * be saved
71 * @param[in] iter the iteration number associated with the file
72 * @param[in] time the time associated with the file
73 * @param[in] local_adjacent_particles Container of the contact pair
74 * candidates information for calculation of the local particle-particle
75 * contact forces.
76 * @param[in] ghost_adjacent_particles Container of the contact pair
77 * candidates information for calculation of the local-ghost particle-particle
78 */
79 virtual void
81 PVDHandler &pvd_handler,
82 const MPI_Comm mpi_communicator,
83 const std::string folder,
84 const unsigned int iter,
85 const double time,
87 &local_adjacent_particles,
89 &ghost_adjacent_particles) = 0;
90};
91
92/**
93 * @brief Class that carries out the calculation of
94 * particle-particle contact force and the visualization of force chains
95 * by writing vtu files, pvtu files and a pvd file. Instead of using an
96 * inheritance hierarchy to distinguish between the contact model, the class is
97 * templated with the type of force model and rolling friction model.
98 * Consequently, the code for each combination of force model is generated at
99 * compile time.
100 *
101 * @tparam dim The dimension of the problem
102 * @tparam force_model The particle-particle contact force model
103 * @tparam rolling_friction_model The rolling resistance model
104 */
105template <
106 int dim,
107 typename PropertiesIndex,
111 : public ParticlesForceChainsBase<dim, PropertiesIndex>,
113 PropertiesIndex,
114 force_model,
115 rolling_friction_model>
116{
117public:
118 ParticlesForceChains(const DEMSolverParameters<dim> &dem_parameters);
119
120 virtual ~ParticlesForceChains() = default;
121
122public:
123 /**
124 * @brief Output the force chains in VTU and PVTU files for each iteration and
125 * a PVD file.
126 *
127 * @param[in] dem_parameters DEM parameters declared in the .prm file.
128 * @param[in] pvd_handler a PVDHandler to store the information about the file
129 * name and time associated with it.
130 * @param[in] mpi_communicator The mpi communicator.
131 * @param[in] folder a string that contains the path where the results are to
132 * be saved.
133 * @param[in] iter the iteration number associated with the file.
134 * @param[in] time the time associated with the file.
135 * @param[in] local_adjacent_particles Container of the contact pair
136 * candidates information for calculation of the local particle-particle
137 * contact forces.
138 * @param[in] ghost_adjacent_particles Container of the contact pair
139 * candidates information for calculation of the local-ghost particle-particle
140 * contact forces.
141 */
142 void
143 write_force_chains(const DEMSolverParameters<dim> &dem_parameters,
144 PVDHandler &pvd_handler,
145 const MPI_Comm mpi_communicator,
146 const std::string folder,
147 const unsigned int iter,
148 const double time,
150 &local_adjacent_particles,
152 &ghost_adjacent_particles) override;
153
154private:
155 /**
156 * @brief Calculate normal forces between all touching particles with
157 * ParticleParticleContactForce class' methods. Stock normal forces and
158 * particles position in vectors.
159 *
160 * @param[in] local_adjacent_particles Container of the contact pair
161 * candidates information for calculation of the local particle-particle
162 * contact forces.
163 * @param[in] ghost_adjacent_particles Container of the contact pair
164 * candidates information for calculation of the local-ghost particle-particle
165 * contact forces.
166 * @param[out] vertices the vector of positions of touching particles.
167 * @param[out] normal_forces_vector the vector of normal forces between each
168 * touching particles.
169 */
170 void
173 &local_adjacent_particles,
175 &ghost_adjacent_particles,
176 std::vector<Point<3>> &vertices,
177 std::vector<double> &normal_forces_vector) override;
178
179 /**
180 * @brief Execute the contact calculation step for the particle-particle
181 * contact only for local-local and local-ghost contacts with no periodicity.
182 * This is a simplified version of the contact calculation of the
183 * particle-particle contact forces class, without the other contact types and
184 * the update of the particles forces, torques and tangential displacement.
185 *
186 * @tparam contact_type The type of contact to be calculated.
187 * @param[in] adjacent_particles_list Container of the adjacent particles of a
188 * particles.
189 * @param[out] vertices the vector of positions of touching particles.
190 * @param[out] normal_forces_vector the vector of normal forces between each
191 * touching particles.
192 */
193 template <ContactType contact_type, typename ContactInfoContainer>
194 inline void
195 execute_contact_calculation(ContactInfoContainer &adjacent_particles_list,
196 std::vector<Point<3>> &vertices,
197 std::vector<double> &normal_forces_vector)
198 {
199 // No contact calculation if no adjacent particles
200 if (adjacent_particles_list.second_particles.empty())
201 return;
202
203 const double force_calculation_threshold_distance =
205
206 // Define local variables which will be used within the contact calculation
207 Tensor<1, 3> normal_unit_vector;
208 Tensor<1, 3> normal_force;
209 Tensor<1, 3> tangential_force;
210 Tensor<1, 3> particle_one_tangential_torque;
211 Tensor<1, 3> particle_two_tangential_torque;
212 Tensor<1, 3> rolling_resistance_torque;
213 double normal_relative_velocity_value;
214 Tensor<1, 3> tangential_relative_velocity;
215
216 // Gather information about particle 1 and set it up. The iterator to
217 // particle 1 is shared by all its contacts and stored once in the adjacency
218 // value.
219 auto particle_one = adjacent_particles_list.particle_one;
220 auto particle_one_properties = particle_one->get_properties();
221
222 // Fix particle one location for 2d and 3d
223 Point<3> particle_one_location = this->get_location(particle_one);
224
225 for (auto &&contact_info :
226 adjacent_particles_list.second_particles | boost::adaptors::map_values)
227 {
228 // Getting information (location and properties) of particle 2 in
229 // contact with particle 1
230 auto particle_two = contact_info.particle_two;
231 auto particle_two_properties = particle_two->get_properties();
232
233 if constexpr (contact_type == ghost_particle_particle)
234 {
235 // We create an arbitrary rule so that forces between local-ghost
236 // particle are not written twice by each processor.
237 if (particle_one->get_id() < particle_two->get_id())
238 continue;
239 }
240
241 // Get particle 2 location in dimension independent way
242 Point<3> particle_two_location = this->get_location(particle_two);
243
244 // Calculation of normal overlap
245 double normal_overlap =
246 0.5 * (particle_one_properties[PropertiesIndex::dp] +
247 particle_two_properties[PropertiesIndex::dp]) -
248 particle_one_location.distance(particle_two_location);
249
250 if (normal_overlap > force_calculation_threshold_distance)
251 {
252 update_contact_information(tangential_relative_velocity,
253 normal_relative_velocity_value,
254 normal_unit_vector,
255 particle_one_properties,
256 particle_two_properties,
257 particle_one_location,
258 particle_two_location);
259
260 this->calculate_contact(
261 contact_info,
262 tangential_relative_velocity,
263 normal_relative_velocity_value,
264 normal_unit_vector,
265 normal_overlap,
266 0., // dt is not required for the force chains
267 particle_one_properties,
268 particle_two_properties,
269 normal_force,
270 tangential_force,
271 particle_one_tangential_torque,
272 particle_two_tangential_torque,
273 rolling_resistance_torque);
274
275 vertices.push_back(particle_one_location);
276 vertices.push_back(particle_two_location);
277 normal_forces_vector.push_back(
278 scalar_product(normal_force, normal_unit_vector));
279 }
280 }
281 }
282
283 /**
284 * @brief Update the contact pair information for all contact force
285 * calculations.
286 *
287 * @param[out] tangential_relative_velocity Tangential relative velocity.
288 * @param[out] normal_relative_velocity_value Normal relative velocity.
289 * @param[out] normal_unit_vector Normal vector of the contact.
290 * @param[in] particle_one_properties Properties of particle one in contact.
291 * @param[in] particle_two_properties Properties of particle two in contact.
292 * @param[in] particle_one_location Location of particle one in contact.
293 * @param[in] particle_two_location Location of particle two in contact.
294 */
295 inline void
297 Tensor<1, 3> &tangential_relative_velocity,
298 double &normal_relative_velocity_value,
299 Tensor<1, 3> &normal_unit_vector,
300 const ArrayView<const double> &particle_one_properties,
301 const ArrayView<const double> &particle_two_properties,
302 const Point<3> &particle_one_location,
303 const Point<3> &particle_two_location)
304 {
305 // Calculation of the contact vector from particle one to particle two
306 Tensor<1, 3> contact_vector = particle_two_location - particle_one_location;
307
308 // Calculation of the normal unit contact vector
309 normal_unit_vector = contact_vector / contact_vector.norm();
310
311 // Defining velocities and angular velocities of particles one and
312 // two as vectors
313 Tensor<1, 3> particle_one_omega, particle_two_omega;
314
315 // Defining relative contact velocity
316 Tensor<1, 3> contact_relative_velocity;
317
318 // Assigning velocities and angular velocities of particles
319 contact_relative_velocity[0] =
320 particle_one_properties[PropertiesIndex::v_x] -
321 particle_two_properties[PropertiesIndex::v_x];
322 contact_relative_velocity[1] =
323 particle_one_properties[PropertiesIndex::v_y] -
324 particle_two_properties[PropertiesIndex::v_y];
325 contact_relative_velocity[2] =
326 particle_one_properties[PropertiesIndex::v_z] -
327 particle_two_properties[PropertiesIndex::v_z];
328
329 particle_one_omega[0] = particle_one_properties[PropertiesIndex::omega_x];
330 particle_one_omega[1] = particle_one_properties[PropertiesIndex::omega_y];
331 particle_one_omega[2] = particle_one_properties[PropertiesIndex::omega_z];
332
333 particle_two_omega[0] = particle_two_properties[PropertiesIndex::omega_x];
334 particle_two_omega[1] = particle_two_properties[PropertiesIndex::omega_y];
335 particle_two_omega[2] = particle_two_properties[PropertiesIndex::omega_z];
336
337 // Calculation of contact relative velocity
338 // v_ij = (v_i - v_j) + (R_i*omega_i + R_j*omega_j) × n_ij
339 contact_relative_velocity += (cross_product_3d(
340 0.5 * (particle_one_properties[PropertiesIndex::dp] * particle_one_omega +
341 particle_two_properties[PropertiesIndex::dp] * particle_two_omega),
342 normal_unit_vector));
343
344 // Calculation of normal relative velocity. Note that in the
345 // following line the product acts as inner product since both
346 // sides are vectors, while in the second line the product is
347 // scalar and vector product
348 normal_relative_velocity_value =
349 contact_relative_velocity * normal_unit_vector;
350
351 // Calculation of tangential relative velocity
352 // v_rt = v_ij - (v_ij⋅n_ij)*n_ij
353 tangential_relative_velocity =
354 contact_relative_velocity -
355 (normal_relative_velocity_value * normal_unit_vector);
356 }
357
358 /**
359 * @brief Create a triangulation with a unique cell (represented by a line)
360 * for each normal force between two particles.
361 *
362 * @param[out] tria Empty triangulation used to create a triangulation with
363 * all the vertices needed.
364 * @param[in] vertices Vector of points used to create a triangulation
365 */
366 void
367 multi_general_cell(Triangulation<1, 3> &tria,
368 const std::vector<Point<3>> &vertices);
369};
370#endif
Handles all the parameters declared in the parameter handler file.
The PVDHandler class manages the storage of the information required to write pvd file....
Definition pvd_handler.h:17
void calculate_contact(particle_particle_contact_info< dim > &contact_info, const Tensor< 1, 3 > &tangential_relative_velocity, const double normal_relative_velocity_value, const Tensor< 1, 3 > &normal_unit_vector, const double normal_overlap, const double dt, const ArrayView< const double > &particle_one_properties, const ArrayView< const double > &particle_two_properties, Tensor< 1, 3 > &normal_force, Tensor< 1, 3 > &tangential_force, Tensor< 1, 3 > &particle_one_tangential_torque, Tensor< 1, 3 > &particle_two_tangential_torque, Tensor< 1, 3 > &rolling_resistance_torque)
Base class for the particles force chains contact force models. This class does not implement any of ...
virtual ~ParticlesForceChainsBase()=default
virtual void write_force_chains(const DEMSolverParameters< dim > &dem_parameters, PVDHandler &pvd_handler, const MPI_Comm mpi_communicator, const std::string folder, const unsigned int iter, const double time, typename dem_data_structures< dim >::adjacent_particle_pairs &local_adjacent_particles, typename dem_data_structures< dim >::adjacent_particle_pairs &ghost_adjacent_particles)=0
Output the force chains in VTU and PVTU files for each iteration and a PVD file.
virtual void calculate_force_chains(typename dem_data_structures< dim >::adjacent_particle_pairs &local_adjacent_particles, typename dem_data_structures< dim >::adjacent_particle_pairs &ghost_adjacent_particles, std::vector< Point< 3 > > &vertices, std::vector< double > &normal_forces_vector)=0
Use a ParticleParticleContactForce object to calculate normal forces between particles....
void update_contact_information(Tensor< 1, 3 > &tangential_relative_velocity, double &normal_relative_velocity_value, Tensor< 1, 3 > &normal_unit_vector, const ArrayView< const double > &particle_one_properties, const ArrayView< const double > &particle_two_properties, const Point< 3 > &particle_one_location, const Point< 3 > &particle_two_location)
Update the contact pair information for all contact force calculations.
void multi_general_cell(Triangulation< 1, 3 > &tria, const std::vector< Point< 3 > > &vertices)
Create a triangulation with a unique cell (represented by a line) for each normal force between two p...
virtual ~ParticlesForceChains()=default
void write_force_chains(const DEMSolverParameters< dim > &dem_parameters, PVDHandler &pvd_handler, const MPI_Comm mpi_communicator, const std::string folder, const unsigned int iter, const double time, typename dem_data_structures< dim >::adjacent_particle_pairs &local_adjacent_particles, typename dem_data_structures< dim >::adjacent_particle_pairs &ghost_adjacent_particles) override
Output the force chains in VTU and PVTU files for each iteration and a PVD file.
ParticlesForceChains(const DEMSolverParameters< dim > &dem_parameters)
void execute_contact_calculation(ContactInfoContainer &adjacent_particles_list, std::vector< Point< 3 > > &vertices, std::vector< double > &normal_forces_vector)
Execute the contact calculation step for the particle-particle contact only for local-local and local...
void calculate_force_chains(typename dem_data_structures< dim >::adjacent_particle_pairs &local_adjacent_particles, typename dem_data_structures< dim >::adjacent_particle_pairs &ghost_adjacent_particles, std::vector< Point< 3 > > &vertices, std::vector< double > &normal_forces_vector) override
Calculate normal forces between all touching particles with ParticleParticleContactForce class' metho...
@ ghost_particle_particle
This namespace defines all the data containers and required operations on these containers for the DE...
ParticleParticleContactForceModel
Contact force model for particle-particle interactions.
RollingResistanceMethod
Method used to compute the rolling resistance torque.
ankerl::unordered_dense::map< types::particle_index, adjacent_particle_pairs_value > adjacent_particle_pairs