Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
dem_properties.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2020, 2022-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4/**
5 * @file dem_properties.h
6 * @brief DEM particle property definitions and output name management.
7 *
8 * This file defines the property indices used to store and access particle
9 * data within the deal.II ParticleHandler PropertyPool. Separate index
10 * enumerations are provided for pure DEM, CFD-DEM, DEM multiphysics and
11 * CFD-DEM multiphysics simulations, as each carries a different set of
12 * per-particle properties.
13 */
14
15#ifndef lethe_dem_properties_h
16#define lethe_dem_properties_h
17
18#include <string>
19#include <type_traits>
20#include <vector>
21
22namespace DEM
23{
24 /**
25 * @brief Identifies which physics is solved for the DEM particles.
26 *
27 * Two solver types are currently supported:
28 * - dem: the particles only carry their kinematic properties.
29 * - dem_mp: DEM multiphysics simulation, in which the particles also carry
30 * thermal properties.
31 *
32 * This is independent of the presence of a fluid: it is the application
33 * which decides whether the particles are coupled to a CFD solver, and thus
34 * whether the CFD-DEM index layout of the ParticleHandler PropertyPool is
35 * used.
36 */
38 {
41 };
42
43
44 namespace DEMProperties
45 {
46 /**
47 * @brief Particle property indices for pure DEM simulations.
48 *
49 * Manages the specific particle indices within the PropertyPool of the
50 * ParticleHandler.
51 * @note A regular enum (not enum class) is used because an
52 * implicit conversion to int is required to access particle properties.
53 */
54 enum PropertiesIndex : int
55 {
56 /// Particle type
57 type = 0,
58 /// Diameter
59 dp = 1,
60 /// Mass
61 mass = 2,
62 /// Velocity - x component
63 v_x = 3,
64 /// Velocity - y component
65 v_y = 4,
66 /// Velocity - z component
67 v_z = 5,
68 /// Angular velocity - x component
70 /// Angular velocity - y component
72 /// Angular velocity - z component
74 /// Number of properties
76 };
77 } // namespace DEMProperties
78
79
81 {
82 /**
83 * @brief Particle property indices for CFD-DEM simulations.
84 *
85 * Manages the specific particle indices within the PropertyPool of the
86 * ParticleHandler. In addition to the base DEM properties, CFD-DEM
87 * particles carry FEM coupling forces, drag forces, torques, volumetric
88 * contributions, and momentum transfer coefficients.
89 * @note A regular enum (not enum class) is used because an implicit
90 * conversion to int is required to access particle properties.
91 */
92 enum PropertiesIndex : int
93 {
94 /// Particle type
95 type = 0,
96 /// Diameter
97 dp = 1,
98 /// Mass
99 mass = 2,
100 /// Velocity - x component
101 v_x = 3,
102 /// Velocity - y component
103 v_y = 4,
104 /// Velocity - z component
105 v_z = 5,
106 /// Angular velocity - x component
108 /// Angular velocity - y component
110 /// Angular velocity - z component
112 /// FEM force which is applied on both fluid and particles - x component
114 /// FEM force which is applied on both fluid and particles - y component
116 /// FEM force which is applied on both fluid and particles - z component
118 /// FEM force which is applied only on the particle - x component
120 /// FEM force which is applied only on the particle - y component
122 /// FEM force which is applied only on the particle - z component
124 /// Drag force - x component
126 /// Drag force - y component
128 /// Drag force - z component
130 /// FEM torque - x component
132 /// FEM torque - y component
134 /// FEM torque - z component
136 /// Volumetric contribution used in the QCM
138 /// Momentum transfer coefficient used for implicit drag coupling
140 /// Number of properties
142 };
143 } // namespace CFDDEMProperties
144
145
147 {
148 /**
149 * @brief Particle property indices for DEM multiphysics simulations.
150 *
151 * Manages the specific particle indices within the PropertyPool of the
152 * ParticleHandler. In addition to the base DEM properties, DEM
153 * multiphysics particles carry temperature and specific heat properties.
154 * @note A regular enum (not enum class) is used because an implicit
155 * conversion to int is required to access particle properties.
156 */
158 {
159 /// Particle type
160 type = 0,
161 /// Diameter
162 dp = 1,
163 /// Mass
164 mass = 2,
165 /// Velocity - x component
166 v_x = 3,
167 /// Velocity - y component
168 v_y = 4,
169 /// Velocity - z component
170 v_z = 5,
171 /// Angular velocity - x component
173 /// Angular velocity - y component
175 /// Angular velocity - z component
177 /// Particle temperature
178 T = 9,
179 /// Particle specific heat
181 /// Number of properties
183 };
184 } // namespace DEMMPProperties
185
186
188 {
189 /**
190 * @brief Particle property indices for CFD-DEM multiphysics simulations.
191 *
192 * Manages the specific particle indices within the PropertyPool of the
193 * ParticleHandler. This index set is the union of the CFD-DEM properties
194 * and of the thermal properties of the DEM multiphysics solver.
195 * @note The thermal properties are appended *after* the CFD-DEM
196 * properties. This is required so that this index set shares the exact
197 * same layout as CFDDEMProperties for its first n_properties indices,
198 * which is asserted below. Some of the fluid-side machinery is not
199 * templated by the properties index and relies on this invariant.
200 * @note A regular enum (not enum class) is used because an implicit
201 * conversion to int is required to access particle properties.
202 */
204 {
205 /// Particle type
206 type = 0,
207 /// Diameter
208 dp = 1,
209 /// Mass
210 mass = 2,
211 /// Velocity - x component
212 v_x = 3,
213 /// Velocity - y component
214 v_y = 4,
215 /// Velocity - z component
216 v_z = 5,
217 /// Angular velocity - x component
219 /// Angular velocity - y component
221 /// Angular velocity - z component
223 /// FEM force which is applied on both fluid and particles - x component
225 /// FEM force which is applied on both fluid and particles - y component
227 /// FEM force which is applied on both fluid and particles - z component
229 /// FEM force which is applied only on the particle - x component
231 /// FEM force which is applied only on the particle - y component
233 /// FEM force which is applied only on the particle - z component
235 /// Drag force - x component
237 /// Drag force - y component
239 /// Drag force - z component
241 /// FEM torque - x component
243 /// FEM torque - y component
245 /// FEM torque - z component
247 /// Volumetric contribution used in the QCM
249 /// Momentum transfer coefficient used for implicit drag coupling
251 /// Particle temperature
252 T = 23,
253 /// Particle specific heat
255 /// Number of properties
257 };
258 } // namespace CFDDEMMPProperties
259
260
261 /**
262 * @brief Compare the position of a property in two different index sets.
263 *
264 * The arguments are taken as integers rather than as enumerators so that
265 * enumerators of two distinct index sets may be compared without triggering
266 * -Wenum-compare.
267 *
268 * @param[in] first_index Position of the property in the first index set.
269 * @param[in] second_index Position of the property in the second index set.
270 * @return Whether the property is stored at the same position in both sets.
271 */
272 constexpr bool
273 is_stored_at_the_same_index(const int first_index, const int second_index)
274 {
275 return first_index == second_index;
276 }
277
278 // The CFD-DEM multiphysics properties must share the layout of the CFD-DEM
279 // properties for every property they have in common. The fluid-side code
280 // (VANS assemblers, particle projector, scratch data) is not templated by
281 // the properties index and reads particle properties through the CFD-DEM
282 // indices, which is only valid as long as these assertions hold.
283 static_assert(
339 "Every property shared by the CFD-DEM and the CFD-DEM multiphysics "
340 "solvers must be stored at the same index, and the thermal properties "
341 "must be appended after them.");
342
343
344 /**
345 * @brief Whether a properties index set carries thermal properties.
346 *
347 * This is true for the index sets used by the multiphysics solvers, which
348 * store the temperature (T) and the specific heat of every particle. It is
349 * used to enable, at compile time, the heat transfer between particles and
350 * the integration of their temperature.
351 *
352 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
353 */
354 template <typename PropertiesIndex>
355 inline constexpr bool has_thermal_properties = false;
356
357 template <>
358 inline constexpr bool
360
361 template <>
362 inline constexpr bool
364
365 /**
366 * @brief The index of the temperature property in a properties index set.
367 *
368 * This is the property start index passed to the ParticleFieldQCM used
369 * to project the particle temperature; -1 indicates that the projection is
370 * not to be done.
371 *
372 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
373 */
374 template <typename PropertiesIndex>
375 inline constexpr int temperature_property_index = -1;
376
377 template <>
378 inline constexpr int
381
382 /**
383 * @brief Whether a properties index set carries fluid coupling properties.
384 *
385 * This is true for the index sets used by the CFD-DEM solvers, which store
386 * the fluid-particle interaction forces and torques, the volumetric
387 * contribution and the momentum transfer coefficient of every particle.
388 *
389 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
390 */
391 template <typename PropertiesIndex>
392 inline constexpr bool has_fluid_coupling_properties = false;
393
394 template <>
395 inline constexpr bool
397
398 template <>
399 inline constexpr bool
401
402
403 /**
404 * @brief The pure DEM index set matching a given index set.
405 *
406 * A CFD-DEM simulation is usually started from the checkpoint of a pure DEM
407 * simulation, whose particle handler carries fewer properties. This alias
408 * gives the index set that checkpoint must have been written with: a
409 * multiphysics CFD-DEM simulation is always restarted from a multiphysics
410 * DEM simulation, so that the temperature and the specific heat of the
411 * particles are carried over rather than reset.
412 *
413 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
414 */
415 template <typename PropertiesIndex>
417 std::conditional_t<has_thermal_properties<PropertiesIndex>,
420
421
422 /**
423 * @brief Controls the name of output variables for the vtu.
424 * @tparam dim An integer that denotes the number of spatial dimensions.
425 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
426 */
427 template <int dim, typename PropertiesIndex>
429 {
430 public:
431 /**
432 * @brief Return the names of each DEM property. Used to properly generate
433 * output files.
434 * @return A vector with the names of each property.
435 */
436 static std::vector<std::pair<std::string, int>>
438 };
439
440} // namespace DEM
441
442#endif
Controls the name of output variables for the vtu.
static std::vector< std::pair< std::string, int > > get_properties_name()
Return the names of each DEM property. Used to properly generate output files.
PropertiesIndex
Particle property indices for CFD-DEM multiphysics simulations.
@ fem_drag_z
Drag force - z component.
@ fem_torque_y
FEM torque - y component.
@ fem_force_two_way_coupling_z
FEM force which is applied on both fluid and particles - z component.
@ fem_force_two_way_coupling_x
FEM force which is applied on both fluid and particles - x component.
@ v_y
Velocity - y component.
@ v_z
Velocity - z component.
@ fem_drag_y
Drag force - y component.
@ specific_heat
Particle specific heat.
@ fem_torque_x
FEM torque - x component.
@ omega_y
Angular velocity - y component.
@ fem_force_one_way_coupling_x
FEM force which is applied only on the particle - x component.
@ omega_z
Angular velocity - z component.
@ fem_force_one_way_coupling_y
FEM force which is applied only on the particle - y component.
@ n_properties
Number of properties.
@ fem_torque_z
FEM torque - z component.
@ fem_drag_x
Drag force - x component.
@ momentum_transfer_coefficient
Momentum transfer coefficient used for implicit drag coupling.
@ omega_x
Angular velocity - x component.
@ fem_force_one_way_coupling_z
FEM force which is applied only on the particle - z component.
@ v_x
Velocity - x component.
@ volumetric_contribution
Volumetric contribution used in the QCM.
@ fem_force_two_way_coupling_y
FEM force which is applied on both fluid and particles - y component.
@ T
Particle temperature.
PropertiesIndex
Particle property indices for CFD-DEM simulations.
@ fem_torque_x
FEM torque - x component.
@ n_properties
Number of properties.
@ fem_force_two_way_coupling_y
FEM force which is applied on both fluid and particles - y component.
@ fem_force_two_way_coupling_z
FEM force which is applied on both fluid and particles - z component.
@ volumetric_contribution
Volumetric contribution used in the QCM.
@ fem_force_one_way_coupling_y
FEM force which is applied only on the particle - y component.
@ v_y
Velocity - y component.
@ fem_torque_z
FEM torque - z component.
@ momentum_transfer_coefficient
Momentum transfer coefficient used for implicit drag coupling.
@ fem_force_two_way_coupling_x
FEM force which is applied on both fluid and particles - x component.
@ type
Particle type.
@ fem_drag_z
Drag force - z component.
@ v_x
Velocity - x component.
@ fem_drag_y
Drag force - y component.
@ v_z
Velocity - z component.
@ omega_z
Angular velocity - z component.
@ fem_drag_x
Drag force - x component.
@ fem_force_one_way_coupling_x
FEM force which is applied only on the particle - x component.
@ omega_x
Angular velocity - x component.
@ omega_y
Angular velocity - y component.
@ fem_torque_y
FEM torque - y component.
@ fem_force_one_way_coupling_z
FEM force which is applied only on the particle - z component.
PropertiesIndex
Particle property indices for DEM multiphysics simulations.
@ type
Particle type.
@ v_z
Velocity - z component.
@ T
Particle temperature.
@ v_x
Velocity - x component.
@ omega_y
Angular velocity - y component.
@ n_properties
Number of properties.
@ omega_x
Angular velocity - x component.
@ specific_heat
Particle specific heat.
@ v_y
Velocity - y component.
@ omega_z
Angular velocity - z component.
PropertiesIndex
Particle property indices for pure DEM simulations.
@ omega_y
Angular velocity - y component.
@ omega_z
Angular velocity - z component.
@ v_z
Velocity - z component.
@ v_y
Velocity - y component.
@ omega_x
Angular velocity - x component.
@ v_x
Velocity - x component.
@ n_properties
Number of properties.
@ type
Particle type.
This namespace defines all the data containers and required operations on these containers for the DE...
constexpr bool has_thermal_properties
Whether a properties index set carries thermal properties.
std::conditional_t< has_thermal_properties< PropertiesIndex >, DEMMPProperties::PropertiesIndex, DEMProperties::PropertiesIndex > matching_dem_properties_index
The pure DEM index set matching a given index set.
constexpr bool is_stored_at_the_same_index(const int first_index, const int second_index)
Compare the position of a property in two different index sets.
constexpr bool has_fluid_coupling_properties
Whether a properties index set carries fluid coupling properties.
SolverType
Identifies which physics is solved for the DEM particles.
constexpr int temperature_property_index
The index of the temperature property in a properties index set.