Peano

Searching...

No Matches

Abstract base class for all flavours of particle sets. More...

#include <ParticleSet.h>

Collaboration diagram for toolbox::particles::ParticleSet< T >:

[legend]

Public Types
typedef T	DoFType

typedef std::list< T * >	ParticleList

using	SieveParticles = SieveParticles<T>

Public Member Functions
std::string	toString (bool addBrackets=true) const

Static Public Member Functions
static void	clearReassignmentStatistics ()
	Clear stats of all counters that have to do with resorting.

static void	clearParticleStateStatistics ()
	Clear stats.

static void	reduceParticleStateStatistics ()
	Reduces and prints the global statistics.

static std::string	printParticleStateStatistics ()

static void	reduceReassignmentStatistics ()

static std::string	printReassignmentStatistics ()

static void	updateLiftDropStatistics (int numberOfLiftsInThisTree, int numberOfDropsInThisTree, int numberOfReassignmentsInThisTree, int numberOfLiftsIntoSieveSetInThisTree, int numberOfDropsFromSieveSetInThisTree, int numberOfDropsIntoHorizontalTreeDecomposition)

static void	updateNumberOfLocalAndExpiredParticles (int numberOfRemainingLocalParticles, int numberOfExpiredHaloParticles, int numberOfParticlesThatHaveLeftTheirDomain)

static int	getNumberOfDropsIntoHorizontalTreeDecomposition ()
	Return number of drops into cuts recorded.

static bool	registeredAnyResorting ()
	Returns true if there have been any lifts, drops, reassignments, ...

static void	initDatatype ()

static void	shutdownDatatype ()

static void	finishedTraversal (const tarch::la::Vector< Dimensions, double > domainOffset, const tarch::la::Vector< Dimensions, double > domainSize, const std::bitset< Dimensions > periodicBC)
	Finish traversal.

static SieveParticles	cloneParticlesToBeSieved ()

static ParticleList	getParticlesToBeSievedIntoVertex (const peano4::datamanagement::VertexMarker &marker)
	Make routine from SieveParticles public.

static bool	hasParticlesToBeSievedIntoVertices ()
	Make routine from SieveParticles public.

static int	getNumberOfParticlesThatHaveBeSievedIntoVertices ()
	Return total number of particles to be sieved.

static int	getNumberOfRemainingLocalParticles ()
	Return global sum of the particles that did remain within their partition at a time.

Static Protected Attributes
static tarch::multicore::BooleanSemaphore	_statisticsSemaphore

static int	_numberOfLifts
	Sorting statistics.

static int	_numberOfDrops
	Sorting statistics.

static int	_numberOfReassignments
	Sorting statistics.

static int	_numberOfLiftsIntoSieveSet
	Sorting statistics.

static int	_numberOfDropsFromSieveSet

static int	_numberOfDropsIntoHorizontalTreeDecomposition

static int	_numberOfRemainingLocalParticles
	Set by parallel state analysis.

static int	_numberOfExpiredHaloParticles
	Set by parallel state analysis.

static int	_numberOfParticlesThatHaveLeftTheirDomain
	Set by parallel state analysis.

static int	_numberOfDroppedIncomingVirtualParticles
	Number of incoming halo particles which are not worked in.

static int	_numberOfRedundantlySharedLocalParticles
	Particles which are local here and local somewhere else.

static int	_numberOfReplacedVirtualParticlesAlongBoundary
	Replace virtual particles are those where we have a copy and receive an update.

static int	_numberOfAddedVirtualParticlesAlongBoundary
	Newly "discovered" virtual particles.

static int	_numberOfAddedLocalParticlesAlongBoundary

static SieveParticles	_sieveParticles
	Map of persistent particles that have to be sieved.

Static Private Attributes
static tarch::logging::Log	_log

Detailed Description

template<typename T>
class toolbox::particles::ParticleSet< T >

Abstract base class for all flavours of particle sets.

Particle sets differ in the way they actually manage the particles. However, they all share common stats, operations, ... This is covered by this class. All particle types (species) are also tied to a sieve set, which is also class attribute of this abstract particle supertype.

Rationale: static attributes vs static aggregation

There's a problem here however: Most of these fields are static fields. If we have them static, they are tied to the base object, not the the particular particle type. However, the fact that we work with templates rides to our rescue. We can assume that this base class is instantiated per particle type. Therefore, all of its static fields are unique again. Along these discussions, this base class is more of an aspect rather than a real base class. The number of real functions and attributes is negligible.

An alternative implementation would make this a real class and let the actual particles sets holds a static attribute of this class. I think that would be a valid implementation, too.

Eventually, I ended up with a compromise, where the sieving is delegated into a class of its own called toolbox::particles::SieveParticles. The rationale here is simple:

All the stuff that has to do with the management of the sieved particles is outsourced into a separate class. All the stats, initialisation and whatever generic stuff is out there is collocated in this very routine.

Sieve semantics

Whenever a particle has to be added to the sieve set, the underlying action set will inform the particle set or vertex, respectively, to move the particle into the sieve set. This step has to be protected by a semaphore, as relaised in SieveParticles. After the mesh sweep, all the particles are exchanged between ranks, and then we have to sort them into the mesh again.

There are two different modes how to use this sieve set: We can either work against a global sieve set, or we can make each thread first create a copy of all the particles to be sieved and then hand out thread-local copies. Which variant to pick is a choice to be made by the sorting action set.

Definition at line 66 of file ParticleSet.h.

Member Typedef Documentation

◆ DoFType

template<typename T >

typedef T toolbox::particles::ParticleSet< T >::DoFType

Definition at line 68 of file ParticleSet.h.

◆ ParticleList

template<typename T >

typedef std::list<T*> toolbox::particles::ParticleSet< T >::ParticleList

Definition at line 69 of file ParticleSet.h.

◆ SieveParticles

template<typename T >

using toolbox::particles::ParticleSet< T >::SieveParticles = SieveParticles<T>

Definition at line 71 of file ParticleSet.h.

Member Function Documentation

◆ clearParticleStateStatistics()

template<typename T >

void toolbox::particles::ParticleSet< T >::clearParticleStateStatistics ( )

static

Clear stats.

Has to be called per rank prior to any mesh traversal assembling stats. I call this routine in the prepare traversal event, i.e. in peano4.toolbox.particles.UpdateParallelState.get_body_of_prepareTraversal(). This means I really get only a snapshot from one grid sweep.

Definition at line 96 of file ParticleSet.cpph.

◆ clearReassignmentStatistics()

template<typename T >

void toolbox::particles::ParticleSet< T >::clearReassignmentStatistics ( )

static

Clear stats of all counters that have to do with resorting.

Has to be called per rank prior to any collection of stats. I used to call this routine in the prepare traversal event, i.e. in peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.get_body_of_prepareTraversal(). However, this is not clever, as the reassignment usually spans multiple grid sweeps. If we clear the stats prior to each of these sweeps, we will only get a state snapshot from what happened in the last sweep.

Therefore, I now typically call this clear routine directly after I've written stats to the terminal. This differs to how I treat clearParticleStateStatistics().

Definition at line 86 of file ParticleSet.cpph.

◆ cloneParticlesToBeSieved()

template<typename T >

toolbox::particles::ParticleSet< T >::SieveParticles toolbox::particles::ParticleSet< T >::cloneParticlesToBeSieved ( )

static

Returns: A copy of all the particles that have to be sieved.

Definition at line 300 of file ParticleSet.cpph.

◆ finishedTraversal()

template<typename T >

void toolbox::particles::ParticleSet< T >::finishedTraversal	(	const tarch::la::Vector< Dimensions, double >	domainOffset,
		const tarch::la::Vector< Dimensions, double >	domainSize,
		const std::bitset< Dimensions >	periodicBC )

static

Finish traversal.

Invokes toolbox::particles::ParticleSet<T>::finishedTraversal(). This routine should be called by prepareTraversal() on each and every rank after particles have been started to be resorted.

Definition at line 290 of file ParticleSet.cpph.

References periodicBC.

◆ getNumberOfDropsIntoHorizontalTreeDecomposition()

template<typename T >

int toolbox::particles::ParticleSet< T >::getNumberOfDropsIntoHorizontalTreeDecomposition ( )

static

Return number of drops into cuts recorded.

This counter is typically updated by the action sets which update the particle-mesh association. The field should guide the simulation main whether to rerun this dropping action set again or continue with next step in simulation pipeline.

Definition at line 259 of file ParticleSet.cpph.

◆ getNumberOfParticlesThatHaveBeSievedIntoVertices()

template<typename T >

int toolbox::particles::ParticleSet< T >::getNumberOfParticlesThatHaveBeSievedIntoVertices ( )

static

Return total number of particles to be sieved.

Delegates to SieveParticles::getNumberOfParticlesThatHaveBeSievedIntoVertices()

Definition at line 326 of file ParticleSet.cpph.

◆ getNumberOfRemainingLocalParticles()

template<typename T >

int toolbox::particles::ParticleSet< T >::getNumberOfRemainingLocalParticles ( )

static

Return global sum of the particles that did remain within their partition at a time.

Should only be called on global master after the reduction.

Definition at line 352 of file ParticleSet.cpph.

◆ getParticlesToBeSievedIntoVertex()

template<typename T >

toolbox::particles::ParticleSet< T >::ParticleList toolbox::particles::ParticleSet< T >::getParticlesToBeSievedIntoVertex ( const peano4::datamanagement::VertexMarker & marker )

static

Make routine from SieveParticles public.

Delegate through. This way, we don't have to expose the actual sieve object. Usually combined with hasParticlesToBeSievedIntoVertices() as guard, which makes the querying faster.

This operation always removes particles from the sieve set, and it sort exclusively local particles into the domain. We use it within the lift-drop sorting approach, where it is used by the dummy mesh sweeps following each sweep that moves around particles. Details on this scheme are provided in peano4.toolbox.particles.api.UpdateParticleGridAssociation_LiftDrop.

All action sets in this scheme share one common sieve set. Therefore, we do not run risk that one tree grabs a particle, sorts it into its mesh, labels it as outside and then this particle disappears. This is avoided, as we only sieve in particles if they become local.

When we take a particle that's local, we have to remove it from the sieve set. This is triggered by a hard-coded boolean that we pass on. If we don't remove it, we can run into situations where a particle sits right in-between two vertices and is hence sieved in twice. It appears two times.

Consult the Sorting: Preserving the mesh-particle data consistency

See also: SieveParticles::getParticlesToBeSievedIntoVertex()

Definition at line 306 of file ParticleSet.cpph.

◆ hasParticlesToBeSievedIntoVertices()

template<typename T >

bool toolbox::particles::ParticleSet< T >::hasParticlesToBeSievedIntoVertices ( )

static

Make routine from SieveParticles public.

Delegate through. This way, we don't have to expose the actual sieve object. This predicate is usually always used as guard before actually invoking getParticlesToBeSievedIntoVertex().

Definition at line 320 of file ParticleSet.cpph.

◆ initDatatype()

template<typename T >

void toolbox::particles::ParticleSet< T >::initDatatype ( )

static

Definition at line 277 of file ParticleSet.cpph.

◆ printParticleStateStatistics()

template<typename T >

std::string toolbox::particles::ParticleSet< T >::printParticleStateStatistics ( )

static

Definition at line 112 of file ParticleSet.cpph.

◆ printReassignmentStatistics()

template<typename T >

std::string toolbox::particles::ParticleSet< T >::printReassignmentStatistics ( )

static

Definition at line 178 of file ParticleSet.cpph.

◆ reduceParticleStateStatistics()

template<typename T >

void toolbox::particles::ParticleSet< T >::reduceParticleStateStatistics ( )

static

Reduces and prints the global statistics.

Definition at line 128 of file ParticleSet.cpph.

References tarch::mpi::Rank::getGlobalMasterRank(), tarch::mpi::Rank::getInstance(), tarch::services::ServiceRepository::getInstance(), tarch::services::ServiceRepository::receiveDanglingMessages(), and tarch::mpi::Rank::reduce().

Here is the call graph for this function:

◆ reduceReassignmentStatistics()

template<typename T >

void toolbox::particles::ParticleSet< T >::reduceReassignmentStatistics ( )

static

Definition at line 191 of file ParticleSet.cpph.

Here is the call graph for this function:

◆ registeredAnyResorting()

template<typename T >

bool toolbox::particles::ParticleSet< T >::registeredAnyResorting ( )

static

Returns true if there have been any lifts, drops, reassignments, ...

Definition at line 265 of file ParticleSet.cpph.

◆ shutdownDatatype()

template<typename T >

void toolbox::particles::ParticleSet< T >::shutdownDatatype ( )

static

Definition at line 283 of file ParticleSet.cpph.

◆ toString()

template<typename T >

std::string toolbox::particles::ParticleSet< T >::toString ( bool addBrackets = true ) const

Definition at line 332 of file ParticleSet.cpph.

◆ updateLiftDropStatistics()

template<typename T >

void toolbox::particles::ParticleSet< T >::updateLiftDropStatistics	(	int	numberOfLiftsInThisTree,
		int	numberOfDropsInThisTree,
		int	numberOfReassignmentsInThisTree,
		int	numberOfLiftsIntoSieveSetInThisTree,
		int	numberOfDropsFromSieveSetInThisTree,
		int	numberOfDropsIntoHorizontalTreeDecomposition )

static

Definition at line 227 of file ParticleSet.cpph.

◆ updateNumberOfLocalAndExpiredParticles()

template<typename T >

void toolbox::particles::ParticleSet< T >::updateNumberOfLocalAndExpiredParticles	(	int	numberOfRemainingLocalParticles,
		int	numberOfExpiredHaloParticles,
		int	numberOfParticlesThatHaveLeftTheirDomain )

static

Definition at line 246 of file ParticleSet.cpph.

Field Documentation

◆ _log

template<typename T >

tarch::logging::Log toolbox::particles::ParticleSet< T >::_log

staticprivate

Definition at line 227 of file ParticleSet.h.

◆ _numberOfAddedLocalParticlesAlongBoundary

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfAddedLocalParticlesAlongBoundary

staticprotected

Definition at line 353 of file ParticleSet.h.

◆ _numberOfAddedVirtualParticlesAlongBoundary

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfAddedVirtualParticlesAlongBoundary

staticprotected

Newly "discovered" virtual particles.

If a particle is far away from "our" boundary and then approaches this boundary on the neighbouring rank, it will, at one point, become visible here and we add it to our set of virtual particles.

Updated by boundary merge operations.

Definition at line 352 of file ParticleSet.h.

◆ _numberOfDroppedIncomingVirtualParticles

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfDroppedIncomingVirtualParticles

staticprotected

Number of incoming halo particles which are not worked in.

Dropped incoming virtual particles "happen" when a neighbour sends in a particle which is already virtual on the neighbour. In this case, the neighbour hasn't updated this particle at all (has no ownership). Therefore, we can just ignore it.

Updated by boundary merge operations.

Definition at line 321 of file ParticleSet.h.

◆ _numberOfDrops

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfDrops

staticprotected

Sorting statistics.

Used by sorting algorithm of choice. The attribute is updated through updateLiftDropStatistics() by each and every tree traversal. The five fields should be cleared through a call of clearReassignmentStatistics() at the begin of a time step, i.e. the first grid sweep starting a time step.

See class documentation of toolbox::particles::ParticleSet for an overview of the statistics tracked.

Definition at line 258 of file ParticleSet.h.

◆ _numberOfDropsFromSieveSet

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfDropsFromSieveSet

staticprotected

Definition at line 287 of file ParticleSet.h.

◆ _numberOfDropsIntoHorizontalTreeDecomposition

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfDropsIntoHorizontalTreeDecomposition

staticprotected

Definition at line 288 of file ParticleSet.h.

◆ _numberOfExpiredHaloParticles

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfExpiredHaloParticles

staticprotected

Set by parallel state analysis.

See documentation of action set peano4.toolbox.particles.api.UpdateParallelState.

Definition at line 302 of file ParticleSet.h.

◆ _numberOfLifts

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfLifts

staticprotected

Sorting statistics.

See class documentation of toolbox::particles::ParticleSet for an overview of the statistics tracked.

Definition at line 244 of file ParticleSet.h.

◆ _numberOfLiftsIntoSieveSet

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfLiftsIntoSieveSet

staticprotected

Sorting statistics.

See class documentation of toolbox::particles::ParticleSet for an overview of the statistics tracked.

Definition at line 286 of file ParticleSet.h.

◆ _numberOfParticlesThatHaveLeftTheirDomain

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfParticlesThatHaveLeftTheirDomain

staticprotected

Set by parallel state analysis.

See documentation of action set peano4.toolbox.particles.api.UpdateParallelState.

Definition at line 309 of file ParticleSet.h.

◆ _numberOfReassignments

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfReassignments

staticprotected

Sorting statistics.

See class documentation of toolbox::particles::ParticleSet for an overview of the statistics tracked.

Definition at line 272 of file ParticleSet.h.

◆ _numberOfRedundantlySharedLocalParticles

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfRedundantlySharedLocalParticles

staticprotected

Particles which are local here and local somewhere else.

This happens if a particle resides almost exactly on the face between two ranks and we therefore decide that both call it a local particle.

Updated by boundary merge operations.

Definition at line 331 of file ParticleSet.h.

◆ _numberOfRemainingLocalParticles

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfRemainingLocalParticles

staticprotected

Set by parallel state analysis.

See documentation of action set peano4.toolbox.particles.api.UpdateParallelState.

Definition at line 295 of file ParticleSet.h.

◆ _numberOfReplacedVirtualParticlesAlongBoundary

template<typename T >

int toolbox::particles::ParticleSet< T >::_numberOfReplacedVirtualParticlesAlongBoundary

staticprotected

Replace virtual particles are those where we have a copy and receive an update.

Virtual particles are owned by someone else. So whenever this owner sends in an update, we throw away our local copy and use this updated data.

Updated by boundary merge operations.

Definition at line 341 of file ParticleSet.h.

◆ _sieveParticles

template<typename T >

toolbox::particles::SieveParticles< T > toolbox::particles::ParticleSet< T >::_sieveParticles

staticprotected

Map of persistent particles that have to be sieved.

Every particle set is tied to one global sieve set realised through this attribute. Sieving is briefly also mentioned on Sorting: Preserving the mesh-particle data consistency. Access to this set is provided through two routines:

getParticlesToBeSievedIntoVertex() pipes your request directly through to the set's getParticlesToBeSievedIntoVertex(), i.e. it grants you access to the global sieve set.
Alternatively, you can clone the whole sieve set for your algorithm via cloneParticlesToBeSieved() and then sieve from thereon.

Different particle sorting strategies these different options the way they see fit.

Definition at line 372 of file ParticleSet.h.

◆ _statisticsSemaphore

template<typename T >

tarch::multicore::BooleanSemaphore toolbox::particles::ParticleSet< T >::_statisticsSemaphore

staticprotected

Definition at line 230 of file ParticleSet.h.

The documentation for this class was generated from the following files:

src/toolbox/particles/ParticleSet.h
src/toolbox/particles/ParticleSet.cpph

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Attributes

Static Private Attributes

Detailed Description

Rationale: static attributes vs static aggregation

Sieve semantics

Member Typedef Documentation

◆ DoFType

◆ ParticleList

◆ SieveParticles

Member Function Documentation

◆ clearParticleStateStatistics()

◆ clearReassignmentStatistics()

◆ cloneParticlesToBeSieved()

◆ finishedTraversal()

◆ getNumberOfDropsIntoHorizontalTreeDecomposition()

◆ getNumberOfParticlesThatHaveBeSievedIntoVertices()

◆ getNumberOfRemainingLocalParticles()

◆ getParticlesToBeSievedIntoVertex()

◆ hasParticlesToBeSievedIntoVertices()

◆ initDatatype()

◆ printParticleStateStatistics()

◆ printReassignmentStatistics()

◆ reduceParticleStateStatistics()

◆ reduceReassignmentStatistics()

◆ registeredAnyResorting()

◆ shutdownDatatype()

◆ toString()

◆ updateLiftDropStatistics()

◆ updateNumberOfLocalAndExpiredParticles()

Field Documentation

◆ _log

◆ _numberOfAddedLocalParticlesAlongBoundary

◆ _numberOfAddedVirtualParticlesAlongBoundary

◆ _numberOfDroppedIncomingVirtualParticles

◆ _numberOfDrops

◆ _numberOfDropsFromSieveSet

◆ _numberOfDropsIntoHorizontalTreeDecomposition

◆ _numberOfExpiredHaloParticles

◆ _numberOfLifts

◆ _numberOfLiftsIntoSieveSet

◆ _numberOfParticlesThatHaveLeftTheirDomain

◆ _numberOfReassignments

◆ _numberOfRedundantlySharedLocalParticles

◆ _numberOfRemainingLocalParticles

◆ _numberOfReplacedVirtualParticlesAlongBoundary

◆ _sieveParticles

◆ _statisticsSemaphore