A class that bins particles in energy bins and allows for adaptive runtime rebinning. More...

#include <AdaptBins.h>

Inheritance diagram for ParticleBinning::AdaptBins< BunchType, BinningSelector >:

Collaboration diagram for ParticleBinning::AdaptBins< BunchType, BinningSelector >:

Public Types
using	value_type = typename BinningSelector::value_type

using	particle_position_type = typename BunchType::particle_position_type

using	position_view_type = typename particle_position_type::view_type

using	size_type = typename BunchType::size_type

using	bin_index_type = typename BunchType::bin_index_type

using	bin_type = typename ippl::ParticleAttrib< bin_index_type >

using	bin_view_type = typename bin_type::view_type

using	hash_type = ippl::detail::hash_type< Kokkos::DefaultExecutionSpace::memory_space >

using	d_histo_type = Histogram< size_type, bin_index_type, value_type, true >

using	dview_type = typename d_histo_type::dview_type

using	hview_type = typename d_histo_type::hview_type

using	dwidth_view_type = typename d_histo_type::dwidth_view_type

using	hindex_transform_type = typename d_histo_type::hindex_transform_type

using	dindex_transform_type = typename d_histo_type::dindex_transform_type

using	h_histo_type_g = Histogram< size_type, bin_index_type, value_type, false, Kokkos::HostSpace >

using	hview_type_g = typename h_histo_type_g::hview_type

using	hwidth_view_type_g = typename h_histo_type_g::hwidth_view_type

using	hindex_transform_type_g = typename h_histo_type_g::hindex_transform_type

Public Member Functions
	AdaptBins (BunchType &bunch, BinningSelector var_selector, bin_index_type maxBins, value_type binningAlpha, value_type binningBeta, value_type desiredWidth, const std::string &binningCmdName)
	Constructs an AdaptBins object with a specified maximum number of bins and a selector.

void	initTimers ()
	Initializes timers for various operations in the binning process.

bin_view_type	getBinView ()
	Returns a view to the particle bin array.

bin_index_type	getCurrentBinCount () const override
	Returns the current number of bins.

const std::string &	getBinningCmdName () const override
	Returns the logical name of the active OPAL `BinningCmd` definition.

bin_index_type	getMaxBinCount () const override
	Gets the maximum number of bins. Will be used for the fine uniform histogram before merging.

value_type	getBinWidth () const override
	Returns the average binwidth.

value_type	getXMin () const override
	Returns the current lower bound of the binning coordinate (xMin).

void	setCurrentBinCount (bin_index_type nBins)
	Sets the current number of bins and adjusts the bin width.

hash_type	getHashArray () override
	Returns the index map that sorts the particle container by bin number.

void	initLimits () override
	Initializes the limits for binning based on the particle data.

void	instantiateHistogram (bool setToZero=false) override
	Initializes the histogram view for binning and optionally sets it to zero.

void	assignBinsToParticles () override
	Assigns each particle in the bunch to a bin based on its position.

void	initLocalHisto (HistoReductionMode modePreference=HistoReductionMode::Standard) override
	Initializes a local histogram for particle binning.

void	executeInitLocalHistoReductionTeamFor () override
	Initializes and performs a team-based histogram reduction for particle bins.

template<typename ReducerType >
void	executeInitLocalHistoReduction (ReducerType &to_reduce)
	Executes a parallel reduction to initialize the local histogram for particle bins.

void	initGlobalHistogram () override
	Retrieves the global histogram across all processes.

void	doFullRebin (bin_index_type nBins, bool recalculateLimits=true, HistoReductionMode modePreference=HistoReductionMode::Standard) override
	Performs a full rebinning operation on the bunch.

void	initHistogram (HistoReductionMode modePreference=HistoReductionMode::Standard) override
	Initializes the local/global histogram based on the Bin attribute.

size_type	getNPartInBin (bin_index_type binIndex, bool global=false) override
	Retrieves the number of particles in a specified bin.

void	sortContainerByBin () override
	Sorts the container of particles by their bin indices.

Kokkos::RangePolicy	getBinIterationPolicy (const bin_index_type &binIndex) override
	Returns the bin iteration policy for a given bin index.

void	genAdaptiveHistogram () override
	Generates an adaptive histogram based on a fine global histogram.

value_type	getBinConfigHost (std::vector< size_type > &binCounts, std::vector< value_type > &binWidths) const override
	Extracts the global bin configuration (counts and widths) on the host.

void	print () override
	Prints the current global histogram to the Inform output stream.

void	debug () override
	Outputs debug information related to Kokkos and MPI configurations.

virtual value_type	getBinConfigHost (std::vector< size_type > &binCounts, std::vector< value_type > &binWidths) const =0

Static Public Member Functions
static KOKKOS_INLINE_FUNCTION bin_index_type	getBin (value_type x, value_type xMin, value_type xMax, value_type binWidthInv, bin_index_type numBins)
	Calculates the bin index for a given position value in a uniform histogram.

Private Attributes
BunchType &	bunch_m
	Borrowed particle container.

BinningSelector	var_selector_m
	Variable selector for binning.

const bin_index_type	maxBins_m
	Maximum number of bins.

bin_index_type	currentBins_m
	Current number of bins in use.

std::string	binningCmdName_m
	Name of the active OPAL `BinningCmd` definition.

value_type	xMin_m
	Minimum value of bin attribute.

value_type	xMax_m
	Maximum value of bin attribute.

value_type	binWidth_m
	Width of each bin (assumes a uniform histogram).

value_type	binningAlpha_m
	Alpha parameter for binning cost function.

value_type	binningBeta_m
	Beta parameter for binning cost function.

value_type	desiredWidth_m
	Desired bin width for binning cost function.

d_histo_type	localBinHisto_m
	Local histogram view for bin counts.

h_histo_type_g	globalBinHisto_m
	Global histogram view (over ranks reduced local histograms).

hash_type	sortedIndexArr_m
	Particle index map that sorts the bunch by bin index.

IpplTimings::TimerRef	bInitLimitsT

IpplTimings::TimerRef	bAllReduceLimitsT

IpplTimings::TimerRef	bAllReduceGlobalHistoT

IpplTimings::TimerRef	bAssignUniformBinsT

IpplTimings::TimerRef	bExecuteHistoReductionT

IpplTimings::TimerRef	bSortContainerByBinT

IpplTimings::TimerRef	bVerifySortingT

Detailed Description

template<typename BunchType, typename BinningSelector>
class ParticleBinning::AdaptBins< BunchType, BinningSelector >

A class that bins particles in energy bins and allows for adaptive runtime rebinning.

This class provides functionality to group particles into energy bins, initialize and reinitialize bin structures, and update bin contents using data structures from IPPL and Kokkos. It is optimized for usage on CPU and GPU. It is explained in detail in Alexander Liemen's master thesis and was developed for OPAL-X to improve the performance when solving the electric field in a relativistic particle bunch.

Template Parameters

BunchType	The type of particle bunch (container) used in the binning process.
BinningSelector	A function or functor that selects the variable for binning (based on attributes).

Definition at line 79 of file AdaptBins.h.

Member Typedef Documentation

◆ bin_index_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::bin_index_type = typename BunchType::bin_index_type

Definition at line 86 of file AdaptBins.h.

◆ bin_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::bin_type = typename ippl::ParticleAttrib<bin_index_type>

Definition at line 87 of file AdaptBins.h.

◆ bin_view_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::bin_view_type = typename bin_type::view_type

Definition at line 88 of file AdaptBins.h.

◆ d_histo_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::d_histo_type = Histogram<size_type, bin_index_type, value_type, true>

Definition at line 92 of file AdaptBins.h.

◆ dindex_transform_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::dindex_transform_type = typename d_histo_type::dindex_transform_type

Definition at line 97 of file AdaptBins.h.

◆ dview_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::dview_type = typename d_histo_type::dview_type

Definition at line 93 of file AdaptBins.h.

◆ dwidth_view_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::dwidth_view_type = typename d_histo_type::dwidth_view_type

Definition at line 95 of file AdaptBins.h.

◆ h_histo_type_g

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::h_histo_type_g = Histogram<size_type, bin_index_type, value_type, false, Kokkos::HostSpace>

Definition at line 99 of file AdaptBins.h.

◆ hash_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::hash_type = ippl::detail::hash_type<Kokkos::DefaultExecutionSpace::memory_space>

Definition at line 89 of file AdaptBins.h.

◆ hindex_transform_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::hindex_transform_type = typename d_histo_type::hindex_transform_type

Definition at line 96 of file AdaptBins.h.

◆ hindex_transform_type_g

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::hindex_transform_type_g = typename h_histo_type_g::hindex_transform_type

Definition at line 103 of file AdaptBins.h.

◆ hview_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::hview_type = typename d_histo_type::hview_type

Definition at line 94 of file AdaptBins.h.

◆ hview_type_g

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::hview_type_g = typename h_histo_type_g::hview_type

Definition at line 101 of file AdaptBins.h.

◆ hwidth_view_type_g

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::hwidth_view_type_g = typename h_histo_type_g::hwidth_view_type

Definition at line 102 of file AdaptBins.h.

◆ particle_position_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::particle_position_type = typename BunchType::particle_position_type

Definition at line 83 of file AdaptBins.h.

◆ position_view_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::position_view_type = typename particle_position_type::view_type

Definition at line 84 of file AdaptBins.h.

◆ size_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::size_type = typename BunchType::size_type

Definition at line 85 of file AdaptBins.h.

◆ value_type

template<typename BunchType , typename BinningSelector >

using ParticleBinning::AdaptBins< BunchType, BinningSelector >::value_type = typename BinningSelector::value_type

Definition at line 82 of file AdaptBins.h.

Constructor & Destructor Documentation

◆ AdaptBins()

template<typename BunchType , typename BinningSelector >

ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins	(	BunchType &	bunch,
		BinningSelector	var_selector,
		bin_index_type	maxBins,
		value_type	binningAlpha,
		value_type	binningBeta,
		value_type	desiredWidth,
		const std::string &	binningCmdName
	)

inline

Constructs an AdaptBins object with a specified maximum number of bins and a selector.

Parameters

bunch	Borrowed particle container used for binning.
var_selector	A function or functor that selects the variable for binning (based on attributes).
maxBins	The maximum number of bins to initialize with (usually 128).
binningAlpha	The alpha parameter for the adaptive binning (merging) algorithm.
binningBeta	The beta parameter for the adaptive binning (merging) algorithm.
desiredWidth	The desiredWidth for the adaptive binning (merging) algorithm.

Note: The cost function parameters for the adaptive binning are outlined in the AdaptBins::partialMergedCDFIntegralCost function and explained in detail in Alexander Liemen's master thesis "Adaptive Energy Binning in OPAL-X".

Definition at line 121 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningAlpha_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningBeta_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::currentBins_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::desiredWidth_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::maxBins_m.

Here is the call graph for this function:

Member Function Documentation

◆ assignBinsToParticles()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::assignBinsToParticles ( )

overridevirtual

Assigns each particle in the bunch to a bin based on its position.

This function iterates over all particles in the bunch, calculates their bin index using getBin(...), and updates the "Bin" attribute in the container structure accordingly.

Note: It only calculates the fine uniform histogram using maxBins bins.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::doFullRebin().

◆ debug()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::debug ( )

inlineoverridevirtual

Outputs debug information related to Kokkos and MPI configurations.

This function prints information about the number of threads (in OpenMP) or GPUs (in CUDA/HIP) available on the current MPI rank, along with other debug information.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 515 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningAlpha_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningBeta_m, and ParticleBinning::AdaptBins< BunchType, BinningSelector >::desiredWidth_m.

◆ doFullRebin()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::doFullRebin	(	bin_index_type	nBins,
		bool	recalculateLimits = `true`,
		HistoReductionMode	modePreference = `HistoReductionMode::Standard`
	)

inlineoverridevirtual

Performs a full rebinning operation on the bunch.

It does the following steps:

Initializes the limits of the binning attribute.
Sets the current number of bins to nBins (usually 128 for the fine histogram).
Assigns uniform bins to particles based on the new limits and bin count.
(Re-)initializes the local and global histogram based on the new bins.

Parameters

nBins	The new number of bins to use for rebinning.
recalculateLimits	If true, the limits are recalculated based on the current particle data.
modePreference	The preferred mode for histogram reduction (default is Standard and choses the best method itself).

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 371 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::assignBinsToParticles(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::initHistogram(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::initLimits(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::setCurrentBinCount().

Here is the call graph for this function:

◆ executeInitLocalHistoReduction()

template<typename BunchType , typename BinningSelector >

template<typename ReducerType >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::executeInitLocalHistoReduction ( ReducerType & to_reduce )

Executes a parallel reduction to initialize the local histogram for particle bins.

This function performs a Kokkos::parallel_reduce over the particles in the bunch, incrementing counts in the reduction array to_reduce based on the bin index for each particle. After the reduction, the results are copied to the final histogram localBinHisto.

Template Parameters

ReducerType The type of the reduction object, which should support the_array for bin counts.

Parameters

to_reduce A reduction object that accumulates bin counts for the histogram.

The function performs the following steps:

Executes a Kokkos parallel reduction loop where each particle increments the bin count corresponding to its bin index.
Executes a parallel loop to copy the reduced bin counts from to_reduce to localBinHisto.

Note: This function uses the Kokkos parallel programming model and assumes that to_reduce has a the_array member which stores the histogram counts. So far, only ParticleBinning::ArrayReduction is implemented in that way (to work together with Kokkos::Sum reducer). the_array needs to have a known size at compile time. To use it on GPU anyways, ParallelReduceTools.h contains a function createReductionObject() to select the reducer object from a std::variant of pre-compiled reducer sizes.

◆ executeInitLocalHistoReductionTeamFor()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::executeInitLocalHistoReductionTeamFor ( )

overridevirtual

Initializes and performs a team-based histogram reduction for particle bins.

This function allocates scratch memory for each team on device, initializes a local histogram for each team in shared memory, updates it based on bin indices of particles assigned to that team and finally reduces the team-local histograms into a global histogram in device memory using pure atomics.

The process consists of the following steps:

Allocating scratch memory for each team's local histogram.
Initializing the local histogram to zero.
Assigning particles to bins in parallel within each team.
Reducing each team's local histogram into a global histogram (atomics).

Memory and Execution

For GPU architecture, this function does not need to be changed. Should problems with unusal execution time occur (e.g. if this function is supposed to be called on CPU – which it shouldn't), it might make sense to look at the following parameters calculated in the function:

Scratch Memory: Scratch memory is allocated per team for a local histogram, with size binCount.
Concurrency: team_size specifies the number of threads per team, and each team processes a block_size.

Note: This function is optimized for GPU execution using team-based parallelism, it does not work on Host (since team_size is hardcoded and to a big number). If you want to run this on Host, change team_size=1 and increase block_size.

Precondition: localBinHisto and binIndex must be initialized with appropriate sizes before calling this function.

Postcondition: localBinHisto contains the reduced histogram for the local data. Next step is to reduce across all MPI ranks.

See also: getGlobalHistogram

Implements ParticleBinning::AdaptBinsBase< BunchType >.

◆ genAdaptiveHistogram()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::genAdaptiveHistogram ( )

overridevirtual

Generates an adaptive histogram based on a fine global histogram.

This function is used to create an adaptive histogram from a fine global histogram. The fine global histogram (usually 128 bins) has to be created beforehand, but does not necessarily have to be uniform (even though this is recommended). The algorithm works perfectly fine as long as the globalBinHisto_m.binWidths_m field is initialized correctly. If not specified otherwise, it will be initialized either uniformly at initialization, or changed by the mergeBins() call or copied from another BinHisto instance.

It performs the following steps:

Merges bins in the global histogram to create an adaptive histogram (see BinHisto::mergeBins()).
Maps old bin indices to new bin indices using the lookup table returned by mergeBins().
Updates the local histogram with the new bin indices and widths.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

◆ getBin()

template<typename BunchType , typename BinningSelector >

static KOKKOS_INLINE_FUNCTION bin_index_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBin	(	value_type	x,
		value_type	xMin,
		value_type	xMax,
		value_type	binWidthInv,
		bin_index_type	numBins
	)

static

Calculates the bin index for a given position value in a uniform histogram.

This static method calculates which bin a position value falls into based on the bin boundaries and bin width. Uses integer casting to get bin index and clamps it to the biggest bin if out of range (only happens if limits and the particle bunch are out of sync – should not happen since particle push is not done between limit calculation and bin assignment).

Parameters

x	The binning parameter value (e.g. z-velocity).
xMin	Minimum boundary for the bins.
xMax	Maximum boundary for the bins.
binWidthInv	Inverse of the bin width for efficiency.
numBins	The total number of bins.

Returns: The calculated bin index for the given x value.

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

◆ getBinConfigHost() [1/2]

template<typename BunchType >

virtual value_type ParticleBinning::AdaptBinsBase< BunchType >::getBinConfigHost	(	std::vector< size_type > &	binCounts,
		std::vector< value_type > &	binWidths
	)		const

pure virtualinherited

◆ getBinConfigHost() [2/2]

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinConfigHost	(	std::vector< size_type > &	binCounts,
		std::vector< value_type > &	binWidths
	)		const

override

Extracts the global bin configuration (counts and widths) on the host.

Fills binCounts and binWidths with the current global histogram data and returns the lower bound xMin used when defining the histogram.

Note: This should be called after initGlobalHistogram()/genAdaptiveHistogram(), since it relies on the global histogram being initialized and available on host.

◆ getBinIterationPolicy()

template<typename BunchType , typename BinningSelector >

Kokkos::RangePolicy ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinIterationPolicy ( const bin_index_type & binIndex )

inlineoverridevirtual

Returns the bin iteration policy for a given bin index.

This function generates a range policy for iterating over the elements within a given bin index. If no DualView is used, it might need to copy some values to host, which might cause overhead. However, this only happens if the localBinHisto_m is implemented as a device only view, which is not its intended type.

Parameters

binIndex The index of the bin for which the iteration policy is to be generated.

Returns: Kokkos::RangePolicy<> The range policy for iterating over the elements in the specified bin.

Note: It returns an iteration policy that can be used together with sortedIndexArr_m inside scatter() to only iterate and scatter particles in a specific bin.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 463 of file AdaptBins.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getBinIterationPolicy(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::localBinHisto_m.

Here is the call graph for this function:

◆ getBinningCmdName()

template<typename BunchType , typename BinningSelector >

const std::string & ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinningCmdName ( ) const

inlineoverridevirtual

Returns the logical name of the active OPAL BinningCmd definition.

Used for diagnostic output (e.g. bin stats table headers).

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 175 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningCmdName_m.

◆ getBinView()

template<typename BunchType , typename BinningSelector >

bin_view_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinView ( )

inline

Returns a view to the particle bin array.

Note: : Change this function if the name of the Bin attribute in the container is changed.

Definition at line 161 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::bunch_m.

◆ getBinWidth()

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinWidth ( ) const

inlineoverridevirtual

Returns the average binwidth.

Returns: Corresponds to (xmax_m - xmin_m)/n_bins. Used in the fine histogram.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 190 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::binWidth_m.

◆ getCurrentBinCount()

template<typename BunchType , typename BinningSelector >

bin_index_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getCurrentBinCount ( ) const

inlineoverridevirtual

Returns the current number of bins.

Returns: The current bin count.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 168 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::currentBins_m.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getNPartInBin().

◆ getHashArray()

template<typename BunchType , typename BinningSelector >

hash_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getHashArray ( )

inlineoverridevirtual

Returns the index map that sorts the particle container by bin number.

Returns: hash_type sorting the container.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 217 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::sortedIndexArr_m.

◆ getMaxBinCount()

template<typename BunchType , typename BinningSelector >

bin_index_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getMaxBinCount ( ) const

inlineoverridevirtual

Gets the maximum number of bins. Will be used for the fine uniform histogram before merging.

Returns: The maximum allowed number of bins.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 183 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::maxBins_m.

◆ getNPartInBin()

template<typename BunchType , typename BinningSelector >

size_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getNPartInBin	(	bin_index_type	binIndex,
		bool	global = `false`
	)

inlineoverridevirtual

Retrieves the number of particles in a specified bin.

This function returns the number of particles in the bin specified by the given index. It assumes that the DualView (if used) has been properly synchronized and initialized. If the function is called frequently, it might create some overhead due to the .view_host() call. However, since it is only called on the host (a maximum of nBins times per iteration), the overhead should be minimal. For better efficiency, one can avoid the Kokkos::View "copying-action" by reusing the host view. Just be careful, since this might change the underlying data structure of the BinHisto class.

Parameters

binIndex	The index of the bin for which the number of particles is to be retrieved.
global	If true, retrieves from global histogram, otherwise from local histogram.

Returns: The number of particles in the specified bin.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 412 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::bunch_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::getCurrentBinCount(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getNPartInBin(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::globalBinHisto_m, and ParticleBinning::AdaptBins< BunchType, BinningSelector >::localBinHisto_m.

Here is the call graph for this function:

◆ getXMin()

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::getXMin ( ) const

inlineoverridevirtual

Returns the current lower bound of the binning coordinate (xMin).

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 195 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::xMin_m.

◆ initGlobalHistogram()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::initGlobalHistogram ( )

overridevirtual

Retrieves the global histogram across all processes.

This function reduces the local histograms across all MPI processes into a single global histogram view.

Returns: A view of the global histogram in host space (used for merging/the adaptive histogram).

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initHistogram().

◆ initHistogram()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::initHistogram ( HistoReductionMode modePreference = HistoReductionMode::Standard )

inlineoverridevirtual

Initializes the local/global histogram based on the Bin attribute.

Parameters

modePreference The preferred mode for histogram reduction (default is Standard).

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 385 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::globalBinHisto_m, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::init(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::initGlobalHistogram(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::initLocalHisto(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::instantiateHistogram(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::localBinHisto_m.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::doFullRebin().

Here is the call graph for this function:

◆ initLimits()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::initLimits ( )

overridevirtual

Initializes the limits for binning based on the particle data.

This function calculates the minimum and maximum limits (xMin and xMax) from the binning attribute (e.g. velocity), which are then used to define bin boundaries.

Note: Called before bins and histograms are initialized.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::doFullRebin().

◆ initLocalHisto()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::initLocalHisto ( HistoReductionMode modePreference = HistoReductionMode::Standard )

overridevirtual

Initializes a local histogram for particle binning.

This function initializes the local histogram (instance of BinHisto) after bin indices were assigned using assignBinsToParticles(). It reduces the indices to a histogram using on the the reduction functions in this class. It chooses which function to use based on the HistoReductionMode parameter (defined in ParallelReduceTools.h) or the optimal method based on the current architecture/bin number.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initHistogram().

◆ initTimers()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers ( )

inline

Initializes timers for various operations in the binning process.

Definition at line 146 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::bAllReduceGlobalHistoT, ParticleBinning::AdaptBins< BunchType, BinningSelector >::bAllReduceLimitsT, ParticleBinning::AdaptBins< BunchType, BinningSelector >::bAssignUniformBinsT, ParticleBinning::AdaptBins< BunchType, BinningSelector >::bExecuteHistoReductionT, ParticleBinning::AdaptBins< BunchType, BinningSelector >::bInitLimitsT, ParticleBinning::AdaptBins< BunchType, BinningSelector >::bSortContainerByBinT, and ParticleBinning::AdaptBins< BunchType, BinningSelector >::bVerifySortingT.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins().

◆ instantiateHistogram()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::instantiateHistogram ( bool setToZero = false )

overridevirtual

Initializes the histogram view for binning and optionally sets it to zero.

Parameters

setToZero If true, initializes the histogram view to zero. Default is false. The 0 initialization is not needed if data is overwritten anyways.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initHistogram().

◆ print()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::print ( )

inlineoverridevirtual

Prints the current global histogram to the Inform output stream.

This function outputs the global histogram data (bin counts) to the standard output. Note: Only for rank 0 in an MPI environment.

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Definition at line 507 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::globalBinHisto_m, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printPythonArrays().

Here is the call graph for this function:

◆ setCurrentBinCount()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::setCurrentBinCount ( bin_index_type nBins )

inline

Sets the current number of bins and adjusts the bin width.

Parameters

nBins The new number of currently used bins (locally).

Note: The other parameters (limits) are set before this function is called in doFullRebin().

Definition at line 205 of file AdaptBins.h.

References ParticleBinning::AdaptBins< BunchType, BinningSelector >::binWidth_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::currentBins_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::maxBins_m, ParticleBinning::AdaptBins< BunchType, BinningSelector >::xMax_m, and ParticleBinning::AdaptBins< BunchType, BinningSelector >::xMin_m.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::doFullRebin().

◆ sortContainerByBin()

template<typename BunchType , typename BinningSelector >

void ParticleBinning::AdaptBins< BunchType, BinningSelector >::sortContainerByBin ( )

overridevirtual

Sorts the container of particles by their bin indices.

This function assumes that the prefix sum (post-sum) has already been initialized. It rearranges a particle indices array into the correct order based on their Bin attribute and verifies the sorting. The function uses a parallelized bin sort.

Steps:

Retrieves the bin view and initializes the bin offsets using the prefix sum that is saved inside the localBinHisto_m instance (should be of type BinHisto in DualView mode).
Allocates a hash_array to store the sorted indices of particles.
Uses a Kokkos loop to place each particle into its target position based on its bin index.
(In Debug mode) verifies that the sorting was successful.

Note: This function is most efficient with a large number of bins, since this minimizes overhead from the atomic operations. Therefore, it should be called before merging (even though calling it afterwards also works).

Implements ParticleBinning::AdaptBinsBase< BunchType >.

Member Data Documentation

◆ bAllReduceGlobalHistoT

template<typename BunchType , typename BinningSelector >

IpplTimings::TimerRef ParticleBinning::AdaptBins< BunchType, BinningSelector >::bAllReduceGlobalHistoT

private

Definition at line 589 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers().

◆ bAllReduceLimitsT

template<typename BunchType , typename BinningSelector >

IpplTimings::TimerRef ParticleBinning::AdaptBins< BunchType, BinningSelector >::bAllReduceLimitsT

private

Definition at line 588 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers().

◆ bAssignUniformBinsT

template<typename BunchType , typename BinningSelector >

IpplTimings::TimerRef ParticleBinning::AdaptBins< BunchType, BinningSelector >::bAssignUniformBinsT

private

Definition at line 590 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers().

◆ bExecuteHistoReductionT

template<typename BunchType , typename BinningSelector >

IpplTimings::TimerRef ParticleBinning::AdaptBins< BunchType, BinningSelector >::bExecuteHistoReductionT

private

Definition at line 591 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers().

◆ bInitLimitsT

template<typename BunchType , typename BinningSelector >

IpplTimings::TimerRef ParticleBinning::AdaptBins< BunchType, BinningSelector >::bInitLimitsT

private

Definition at line 587 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers().

◆ binningAlpha_m

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningAlpha_m

private

Alpha parameter for binning cost function.

Definition at line 575 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::debug().

◆ binningBeta_m

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningBeta_m

private

Beta parameter for binning cost function.

Definition at line 576 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::debug().

◆ binningCmdName_m

template<typename BunchType , typename BinningSelector >

std::string ParticleBinning::AdaptBins< BunchType, BinningSelector >::binningCmdName_m

private

Name of the active OPAL BinningCmd definition.

Definition at line 569 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinningCmdName().

◆ binWidth_m

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::binWidth_m

private

Width of each bin (assumes a uniform histogram).

Definition at line 572 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinWidth(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::setCurrentBinCount().

◆ bSortContainerByBinT

template<typename BunchType , typename BinningSelector >

IpplTimings::TimerRef ParticleBinning::AdaptBins< BunchType, BinningSelector >::bSortContainerByBinT

private

Definition at line 592 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers().

◆ bunch_m

template<typename BunchType , typename BinningSelector >

BunchType& ParticleBinning::AdaptBins< BunchType, BinningSelector >::bunch_m

private

Borrowed particle container.

Definition at line 565 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinView(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::getNPartInBin().

◆ bVerifySortingT

template<typename BunchType , typename BinningSelector >

IpplTimings::TimerRef ParticleBinning::AdaptBins< BunchType, BinningSelector >::bVerifySortingT

private

Definition at line 593 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::initTimers().

◆ currentBins_m

template<typename BunchType , typename BinningSelector >

bin_index_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::currentBins_m

private

Current number of bins in use.

Definition at line 568 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::getCurrentBinCount(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::setCurrentBinCount().

◆ desiredWidth_m

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::desiredWidth_m

private

Desired bin width for binning cost function.

Definition at line 577 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::debug().

◆ globalBinHisto_m

template<typename BunchType , typename BinningSelector >

h_histo_type_g ParticleBinning::AdaptBins< BunchType, BinningSelector >::globalBinHisto_m

private

Global histogram view (over ranks reduced local histograms).

Definition at line 582 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getNPartInBin(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::initHistogram(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::print().

◆ localBinHisto_m

template<typename BunchType , typename BinningSelector >

d_histo_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::localBinHisto_m

private

Local histogram view for bin counts.

Definition at line 580 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getBinIterationPolicy(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::getNPartInBin(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::initHistogram().

◆ maxBins_m

template<typename BunchType , typename BinningSelector >

const bin_index_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::maxBins_m

private

Maximum number of bins.

Definition at line 567 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins(), ParticleBinning::AdaptBins< BunchType, BinningSelector >::getMaxBinCount(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::setCurrentBinCount().

◆ sortedIndexArr_m

template<typename BunchType , typename BinningSelector >

hash_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::sortedIndexArr_m

private

Particle index map that sorts the bunch by bin index.

Definition at line 584 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getHashArray().

◆ var_selector_m

template<typename BunchType , typename BinningSelector >

BinningSelector ParticleBinning::AdaptBins< BunchType, BinningSelector >::var_selector_m

private

Variable selector for binning.

Definition at line 566 of file AdaptBins.h.

◆ xMax_m

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::xMax_m

private

Maximum value of bin attribute.

Definition at line 571 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::setCurrentBinCount().

◆ xMin_m

template<typename BunchType , typename BinningSelector >

value_type ParticleBinning::AdaptBins< BunchType, BinningSelector >::xMin_m

private

Minimum value of bin attribute.

Definition at line 570 of file AdaptBins.h.

Referenced by ParticleBinning::AdaptBins< BunchType, BinningSelector >::getXMin(), and ParticleBinning::AdaptBins< BunchType, BinningSelector >::setCurrentBinCount().

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

AdaptBins.h

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ bin_index_type

◆ bin_type

◆ bin_view_type

◆ d_histo_type

◆ dindex_transform_type

◆ dview_type

◆ dwidth_view_type

◆ h_histo_type_g

◆ hash_type

◆ hindex_transform_type

◆ hindex_transform_type_g

◆ hview_type

◆ hview_type_g

◆ hwidth_view_type_g

◆ particle_position_type

◆ position_view_type

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ AdaptBins()

Member Function Documentation

◆ assignBinsToParticles()

◆ debug()

◆ doFullRebin()

◆ executeInitLocalHistoReduction()

◆ executeInitLocalHistoReductionTeamFor()

Memory and Execution

◆ genAdaptiveHistogram()

◆ getBin()

◆ getBinConfigHost() [1/2]

◆ getBinConfigHost() [2/2]

◆ getBinIterationPolicy()

◆ getBinningCmdName()

◆ getBinView()

◆ getBinWidth()

◆ getCurrentBinCount()

◆ getHashArray()

◆ getMaxBinCount()

◆ getNPartInBin()

◆ getXMin()

◆ initGlobalHistogram()

◆ initHistogram()

◆ initLimits()

◆ initLocalHisto()

◆ initTimers()

◆ instantiateHistogram()

◆ print()

◆ setCurrentBinCount()

◆ sortContainerByBin()

Member Data Documentation

◆ bAllReduceGlobalHistoT

◆ bAllReduceLimitsT

◆ bAssignUniformBinsT

◆ bExecuteHistoReductionT

◆ bInitLimitsT

◆ binningAlpha_m

◆ binningBeta_m

◆ binningCmdName_m

◆ binWidth_m

◆ bSortContainerByBinT

◆ bunch_m

◆ bVerifySortingT

◆ currentBins_m

◆ desiredWidth_m

◆ globalBinHisto_m

◆ localBinHisto_m

◆ maxBins_m

◆ sortedIndexArr_m

◆ var_selector_m

◆ xMax_m

◆ xMin_m