Debian Codegraph @

include/deal.II/particles/property_pool.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_particles_property_pool_h
16 #define dealii_particles_property_pool_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/array_view.h>
21 #include <deal.II/base/point.h>
22
23
24 DEAL_II_NAMESPACE_OPEN
25
26 namespace types
27 {
28 /* Type definitions */
29
30 #ifdef DEAL_II_WITH_64BIT_INDICES
31 /**
32 * The type used for indices of particles. While in
33 * sequential computations the 4 billion indices of 32-bit unsigned integers
34 * is plenty, parallel computations using hundreds of processes can overflow
35 * this number and we need a bigger index space. We here utilize the same
36 * build variable that controls the dof indices because the number
37 * of degrees of freedom and the number of particles are typically on the same
38 * order of magnitude.
39 *
40 * The data type always indicates an unsigned integer type.
41 */
42 using particle_index = std::uint64_t;
43
44 # ifdef DEAL_II_WITH_MPI
45 /**
46 * An identifier that denotes the MPI type associated with
47 * types::global_dof_index.
48 *
49 * This preprocessor variable is deprecated. Use the variable
50 * `Utilities::MPI::mpi_type_id_for_type<types::particle_index>`
51 * instead.
52 */
53 # define DEAL_II_PARTICLE_INDEX_MPI_TYPE MPI_UINT64_T
54 # endif
55
56 #else
57 /**
58 * The type used for indices of particles. While in
59 * sequential computations the 4 billion indices of 32-bit unsigned integers
60 * is plenty, parallel computations using hundreds of processes can overflow
61 * this number and we need a bigger index space. We here utilize the same
62 * build variable that controls the dof indices because the number
63 * of degrees of freedom and the number of particles are typically on the same
64 * order of magnitude.
65 *
66 * The data type always indicates an unsigned integer type.
67 */
68 using particle_index = unsigned int;
69
70 # ifdef DEAL_II_WITH_MPI
71 /**
72 * An identifier that denotes the MPI type associated with
73 * types::global_dof_index.
74 */
75 # define DEAL_II_PARTICLE_INDEX_MPI_TYPE MPI_UNSIGNED
76 # endif
77 #endif
78 } // namespace types
79
80 namespace Particles
81 {
82 /**
83 * This class manages a memory space in which all particles associated with
84 * a ParticleHandler store their properties. It also stores the locations
85 * and reference locations of particles.
86 *
87 * The rationale for this class is
88 * that because typically every particle stores the same number of
89 * properties, and because algorithms generally traverse over all particles
90 * doing the same operation on all particles' properties, it is more efficient
91 * to let the memory used for properties be handled by a central manager.
92 * Particles then do not store a pointer to a memory area in which they store
93 * their properties, but instead a "handle" that the PropertyPool class then
94 * translates into a pointer to concrete memory.
95 *
96 * All this said, the current implementation only provides this kind of
97 * interface, but still uses simple new/delete allocation for every
98 * set of properties requested by a particle. Additionally, the current
99 * implementation assumes the same number of properties per particle, but of
100 * course the PropertyType could contain a pointer to dynamically allocated
101 * memory with varying sizes per particle (this memory would not be managed by
102 * this class).
103 */
104 template <int dim, int spacedim = dim>
105 class PropertyPool
106 {
107 public:
108 /**
109 * Typedef for the handle that is returned to the particles, and that
110 * uniquely identifies the slot of memory that is reserved for this
111 * particle.
112 */
113 using Handle = unsigned int;
114
115 /**
116 * Define a default (invalid) value for handles.
117 */
118 static const Handle invalid_handle;
119
120 /**
121 * Constructor. Stores the number of properties per reserved slot.
122 */
123 PropertyPool(const unsigned int n_properties_per_slot);
124
125 /**
126 * Destructor. This function ensures that all memory that had
127 * previously been allocated using allocate_properties_array()
128 * has also been returned via deallocate_properties_array().
129 */
130 ~PropertyPool();
131
132 /**
133 * Clear the dynamic memory allocated by this class. This function
134 * ensures that all memory that had previously been allocated using
135 * allocate_properties_array() has also been returned via
136 * deallocate_properties_array().
137 */
138 void
139 clear();
140
141 /**
142 * Return a new handle that allows a particle to store information such as
143 * properties and locations. This also allocates memory in this PropertyPool
144 * variable.
145 */
146 Handle
147 register_particle();
148
149 /**
150 * Return a handle obtained by register_particle() and mark the memory
151 * allocated for storing the particle's data as free for re-use.
152 */
153 void
154 deregister_particle(Handle &handle);
155
156 /**
157 * Return a read-only reference to the location of a particle
158 * identified by the given `handle`.
159 */
160 const Point<spacedim> &
161 get_location(const Handle handle) const;
162
163 /**
164 * Return a writeable reference to the location of a particle
165 * identified by the given `handle`.
166 */
167 Point<spacedim> &
168 get_location(const Handle handle);
169
170 /**
171 * Set the location of a particle identified by the given `handle`.
172 */
173 void
174 set_location(const Handle handle, const Point<spacedim> &new_location);
175
176 /**
177 * Return a read-only reference to the reference location of a particle
178 * identified by the given `handle`.
179 */
180 const Point<dim> &
181 get_reference_location(const Handle handle) const;
182
183 /**
184 * Set the reference location of a particle identified by the given
185 * `handle`.
186 */
187 void
188 set_reference_location(const Handle handle,
189 const Point<dim> &new_reference_location);
190
191 /**
192 * Return the ID number of this particle identified by the given
193 * `handle`.
194 */
195 types::particle_index
196 get_id(const Handle handle) const;
197
198 /**
199 * Set the ID number of this particle identified by the given
200 * `handle`.
201 */
202 void
203 set_id(const Handle handle, const types::particle_index &new_id);
204
205 /**
206 * Return an ArrayView to the properties that correspond to the given
207 * handle @p handle.
208 */
209 ArrayView<double, dealii::MemorySpace::Host>
210 get_properties(const Handle handle)
211 {
212 // The implementation is up here inside the class declaration because
213 // NVCC (at least in 12.5 and 12.6) otherwise produce a compile error:
214 //
215 // error: no declaration matches ‘dealii::ArrayView<__remove_cv(const
216 // double)> dealii::Particles::PropertyPool<dim,
217 // spacedim>::get_properties(Handle)’
218 //
219 // See https://github.com/dealii/dealii/issues/17148
220
221 const std::vector<double>::size_type data_index =
222 (handle != invalid_handle) ? handle * n_properties : 0;
223
224 // Ideally we would need to assert that 'handle' has not been deallocated
225 // by searching through 'currently_available_handles'. However, this
226 // is expensive and this function is performance critical, so instead
227 // just check against the array range, and rely on the fact
228 // that handles are invalidated when handed over to
229 // deallocate_properties_array().
230 Assert(data_index <= properties.size() - n_properties,
231 ExcMessage(
232 "Invalid property handle. This can happen if the "
233 "handle was duplicated and then one copy was deallocated "
234 "before trying to access the properties."));
235
236 return ArrayView<double>(properties.data() + data_index, n_properties);
237 }
238
239
240 /**
241 * Reserve the dynamic memory needed for storing the properties of
242 * @p size particles.
243 */
244 void
245 reserve(const std::size_t size);
246
247 /**
248 * Return how many properties are stored per slot in the pool.
249 */
250 unsigned int
251 n_properties_per_slot() const;
252
253 /**
254 * Return the total number of slots in the pool, including both registered
255 * and unregistered ones.
256 */
257 unsigned int
258 n_slots() const;
259
260 /**
261 * Return how many slots are currently registered in the pool.
262 */
263 unsigned int
264 n_registered_slots() const;
265
266 /**
267 * This function makes sure that all internally stored memory blocks
268 * are sorted in the same order as one would loop over the @p handles_to_sort
269 * container. This makes sure memory access is contiguous with actual
270 * memory location. Because the ordering is given in the input argument
271 * the complexity of this function is $O(N)$ where $N$ is the number of
272 * elements in the input argument.
273 */
274 void
275 sort_memory_slots(const std::vector<Handle> &handles_to_sort);
276
277 private:
278 /**
279 * The number of properties that are reserved per particle.
280 */
281 const unsigned int n_properties;
282
283 /**
284 * A vector that stores the locations of particles. It is indexed in the
285 * same way as the `reference_locations` and `properties` arrays, i.e., via
286 * handles.
287 */
288 std::vector<Point<spacedim>> locations;
289
290 /**
291 * A vector that stores the reference locations of particles. It is indexed
292 * in the same way as the `locations` and `properties` arrays, i.e., via
293 * handles.
294 */
295 std::vector<Point<dim>> reference_locations;
296
297 /**
298 * A vector that stores the unique identifiers of particles. It is indexed
299 * in the same way as the `locations` and `properties` arrays, i.e., via
300 * handles.
301 */
302 std::vector<types::particle_index> ids;
303
304 /**
305 * The currently allocated properties (whether assigned to
306 * a particle or available for assignment). It is indexed the same way as
307 * the `locations` and `reference_locations` arrays via handles.
308 */
309 std::vector<double> properties;
310
311 /**
312 * A collection of handles that have been created by
313 * allocate_properties_array() and have been destroyed by
314 * deallocate_properties_array(). Since the memory is still
315 * allocated these handles can be reused for new particles
316 * to avoid memory allocation.
317 */
318 std::vector<Handle> currently_available_handles;
319 };
320
321
322
323 /* ---------------------- inline and template functions ------------------ */
324
325 template <int dim, int spacedim>
326 inline const Point<spacedim> &
327 PropertyPool<dim, spacedim>::get_location(const Handle handle) const
328 {
329 const std::vector<double>::size_type data_index =
330 (handle != invalid_handle) ? handle : 0;
331
332 // Ideally we would need to assert that 'handle' has not been deallocated
333 // by searching through 'currently_available_handles'. However, this
334 // is expensive and this function is performance critical, so instead
335 // just check against the array range, and rely on the fact
336 // that handles are invalidated when handed over to
337 // deallocate_properties_array().
338 Assert(data_index <= locations.size() - 1,
339 ExcMessage("Invalid location handle. This can happen if the "
340 "handle was duplicated and then one copy was deallocated "
341 "before trying to access the properties."));
342
343 return locations[data_index];
344 }
345
346
347
348 template <int dim, int spacedim>
349 inline Point<spacedim> &
350 PropertyPool<dim, spacedim>::get_location(const Handle handle)
351 {
352 const std::vector<double>::size_type data_index =
353 (handle != invalid_handle) ? handle : 0;
354
355 // Ideally we would need to assert that 'handle' has not been deallocated
356 // by searching through 'currently_available_handles'. However, this
357 // is expensive and this function is performance critical, so instead
358 // just check against the array range, and rely on the fact
359 // that handles are invalidated when handed over to
360 // deallocate_properties_array().
361 Assert(data_index <= locations.size() - 1,
362 ExcMessage("Invalid location handle. This can happen if the "
363 "handle was duplicated and then one copy was deallocated "
364 "before trying to access the properties."));
365
366 return locations[data_index];
367 }
368
369
370
371 template <int dim, int spacedim>
372 inline void
373 PropertyPool<dim, spacedim>::set_location(const Handle handle,
374 const Point<spacedim> &new_location)
375 {
376 const std::vector<double>::size_type data_index =
377 (handle != invalid_handle) ? handle : 0;
378
379 // Ideally we would need to assert that 'handle' has not been deallocated
380 // by searching through 'currently_available_handles'. However, this
381 // is expensive and this function is performance critical, so instead
382 // just check against the array range, and rely on the fact
383 // that handles are invalidated when handed over to
384 // deallocate_properties_array().
385 Assert(data_index <= locations.size() - 1,
386 ExcMessage("Invalid location handle. This can happen if the "
387 "handle was duplicated and then one copy was deallocated "
388 "before trying to access the properties."));
389
390 locations[data_index] = new_location;
391 }
392
393
394
395 template <int dim, int spacedim>
396 inline const Point<dim> &
397 PropertyPool<dim, spacedim>::get_reference_location(const Handle handle) const
398 {
399 const std::vector<double>::size_type data_index =
400 (handle != invalid_handle) ? handle : 0;
401
402 // Ideally we would need to assert that 'handle' has not been deallocated
403 // by searching through 'currently_available_handles'. However, this
404 // is expensive and this function is performance critical, so instead
405 // just check against the array range, and rely on the fact
406 // that handles are invalidated when handed over to
407 // deallocate_properties_array().
408 Assert(data_index <= reference_locations.size() - 1,
409 ExcMessage("Invalid location handle. This can happen if the "
410 "handle was duplicated and then one copy was deallocated "
411 "before trying to access the properties."));
412
413 return reference_locations[data_index];
414 }
415
416
417
418 template <int dim, int spacedim>
419 inline void
420 PropertyPool<dim, spacedim>::set_reference_location(
421 const Handle handle,
422 const Point<dim> &new_reference_location)
423 {
424 const std::vector<double>::size_type data_index =
425 (handle != invalid_handle) ? handle : 0;
426
427 // Ideally we would need to assert that 'handle' has not been deallocated
428 // by searching through 'currently_available_handles'. However, this
429 // is expensive and this function is performance critical, so instead
430 // just check against the array range, and rely on the fact
431 // that handles are invalidated when handed over to
432 // deallocate_properties_array().
433 Assert(data_index <= reference_locations.size() - 1,
434 ExcMessage("Invalid location handle. This can happen if the "
435 "handle was duplicated and then one copy was deallocated "
436 "before trying to access the properties."));
437
438 reference_locations[data_index] = new_reference_location;
439 }
440
441
442
443 template <int dim, int spacedim>
444 inline types::particle_index
445 PropertyPool<dim, spacedim>::get_id(const Handle handle) const
446 {
447 const std::vector<double>::size_type data_index =
448 (handle != invalid_handle) ? handle : 0;
449
450 // Ideally we would need to assert that 'handle' has not been deallocated
451 // by searching through 'currently_available_handles'. However, this
452 // is expensive and this function is performance critical, so instead
453 // just check against the array range, and rely on the fact
454 // that handles are invalidated when handed over to
455 // deallocate_properties_array().
456 Assert(data_index <= ids.size() - 1,
457 ExcMessage("Invalid location handle. This can happen if the "
458 "handle was duplicated and then one copy was deallocated "
459 "before trying to access the properties."));
460
461 return ids[data_index];
462 }
463
464
465
466 template <int dim, int spacedim>
467 inline void
468 PropertyPool<dim, spacedim>::set_id(const Handle handle,
469 const types::particle_index &new_id)
470 {
471 const std::vector<double>::size_type data_index =
472 (handle != invalid_handle) ? handle : 0;
473
474 // Ideally we would need to assert that 'handle' has not been deallocated
475 // by searching through 'currently_available_handles'. However, this
476 // is expensive and this function is performance critical, so instead
477 // just check against the array range, and rely on the fact
478 // that handles are invalidated when handed over to
479 // deallocate_properties_array().
480 Assert(data_index <= ids.size() - 1,
481 ExcMessage("Invalid location handle. This can happen if the "
482 "handle was duplicated and then one copy was deallocated "
483 "before trying to access the properties."));
484
485 ids[data_index] = new_id;
486 }
487
488
489
490 // template <int dim, int spacedim>
491 // inline ArrayView<double, dealii::MemorySpace::Host>
492 // PropertyPool<dim, spacedim>::get_properties(const Handle handle)
493
494
495
496 template <int dim, int spacedim>
497 inline unsigned int
498 PropertyPool<dim, spacedim>::n_slots() const
499 {
500 return locations.size();
501 }
502
503
504 } // namespace Particles
505
506 DEAL_II_NAMESPACE_CLOSE
507
508 #endif