Debian Codegraph @

include/deal.II/particles/particle_handler.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_handler_h
16 #define dealii_particles_particle_handler_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/array_view.h>
21 #include <deal.II/base/bounding_box.h>
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/function.h>
24 #include <deal.II/base/observer_pointer.h>
25
26 #include <deal.II/distributed/tria.h>
27
28 #include <deal.II/fe/mapping.h>
29
30 #include <deal.II/grid/grid_tools_cache.h>
31
32 #include <deal.II/particles/particle.h>
33 #include <deal.II/particles/particle_iterator.h>
34 #include <deal.II/particles/partitioner.h>
35 #include <deal.II/particles/property_pool.h>
36
37 #include <boost/range/iterator_range.hpp>
38 #include <boost/serialization/map.hpp>
39 #include <boost/signals2.hpp>
40
41
42 DEAL_II_NAMESPACE_OPEN
43
44 namespace Particles
45 {
46 /**
47 * This class manages the storage and handling of particles. It provides
48 * the data structures necessary to store particles efficiently, accessor
49 * functions to iterate over particles and find particles, and algorithms
50 * to distribute particles in parallel domains. Note that the class
51 * is designed in a similar way as the triangulation class. In particular,
52 * we call particles in the domain of the local process local particles,
53 * and particles that belong to neighbor processes and live in the ghost cells
54 * around the locally owned domain "ghost particles". The class also includes
55 * functionality that is similar to the DoFHandler class (it knows which
56 * particles live on which cells) and the SolutionTransfer class (it knows
57 * how to transfer particles between cells and subdomains).
58 *
59 * For examples on how to use this class to track particles, store properties
60 * on particles, and let the properties on the particles influence the
61 * finite-element solution see step-19, step-68, step-70, and step-83.
62 */
63 template <int dim, int spacedim = dim>
64 class ParticleHandler : public EnableObserverPointer
65 {
66 public:
67 /**
68 * A type that can be used to iterate over all particles in the domain.
69 */
70 using particle_iterator = ParticleIterator<dim, spacedim>;
71
72 /**
73 * A type that represents a range of particles.
74 */
75 using particle_iterator_range = boost::iterator_range<particle_iterator>;
76
77 /**
78 * A type for the storage container for particles.
79 */
80 using particle_container =
81 typename ParticleAccessor<dim, spacedim>::particle_container;
82
83 /**
84 * Default constructor.
85 */
86 ParticleHandler();
87
88 /**
89 * Constructor that initializes the particle handler with
90 * a given triangulation and mapping. Since particles are stored with
91 * respect to their surrounding cells this information is necessary to
92 * correctly organize the particle collection.
93 * This constructor is equivalent to calling the default constructor and
94 * the initialize function.
95 */
96 ParticleHandler(const Triangulation<dim, spacedim> &tria,
97 const Mapping<dim, spacedim> &mapping,
98 const unsigned int n_properties = 0);
99
100 /**
101 * Destructor.
102 */
103 virtual ~ParticleHandler();
104
105 /**
106 * Initialize the particle handler. This function clears the
107 * internal data structures, and sets the triangulation and the
108 * mapping to be used.
109 */
110 void
111 initialize(const Triangulation<dim, spacedim> &tria,
112 const Mapping<dim, spacedim> &mapping,
113 const unsigned int n_properties = 0);
114
115 /**
116 * Copy the state of particle handler @p particle_handler into the
117 * current object. This will copy
118 * all particles and properties and leave this object
119 * as an identical copy of @p particle_handler. Existing
120 * particles in this object are deleted. Be aware that this
121 * does not copy functions that are connected to the signals of
122 * @p particle_handler, nor does it connect the current object's member
123 * functions to triangulation signals, which must be done by the caller
124 * if necessary, that is if the @p particle_handler had
125 * connected functions.
126 *
127 * This function is expensive as it has to duplicate all data
128 * in @p particle_handler, and insert it into this object,
129 * which may be a significant amount of data. However, it can
130 * be useful to save the state of a particle
131 * collection at a certain point in time and reset this
132 * state later under certain conditions, for example if
133 * a timestep has to be undone and repeated.
134 */
135 void
136 copy_from(const ParticleHandler<dim, spacedim> &particle_handler);
137
138 /**
139 * Clear all particle related data but keep the handler initialized.
140 */
141 void
142 clear();
143
144 /**
145 * Only clear particle data, but keep cache information about number
146 * of particles. This is useful during reorganization of particle data
147 * between processes.
148 */
149 void
150 clear_particles();
151
152 /**
153 * This function can be used to preemptively reserve memory for particle
154 * data. Calling this function before inserting particles will reduce
155 * memory allocations and therefore increase the performance. Calling
156 * this function is optional; if memory is not already allocated it will
157 * be allocated automatically during the insertion. It is recommended to
158 * use this function if you know the number of particles that will be
159 * inserted, but cannot use one of the collective particle insertion
160 * functions.
161 *
162 * @param n_particles Number of particles to reserve memory for. Note that
163 * this is the total number of particles to be stored, not the number of
164 * particles to be newly inserted.
165 */
166 void
167 reserve(const std::size_t n_particles);
168
169 /**
170 * Update all internally cached numbers. Note that all functions that
171 * modify internal data structures and act on multiple particles will
172 * call this function automatically (e.g. insert_particles), while
173 * functions that act on single particles will not call this function
174 * (e.g. insert_particle). This is done because the update is
175 * expensive compared to single operations.
176 */
177 void
178 update_cached_numbers();
179
180 /**
181 * Return an iterator to the first locally owned particle.
182 */
183 particle_iterator
184 begin() const;
185
186 /**
187 * Return an iterator to the first locally owned particle.
188 */
189 particle_iterator
190 begin();
191
192 /**
193 * Return an iterator past the end of the particles.
194 */
195 particle_iterator
196 end() const;
197
198 /**
199 * Return an iterator past the end of the particles.
200 */
201 particle_iterator
202 end();
203
204 /**
205 * Return an iterator to the first ghost particle.
206 */
207 particle_iterator
208 begin_ghost() const;
209
210 /**
211 * Return an iterator to the first ghost particle.
212 */
213 particle_iterator
214 begin_ghost();
215
216 /**
217 * Return an iterator past the end of the ghost particles.
218 */
219 particle_iterator
220 end_ghost() const;
221
222 /**
223 * Return an iterator past the end of the ghost particles.
224 */
225 particle_iterator
226 end_ghost();
227
228 /**
229 * Return the number of particles that live on the given cell.
230 */
231 types::particle_index
232 n_particles_in_cell(
233 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell)
234 const;
235
236 /**
237 * Return a pair of particle iterators that mark the begin and end of
238 * the particles in a particular cell. The last iterator is the first
239 * particle that is no longer in the cell.
240 *
241 * The number of elements in the returned range equals what the
242 * n_particles_in_cell() function returns.
243 */
244 particle_iterator_range
245 particles_in_cell(
246 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell);
247
248 /**
249 * Return a pair of particle iterators that mark the begin and end of
250 * the particles in a particular cell. The last iterator is the first
251 * particle that is no longer in the cell.
252 *
253 * The number of elements in the returned range equals what the
254 * n_particles_in_cell() function returns.
255 */
256 particle_iterator_range
257 particles_in_cell(
258 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell)
259 const;
260
261 /**
262 * Remove a particle pointed to by the iterator. Note that @p particle
263 * and all iterators that point to other particles in the same cell
264 * as @p particle will be invalidated during this call.
265 */
266 void
267 remove_particle(const particle_iterator &particle);
268
269 /**
270 * Remove a vector of particles indicated by the particle iterators.
271 * The iterators and all other particle iterators are invalidated
272 * during the function call.
273 */
274 void
275 remove_particles(const std::vector<particle_iterator> &particles);
276
277 /**
278 * Insert a particle into the collection of particles. Return an iterator
279 * to the new position of the particle. This function involves a copy of
280 * the particle and its properties. Note that this function is of $O(N \log
281 * N)$ complexity for $N$ particles.
282 */
283 particle_iterator
284 insert_particle(
285 const Particle<dim, spacedim> &particle,
286 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell);
287
288 /**
289 * Insert a particle into the collection of particles given all the
290 * properties necessary for creating a particle. This function is used to
291 * efficiently generate particles without the detour through a Particle
292 * object.
293 *
294 * @param[in] position Initial position of the particle in real space.
295 * @param[in] reference_position Initial position of the particle
296 * in the coordinate system of the reference cell.
297 * @param[in] particle_index Globally unique identifier for this particle.
298 * @param[in] cell The cell in which the particle is located.
299 * @param[in] properties An optional ArrayView that describes the
300 * particle properties. If given this has to be of size
301 * n_properties_per_particle().
302 */
303 particle_iterator
304 insert_particle(
305 const Point<spacedim> &position,
306 const Point<dim> &reference_position,
307 const types::particle_index particle_index,
308 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell,
309 const ArrayView<const double> &properties = {});
310
311 /**
312 * Insert a number of particles into the collection of particles.
313 * This function involves a copy of the particles and their properties.
314 * Note that this function is of O(n_existing_particles + n_particles)
315 * complexity.
316 */
317 void
318 insert_particles(
319 const std::multimap<
320 typename Triangulation<dim, spacedim>::active_cell_iterator,
321 Particle<dim, spacedim>> &particles);
322
323 /**
324 * Create and insert a number of particles into the collection of particles.
325 * This function takes a list of positions and creates a set of particles
326 * at these positions, which are then added to the local particle
327 * collection. Note that this function currently uses
328 * GridTools::compute_point_locations(), which assumes all positions are
329 * within the local part of the triangulation. If one of them is not in the
330 * local domain this function will throw an exception.
331 */
332 void
333 insert_particles(const std::vector<Point<spacedim>> &positions);
334
335 /**
336 * Create and insert a number of particles into the collection of particles.
337 * This function takes a list of positions and creates a set of particles
338 * at these positions, which are then distributed and added to the local
339 * particle collection of a processor. Note that this function uses
340 * GridTools::distributed_compute_point_locations(). Consequently, it can
341 * require intense communications between the processors. This function
342 * is used in step-70.
343 *
344 * This function figures out what mpi process owns the points that do not
345 * fall within the locally owned part of the triangulation, it sends
346 * to that process the points passed to this function on this process,
347 * and receives the points that fall within the locally owned cells of
348 * the triangulation from whoever received them as input.
349 *
350 * In order to keep track of what mpi process received what points, a map
351 * from mpi process to IndexSet is returned by the function. This IndexSet
352 * contains the local indices of the points that were passed to this
353 * function on the calling mpi process, and that falls within the part of
354 * triangulation owned by this mpi process.
355 *
356 * The ids of the resulting particles are assigned from the optional
357 * argument @p ids. If the vector of @p ids is empty, then the ids are
358 * computed automatically from the get_next_free_particle_index() onward.
359 * For example, if the method get_next_free_particle_index() returns n0,
360 * calling this function with two MPI processes each adding n1 and n2
361 * particles will result in the n1 particles added by process zero having
362 * ids equal to `[n0,n0+n1)`, and the n2 particles added by process one
363 * having ids `[n0+n1, n0+n1+n2)`.
364 *
365 * @param[in] positions A vector of points that do not need to be on the
366 * local processor, but have to be in the triangulation that is associated
367 * with this ParticleHandler object.
368 *
369 * @param[in] global_bounding_boxes A vector of vectors of bounding boxes.
370 * The bounding boxes `global_bboxes[rk]` describe which part of the mesh is
371 * locally owned by the mpi process with rank `rk`. The local description
372 * can be obtained from GridTools::compute_mesh_predicate_bounding_box(),
373 * and the global one can be obtained by passing the local ones to
374 * Utilities::MPI::all_gather().
375 *
376 * @param[in] properties (Optional) A vector of vector of properties
377 * associated with each local point. The size of the vector should be either
378 * zero (no properties will be transferred nor attached to the generated
379 * particles) or it should be a vector of `positions.size()` vectors of size
380 * `n_properties_per_particle()`. Notice that this function call will
381 * transfer the properties from the local mpi process to the final mpi
382 * process that will own each of the particles, and it may therefore be
383 * communication intensive.
384 *
385 * @param[in] ids (Optional) A vector of ids to associate to each particle.
386 * If the vector is empty, the ids are assigned as a continuous range
387 * from the first available index, as documented above. If the vector is not
388 * empty, then its size must match the size of the @p positions vector.
389 *
390 * @return A map from owner to IndexSet, that contains the local indices
391 * of the points that were passed to this function on the calling mpi
392 * process, and that falls within the part of triangulation owned by this
393 * mpi process.
394 */
395 std::map<unsigned int, IndexSet>
396 insert_global_particles(
397 const std::vector<Point<spacedim>> &positions,
398 const std::vector<std::vector<BoundingBox<spacedim>>>
399 &global_bounding_boxes,
400 const std::vector<std::vector<double>> &properties = {},
401 const std::vector<types::particle_index> &ids = {});
402
403 /**
404 * Insert a number of particles into the collection of particles. This
405 * function takes a list of particles for which we don't know the associated
406 * cell iterator, and distributes them to the correct local particle
407 * collection of a processor, by unpacking the locations, figuring out where
408 * to send the particles by calling
409 * GridTools::distributed_compute_point_locations(), and sending the
410 * particles to the corresponding process.
411 *
412 * In order to keep track of what mpi process received what particles, a map
413 * from mpi process to IndexSet is returned by the function. This IndexSet
414 * contains the local indices of the particles that were passed to this
415 * function on the calling mpi process, and that falls within the part of
416 * the triangulation owned by this mpi process.
417 *
418 * @param[in] particles A vector of particles that do not need to be on the
419 * local processor.
420 *
421 * @param[in] global_bounding_boxes A vector of vectors of bounding boxes.
422 * The bounding boxes `global_bboxes[rk]` describe which part of the mesh is
423 * locally owned by the mpi process with rank `rk`. The local description
424 * can be obtained from GridTools::compute_mesh_predicate_bounding_box(),
425 * and the global one can be obtained by passing the local ones to
426 * Utilities::MPI::all_gather().
427 *
428 * @return A map from owner to IndexSet, that contains the local indices
429 * of the points that were passed to this function on the calling mpi
430 * process, and that falls within the part of triangulation owned by this
431 * mpi process.
432 */
433 std::map<unsigned int, IndexSet>
434 insert_global_particles(
435 const std::vector<Particle<dim, spacedim>> &particles,
436 const std::vector<std::vector<BoundingBox<spacedim>>>
437 &global_bounding_boxes);
438
439 /**
440 * Set the position of the particles by using the values contained in the
441 * vector @p input_vector.
442 *
443 * @tparam VectorType Any of the parallel distributed vectors supported by
444 * the library.
445 *
446 * The vector @p input_vector should have read access to the indices
447 * created by extracting the locally relevant ids with
448 * locally_owned_particle_ids(), and taking its tensor
449 * product with the index set representing the range `[0, spacedim)`, i.e.:
450 * @code
451 * IndexSet ids = particle_handler.locally_owned_particle_ids().
452 * tensor_product(complete_index_set(spacedim));
453 * @endcode
454 *
455 * The position of the particle with global index `id` is read from
456 * spacedim consecutive entries starting from
457 * `input_vector[id*spacedim]`.
458 *
459 * Notice that it is not necessary that the @p input_vector *owns* those
460 * indices, however it has to have read access to them (i.e., it can be a
461 * distributed vector with ghost entries).
462 *
463 * If the argument @p displace_particles is set to false, then the new
464 * position taken from the values contained in
465 * @p input_vector, replacing the previously stored particle position.
466 * By default, the particles are displaced by the amount contained in the
467 * @p input_vector, i.e., the contents of the vector are considered
468 * *offsets* that are added to the previous position.
469 *
470 * After setting the new position, this function calls internally the method
471 * sort_particles_into_subdomains_and_cells(). You should
472 * make sure you satisfy the requirements of that function.
473 *
474 * @param[in] input_vector A parallel distributed vector containing
475 * the displacement to apply to each particle, or their new absolute
476 * position.
477 *
478 * @param[in] displace_particles Control if the @p input_vector should
479 * be interpreted as a displacement vector, or a vector of absolute
480 * positions.
481 */
482 template <typename VectorType>
483 std::enable_if_t<
484 std::is_convertible_v<VectorType *, Function<spacedim> *> == false>
485 set_particle_positions(const VectorType &input_vector,
486 const bool displace_particles = true);
487
488 /**
489 * Set the position of the particles within the particle handler using a
490 * vector of points. The new set of point defined by the
491 * vector has to be sufficiently close to the original one to ensure that
492 * the sort_particles_into_subdomains_and_cells() function manages to find
493 * the new cells in which the particles belong.
494 *
495 * Points are numbered in the same way they are traversed locally by the
496 * ParticleHandler. A typical way to use this method, is to first call the
497 * get_particle_positions() function, and then modify the resulting vector.
498 *
499 * @param [in] new_positions A vector of points of dimension
500 * particle_handler.n_locally_owned_particles()
501 *
502 * @param [in] displace_particles When true, this function adds the value
503 * of the vector of points to the
504 * current position of the particle, thus displacing them by the
505 * amount given by the function. When false, the position of the
506 * particle is replaced by the value in the vector.
507 */
508 void
509 set_particle_positions(const std::vector<Point<spacedim>> &new_positions,
510 const bool displace_particles = true);
511
512
513 /**
514 * Set the position of the particles within the particle handler using a
515 * function with spacedim components. The new set of point defined by the
516 * function has to be sufficiently close to the original one to ensure that
517 * the sort_particles_into_subdomains_and_cells algorithm manages to find
518 * the new cells in which the particles belong.
519 *
520 * The function is evaluated at the current location of the particles.
521 *
522 * @param [in] function A function that has n_components==spacedim that
523 * describes either the displacement or the new position of the particles as
524 * a function of the current location of the particle.
525 *
526 * @param [in] displace_particles When true, this function adds the results
527 * of the function to the current position of the particle, thus displacing
528 * them by the amount given by the function. When false, the position of the
529 * particle is replaced by the value of the function.
530 */
531 void
532 set_particle_positions(const Function<spacedim> &function,
533 const bool displace_particles = true);
534
535 /**
536 * Read the position of the particles and store them into the distributed
537 * vector @p output_vector. By default the
538 * @p output_vector is overwritten by this operation, but you can add to
539 * its entries by setting @p add_to_output_vector to `true`.
540 *
541 * @tparam VectorType Any of the parallel distributed vectors supported by
542 * the library.
543 *
544 * This is the reverse operation of the set_particle_positions() function.
545 * The position of the particle with global index `id` is written to
546 * spacedim consecutive entries starting from
547 * `output_vector[id*spacedim]`.
548 *
549 * Notice that, if you use a distributed vector type, it is not necessary
550 * for the @p output_vector to own the entries corresponding to the indices
551 * that will be written. However you should keep in mind that this requires
552 * a global communication to distribute the entries above to their
553 * respective owners.
554 *
555 * @param[in, out] output_vector A parallel distributed vector containing
556 * the positions of the particles, or updated with the positions of the
557 * particles.
558 *
559 * @param[in] add_to_output_vector Control if the function should set the
560 * entries of the @p output_vector or if should add to them.
561 */
562 template <typename VectorType>
563 void
564 get_particle_positions(VectorType &output_vector,
565 const bool add_to_output_vector = false);
566
567 /**
568 * Gather the position of the particles within the particle handler in
569 * a vector of points. The order of the points is the same on would obtain
570 * by iterating over all (local) particles, and querying their locations.
571 *
572 * @param [in,out] positions A vector preallocated at size
573 * `particle_handler.n_locally_owned_articles` and whose points will become
574 * the positions of the locally owned particles
575 *
576 * @param [in] add_to_output_vector When true, the value of the point of
577 * the particles is added to the positions vector. When false,
578 * the value of the points in the positions vector are replaced by the
579 * position of the particles.
580 */
581 void
582 get_particle_positions(std::vector<Point<spacedim>> &positions,
583 const bool add_to_output_vector = false);
584
585 /**
586 * This function allows to register three additional functions that are
587 * called every time a particle is transferred to another process
588 * (i.e. during sorting into cells, during ghost particle transfer, or
589 * during serialization of all particles).
590 *
591 * @param size_callback A function that is called when serializing
592 * particle data. The function gets no arguments and is expected to
593 * return the size of the additional data that is serialized per
594 * particle. Note that this currently implies the data size has to be
595 * the same for every particle.
596 * @param store_callback A function that is called once per particle
597 * when serializing particle data. Arguments to the function are a
598 * particle iterator that identifies the current particle and a void
599 * pointer that points to a data block of size size_callback() in which
600 * the function can store additional data. The function is expected to
601 * return a void pointer pointing to a position right after its data
602 * block.
603 * @param load_callback A function that is called once per particle
604 * when deserializing particle data. Arguments to the function are a
605 * particle iterator that identifies the current particle and a void
606 * pointer that points to a data block of size size_callback() in which
607 * additional data was stored by the store_callback function. The
608 * function is expected to return a void pointer pointing to a position
609 * right after its data block.
610 */
611 void
612 register_additional_store_load_functions(
613 const std::function<std::size_t()> &size_callback,
614 const std::function<void *(const particle_iterator &, void *)>
615 &store_callback,
616 const std::function<const void *(const particle_iterator &, const void *)>
617 &load_callback);
618
619 /**
620 * Return the total number of particles that were managed by this class
621 * the last time the update_cached_numbers() function was called.
622 * The actual number of particles may have changed since then if
623 * particles have been added or removed.
624 *
625 * @return Total number of particles in simulation.
626 */
627 types::particle_index
628 n_global_particles() const;
629
630 /**
631 * Return the maximum number of particles per cell the last
632 * time the update_cached_numbers() function was called.
633 *
634 * @return Maximum number of particles in one cell in simulation.
635 */
636 types::particle_index
637 n_global_max_particles_per_cell() const;
638
639 /**
640 * Return the number of particles in the local part of the
641 * triangulation.
642 */
643 types::particle_index
644 n_locally_owned_particles() const;
645
646 /**
647 * Return the next free particle index in the global set
648 * of particles the last
649 * time the update_cached_numbers() function was called.
650 */
651 types::particle_index
652 get_next_free_particle_index() const;
653
654 /**
655 * Extract an IndexSet with global dimensions equal to
656 * get_next_free_particle_index(), containing the locally owned
657 * particle indices.
658 *
659 * This function can be used to construct distributed vectors and matrices
660 * to manipulate particles using linear algebra operations.
661 *
662 * Notice that it is the user's responsibility to guarantee that particle
663 * indices are unique, and no check is performed to verify that this is the
664 * case, nor that the union of all IndexSet objects on each mpi process is
665 * complete.
666 *
667 * @return An IndexSet of size get_next_free_particle_index(), containing
668 * n_locally_owned_particle() indices.
669 */
670 IndexSet
671 locally_owned_particle_ids() const;
672
673 /**
674 * Return the number of properties each particle has.
675 */
676 unsigned int
677 n_properties_per_particle() const;
678
679 /**
680 * Return one past the largest local index (in MPI-local index space)
681 * returned by ParticleAccessor::get_local_index(). This number can be
682 * larger than locally_owned_particle_ids().n_elements(), because local
683 * indices are not necessarily forming a contiguous range and can contain
684 * gaps in the range 0 to get_max_local_particle_index(). As a
685 * consequence, the number is not updated upon calls to remove_particle()
686 * or similar functions, and refreshed only as new particles get added or
687 * in sort_particles_into_subdomains_and_cells().
688 *
689 * This function is appropriate for resizing vectors working with
690 * ParticleAccessor::get_local_index().
691 */
692 types::particle_index
693 get_max_local_particle_index() const;
694
695 /**
696 * Return a reference to the property pool that owns all particle
697 * properties, and organizes them physically.
698 */
699 PropertyPool<dim, spacedim> &
700 get_property_pool() const;
701
702 /**
703 * Find and update the cells containing each particle for all locally owned
704 * particles. If particles moved out of the local subdomain
705 * they will be sent to their new process and inserted there.
706 * After this function call every particle is either on its current
707 * process and in its current cell, or deleted (if it could not find
708 * its new process or cell).
709 *
710 * The user may attach a function to the signal
711 * Particles::ParticleHandler::Signals::particle_lost(). The signal is
712 * triggered whenever a particle is deleted, and the connected functions
713 * are called passing an iterator to the particle in question, and its last
714 * known cell association.
715 */
716 void
717 sort_particles_into_subdomains_and_cells();
718
719 /**
720 * Exchange all particles that live in cells that are ghost cells to
721 * other processes. Clears and re-populates the ghost_neighbors
722 * member variable.
723 */
724 void
725 exchange_ghost_particles(const bool enable_ghost_cache = false);
726
727 /**
728 * Update all particles that live in cells that are ghost cells to
729 * other processes. In this context, update means to update the
730 * location and the properties of the ghost particles assuming that
731 * the ghost particles have not changed cells. Consequently, this will
732 * not update the reference location of the particles.
733 */
734 void
735 update_ghost_particles();
736
737 /**
738 * This function prepares the particle handler for a coarsening and
739 * refinement cycle, by storing the necessary information to transfer
740 * particles to their new cells. The implementation depends on the
741 * triangulation type that is connected to the particle handler and differs
742 * between shared and distributed triangulations. This function should be
743 * used like the corresponding function with the same name in the
744 * SolutionTransfer() class.
745 */
746 void
747 prepare_for_coarsening_and_refinement();
748
749 /**
750 * This function unpacks the particle data after a coarsening and
751 * refinement cycle, by reading the necessary information to transfer
752 * particles to their new cells. This function should be
753 * used like the SolutionTransfer::interpolate() function after mesh
754 * refinement has finished. Note that this function requires a working
755 * mapping, i.e. if you use a mapping class that requires setup after
756 * a mesh refinement (e.g. MappingQCache(), or MappingEulerian()), the
757 * mapping has to be ready before you can call this function.
758 *
759 * @note It is important to note, that if you do not call this function
760 * after a refinement/coarsening operation (and a repartitioning operation
761 * in a distributed triangulation) and the particle handler contained
762 * particles before, the particle handler will not be usable any more. Not
763 * calling this function after refinement would be similar to trying to
764 * access a solution vector after mesh refinement without first using a
765 * SolutionTransfer class to transfer the vector to the new mesh.
766 */
767 void
768 unpack_after_coarsening_and_refinement();
769
770 /**
771 * This function prepares the particle handler for serialization. This needs
772 * to be done before calling Triangulation::save(). This function should be
773 * used like the corresponding function with the same name in the
774 * SolutionTransfer() class.
775 *
776 * @note It is important to note, that if you do not call this function
777 * before a serialization operation in a distributed triangulation, the
778 * particles will not be serialized, and therefore will disappear after
779 * deserialization.
780 */
781 void
782 prepare_for_serialization();
783
784 /**
785 * Execute the deserialization of the particle data. This needs to be
786 * done after calling Triangulation::load(). The data must have been stored
787 * before the serialization of the triangulation using the
788 * prepare_for_serialization() function. This function should be used like
789 * the corresponding function with the same name in the SolutionTransfer
790 * class.
791 */
792 void
793 deserialize();
794
795 /**
796 * Serialize the contents of this class using the [BOOST serialization
797 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
798 *
799 * This function is used in step-83.
800 */
801 template <class Archive>
802 void
803 serialize(Archive &ar, const unsigned int version);
804
805 /**
806 * A structure that has boost::signal objects for a number of actions that a
807 * particle handler can do to itself. How signals can be used in
808 * applications is explained in the "Getting notice when a triangulation
809 * changes" section in the Triangulation class with more information and
810 * examples. In short these signals allow the particle handler to notify
811 * applications about certain events inside the particle handler, e.g. when
812 * a particle is lost.
813 *
814 * For documentation on signals, see
815 * http://www.boost.org/doc/libs/release/libs/signals2 .
816 */
817 struct Signals
818 {
819 /**
820 * This signal is triggered whenever the
821 * ParticleHandler::sort_particles_into_subdomains_and_cells() function
822 * encounters a particle that can not be associated with a cell. This can
823 * happen if the particle leaves the domain of the triangulation, or if it
824 * leaves the locally known domain in a parallel triangulation (including
825 * the ghost cells for a parallel::distributed::triangulation).
826 *
827 * The connected function receives an iterator to the particle in
828 * question, and its last known cell association.
829 *
830 * This signal is used in step-19.
831 */
832 boost::signals2::signal<void(
833 const typename Particles::ParticleIterator<dim, spacedim> &particle,
834 const typename Triangulation<dim, spacedim>::active_cell_iterator
835 &cell)>
836 particle_lost;
837 };
838
839 /**
840 * Signals for the events that a particle handler can notify the
841 * calling application about.
842 */
843 mutable Signals signals;
844
845 private:
846 /**
847 * Insert a particle into the collection of particles from a raw
848 * data pointer. This function is used for shipping particles
849 * during serialization and refinement and not intended for use outside
850 * of this class. Return an iterator to the new position of the particle.
851 */
852 particle_iterator
853 insert_particle(
854 const void *&data,
855 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell);
856
857 /**
858 * Perform the local insertion operation into the particle container. This
859 * function is used in the higher-level functions inserting particles.
860 */
861 particle_iterator
862 insert_particle(
863 const typename PropertyPool<dim, spacedim>::Handle
864 tria_attached_data_index,
865 const typename Triangulation<dim, spacedim>::cell_iterator &cell);
866
867 /**
868 * Delete all entries in the particles container, and then set the three
869 * anchor entries used to distinguish between owned and ghost cells: We
870 * add one item to the front, one between and one as the last element in
871 * the particle container to be able to iterate across particles without
872 * `if` statements, solely relying on ParticleAccessor::operator== to
873 * terminate operations, and using the `cell_iterator` inside the particle
874 * container to check for valid states.
875 */
876 void
877 reset_particle_container(particle_container &particles);
878
879 /**
880 * Address of the triangulation to work on.
881 */
882 ObserverPointer<const Triangulation<dim, spacedim>,
883 ParticleHandler<dim, spacedim>>
884 triangulation;
885
886 /**
887 * Address of the mapping to work on.
888 */
889 ObserverPointer<const Mapping<dim, spacedim>,
890 ParticleHandler<dim, spacedim>>
891 mapping;
892
893 /**
894 * This object owns and organizes the memory for all particle
895 * properties. Since particles reference the property pool, the
896 * latter has to be destroyed *after* the particles are destroyed.
897 * This is achieved by making sure the `property_pool` member variable
898 * precedes the declaration of the `particles`
899 * member variable.
900 */
901 std::unique_ptr<PropertyPool<dim, spacedim>> property_pool;
902
903 /**
904 * Set of particles currently living in the locally owned or ghost cells.
905 */
906 particle_container particles;
907
908 /**
909 * Iterator to the end of the list elements of particle_container which
910 * belong to locally owned elements. Made const to avoid accidental
911 * modification.
912 */
913 const typename particle_container::iterator owned_particles_end;
914
915 /**
916 * List from the active cells on the present MPI process to positions in
917 * either `owned_particles` or `ghost_particles` for fast $\mathcal O(1)$
918 * access to the particles of a cell.
919 */
920 std::vector<typename particle_container::iterator> cells_to_particle_cache;
921
922 /**
923 * This variable stores how many particles are stored globally. It is
924 * calculated by update_cached_numbers().
925 */
926 types::particle_index global_number_of_particles;
927
928 /**
929 * This variable stores how many particles are locally owned. It is
930 * calculated by update_cached_numbers().
931 */
932 types::particle_index number_of_locally_owned_particles;
933
934 /**
935 * The maximum number of particles per cell in the global domain. This
936 * variable is important to store and load particle data during
937 * repartition and serialization of the solution. Note that the
938 * variable is only updated when it is needed, e.g. after particle
939 * movement, before/after mesh refinement, before creating a
940 * checkpoint and after resuming from a checkpoint.
941 */
942 unsigned int global_max_particles_per_cell;
943
944 /**
945 * This variable stores the next free particle index that is available
946 * globally in case new particles need to be generated.
947 */
948 types::particle_index next_free_particle_index;
949
950 /**
951 * A function that can be registered by calling
952 * register_additional_store_load_functions. It is called when serializing
953 * particle data. The function gets no arguments and is expected to
954 * return the size of the additional data that is serialized per
955 * particle. Note that this currently implies the data size has to be
956 * the same for every particle, but it does not have to be the same for
957 * every serialization process (e.g. a serialization during particle
958 * movement might include temporary data, while a serialization after
959 * movement was finished does not need to transfer this data).
960 */
961 std::function<std::size_t()> size_callback;
962
963 /**
964 * A function that can be registered by calling
965 * register_additional_store_load_functions. It is called once per
966 * particle when serializing particle data. Arguments to the function
967 * are a particle iterator that identifies the current particle and a void
968 * pointer that points to a data block of size size_callback() in which
969 * the function can store additional data. The function is expected to
970 * return a void pointer pointing to a position right after its data
971 * block.
972 */
973 std::function<void *(const particle_iterator &, void *)> store_callback;
974
975 /**
976 * A function that is called once per particle
977 * when deserializing particle data. Arguments to the function are a
978 * particle iterator that identifies the current particle and a void
979 * pointer that points to a data block of size size_callback() from
980 * which the function can load additional data. This block was filled
981 * by the store_callback function during serialization. This function
982 * is expected to return a void pointer pointing to a position right
983 * after its data block.
984 */
985 std::function<const void *(const particle_iterator &, const void *)>
986 load_callback;
987
988 /**
989 * This variable is set by the register_data_attach()
990 * function and used by the notify_ready_to_unpack() function
991 * to check where the particle data was registered in the corresponding
992 * triangulation object.
993 */
994 unsigned int tria_attached_data_index;
995
996 /**
997 * Tolerance to be used for GeometryInfo<dim>::is_inside_cell().
998 */
999 const double tolerance_inside_cell = 1e-12;
1000
1001 /**
1002 * The GridTools::Cache is used to store the information about the
1003 * vertex_to_cells set and the vertex_to_cell_centers vectors to prevent
1004 * recomputing them every time we sort_into_subdomain_and_cells().
1005 * This cache is automatically updated when the triangulation has
1006 * changed. This cache is stored within a unique pointer because the
1007 * particle handler has a constructor that enables it to be constructed
1008 * without a triangulation. The cache does not have such a constructor.
1009 */
1010 std::unique_ptr<GridTools::Cache<dim, spacedim>> triangulation_cache;
1011
1012 #ifdef DEAL_II_WITH_MPI
1013 /**
1014 * Transfer particles that have crossed subdomain boundaries to other
1015 * processors.
1016 * All received particles and their new cells will be appended to the
1017 * class variable `particles` at the right slot.
1018 *
1019 * @param [in] particles_to_send All particles that should be sent and
1020 * their new subdomain_ids are in this map.
1021 *
1022 * @param [in] new_cells_for_particles Optional vector of cell
1023 * iterators with the same structure as @p particles_to_send. If this
1024 * parameter is given it should contain the cell iterator for every
1025 * particle to be send in which the particle belongs. This parameter
1026 * is necessary if the cell information of the particle iterator is
1027 * outdated (e.g. after particle movement).
1028 *
1029 * @param [in] enable_cache Optional bool that enables updating
1030 * the ghost particles without rebuilding them from scratch by
1031 * building a cache of type GhostParticlePartitioner, which
1032 * stores the necessary information to update the ghost particles.
1033 * Once this cache is built, the ghost particles can be updated
1034 * by a call to send_recv_particles_properties_and_location().
1035 */
1036 void
1037 send_recv_particles(
1038 const std::map<types::subdomain_id, std::vector<particle_iterator>>
1039 &particles_to_send,
1040 const std::map<
1041 types::subdomain_id,
1042 std::vector<
1043 typename Triangulation<dim, spacedim>::active_cell_iterator>>
1044 &new_cells_for_particles = std::map<
1045 types::subdomain_id,
1046 std::vector<
1047 typename Triangulation<dim, spacedim>::active_cell_iterator>>(),
1048 const bool enable_cache = false);
1049
1050 /**
1051 * Transfer ghost particles' position and properties assuming that the
1052 * particles have not changed cells. This routine uses the
1053 * GhostParticlePartitioner as a caching structure to know which particles
1054 * are ghost to other processes, and where they need to be sent. It
1055 * inherently assumes that particles cannot have changed cell, and writes
1056 * the result back to the `particles` member variable.
1057 *
1058 * @param [in] particles_to_send All particles for which information
1059 * should be sent and their new subdomain_ids are in this map.
1060 */
1061 void
1062 send_recv_particles_properties_and_location(
1063 const std::map<types::subdomain_id, std::vector<particle_iterator>>
1064 &particles_to_send);
1065
1066 #endif
1067
1068 /**
1069 * Cache structure used to store the elements which are required to
1070 * exchange the particle information (location and properties) across
1071 * processors in order to update the ghost particles. This structure
1072 * is only used to update the ghost particles.
1073 */
1074 internal::GhostParticlePartitioner<dim, spacedim> ghost_particles_cache;
1075
1076 /**
1077 * Connect the particle handler to the relevant triangulation signals to
1078 * appropriately react to changes in the underlying triangulation.
1079 */
1080 void
1081 connect_to_triangulation_signals();
1082
1083 /**
1084 * A list of connections with which this object connects to the
1085 * triangulation to get information about when the triangulation changes.
1086 */
1087 std::vector<boost::signals2::connection> tria_listeners;
1088
1089 /**
1090 * Function that gets called by the triangulation signals if
1091 * the structure of the mesh has changed. This function is
1092 * responsible for resizing the particle container if no
1093 * particles are stored, i.e. if the usual call to
1094 * prepare_for_..., and transfer_particles_after_... functions
1095 * is not necessary.
1096 */
1097 void
1098 post_mesh_change_action();
1099
1100 /**
1101 * Function that should be called before every refinement
1102 * and when writing checkpoints. This function is used to
1103 * register pack_callback() with the triangulation.
1104 */
1105 void
1106 register_data_attach();
1107
1108 /**
1109 * Callback function that should be called after every refinement
1110 * and after resuming from a checkpoint. This function is used to
1111 * call the notify_ready_to_unpack() function of the triangulation
1112 * and hand over the unpack_callback() function, which will
1113 * unpack the particle data for each cell.
1114 */
1115 void
1116 notify_ready_to_unpack(const bool serialization);
1117
1118 /**
1119 * Called by listener functions from Triangulation for every cell
1120 * before a refinement step. All particles have to be attached to their
1121 * cell to be sent around to the new cell and owning process.
1122 */
1123 std::vector<char>
1124 pack_callback(
1125 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1126 const CellStatus status) const;
1127
1128 /**
1129 * Called by listener functions after a refinement step for each cell
1130 * to unpack the particle data and transfer it to the local container.
1131 */
1132 void
1133 unpack_callback(
1134 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
1135 const CellStatus status,
1136 const boost::iterator_range<std::vector<char>::const_iterator>
1137 &data_range);
1138
1139 /**
1140 * Internal function returning an iterator to the begin of the container
1141 * for owned particles.
1142 */
1143 typename particle_container::iterator
1144 particle_container_owned_begin() const;
1145
1146 /**
1147 * Internal function returning an iterator to the end of the container for
1148 * owned particles.
1149 */
1150 typename particle_container::iterator
1151 particle_container_owned_end() const;
1152
1153 /**
1154 * Internal function returning an iterator to the begin of the container
1155 * for ghost particles.
1156 */
1157 typename particle_container::iterator
1158 particle_container_ghost_begin() const;
1159
1160 /**
1161 * Internal function returning an iterator to the end of the container for
1162 * ghost particles.
1163 */
1164 typename particle_container::iterator
1165 particle_container_ghost_end() const;
1166 };
1167
1168
1169
1170 /* ---------------------- inline and template functions ------------------
1171 */
1172
1173 template <int dim, int spacedim>
1174 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1175 ParticleHandler<dim, spacedim>::begin() const
1176 {
1177 return (const_cast<ParticleHandler<dim, spacedim> *>(this))->begin();
1178 }
1179
1180
1181
1182 template <int dim, int spacedim>
1183 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1184 ParticleHandler<dim, spacedim>::begin()
1185 {
1186 return particle_iterator(particle_container_owned_begin(),
1187 *property_pool,
1188 0);
1189 }
1190
1191
1192
1193 template <int dim, int spacedim>
1194 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1195 ParticleHandler<dim, spacedim>::end() const
1196 {
1197 return (const_cast<ParticleHandler<dim, spacedim> *>(this))->end();
1198 }
1199
1200
1201
1202 template <int dim, int spacedim>
1203 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1204 ParticleHandler<dim, spacedim>::end()
1205 {
1206 return particle_iterator(particle_container_owned_end(), *property_pool, 0);
1207 }
1208
1209
1210
1211 template <int dim, int spacedim>
1212 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1213 ParticleHandler<dim, spacedim>::begin_ghost() const
1214 {
1215 return (const_cast<ParticleHandler<dim, spacedim> *>(this))->begin_ghost();
1216 }
1217
1218
1219
1220 template <int dim, int spacedim>
1221 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1222 ParticleHandler<dim, spacedim>::begin_ghost()
1223 {
1224 return particle_iterator(particle_container_ghost_begin(),
1225 *property_pool,
1226 0);
1227 }
1228
1229
1230
1231 template <int dim, int spacedim>
1232 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1233 ParticleHandler<dim, spacedim>::end_ghost() const
1234 {
1235 return (const_cast<ParticleHandler<dim, spacedim> *>(this))->end_ghost();
1236 }
1237
1238
1239
1240 template <int dim, int spacedim>
1241 inline typename ParticleHandler<dim, spacedim>::particle_iterator
1242 ParticleHandler<dim, spacedim>::end_ghost()
1243 {
1244 return particle_iterator(particle_container_ghost_end(), *property_pool, 0);
1245 }
1246
1247
1248
1249 template <int dim, int spacedim>
1250 inline typename ParticleHandler<dim, spacedim>::particle_container::iterator
1251 ParticleHandler<dim, spacedim>::particle_container_owned_begin() const
1252 {
1253 // We should always have at least the three anchor entries in the list of
1254 // particles
1255 Assert(!particles.empty(), ExcInternalError());
1256 typename particle_container::iterator begin =
1257 const_cast<particle_container &>(particles).begin();
1258 return ++begin;
1259 }
1260
1261
1262
1263 template <int dim, int spacedim>
1264 inline typename ParticleHandler<dim, spacedim>::particle_container::iterator
1265 ParticleHandler<dim, spacedim>::particle_container_owned_end() const
1266 {
1267 Assert(!particles.empty(), ExcInternalError());
1268 return owned_particles_end;
1269 }
1270
1271
1272
1273 template <int dim, int spacedim>
1274 inline typename ParticleHandler<dim, spacedim>::particle_container::iterator
1275 ParticleHandler<dim, spacedim>::particle_container_ghost_begin() const
1276 {
1277 Assert(!particles.empty(), ExcInternalError());
1278 typename particle_container::iterator begin = owned_particles_end;
1279 return ++begin;
1280 }
1281
1282
1283
1284 template <int dim, int spacedim>
1285 inline typename ParticleHandler<dim, spacedim>::particle_container::iterator
1286 ParticleHandler<dim, spacedim>::particle_container_ghost_end() const
1287 {
1288 Assert(!particles.empty(), ExcInternalError());
1289 typename particle_container::iterator end =
1290 const_cast<particle_container &>(particles).end();
1291 return --end;
1292 }
1293
1294
1295
1296 template <int dim, int spacedim>
1297 template <class Archive>
1298 inline void
1299 ParticleHandler<dim, spacedim>::serialize(Archive &ar, const unsigned int)
1300 {
1301 // Note that we do not serialize the particle data itself (i.e., the
1302 // 'particles' member variable). Instead we
1303 // use the serialization functionality of the triangulation class, because
1304 // this guarantees that data is immediately shipped to new processes if
1305 // the domain is distributed differently after resuming from a checkpoint.
1306 //
1307 // See step-83 for how to serialize ParticleHandler objects.
1308 ar &global_number_of_particles &global_max_particles_per_cell
1309 &next_free_particle_index;
1310 }
1311
1312
1313
1314 template <int dim, int spacedim>
1315 template <typename VectorType>
1316 inline std::enable_if_t<
1317 std::is_convertible_v<VectorType *, Function<spacedim> *> == false>
1318 ParticleHandler<dim, spacedim>::set_particle_positions(
1319 const VectorType &input_vector,
1320 const bool displace_particles)
1321 {
1322 AssertDimension(input_vector.size(),
1323 get_next_free_particle_index() * spacedim);
1324 for (auto &p : *this)
1325 {
1326 Point<spacedim> &position = p.get_location();
1327 const auto id = p.get_id();
1328
1329 if (displace_particles)
1330 for (unsigned int i = 0; i < spacedim; ++i)
1331 position[i] += input_vector[id * spacedim + i];
1332 else
1333 for (unsigned int i = 0; i < spacedim; ++i)
1334 position[i] = input_vector[id * spacedim + i];
1335 }
1336 sort_particles_into_subdomains_and_cells();
1337 }
1338
1339
1340
1341 template <int dim, int spacedim>
1342 template <typename VectorType>
1343 inline void
1344 ParticleHandler<dim, spacedim>::get_particle_positions(
1345 VectorType &output_vector,
1346 const bool add_to_output_vector)
1347 {
1348 AssertDimension(output_vector.size(),
1349 get_next_free_particle_index() * spacedim);
1350 for (const auto &p : *this)
1351 {
1352 auto point = p.get_location();
1353 const auto id = p.get_id();
1354 if (add_to_output_vector)
1355 for (unsigned int i = 0; i < spacedim; ++i)
1356 output_vector[id * spacedim + i] += point[i];
1357 else
1358 for (unsigned int i = 0; i < spacedim; ++i)
1359 output_vector[id * spacedim + i] = point[i];
1360 }
1361 if (add_to_output_vector)
1362 output_vector.compress(VectorOperation::add);
1363 else
1364 output_vector.compress(VectorOperation::insert);
1365 }
1366
1367 } // namespace Particles
1368
1369 DEAL_II_NAMESPACE_CLOSE
1370
1371 #endif