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

#include <AdaptBins.h>

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	hindex_transform_type_g = typename h_histo_type_g::hindex_transform_type

Public Member Functions
	AdaptBins (std::shared_ptr< BunchType > bunch, BinningSelector var_selector, bin_index_type maxBins, value_type binningAlpha, value_type binningBeta, value_type desiredWidth)
	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
	Returns the current number of bins.
bin_index_type	getMaxBinCount () const
	Gets the maximum number of bins. Will be used for the fine uniform histogram before merging.
value_type	getBinWidth () const
	Returns the average binwidth.
void	setCurrentBinCount (bin_index_type nBins)
	Sets the current number of bins and adjusts the bin width.
hash_type	getHashArray ()
	Returns the index map that sorts the particle container by bin number.
void	initLimits ()
	Initializes the limits for binning based on the particle data.
void	instantiateHistogram (bool setToZero=false)
	Initializes the histogram view for binning and optionally sets it to zero.
void	assignBinsToParticles ()
	Assigns each particle in the bunch to a bin based on its position.
void	initLocalHisto (HistoReductionMode modePreference=HistoReductionMode::Standard)
	Initializes a local histogram for particle binning.
void	executeInitLocalHistoReductionTeamFor ()
	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 ()
	Retrieves the global histogram across all processes.
void	doFullRebin (bin_index_type nBins, bool recalculateLimits=true, HistoReductionMode modePreference=HistoReductionMode::Standard)
	Performs a full rebinning operation on the bunch.
void	initHistogram (HistoReductionMode modePreference=HistoReductionMode::Standard)
	Initializes the local/global histogram based on the Bin attribute.
size_type	getNPartInBin (bin_index_type binIndex, bool global=false)
	Retrieves the number of particles in a specified bin.
void	sortContainerByBin ()
	Sorts the container of particles by their bin indices.
Kokkos::RangePolicy	getBinIterationPolicy (const bin_index_type &binIndex)
	Returns the bin iteration policy for a given bin index.
void	genAdaptiveHistogram ()
	Generates an adaptive histogram based on a fine global histogram.
void	print ()
	Prints the current global histogram to the Inform output stream.
void	debug ()
	Outputs debug information related to Kokkos and MPI configurations.
template<typename T, unsigned Dim>
VField_t< T, Dim > &	LTrans (VField_t< T, Dim > &field, const bin_index_type &currentBin)
	Applies a Lorentz transformation to a given vector field based on particle velocities.

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
std::shared_ptr< BunchType >	bunch_m
	Shared pointer to the 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.
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 36 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 43 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 44 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 45 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 49 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 54 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 50 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 52 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 56 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 46 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 53 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 58 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 51 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 57 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 40 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 41 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 42 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 39 of file AdaptBins.h.

Constructor & Destructor Documentation

◆ AdaptBins()

template<typename BunchType, typename BinningSelector>

ParticleBinning::AdaptBins< BunchType, BinningSelector >::AdaptBins	(	std::shared_ptr< BunchType >	bunch,
		BinningSelector	var_selector,
		bin_index_type	maxBins,
		value_type	binningAlpha,
		value_type	binningBeta,
		value_type	desiredWidth )

inline

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

Parameters

bunch	A shared pointer to the underlying particle container.
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 74 of file AdaptBins.h.

References binningAlpha_m, binningBeta_m, bunch_m, currentBins_m, desiredWidth_m, initTimers(), maxBins_m, and var_selector_m.

Here is the call graph for this function:

Member Function Documentation

◆ assignBinsToParticles()

template<typename BunchType, typename BinningSelector>

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

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.

Referenced by doFullRebin().

Here is the caller graph for this function:

◆ debug()

template<typename BunchType, typename BinningSelector>

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

inline

Outputs debug information related to Kokkos and MPI configurations.

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

Definition at line 416 of file AdaptBins.h.

References binningAlpha_m, binningBeta_m, and 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 )

inline

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).

Definition at line 295 of file AdaptBins.h.

References assignBinsToParticles(), initHistogram(), initLimits(), setCurrentBinCount(), and ParticleBinning::Standard.

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 ( )

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

◆ genAdaptiveHistogram()

template<typename BunchType, typename BinningSelector>

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

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.

◆ getBin()

template<typename BunchType, typename BinningSelector>

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.

◆ getBinIterationPolicy()

template<typename BunchType, typename BinningSelector>

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

inline

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.

Definition at line 379 of file AdaptBins.h.

References localBinHisto_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 114 of file AdaptBins.h.

References bunch_m.

◆ getBinWidth()

template<typename BunchType, typename BinningSelector>

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

inline

Returns the average binwidth.

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

Definition at line 135 of file AdaptBins.h.

References binWidth_m.

◆ getCurrentBinCount()

template<typename BunchType, typename BinningSelector>

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

inline

Returns the current number of bins.

Returns: The current bin count.

Definition at line 121 of file AdaptBins.h.

References currentBins_m.

Referenced by getNPartInBin().

Here is the caller graph for this function:

◆ getHashArray()

template<typename BunchType, typename BinningSelector>

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

inline

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

Returns: hash_type sorting the container.

Definition at line 154 of file AdaptBins.h.

References sortedIndexArr_m.

◆ getMaxBinCount()

template<typename BunchType, typename BinningSelector>

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

inline

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

Returns: The maximum allowed number of bins.

Definition at line 128 of file AdaptBins.h.

References maxBins_m.

◆ getNPartInBin()

template<typename BunchType, typename BinningSelector>

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

inline

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 using dualView.h_view(binIndex). 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.

Definition at line 332 of file AdaptBins.h.

References bunch_m, getCurrentBinCount(), globalBinHisto_m, and localBinHisto_m.

Here is the call graph for this function:

◆ initGlobalHistogram()

template<typename BunchType, typename BinningSelector>

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

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).

Referenced by initHistogram().

Here is the caller graph for this function:

◆ initHistogram()

template<typename BunchType, typename BinningSelector>

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

inline

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

Parameters

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

Definition at line 307 of file AdaptBins.h.

References globalBinHisto_m, initGlobalHistogram(), initLocalHisto(), instantiateHistogram(), localBinHisto_m, and ParticleBinning::Standard.

Referenced by doFullRebin().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ initLimits()

template<typename BunchType, typename BinningSelector>

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

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.

Referenced by doFullRebin().

Here is the caller graph for this function:

◆ initLocalHisto()

template<typename BunchType, typename BinningSelector>

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

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.

References ParticleBinning::Standard.

Referenced by initHistogram().

Here is the caller graph for this function:

◆ 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 99 of file AdaptBins.h.

References bAllReduceGlobalHistoT, bAllReduceLimitsT, bAssignUniformBinsT, bExecuteHistoReductionT, bInitLimitsT, bSortContainerByBinT, and bVerifySortingT.

Referenced by AdaptBins().

Here is the caller graph for this function:

◆ instantiateHistogram()

template<typename BunchType, typename BinningSelector>

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

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.

Referenced by initHistogram().

Here is the caller graph for this function:

◆ LTrans()

template<typename BunchType, typename BinningSelector>

template<typename T, unsigned Dim>

VField_t< T, Dim > & ParticleBinning::AdaptBins< BunchType, BinningSelector >::LTrans	(	VField_t< T, Dim > &	field,
		const bin_index_type &	currentBin )

Applies a Lorentz transformation to a given vector field based on particle velocities.

Template Parameters

T	The data type of the field components (e.g., double, float).
Dim	The dimensionality of the field.

Parameters

field A reference to the vector field to be transformed.

Returns: A reference to the transformed field.

Gamma Factor Calculation: The gamma factor is derived from the velocity components of particles. For a given particle velocity (v), the gamma factor is computed as: [ \gamma = \frac{1}{\sqrt{1 - \vec{v} \cdot \vec{v}}} ] where (\vec{v}) is the velocity vector of a particle.
Field Transformation: After computing the gamma factor, each component of the field is multiplied by the corresponding gamma factor.

Example Usage:

VField_t<double, 3> field = ...; // Initialize the field

this->bins_m->LTrans(field); // Apply Lorentz transformation

VField_t

ippl::Field< ippl::Vector< T, Dim >, Dim, ViewArgs... > VField_t

Definition PBunchDefs.h:33

Note: This function should not be used inside OPAL-X, since it makes assumptions regarding the actual particle bunch. It is just for testing during development.

◆ print()

template<typename BunchType, typename BinningSelector>

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

inline

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.

Definition at line 406 of file AdaptBins.h.

References globalBinHisto_m.

◆ 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 144 of file AdaptBins.h.

References binWidth_m, currentBins_m, maxBins_m, xMax_m, and xMin_m.

Referenced by doFullRebin().

Here is the caller graph for this function:

◆ sortContainerByBin()

template<typename BunchType, typename BinningSelector>

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

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).

Definition at line 496 of file AdaptBins.h.

Referenced by AdaptBins(), and 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 497 of file AdaptBins.h.

Referenced by AdaptBins(), and debug().

◆ 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 493 of file AdaptBins.h.

Referenced by getBinWidth(), and setCurrentBinCount().

◆ bSortContainerByBinT

template<typename BunchType, typename BinningSelector>

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

private

Definition at line 512 of file AdaptBins.h.

Referenced by initTimers().

◆ bunch_m

template<typename BunchType, typename BinningSelector>

std::shared_ptr<BunchType> ParticleBinning::AdaptBins< BunchType, BinningSelector >::bunch_m

private

Shared pointer to the particle container.

Definition at line 487 of file AdaptBins.h.

Referenced by AdaptBins(), getBinView(), and getNPartInBin().

template<typename BunchType, typename BinningSelector>

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

private

Minimum value of bin attribute.

Definition at line 491 of file AdaptBins.h.

Referenced by 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

◆ 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()

◆ getBinIterationPolicy()

◆ getBinView()

◆ getBinWidth()

◆ getCurrentBinCount()

◆ getHashArray()

◆ getMaxBinCount()

◆ getNPartInBin()

◆ initGlobalHistogram()

◆ initHistogram()

◆ initLimits()

◆ initLocalHisto()

◆ initTimers()

◆ instantiateHistogram()

◆ LTrans()

Example Usage:

◆ print()

◆ setCurrentBinCount()

◆ sortContainerByBin()

Member Data Documentation

◆ bAllReduceGlobalHistoT

◆ bAllReduceLimitsT

◆ bAssignUniformBinsT

◆ bExecuteHistoReductionT

◆ bInitLimitsT

◆ binningAlpha_m

◆ binningBeta_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