Debian Codegraph @

include/deal.II/particles/particle.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_particle_h
16 #define dealii_particles_particle_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 #include <deal.II/base/types.h>
23
24 #include <deal.II/particles/property_pool.h>
25
26 #include <boost/geometry/index/indexable.hpp>
27 #include <boost/serialization/array.hpp>
28
29 #include <cstdint>
30
31
32 DEAL_II_NAMESPACE_OPEN
33
34 /**
35 * A namespace that contains all classes that are related to the particle
36 * implementation, in particular the fundamental Particle class.
37 */
38 namespace Particles
39 {
40 namespace internal
41 {
42 /**
43 * Internal alias of cell level/index pair.
44 */
45 using LevelInd = std::pair<int, int>;
46 } // namespace internal
47
48 /**
49 * A class that represents a particle in a domain that is meshed by
50 * a triangulation of some kind. The data this class stores is the
51 * position of the particle in the overall space, the position of
52 * the particle in the reference coordinate system of the cell it is
53 * currently in, an ID number that is unique among all particles,
54 * and a variable number of "properties".
55 *
56 * The "properties" attached to each object of this class are
57 * stored by a PropertyPool object. These properties are
58 * stored as an array of `double` variables that can be accessed
59 * via an ArrayView object. For example, if one wanted to equip
60 * each particle with a "temperature" and "chemical composition"
61 * property that is advected along with the particle (and may change
62 * from time step to time step based on some differential equation,
63 * for example), then one would allocate two properties per particle
64 * in the PropertyPool object.
65 *
66 * In practice, however, one often wants to associate properties
67 * with particles that are not just independent numbers as in the
68 * situation above. An example would be if one wanted to track the
69 * stress or strain that a particle is subjected to -- a tensor-valued
70 * quantity. In these cases, one would <i>interpret</i> these scalar
71 * properties as the <i>components of the stress or strain</i>. In
72 * other words, one would first tell the PropertyPool to allocate
73 * as many properties per particle as there are components in the
74 * tensor one wants to track, and then write small conversion functions that
75 * take the ArrayView of scalar properties returned by the
76 * get_properties() function and convert it to a tensor of the
77 * appropriate type. This can then be evaluated and evolved in each
78 * time step. A second conversion function would convert back from a
79 * tensor to an ArrayView object to store the updated data back in the
80 * particle via the set_properties() function.
81 *
82 * There are of course cases where the properties one cares about are
83 * not real (or, in computers, floating point) numbers but rather
84 * categorical: For example, one may want to mark some particles
85 * as "red", "blue", or "green". The property might then either be
86 * represented as an integer, or as an element of an `enum`. In these
87 * cases, one would need to come up with a way to <i>represent</i>
88 * these sorts of categorical fields in terms of floating point
89 * numbers. For example, one could map "red" to the floating point number
90 * 1.0, "blue" to 2.0, and "green" to 3.0. The conversion functions
91 * to translate between these two representations should then not be very
92 * difficult to write either.
93 */
94 template <int dim, int spacedim = dim>
95 class Particle
96 {
97 public:
98 /**
99 * Empty constructor for Particle, creates a particle at the
100 * origin.
101 */
102 Particle();
103
104 /**
105 * Constructor for Particle. This function creates a particle with the
106 * specified ID at the specified location. Note that there is no check for
107 * duplicate particle IDs so the user must make sure the IDs are unique over
108 * all processes. Data is stored in a global PropertyPool object
109 * (corresponding to the global "heap") but can later be transferred to
110 * another property pool by calling set_property_pool().
111 *
112 * @param[in] location Initial location of particle.
113 * @param[in] reference_location Initial location of the particle
114 * in the coordinate system of the reference cell.
115 * @param[in] id Globally unique ID number of particle.
116 */
117 Particle(const Point<spacedim> &location,
118 const Point<dim> &reference_location,
119 const types::particle_index id);
120
121 /**
122 * Copy-constructor for Particle. This function creates a particle with
123 * exactly the state of the input argument. The copied data is stored in a
124 * global PropertyPool object (corresponding to the global "heap") but can
125 * later be transferred to another property pool by calling
126 * set_property_pool().
127 */
128 Particle(const Particle<dim, spacedim> &particle);
129
130 /**
131 * Constructor for Particle. This function creates a particle from a data
132 * vector. Data is stored in a global PropertyPool object (corresponding to
133 * the global "heap") but can later be transferred to another property pool
134 * by calling set_property_pool(). This constructor is usually called after
135 * serializing a particle by calling the write_data() function.
136 *
137 * @param[in,out] begin_data A pointer to a memory location from which
138 * to read the information that completely describes a particle. This
139 * class then de-serializes its data from this memory location and
140 * advances the pointer beyond the data that has been read to initialize
141 * the particle information.
142 *
143 * @param[in,out] property_pool An optional pointer to a property pool
144 * that is used to manage the property data used by this particle. If this
145 * argument is not provided, then a global property pool is used; on the
146 * other hand,
147 * if a non-null pointer is provided, this constructor assumes @p begin_data
148 * contains serialized data of the same length and type that is allocated
149 * by @p property_pool. If the data pointer provided here corresponds
150 * to data for a particle that has properties, then this function will only
151 * succeed if a property pool is provided as second argument that is able to
152 * store the correct number of properties per particle.
153 */
154 Particle(const void *&begin_data,
155 PropertyPool<dim, spacedim> *const property_pool = nullptr);
156
157 /**
158 * Move constructor for Particle, creates a particle from an existing
159 * one by stealing its state.
160 */
161 Particle(Particle<dim, spacedim> &&particle) noexcept;
162
163 /**
164 * Copy assignment operator.
165 */
166 Particle<dim, spacedim> &
167 operator=(const Particle<dim, spacedim> &particle);
168
169 /**
170 * Move assignment operator.
171 */
172 Particle<dim, spacedim> &
173 operator=(Particle<dim, spacedim> &&particle) noexcept;
174
175 /**
176 * Destructor. Releases the property handle if it is valid, and
177 * therefore frees that memory space for other particles. (Note:
178 * the memory is managed by the property pool, and the pool is responsible
179 * for what happens to the memory.
180 */
181 ~Particle();
182
183 /**
184 * Write particle data into a data array. The array is expected
185 * to be large enough to take the data, and the void pointer should
186 * point to the first entry of the array to which the data should be
187 * written. This function is meant for serializing all particle properties
188 * and later de-serializing the properties by calling the appropriate
189 * constructor Particle(void *&data, PropertyPool *property_pool = nullptr);
190 *
191 * @param [in] data The memory location to write particle data
192 * into.
193 *
194 * @return A pointer to the next byte after the array to which data has
195 * been written.
196 */
197 void *
198 write_particle_data_to_memory(void *data) const;
199
200
201 /**
202 * Update all of the data associated with a particle: id,
203 * location, reference location and, if any, properties by using a
204 * data array. The array is expected to be large enough to take the data,
205 * and the void pointer should point to the first entry of the array to
206 * which the data should be written. This function is meant for
207 * de-serializing the particle data without requiring that a new Particle
208 * class be built. This is used in the ParticleHandler to update the
209 * ghost particles without de-allocating and re-allocating memory.
210 *
211 * @param[in] data A pointer to a memory location from which
212 * to read the information that completely describes a particle. This
213 * class then de-serializes its data from this memory location.
214 *
215 * @return A pointer to the next byte after the array from which data has
216 * been read.
217 */
218 const void *
219 read_particle_data_from_memory(const void *data);
220
221 /**
222 * Set the location of this particle. Note that this does not check
223 * whether this is a valid location in the simulation domain.
224 *
225 * @param [in] new_location The new location for this particle.
226 *
227 * @note In parallel programs, the ParticleHandler class stores particles
228 * on both the locally owned cells, as well as on ghost cells. The
229 * particles on the latter are *copies* of particles owned on other
230 * processors, and should therefore be treated in the same way as
231 * ghost entries in
232 * @ref GlossGhostedVector "vectors with ghost elements"
233 * or
234 * @ref GlossGhostCell "ghost cells":
235 * In both cases, one should
236 * treat the ghost elements or cells as `const` objects that shouldn't
237 * be modified even if the objects allow for calls that modify
238 * properties. Rather, properties should only be modified on processors
239 * that actually *own* the particle.
240 */
241 void
242 set_location(const Point<spacedim> &new_location);
243
244 /**
245 * Get the location of this particle.
246 *
247 * @return The location of this particle.
248 */
249 const Point<spacedim> &
250 get_location() const;
251
252 /**
253 * Get read- and write-access to the location of this particle.
254 * Note that changing the location does not check
255 * whether this is a valid location in the simulation domain.
256 *
257 * @note In parallel programs, the ParticleHandler class stores particles
258 * on both the locally owned cells, as well as on ghost cells. The
259 * particles on the latter are *copies* of particles owned on other
260 * processors, and should therefore be treated in the same way as
261 * ghost entries in
262 * @ref GlossGhostedVector "vectors with ghost elements"
263 * or
264 * @ref GlossGhostCell "ghost cells":
265 * In both cases, one should
266 * treat the ghost elements or cells as `const` objects that shouldn't
267 * be modified even if the objects allow for calls that modify
268 * properties. Rather, properties should only be modified on processors
269 * that actually *own* the particle.
270 *
271 * @return The location of this particle.
272 */
273 Point<spacedim> &
274 get_location();
275
276 /**
277 * Set the reference location of this particle.
278 *
279 * @param [in] new_reference_location The new reference location for
280 * this particle.
281 *
282 * @note In parallel programs, the ParticleHandler class stores particles
283 * on both the locally owned cells, as well as on ghost cells. The
284 * particles on the latter are *copies* of particles owned on other
285 * processors, and should therefore be treated in the same way as
286 * ghost entries in
287 * @ref GlossGhostedVector "vectors with ghost elements"
288 * or
289 * @ref GlossGhostCell "ghost cells":
290 * In both cases, one should
291 * treat the ghost elements or cells as `const` objects that shouldn't
292 * be modified even if the objects allow for calls that modify
293 * properties. Rather, properties should only be modified on processors
294 * that actually *own* the particle.
295 */
296 void
297 set_reference_location(const Point<dim> &new_reference_location);
298
299 /**
300 * Return the reference location of this particle in its current cell.
301 */
302 const Point<dim> &
303 get_reference_location() const;
304
305 /**
306 * Return the ID number of this particle. The ID of a particle is intended
307 * to be a property that is globally unique even in parallel computations
308 * and is transferred along with other properties of a particle if it
309 * moves from a cell owned by the current processor to a cell owned by
310 * a different processor, or if ownership of the cell it is on is
311 * transferred to a different processor.
312 */
313 types::particle_index
314 get_id() const;
315
316 /**
317 * Set the ID number of this particle. The ID of a particle is intended
318 * to be a property that is globally unique even in parallel computations
319 * and is transferred along with other properties of a particle if it
320 * moves from a cell owned by the current processor to a cell owned by
321 * a different processor, or if ownership of the cell it is on is
322 * transferred to a different processor. As a consequence, when setting
323 * the ID of a particle, care needs to be taken to ensure that particles
324 * have globally unique IDs. (The ParticleHandler does not itself check
325 * whether particle IDs so set are globally unique in a parallel setting
326 * since this would be a very expensive operation.)
327 *
328 * @param[in] new_id The new ID number for this particle.
329 *
330 * @note In parallel programs, the ParticleHandler class stores particles
331 * on both the locally owned cells, as well as on ghost cells. The
332 * particles on the latter are *copies* of particles owned on other
333 * processors, and should therefore be treated in the same way as
334 * ghost entries in
335 * @ref GlossGhostedVector "vectors with ghost elements"
336 * or
337 * @ref GlossGhostCell "ghost cells":
338 * In both cases, one should
339 * treat the ghost elements or cells as `const` objects that shouldn't
340 * be modified even if the objects allow for calls that modify
341 * properties. Rather, properties should only be modified on processors
342 * that actually *own* the particle.
343 */
344 void
345 set_id(const types::particle_index &new_id);
346
347 /**
348 * Tell the particle where to store its properties (even if it does not
349 * own properties). Usually this is only done once per particle, but
350 * since the particle does not know about the properties,
351 * we want to do it not at construction time. Another use for this
352 * function is after particle transfer to a new process.
353 *
354 * If a particle already stores properties in a property pool, then
355 * their values are saved, the memory is released in the previous
356 * property pool, and a copy of the particle's properties will be
357 * allocated in the new property pool.
358 */
359 void
360 set_property_pool(PropertyPool<dim, spacedim> &property_pool);
361
362 /**
363 * Return whether this particle has a valid property pool and a valid
364 * handle to properties.
365 */
366 bool
367 has_properties() const;
368
369 /**
370 * Set the properties of this particle.
371 *
372 * @param [in] new_properties An ArrayView containing the
373 * new properties for this particle.
374 *
375 * @note In parallel programs, the ParticleHandler class stores particles
376 * on both the locally owned cells, as well as on ghost cells. The
377 * particles on the latter are *copies* of particles owned on other
378 * processors, and should therefore be treated in the same way as
379 * ghost entries in
380 * @ref GlossGhostedVector "vectors with ghost elements"
381 * or
382 * @ref GlossGhostCell "ghost cells":
383 * In both cases, one should
384 * treat the ghost elements or cells as `const` objects that shouldn't
385 * be modified even if the objects allow for calls that modify
386 * properties. Rather, properties should only be modified on processors
387 * that actually *own* the particle.
388 */
389 void
390 set_properties(const ArrayView<const double> &new_properties);
391
392 /**
393 * Get write-access to properties of this particle. If the
394 * particle has no properties yet, but has access to a
395 * PropertyPool object it will allocate properties to
396 * allow writing into them. If it has no properties and
397 * has no access to a PropertyPool this function will
398 * throw an exception.
399 *
400 * @return An ArrayView of the properties of this particle.
401 */
402 ArrayView<double>
403 get_properties();
404
405 /**
406 * Get read-access to properties of this particle. If the particle
407 * has no properties this function throws an exception.
408 *
409 * @return An ArrayView of the properties of this particle.
410 */
411 ArrayView<const double>
412 get_properties() const;
413
414 /**
415 * Return the size in bytes this particle occupies if all of its data is
416 * serialized (i.e. the number of bytes that is written by the write_data
417 * function of this class).
418 */
419 std::size_t
420 serialized_size_in_bytes() const;
421
422 /**
423 * Write the data of this object to a stream for the purpose of
424 * serialization using the [BOOST serialization
425 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
426 */
427 template <class Archive>
428 void
429 save(Archive &ar, const unsigned int version) const;
430
431 /**
432 * Read the data of this object from a stream for the purpose of
433 * serialization using the [BOOST serialization
434 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
435 * Note that in order to store the properties correctly, the property pool
436 * of this particle has to be known at the time of reading, i.e.
437 * set_property_pool() has to have been called, before this function is
438 * called.
439 */
440 template <class Archive>
441 void
442 load(Archive &ar, const unsigned int version);
443
444 /**
445 * Free the memory of the property pool
446 */
447 void
448 free_properties();
449
450 #ifdef DOXYGEN
451 /**
452 * Write and read the data of this object from a stream for the purpose
453 * of serialization using the [BOOST serialization
454 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
455 */
456 template <class Archive>
457 void
458 serialize(Archive &archive, const unsigned int version);
459 #else
460 // This macro defines the serialize() method that is compatible with
461 // the templated save() and load() method that have been implemented.
462 BOOST_SERIALIZATION_SPLIT_MEMBER()
463 #endif
464
465 private:
466 /**
467 * A global property pool used when a particle is not associated with
468 * a property pool that belongs to, for example, a ParticleHandler.
469 */
470 static PropertyPool<dim, spacedim> global_property_pool;
471
472 /**
473 * A pointer to the property pool. Necessary to translate from the
474 * handle to the actual memory locations.
475 */
476 PropertyPool<dim, spacedim> *property_pool;
477
478 /**
479 * A handle to all particle properties
480 */
481 typename PropertyPool<dim, spacedim>::Handle property_pool_handle;
482 };
483
484
485
486 /* ---------------------- inline and template functions ------------------ */
487
488 template <int dim, int spacedim>
489 template <class Archive>
490 inline void
491 Particle<dim, spacedim>::load(Archive &ar, const unsigned int)
492 {
493 unsigned int n_properties = 0;
494
495 Point<spacedim> location;
496 Point<dim> reference_location;
497 types::particle_index id;
498 ar &location &reference_location &id &n_properties;
499
500 set_location(location);
501 set_reference_location(reference_location);
502 set_id(id);
503
504 if (n_properties > 0)
505 {
506 ArrayView<double> properties(get_properties());
507 Assert(
508 properties.size() == n_properties,
509 ExcMessage(
510 "This particle was serialized with " +
511 std::to_string(n_properties) +
512 " properties, but the new property handler provides space for " +
513 std::to_string(properties.size()) +
514 " properties. Deserializing a particle only works for matching property sizes."));
515
516 ar &boost::serialization::make_array(properties.data(), n_properties);
517 }
518 }
519
520
521
522 template <int dim, int spacedim>
523 template <class Archive>
524 inline void
525 Particle<dim, spacedim>::save(Archive &ar, const unsigned int) const
526 {
527 unsigned int n_properties = 0;
528 if ((property_pool != nullptr) &&
529 (property_pool_handle != PropertyPool<dim, spacedim>::invalid_handle))
530 n_properties = get_properties().size();
531
532 Point<spacedim> location = get_location();
533 Point<dim> reference_location = get_reference_location();
534 types::particle_index id = get_id();
535
536 ar &location &reference_location &id &n_properties;
537
538 if (n_properties > 0)
539 ar &boost::serialization::make_array(get_properties().data(),
540 n_properties);
541 }
542
543
544
545 template <int dim, int spacedim>
546 inline void
547 Particle<dim, spacedim>::set_location(const Point<spacedim> &new_loc)
548 {
549 property_pool->set_location(property_pool_handle, new_loc);
550 }
551
552
553
554 template <int dim, int spacedim>
555 inline const Point<spacedim> &
556 Particle<dim, spacedim>::get_location() const
557 {
558 return property_pool->get_location(property_pool_handle);
559 }
560
561
562
563 template <int dim, int spacedim>
564 inline Point<spacedim> &
565 Particle<dim, spacedim>::get_location()
566 {
567 return property_pool->get_location(property_pool_handle);
568 }
569
570
571
572 template <int dim, int spacedim>
573 inline void
574 Particle<dim, spacedim>::set_reference_location(const Point<dim> &new_loc)
575 {
576 property_pool->set_reference_location(property_pool_handle, new_loc);
577 }
578
579
580
581 template <int dim, int spacedim>
582 inline const Point<dim> &
583 Particle<dim, spacedim>::get_reference_location() const
584 {
585 return property_pool->get_reference_location(property_pool_handle);
586 }
587
588
589
590 template <int dim, int spacedim>
591 inline types::particle_index
592 Particle<dim, spacedim>::get_id() const
593 {
594 return property_pool->get_id(property_pool_handle);
595 }
596
597
598
599 template <int dim, int spacedim>
600 inline void
601 Particle<dim, spacedim>::set_id(const types::particle_index &new_id)
602 {
603 property_pool->set_id(property_pool_handle, new_id);
604 }
605
606
607
608 template <int dim, int spacedim>
609 inline void
610 Particle<dim, spacedim>::set_property_pool(
611 PropertyPool<dim, spacedim> &new_property_pool)
612 {
613 // First, we do want to save any properties that may
614 // have previously been set, and copy them over to the memory allocated
615 // on the new pool.
616 //
617 // It is possible that a particle currently has no properties -- for
618 // example if it has been created without an associated property
619 // pool (i.e., uses the default global pool which does not store any
620 // properties) but that the new pool has properties. In that case,
621 // there is simply nothing to transfer -- but the register_particle()
622 // call here will make sure that the newly allocated properties are
623 // zero-initialized.
624 const typename PropertyPool<dim, spacedim>::Handle new_handle =
625 new_property_pool.register_particle();
626
627 const Point<spacedim> location = get_location();
628 const Point<dim> reference_location = get_reference_location();
629 const types::particle_index id = get_id();
630
631 if (/* old pool */ has_properties())
632 {
633 ArrayView<const double> old_properties = this->get_properties();
634 ArrayView<double> new_properties =
635 new_property_pool.get_properties(new_handle);
636 std::copy(old_properties.cbegin(),
637 old_properties.cend(),
638 new_properties.begin());
639 }
640
641 // Now release the old memory handle
642 property_pool->deregister_particle(property_pool_handle);
643
644
645 // Then set the pointer to the property pool we want to use. Also set the
646 // handle to any properties.
647 property_pool = &new_property_pool;
648 property_pool_handle = new_handle;
649
650 // Now also store the saved locations
651 set_location(location);
652 set_reference_location(reference_location);
653 set_id(id);
654 }
655
656
657
658 template <int dim, int spacedim>
659 inline ArrayView<const double>
660 Particle<dim, spacedim>::get_properties() const
661 {
662 if (has_properties() == false)
663 return {};
664 else
665 return property_pool->get_properties(property_pool_handle);
666 }
667
668
669
670 template <int dim, int spacedim>
671 inline bool
672 Particle<dim, spacedim>::has_properties() const
673 {
674 // Particles always have a property pool associated with them,
675 // but we can access properties only if there is a valid handle.
676 // The only way a particle can have no valid handle if it has
677 // been moved-from -- but that leaves an object in an invalid
678 // state, and so we can just assert that that can't be the case.
679 Assert((property_pool_handle !=
680 PropertyPool<dim, spacedim>::invalid_handle),
681 ExcInternalError());
682 return (property_pool->n_properties_per_slot() > 0);
683 }
684
685 } // namespace Particles
686
687 DEAL_II_NAMESPACE_CLOSE // Do not convert for module purposes
688
689
690 namespace boost
691 {
692 namespace geometry
693 {
694 namespace index
695 {
696 /**
697 * Make sure we can construct an RTree of Particles::Particle objects.
698 */
699 template <int dim, int spacedim>
700 struct indexable<dealii::Particles::Particle<dim, spacedim>>
701 {
702 /**
703 * boost::rtree expects a const reference to an indexable object. For
704 * a Particles::Particle object, this is its reference location.
705 */
706 using result_type = const dealii::Point<spacedim> &;
707
708 result_type
709 operator()(
710 const dealii::Particles::Particle<dim, spacedim> &particle) const
711 {
712 return particle.get_location();
713 }
714 };
715
716 } // namespace index
717 } // namespace geometry
718 } // namespace boost
719
720
721 DEAL_II_NAMESPACE_OPEN // Do not convert for module purposes
722 DEAL_II_NAMESPACE_CLOSE
723
724 #endif