From b2c3b7fc1524129e31c58aa5c033ec1a6dcf519a Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 6 Jul 2020 21:39:04 -0600 Subject: [PATCH] Add warnings to functions that set particle properties. --- include/deal.II/particles/particle.h | 44 +++++++++++++++++++ include/deal.II/particles/particle_accessor.h | 44 +++++++++++++++++++ 2 files changed, 88 insertions(+) diff --git a/include/deal.II/particles/particle.h b/include/deal.II/particles/particle.h index 7e7e0848eb..6f42ce801b 100644 --- a/include/deal.II/particles/particle.h +++ b/include/deal.II/particles/particle.h @@ -240,6 +240,17 @@ namespace Particles * whether this is a valid location in the simulation domain. * * @param [in] new_location The new location for this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_location(const Point &new_location); @@ -257,6 +268,17 @@ namespace Particles * * @param [in] new_reference_location The new reference location for * this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_reference_location(const Point &new_reference_location); @@ -291,6 +313,17 @@ namespace Particles * since this would be a very expensive operation.) * * @param[in] new_id The new ID number for this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_id(const types::particle_index &new_id); @@ -317,6 +350,17 @@ namespace Particles * * @param [in] new_properties An ArrayView containing the * new properties for this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_properties(const ArrayView &new_properties); diff --git a/include/deal.II/particles/particle_accessor.h b/include/deal.II/particles/particle_accessor.h index 50a38480fc..1de0522555 100644 --- a/include/deal.II/particles/particle_accessor.h +++ b/include/deal.II/particles/particle_accessor.h @@ -64,6 +64,17 @@ namespace Particles * whether this is a valid location in the simulation domain. * * @param [in] new_location The new location for this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_location(const Point &new_location); @@ -81,6 +92,17 @@ namespace Particles * * @param [in] new_reference_location The new reference location for * this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_reference_location(const Point &new_reference_location); @@ -119,6 +141,17 @@ namespace Particles * * @param [in] new_properties A vector containing the * new properties for this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_properties(const std::vector &new_properties); @@ -128,6 +161,17 @@ namespace Particles * * @param [in] new_properties An ArrayView pointing to memory locations * containing the new properties for this particle. + * + * @note In parallel programs, the ParticleHandler class stores particles + * on both the locally owned cells, as well as on ghost cells. The + * particles on the latter are *copies* of particles owned on other + * processors, and should therefore be treated in the same way as + * ghost entries in @ref GlossGhostedVector "vectors with ghost elements" + * or @ref GlossGhostCells "ghost cells": In both cases, one should + * treat the ghost elements or cells as `const` objects that shouldn't + * be modified even if the objects allow for calls that modify + * properties. Rather, properties should only be modified on processors + * that actually *own* the particle. */ void set_properties(const ArrayView &new_properties); -- 2.39.5