From 1ea7883d2f6bd42792a9a95fc142a3c812b96215 Mon Sep 17 00:00:00 2001 From: Martin Kronbichler Date: Tue, 6 Jul 2021 09:16:41 +0200 Subject: [PATCH] Make the descriptions clearer --- include/deal.II/particles/particle_accessor.h | 13 +++++++++---- include/deal.II/particles/particle_handler.h | 17 +++++++++++------ 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/include/deal.II/particles/particle_accessor.h b/include/deal.II/particles/particle_accessor.h index 70103e3754..48f3d33931 100644 --- a/include/deal.II/particles/particle_accessor.h +++ b/include/deal.II/particles/particle_accessor.h @@ -135,13 +135,18 @@ namespace Particles * enables the direct array access (similar to * LinearAlgebra::distributed::Vector::local_element()) to quantities used * for local computations. Use - * ParticleHandler::get_max_local_particle_index() to query the largest - * index for suitable array sizes. + * ParticleHandler::get_max_local_particle_index() to query suitable array + * sizes. * * @note The number returned by this function is not stable between calls * of ParticleHandler::sort_particles_into_subdomains_and_cells() and - * therefore it cannot be used to track quantities across those calls. Use - * particle properties for storing persistent information. + * therefore it cannot be used to track quantities across those + * calls. Furthermore, the numbers returned by this function are typically + * not refreshed in case individual particles are removed from the + * underlying ParticleHandler object, which means that the returned + * indices of all particles on an MPI process typically do not form a + * contiguous interval of numbers. Use particle properties for storing + * persistent information and checkpointing the actual data. */ types::particle_index get_local_index() const; diff --git a/include/deal.II/particles/particle_handler.h b/include/deal.II/particles/particle_handler.h index 2fe3ec54a3..8f19a6fbc1 100644 --- a/include/deal.II/particles/particle_handler.h +++ b/include/deal.II/particles/particle_handler.h @@ -661,12 +661,17 @@ namespace Particles n_properties_per_particle() const; /** - * Return the maximal local index (in MPI-local index space) returned by - * ParticleAccessor::get_local_index(). More precisely, the returned value - * is one larger than the largest index that will be returned, which makes - * this value useful for resizing vectors. This number can be larger than - * locally_owned_particle_ids().n_elements(), because local indices can - * contain gaps in the range 0 to get_max_local_particle_index(). + * Return one past the largest local index (in MPI-local index space) + * returned by ParticleAccessor::get_local_index(). This number can be + * larger than locally_owned_particle_ids().n_elements(), because local + * indices are not necessarily forming a contiguous range and can contain + * gaps in the range 0 to get_max_local_particle_index(). As a + * consequence, the number is not updated upon calls to remove_particle() + * or similar functions, and refreshed only as new particles get added or + * in sort_particles_into_subdomains_and_cells(). + * + * This function is appropriate for resizing vectors working with + * ParticleAccessor::get_local_index(). */ types::particle_index get_max_local_particle_index() const; -- 2.39.5