From: Wolfgang Bangerth Date: Tue, 7 Jul 2020 03:39:04 +0000 (-0600) Subject: Add warnings to functions that set particle properties. X-Git-Tag: v9.3.0-rc1~1333^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b2c3b7fc1524129e31c58aa5c033ec1a6dcf519a;p=dealii.git Add warnings to functions that set particle properties. --- 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);