| 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 |