Centralised tracking of mutable bunch-level and per-container status flags. More...

#include <BunchStateHandler.h>

Collaboration diagram for BunchStateHandler:

Classes
struct	ContainerState
	Per-container slot of mutable flags. One per registered ParticleContainer. Lifetime is tied to the owning container (see registerContainer() for details). More...

Public Member Functions
	BunchStateHandler ()=default

std::shared_ptr< ContainerState >	registerContainer ()
	Allocate a new per-container slot and return a strong reference to it. The handler itself retains only a `std::weak_ptr`, so the slot is destroyed automatically once the caller (typically a ParticleContainer) releases its shared_ptr.

bool	isFirstRepartition () const

bool &	isFirstRepartitionRef ()
	Non-const reference escape hatch used by LoadBalancer::repartition.

void	setFirstRepartition (bool v)

Private Attributes
std::vector< std::weak_ptr< ContainerState > >	registered_m

bool	firstRepartition_m = true

Detailed Description

Centralised tracking of mutable bunch-level and per-container status flags.

Single instance per PartBunch, shared with every component that needs access (ParticleContainer, DistributionMoments, ...).

Two classes of state live here:

Bunch-wide flags (firstRepartition, future emittingNow) apply to the bunch as a whole and are stored as plain members.
Per-container flags (momentsDirty, unitlessPositions) live in the nested ContainerState struct. Each ParticleContainer registers itself via registerContainer() at setBunchStateHandler time and receives a std::shared_ptr<ContainerState> slot. The container holds the only strong reference; the handler keeps a std::weak_ptr so the slot is released automatically when the container is destroyed (no unregister needed).
emittingNow (aka "isEmitting"): managed by the emitting distribution itself (e.g. FlatTop sets it when t > t0 and particles are being created).

Invariants

unitlessPositions: true while the container's positions are in the dimensionless form R' = R / (c * dt). Toggled only by ParticleContainer::switchToUnitlessPositions / switchOffUnitlessPositions. Does NOT mark the container's moments dirty (coordinate representation change only).
momentsDirty: set whenever a physics operation mutates this container's particle positions (R) or momenta (P) – push, kick, emission, particle deletion. Cleared by DistributionMoments::computeMoments once the moments cache is consistent with the particle state.
firstRepartition: true until the first ORB-style repartition has run for the bunch. Bunch-wide because the load balancer is shared.

MPI consistency

Every flag is conceptually consistent across MPI ranks. The OPALX option AGGRESSIVE_STATE_SYNC (see Options::aggressiveStateSync) forces every setter below to perform an ippl::Comm->allreduce with std::logical_or<bool> so ranks converge to the same (conservative) value even if a caller mutated the flag on only a subset of ranks. Default off: the allreduce on every mutation adds up, and correctly-written callers already set the same value on every rank.

Definition at line 56 of file BunchStateHandler.h.

Constructor & Destructor Documentation

◆ BunchStateHandler()

BunchStateHandler::BunchStateHandler ( )

default

Member Function Documentation

◆ isFirstRepartition()

bool BunchStateHandler::isFirstRepartition ( ) const

inline

Definition at line 92 of file BunchStateHandler.h.

References firstRepartition_m.

Referenced by TEST_F(), TEST_F(), and TEST_F().

◆ isFirstRepartitionRef()

bool & BunchStateHandler::isFirstRepartitionRef ( )

inline

Non-const reference escape hatch used by LoadBalancer::repartition.

Bypasses the aggressive-sync setter path. The load balancer is the single well-defined caller that flips this flag from true to false on all ranks after the first repartition.

Definition at line 100 of file BunchStateHandler.h.

References firstRepartition_m.

◆ registerContainer()

std::shared_ptr< BunchStateHandler::ContainerState > BunchStateHandler::registerContainer ( )

Allocate a new per-container slot and return a strong reference to it. The handler itself retains only a std::weak_ptr, so the slot is destroyed automatically once the caller (typically a ParticleContainer) releases its shared_ptr.

Definition at line 39 of file BunchStateHandler.cpp.

References registered_m.

Referenced by TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ setFirstRepartition()

void BunchStateHandler::setFirstRepartition ( bool v )

Definition at line 45 of file BunchStateHandler.cpp.

References Options::aggressiveStateSync, and firstRepartition_m.

Referenced by TEST_F(), and TEST_F().

Member Data Documentation

◆ firstRepartition_m

bool BunchStateHandler::firstRepartition_m = true

private

Definition at line 115 of file BunchStateHandler.h.

Referenced by isFirstRepartition(), isFirstRepartitionRef(), and setFirstRepartition().

◆ registered_m

std::vector<std::weak_ptr<ContainerState> > BunchStateHandler::registered_m