Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
ib_particle.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2020-2025 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_ib_particle_h
5#define lethe_ib_particle_h
6
8#include <core/shape.h>
9
10#include <deal.II/base/parsed_function.h>
11#include <deal.II/base/point.h>
12
13#include <vector>
14
15using namespace dealii;
16
17/**
18 * @brief Define the behavior of a specific particle for the sharp interface IB solver.
19 *
20 * Each particle defined will have these values used in the solver.
21 *
22 * @tparam dim An integer that denotes the number of spatial dimensions.
23 */
24template <int dim>
26{
27public:
28 /**
29 * @brief Initialize all particles.
30 */
31 void
33
34 /**
35 * @brief Initialize the value of the last state of the particle.
36 */
37 void
39
40 /**
41 * @brief Return the names of the DEM properties, for visualization.
42 */
43 std::vector<std::pair<std::string, int>>
45
46 /**
47 * @brief Return the value of the DEM properties, for visualization.
48 */
49 std::vector<double>
51
52 /**
53 * @brief Return the number of DEM properties, for visualization.
54 */
55 inline unsigned int
60
61 /**
62 * @brief Compute the evaluation of the signed distance function of this shape.
63 *
64 * Most level set functions used here come from Inigo Quilez:
65 * iquilezles.org/articles/distfunctions
66 *
67 * @param[in] p Point at which the evaluation is performed.
68 *
69 * @param[in] cell_guess Guess of the cell containing the evaluation point,
70 * which is useful to reduce computation time.
71 *
72 * @return Signed distance function at evaluation point.
73 */
74 inline double
75 get_levelset(const Point<dim> &p,
76 const typename DoFHandler<dim>::active_cell_iterator &cell_guess)
77 {
78 return shape->value_with_cell_guess(p, cell_guess);
79 }
80
81 /**
82 * @brief See overloaded function.
83 */
84 inline double
85 get_levelset(const Point<dim> &p)
86 {
87 return shape->value(p);
88 }
89
90 /**
91 * @brief Find the closest surface point on the shape.
92 *
93 * This point has the minimal absolute distance from the given point p.
94 *
95 * @param[in] p Point at which the evaluation is performed.
96 *
97 * @param[out] closest_point Reference to the closest point. This point
98 * will be modified by the function.
99 *
100 * @param[in] cell_guess A guess of the cell containing the evaluation point,
101 * which is useful to reduce computation time.
102 */
103 void
105 const Point<dim> &p,
106 Point<dim> &closest_point,
107 const typename DoFHandler<dim>::active_cell_iterator &cell_guess);
108
109 /**
110 * @brief See overloaded function.
111 */
112 void
113 closest_surface_point(const Point<dim> &p, Point<dim> &closest_point);
114
115 /**
116 * @brief Determine if the given point is inside the crown for which the limits
117 * are defined by inner and outer radius factors. An effective radius is used
118 * for non spherical shapes.
119 *
120 * @param[in] evaluation_point Point at which the evaluation is performed.
121 *
122 * @param[in] outer_radius Relative or absolute distance to check if the
123 * evaluation point is inside the outer limits.
124 *
125 * @param[in] inside_radius Relative or absolute distance to check if the
126 * evaluation point is outside the inner limits.
127 *
128 * @param[in] absolute_distance Boolean for whether the radii are defined as
129 * absolute or relative to radius. If the value is false, the outer and inner
130 * radii are multiplied by the effective radius to construct the absolute
131 * distances to be used.
132 *
133 * @param[in] cell_guess Guess of the cell containing the evaluation point,
134 * which is useful to reduce computation time.
135 *
136 * @return true if the evaluation point is inside the crown.
137 */
138 bool
140 const Point<dim> &evaluation_point,
141 const double outer_radius,
142 const double inside_radius,
143 const bool absolute_distance,
144 const typename DoFHandler<dim>::active_cell_iterator &cell_guess);
145
146 /**
147 * @brief See overloaded function.
148 */
149 bool
150 is_inside_crown(const Point<dim> &evaluation_point,
151 const double outer_radius,
152 const double inside_radius,
153 const bool absolute_distance);
154
155 /**
156 * @brief Set the position and dependent members to the argument.
157 *
158 * @param[in] position New position to use.
159 */
160 inline void
161 set_position(const Point<dim> position)
162 {
163 this->position = position;
164 this->shape->set_position(this->position);
165 }
166
167
168 /**
169 * @brief Clear the cache used to evaluate the value and vector defining
170 * the signed distance function.
171 */
172 void
174
175 /**
176 * @brief Set up a shape in accordance with the given type and arguments.
177 *
178 * @param[in] type Type of the shape to be initialized.
179 *
180 * @param[in] shape_arguments Arguments to be used for shape initialization.
181 */
182 void
183 initialize_shape(const std::string &type,
184 const std::vector<double> &shape_arguments);
185
186 /**
187 * @brief Set up a shape in accordance with the given type and raw text argument.
188 *
189 * The raw text argument is typically a file name.
190 *
191 * @param[in] type Type of shape to be initialized.
192 *
193 * @param[in] raw_arguments Untreated arguments of the shape.
194 */
195 void
196 initialize_shape(const std::string &type, const std::string &raw_arguments);
197
198 /**
199 * @brief Set the position and dependent members to the position for
200 * one component only.
201 *
202 * @param[in] position_component Component of the new position to set the
203 * particle at.
204 *
205 * @param[in] component Component index for which the position will be
206 * updated.
207 */
208 inline void
209 set_position(const double position_component,
210 const unsigned int component = 0)
211 {
212 this->position[component] = position_component;
213 this->shape->set_position(this->position);
214 }
215
216 /**
217 * @brief Set the orientation and dependent members to the given orientation.
218 *
219 * @param[in] orientation New orientation to set the particle at.
220 */
221 void
222 set_orientation(const Tensor<1, 3> &orientation);
223
224 /**
225 * @brief Set the layer thickening value (positive or negative) of the shape.
226 *
227 * @param[in] layer_thickening Thickness to be artificially added to the
228 * particle. A negative value will decrease the particle's thickness by
229 * subtracting a layer of specified width.
230 */
231 void
232 set_layer_thickening(const double layer_thickening)
233 {
234 shape->set_layer_thickening(layer_thickening);
235 }
236
237 /**
238 * @brief Set the proper DOF handler, then compute/update the map of cells
239 * and their likely non-null nodes.
240 *
241 * @param[in,out] updated_dof_handler Reference to the new dof_handler.
242 *
243 * @param[in] mesh_based_precalculations Define if mesh-based precalculations
244 * are used (if type=RBF).
245 */
246 void
247 update_precalculations(DoFHandler<dim> &updated_dof_handler,
248 const bool mesh_based_precalculations);
249
250 /**
251 * @brief Update precalculations if needed, then compute and remove superfluous data.
252 *
253 * @param[in,out] updated_dof_handler Reference to the new dof_handler.
254 *
255 * @param[in] mesh_based_precalculations Define if mesh-based precalculations
256 * are used (if type=RBF).
257 */
258 void
259 remove_superfluous_data(DoFHandler<dim> &updated_dof_handler,
260 const bool mesh_based_precalculations);
261
262 /**
263 * @brief Load data from the files (for file-based Shapes).
264 */
265 void
267
268 /**
269 * @brief Unique identification number.
270 */
271 unsigned int particle_id;
272
273 /**
274 * @brief Geometrical information for IB application.
275 */
276 std::shared_ptr<Shape<dim>> shape;
277
278 /**
279 * @brief Effective radius, which is the actual radius for spheres.
280 */
281 double radius;
282
283 /**
284 * @brief Young's modulus used for contact force calculations.
285 */
287
288 /**
289 * @brief Restitution coefficient used for contact force calculations.
290 */
292
293 /**
294 * @brief Poisson's ratio used for contact force calculations.
295 */
297
298 /**
299 * @brief Friction coefficient used for contact force calculations.
300 */
302
303 /**
304 * @brief Rolling friction coefficient used for contact force calculations.
305 */
307
308 /**
309 * @brief Particle's mass.
310 */
311 double mass;
312
313 /**
314 * @brief Particle's volume
315 */
316 double volume;
317
318 /**
319 * @brief Surface energy
320 */
322
323 /**
324 * @brief Inertia matrix in the particle frame of reference.
325 */
326 Tensor<2, 3> inertia;
327
328 /**
329 * @brief Position, which corresponds to the centroid for most implemented shapes.
330 */
331 Point<dim> position;
332
333 /**
334 * @brief Positions at the last n time steps. n depends on the time integration scheme.
335 */
336 std::vector<Point<dim>> previous_positions;
337
338 /**
339 * @brief Total fluid force applied on the particle.
340 */
341 Tensor<1, 3> fluid_forces;
342
343 /**
344 * @brief Viscous contribution to the fluid force applied on the particle.
345 */
347
348 /**
349 * @brief Pressure contribution to the fluid force applied on the particle.
350 */
352
353 /**
354 * @brief Previous time step's total fluid force applied on the particle.
355 */
357
358 /**
359 * @brief Previous time step's viscous contribution to the fluid force
360 * applied on the particle.
361 */
363
364 /**
365 * @brief Previous time step's pressure contribution to the fluid force.
366 */
368
369 /**
370 * @brief Fluid torque applied on the particle.
371 */
372 Tensor<1, 3> fluid_torque;
373
374 /**
375 * @brief Previous time step's fluid torque applied on the particle.
376 */
378 /**
379 * @brief Translational velocity.
380 */
381 Tensor<1, 3> velocity;
382
383 /**
384 * @brief Previous time step's translational velocity.
385 */
386 std::vector<Tensor<1, 3>> previous_velocity;
387
388 /**
389 * @brief Last non-linear iteration's velocity for CFD-DEM coupling.
390 */
391 Tensor<1, 3> velocity_iter;
392
393 /**
394 * @brief Last non-linear correction (without relaxation) to the velocity.
395 */
397
398 /**
399 * @brief Orientation, with 0 angular position by default on every axis.
400 */
401 Tensor<1, 3> orientation;
402
403 /**
404 * @brief Previous time step's orientation.
405 */
406 std::vector<Tensor<1, 3>> previous_orientation;
407
408 /**
409 * @brief Angular velocity.
410 */
411 Tensor<1, 3> omega;
412
413 /**
414 * @brief Previous time step's angular velocity.
415 */
416 std::vector<Tensor<1, 3>> previous_omega;
417
418 /**
419 * @brief Last non-linear iteration's angular velocity for CFD-DEM coupling.
420 */
421 Tensor<1, 3> omega_iter;
422
423 /**
424 * @brief Last non-linear correction (without relaxation) to the angular velocity.
425 */
427
428 /**
429 * @brief Total impulsion felt by the particle during the current time step.
430 */
431 Tensor<1, 3> impulsion;
432
433 /**
434 * @brief Contact-generated impulsion felt by the particle.
435 */
436 Tensor<1, 3> contact_impulsion;
437
438 /**
439 * @brief Last non-linear iteration's total impulsion on the particle.
440 */
441 Tensor<1, 3> impulsion_iter;
442
443 /**
444 * @brief Total angular impulsion felt by the particle during the current time step.
445 */
446 Tensor<1, 3> omega_impulsion;
447
448 /**
449 * @brief Contact-generated angular impulsion felt by the particle.
450 */
452
453 /**
454 * @brief Last non-linear iteration's total angular impulsion on the particle.
455 */
457
458 /**
459 * @brief Function that determines the velocity.
460 *
461 * If the particle dynamics is solved, this function determines the
462 * value only at the initial state.
463 */
464 std::shared_ptr<Functions::ParsedFunction<dim>> f_velocity;
465
466 /**
467 * @brief Function that determines the position.
468 *
469 * If the particle dynamics is solved, this function determines the
470 * value only at the initial state.
471 */
472 std::shared_ptr<Functions::ParsedFunction<dim>> f_position;
473
474 /**
475 * @brief Function that determines the angular velocity.
476 *
477 * If the particle dynamics is solved, this function determines the
478 * value only at the initial state.
479 */
480 std::shared_ptr<Functions::ParsedFunction<dim>> f_omega;
481
482 /**
483 * @brief Function that determines the orientation.
484 *
485 * If the particle dynamics is solved, this function determines the
486 * value only at the initial state.
487 */
488 std::shared_ptr<Functions::ParsedFunction<dim>> f_orientation;
489
490 /**
491 * @brief Indicate if the particle dynamics are solved.
492 *
493 * If not, functions are used to define position, velocity, orientation and
494 * angular velocity.
495 */
497
498 /**
499 * @brief Indicate if mesh-based precalculations are performed.
500 *
501 * For RBF shapes with nodes outside the background mesh, slight deformations
502 * can happen near the boundary when mesh-based precalculations are enabled
503 * (due to the RBF nodes partitioning algorithm).
504 */
506
507 /**
508 * @brief Current residual of the particle velocity.
509 */
511
512 /**
513 * @brief Current residual of the particle angular velocity.
514 */
516
517 /**
518 * @brief Previous iteration's relaxation parameter used for the translational velocity
519 * iteration.
520 */
522
523 /**
524 * @brief Previous iteration's relaxation parameter used for the angular velocity
525 * iteration.
526 */
528
529 /**
530 * @brief Position of the pressure reference point in the particle's
531 * referential. This point is used to define a constant on the pressure.
532 */
534
535 /**
536 * @brief Rotation matrix in the global space.
537 */
538 Tensor<2, 3> rotation_matrix;
539};
540
541#endif
Define the behavior of a specific particle for the sharp interface IB solver.
Definition ib_particle.h:26
std::vector< Tensor< 1, 3 > > previous_orientation
Previous time step's orientation.
Tensor< 1, 3 > fluid_viscous_forces
Viscous contribution to the fluid force applied on the particle.
double previous_local_alpha_velocity
Previous iteration's relaxation parameter used for the translational velocity iteration.
Tensor< 1, 3 > orientation
Orientation, with 0 angular position by default on every axis.
double residual_omega
Current residual of the particle angular velocity.
std::vector< double > get_properties()
Return the value of the DEM properties, for visualization.
double radius
Effective radius, which is the actual radius for spheres.
Tensor< 1, 3 > omega
Angular velocity.
std::shared_ptr< Functions::ParsedFunction< dim > > f_omega
Function that determines the angular velocity.
Tensor< 1, 3 > previous_velocity_residual
Last non-linear correction (without relaxation) to the velocity.
Tensor< 1, 3 > fluid_forces
Total fluid force applied on the particle.
std::vector< Point< dim > > previous_positions
Positions at the last n time steps. n depends on the time integration scheme.
bool integrate_motion
Indicate if the particle dynamics are solved.
void set_orientation(const Tensor< 1, 3 > &orientation)
Set the orientation and dependent members to the given orientation.
void load_data_from_file()
Load data from the files (for file-based Shapes).
Tensor< 1, 3 > contact_impulsion
Contact-generated impulsion felt by the particle.
bool is_inside_crown(const Point< dim > &evaluation_point, const double outer_radius, const double inside_radius, const bool absolute_distance, const typename DoFHandler< dim >::active_cell_iterator &cell_guess)
Determine if the given point is inside the crown for which the limits are defined by inner and outer ...
double mass
Particle's mass.
double poisson_ratio
Poisson's ratio used for contact force calculations.
Tensor< 1, 3 > fluid_pressure_forces
Pressure contribution to the fluid force applied on the particle.
void clear_shape_cache()
Clear the cache used to evaluate the value and vector defining the signed distance function.
unsigned int get_number_properties()
Return the number of DEM properties, for visualization.
Definition ib_particle.h:56
Tensor< 1, 3 > previous_fluid_viscous_forces
Previous time step's viscous contribution to the fluid force applied on the particle.
Tensor< 2, 3 > rotation_matrix
Rotation matrix in the global space.
Tensor< 2, 3 > inertia
Inertia matrix in the particle frame of reference.
void update_precalculations(DoFHandler< dim > &updated_dof_handler, const bool mesh_based_precalculations)
Set the proper DOF handler, then compute/update the map of cells and their likely non-null nodes.
void remove_superfluous_data(DoFHandler< dim > &updated_dof_handler, const bool mesh_based_precalculations)
Update precalculations if needed, then compute and remove superfluous data.
Tensor< 1, 3 > velocity
Translational velocity.
Tensor< 1, 3 > previous_fluid_torque
Previous time step's fluid torque applied on the particle.
void closest_surface_point(const Point< dim > &p, Point< dim > &closest_point, const typename DoFHandler< dim >::active_cell_iterator &cell_guess)
Find the closest surface point on the shape.
void set_position(const double position_component, const unsigned int component=0)
Set the position and dependent members to the position for one component only.
void initialize_all()
Initialize all particles.
Definition ib_particle.cc:9
double volume
Particle's volume.
Tensor< 1, 3 > previous_fluid_pressure_forces
Previous time step's pressure contribution to the fluid force.
double previous_local_alpha_omega
Previous iteration's relaxation parameter used for the angular velocity iteration.
double restitution_coefficient
Restitution coefficient used for contact force calculations.
Tensor< 1, 3 > impulsion
Total impulsion felt by the particle during the current time step.
void initialize_previous_solution()
Initialize the value of the last state of the particle.
double residual_velocity
Current residual of the particle velocity.
unsigned int particle_id
Unique identification number.
std::vector< std::pair< std::string, int > > get_properties_name()
Return the names of the DEM properties, for visualization.
void set_layer_thickening(const double layer_thickening)
Set the layer thickening value (positive or negative) of the shape.
void set_position(const Point< dim > position)
Set the position and dependent members to the argument.
Tensor< 1, 3 > previous_omega_residual
Last non-linear correction (without relaxation) to the angular velocity.
void initialize_shape(const std::string &type, const std::vector< double > &shape_arguments)
Set up a shape in accordance with the given type and arguments.
std::shared_ptr< Functions::ParsedFunction< dim > > f_velocity
Function that determines the velocity.
double get_levelset(const Point< dim > &p, const typename DoFHandler< dim >::active_cell_iterator &cell_guess)
Compute the evaluation of the signed distance function of this shape.
Definition ib_particle.h:75
Point< dim > pressure_location
Position of the pressure reference point in the particle's referential. This point is used to define ...
Tensor< 1, 3 > omega_iter
Last non-linear iteration's angular velocity for CFD-DEM coupling.
Tensor< 1, 3 > omega_impulsion_iter
Last non-linear iteration's total angular impulsion on the particle.
double get_levelset(const Point< dim > &p)
See overloaded function.
Definition ib_particle.h:85
Tensor< 1, 3 > fluid_torque
Fluid torque applied on the particle.
std::shared_ptr< Functions::ParsedFunction< dim > > f_position
Function that determines the position.
std::shared_ptr< Functions::ParsedFunction< dim > > f_orientation
Function that determines the orientation.
double friction_coefficient
Friction coefficient used for contact force calculations.
Tensor< 1, 3 > impulsion_iter
Last non-linear iteration's total impulsion on the particle.
Tensor< 1, 3 > velocity_iter
Last non-linear iteration's velocity for CFD-DEM coupling.
double surface_energy
Surface energy.
bool mesh_based_precalculations
Indicate if mesh-based precalculations are performed.
double youngs_modulus
Young's modulus used for contact force calculations.
std::shared_ptr< Shape< dim > > shape
Geometrical information for IB application.
double rolling_friction_coefficient
Rolling friction coefficient used for contact force calculations.
Tensor< 1, 3 > omega_contact_impulsion
Contact-generated angular impulsion felt by the particle.
Tensor< 1, 3 > omega_impulsion
Total angular impulsion felt by the particle during the current time step.
Tensor< 1, 3 > previous_fluid_forces
Previous time step's total fluid force applied on the particle.
std::vector< Tensor< 1, 3 > > previous_omega
Previous time step's angular velocity.
Point< dim > position
Position, which corresponds to the centroid for most implemented shapes.
std::vector< Tensor< 1, 3 > > previous_velocity
Previous time step's translational velocity.
DEM particle property definitions and output name management.
@ n_properties
Number of properties.