From: Martin Kronbichler <kronbichler@lnm.mw.tum.de>
Date: Tue, 6 Jul 2021 07:16:41 +0000 (+0200)
Subject: Make the descriptions clearer
X-Git-Tag: v9.4.0-rc1~1159^2~1
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1ea7883d2f6bd42792a9a95fc142a3c812b96215;p=dealii.git

Make the descriptions clearer
---

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;