Template class providing adaptive particle histogram binning with support for Kokkos Views and DualViews. More...

#include <BinHisto.h>

Collaboration diagram for ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >:

Public Types
using	view_type = std::conditional_t< UseDualView, Kokkos::DualView< size_type , Properties... >, Kokkos::View< size_type , Properties... > >

using	dview_type = typename DeviceViewTraits< UseDualView, view_type >::d_type

using	hview_type = typename DeviceViewTraits< UseDualView, view_type >::h_type

using	width_view_type = std::conditional_t< UseDualView, Kokkos::DualView< value_type , Properties... >, Kokkos::View< value_type , Properties... > >

using	hwidth_view_type = typename DeviceViewTraits< UseDualView, width_view_type >::h_type

using	dwidth_view_type = typename DeviceViewTraits< UseDualView, width_view_type >::d_type

template<class... Args>
using	index_transform_type = Kokkos::View< bin_index_type *, Args... >

using	dindex_transform_type = index_transform_type< Kokkos::DefaultExecutionSpace >

using	hindex_transform_type = index_transform_type< Kokkos::HostSpace >

Public Member Functions
	Histogram ()=default
	Default constructor for the Histogram class.

	Histogram (std::string debug_name, bin_index_type numBins, value_type totalBinWidth, value_type binningAlpha, value_type binningBeta, value_type desiredWidth)
	Constructor for the Histogram class with a given name, number of bins, and total bin width.

	Histogram (const Histogram &other)
	Default destructor for the Histogram class.

Histogram &	operator= (const Histogram &other)
	Assignment operator for copying the fields from another Histogram object.

size_type	getNPartInBin (bin_index_type binIndex)
	Retrieves the number of particles in a specified bin.

size_type	getCurrentBinCount () const
	Returns the current number of bins in the histogram.

view_type	getHistogram ()
	Returns the Kokkos View containing the histogram bin counts.

view_type	getHistogram () const

view_type	getPostSum ()
	Returns the Kokkos View containing the post-sum of bin counts.

width_view_type	getBinWidths () const
	Returns the Kokkos View of bin widths in the current histogram configuration. It will be an array of constant values if the histogram is uniform.

template<typename Histogram_t >
void	copyBinWidths (const Histogram_t &other)
	Sets the bin widths by copying them from a different Histogram instance (usually neccessary after merging the global histogram to copy the new non-uniform widths to the local histogram).

void	init ()
	Synchronizes the histogram view and initializes the bin widths and post-sum.

void	initConstBinWidths (const value_type constBinWidth)
	Initializes the bin widths with a constant value.

void	initPostSum ()
	Initializes and computes the post-sum for the histogram.

Kokkos::RangePolicy	getBinIterationPolicy (const bin_index_type &binIndex1, const bin_index_type numBins=1)
	Returns a `Kokkos::RangePolicy` for iterating over the elements in a specified bin.

void	sync ()
	Synchronizes the histogram data between host and device.

void	modify_device ()
	If a DualView is used, it sets the flag on the view that the device has been modified.

void	modify_host ()
	If a DualView is used, it sets the flag on the view that the host has been modified.

hindex_transform_type	mergeBins ()
	Merges bins in a histogram to reduce the number of bins while minimizing a cost function.

void	printHistogram (std::ostream &os=std::cout)
	Prints a nicely formatted table of bin indices, counts, and widths.

void	printPythonArrays () const

Static Public Member Functions
template<typename return_type , typename HistogramType >
static constexpr return_type	getDeviceView (HistogramType histo)
	Retrieves the device view of the histogram.

template<typename return_type , typename HistogramType >
static constexpr return_type	getHostView (HistogramType histo)
	Retrieves a host view of the given histogram.

Private Member Functions
value_type	adaptiveBinningCostFunction (const size_type &sumCount, const value_type &sumWidth, const size_type &totalNumParticles)
	Computes the cost function for adaptive binning in a histogram.

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

void	instantiateHistograms ()
	Instantiates the histogram, bin widths, and post-sum views (Possibly DualView).

void	copyFields (const Histogram &other)
	Copies the fields from another Histogram object.

Private Attributes
std::string	debug_name_m

bin_index_type	numBins_m
	Debug name for identifying the histogram instance.

value_type	totalBinWidth_m
	Number of bins in the histogram.

value_type	binningAlpha_m
	Total width of all bins combined.

value_type	binningBeta_m
	Alpha parameter for the adaptive binning (merging) cost function.

value_type	desiredWidth_m
	Beta parameter for the adaptive binning (merging) cost function.

view_type	histogram_m
	Desired width for the adaptive binning (merging) cost function.

width_view_type	binWidths_m
	View storing the particle counts in each bin.

view_type	postSum_m
	View storing the widths of the bins.

IpplTimings::TimerRef	bDeviceSyncronizationT
	View storing the cumulative sum of bin counts (used in sorting, generating range policies).

IpplTimings::TimerRef	bHistogramInitT

IpplTimings::TimerRef	bMergeBinsT

Detailed Description

template<typename size_type, typename bin_index_type, typename value_type, bool UseDualView = false, class... Properties>
class ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >

Template class providing adaptive particle histogram binning with support for Kokkos Views and DualViews.

The Histogram class implements a flexible histogram for particle binning. It manages bin counts, bin widths, and post-sums, supporting both uniform and adaptive binning (merging). All operations can be performed on the host or device, as required. The class can be initialized as a Kokkos::DualView or a simple Kokkos::View, should it be necessary to use the host/device views separately. In that case, one needs to make sure that the sync() and modify_... functions are called correctly to ensure that the data is synchronized. The synchronization is a wrapper around the Kokkos sync functions. More can be found in the Kokkos::DualView documentation.

Template Parameters

size_type	Type used for counting (e.g., int, size_t).
bin_index_type	Type used for bin indices.
value_type	Type representing binning parameter.
UseDualView	If true, uses Kokkos::DualView for host/device sync; else, Kokkos::View.
Properties	Additional properties for Kokkos Views/DualViews (e.g. explicit memory spaces).

Definition at line 64 of file BinHisto.h.

Member Typedef Documentation

◆ dindex_transform_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::dindex_transform_type = index_transform_type< Kokkos::DefaultExecutionSpace>

Definition at line 83 of file BinHisto.h.

◆ dview_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::dview_type = typename DeviceViewTraits<UseDualView, view_type>::d_type

Definition at line 70 of file BinHisto.h.

◆ dwidth_view_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::dwidth_view_type = typename DeviceViewTraits<UseDualView, width_view_type>::d_type

Definition at line 78 of file BinHisto.h.

◆ hindex_transform_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::hindex_transform_type = index_transform_type<Kokkos::HostSpace>

Definition at line 86 of file BinHisto.h.

◆ hview_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::hview_type = typename DeviceViewTraits<UseDualView, view_type>::h_type

Definition at line 71 of file BinHisto.h.

◆ hwidth_view_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::hwidth_view_type = typename DeviceViewTraits<UseDualView, width_view_type>::h_type

Definition at line 77 of file BinHisto.h.

◆ index_transform_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

template<class... Args>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::index_transform_type = Kokkos::View<bin_index_type*, Args...>

Definition at line 82 of file BinHisto.h.

◆ view_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::view_type = std::conditional_t< UseDualView, Kokkos::DualView<size_type*, Properties...>, Kokkos::View<size_type*, Properties...> >

Definition at line 67 of file BinHisto.h.

◆ width_view_type

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

using ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::width_view_type = std::conditional_t< UseDualView, Kokkos::DualView<value_type*, Properties...>, Kokkos::View<value_type*, Properties...> >

Definition at line 74 of file BinHisto.h.

Constructor & Destructor Documentation

◆ Histogram() [1/3]

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::Histogram ( )

default

Default constructor for the Histogram class.

◆ Histogram() [2/3]

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::Histogram	(	std::string	debug_name,
		bin_index_type	numBins,
		value_type	totalBinWidth,
		value_type	binningAlpha,
		value_type	binningBeta,
		value_type	desiredWidth
	)

inline

Constructor for the Histogram class with a given name, number of bins, and total bin width.

Parameters

debug_name	The name of the histogram for debugging purposes. Is passed as a name for the Kokkos::...View.
numBins	The number of bins in the histogram. Might change once the merging algorithm is used.
totalBinWidth	The total width of the value range covered by the particles, so $x_\mathrm{max} - x_\mathrm{min}$.
binningAlpha	The alpha parameter for the adaptive binning (merging) cost function.
binningBeta	The beta parameter for the adaptive binning (merging) cost function.
desiredWidth	The desired width for the adaptive binning (merging) cost function.

Definition at line 109 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initTimers(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::instantiateHistograms().

Here is the call graph for this function:

◆ Histogram() [3/3]

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::Histogram ( const Histogram< size_type, bin_index_type, value_type, UseDualView, Properties > & other )

inline

Default destructor for the Histogram class.

Copy constructor for copying the fields from another Histogram object.

See also: copyFields() for more information on how the fields are copied (uses Kokkos shallow copy).

Definition at line 136 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::copyFields().

Here is the call graph for this function:

Member Function Documentation

◆ adaptiveBinningCostFunction()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

value_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::adaptiveBinningCostFunction	(	const size_type &	sumCount,
		const value_type &	sumWidth,
		const size_type &	totalNumParticles
	)

private

Computes the cost function for adaptive binning in a histogram.

This function calculates a cost value based on several factors, including Shannon entropy, bin width penalties, and sparsity penalties. It is used to optimize the binning process by balancing the distribution of particles across bins while considering desired bin width and sparsity constraints.

Parameters

sumCount	The total count of particles in the current to-be-merged bin.
sumWidth	The total width of the current to-be-merged bin.
totalNumParticles	The total number of particles across all bins.

Returns: The computed cost value for the current to-be-merged bin configuration.

Note: The function assumes sumCount > 0 as a precondition. This is only checked in debug mode. However, the cost should not even be computed in that case.

The cost function is composed of the following terms:

Shannon Entropy: Encourages a balanced distribution of particles.
Wide Bin Penalty: Penalizes bins that are too wide or too narrow, based on the binningAlpha parameter.
Bin Size Bias: Biases the bin size towards desiredWidth, controlled by the binningBeta parameter.
Sparse Penalty: Penalizes bins with too few particles, particularly in the distribution tails, normalized by the desired width.

The cost function is defined as:

\[ c[i, j] \overset{!}{=} \underbrace{N_\mathrm{tot}\, \log\left(N_\mathrm{tot}\right)\, \Delta v_\mathrm{tot}}_{\text{Shannon Entropy}} + \underbrace{\alpha \, \Delta v_\mathrm{tot}^2}_{\text{Width Bias}} + \underbrace{\beta \, \left(\Delta v_\mathrm{tot} - \Delta v_\mathrm{bias}\right)^2}_{\text{Deviation Penalty}} + \underbrace{\frac{\Delta v_\mathrm{bias}}{N_\mathrm{tot}} \Theta\left(\Delta v_\mathrm{bias}-N_\mathrm{tot}\right)}_{\text{Sparse Penalty}} \]

Where:

( N_\mathrm{tot} ): Total number of particles in the bin.
( \Delta v_\mathrm{tot} ): Total width of the bin.
( \Delta v_\mathrm{bias} ): Desired bin width.
( \alpha ): Weight for the width bias term.
( \beta ): Weight for the deviation penalty term.
( \Theta(x) ): Heaviside step function.

The function is designed to judge how exactly an "optimally merged histogram" looks like. For a more detailed explanation, see Alexander Liemen's master thesis ("Adaptive Energy Binning in OPAL-X").

◆ copyBinWidths()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

template<typename Histogram_t >

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::copyBinWidths ( const Histogram_t & other )

inline

Sets the bin widths by copying them from a different Histogram instance (usually neccessary after merging the global histogram to copy the new non-uniform widths to the local histogram).

Note: This function needs to be templated to allow copying from BinHisto instances that are from a different type than "this". It is neccessary in this context, since localBinHisto_m in AdaptBins is usually a DualView setup, while globalBinHisto_m is modified to use a host-only view.

Definition at line 213 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bDeviceSyncronizationT, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binWidths_m.

◆ copyFields()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::copyFields ( const Histogram< size_type, bin_index_type, value_type, UseDualView, Properties > & other )

private

Copies the fields from another Histogram object.

This function copies the internal fields from the provided Histogram object to the current object. The fields are copied using Kokkos' shallow copy.

Parameters

other The Histogram object from which to copy the fields.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::Histogram(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::operator=().

◆ getBinIterationPolicy()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

Kokkos::RangePolicy ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getBinIterationPolicy	(	const bin_index_type &	binIndex1,
		const bin_index_type	numBins = `1`
	)

inline

Returns a Kokkos::RangePolicy for iterating over the elements in a specified bin.

This function generates a range policy for iterating over the elements within a given bin index range.

Template Parameters

bin_index_type The type of the bin index.

Parameters

binIndex1	The index of the bin for which the iteration policy is to be generated.
numBins	The number of bins to iterate over (default is 1) starting at `binIndex1`.

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

Note: The bounds are needed on host. So if no DualView is used or the values are only available on device, then there will be some values copied from device to host.

Definition at line 306 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::postSum_m.

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

◆ getBinWidths()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

width_view_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getBinWidths ( ) const

inline

Returns the Kokkos View of bin widths in the current histogram configuration. It will be an array of constant values if the histogram is uniform.

Definition at line 200 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binWidths_m.

◆ getCurrentBinCount()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

size_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getCurrentBinCount ( ) const

inline

Returns the current number of bins in the histogram.

Definition at line 183 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::numBins_m.

◆ getDeviceView()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

template<typename return_type , typename HistogramType >

static constexpr return_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getDeviceView ( HistogramType histo )

inlinestaticconstexpr

Retrieves the device view of the histogram.

This function returns the device view of the histogram if the UseDualView flag is set to true. Otherwise, it returns the histogram itself (which might not be on device!).

Template Parameters

HistogramType The type of the histogram.

Parameters

histo Reference to the histogram.

Returns: The device view of the histogram if UseDualView is true, otherwise the histogram itself.

Definition at line 392 of file BinHisto.h.

◆ getHistogram() [1/2]

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

view_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getHistogram ( )

inline

Returns the Kokkos View containing the histogram bin counts.

Definition at line 188 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m.

◆ getHistogram() [2/2]

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

view_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getHistogram ( ) const

inline

Definition at line 189 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m.

◆ getHostView()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

template<typename return_type , typename HistogramType >

static constexpr return_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getHostView ( HistogramType histo )

inlinestaticconstexpr

Retrieves a host view of the given histogram.

This function returns a host view of the provided histogram object. If a DualView is used, it calls the view_host(), otherwise it returns the normal view.

Template Parameters

HistogramType The type of the histogram object.

Parameters

histo The histogram object from which to retrieve the host view.

Returns: A host view of the histogram object.

Definition at line 411 of file BinHisto.h.

◆ getNPartInBin()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

size_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getNPartInBin ( bin_index_type binIndex )

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

Template Parameters

UseDualView A boolean template parameter indicating whether DualView is used.

Parameters

binIndex The index of the bin for which the number of particles is to be retrieved.

Returns: The number of particles in the specified bin.

Definition at line 165 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m.

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

◆ getPostSum()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

view_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getPostSum ( )

inline

Returns the Kokkos View containing the post-sum of bin counts.

Definition at line 194 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::postSum_m.

◆ init()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::init ( )

inline

Synchronizes the histogram view and initializes the bin widths and post-sum.

Note: The bin widths are assumed to be constant. Should only be called the first time the histogram is created.

Definition at line 233 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initConstBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initPostSum(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::sync(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::totalBinWidth_m.

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

Here is the call graph for this function:

◆ initConstBinWidths()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initConstBinWidths ( const value_type constBinWidth )

inline

Initializes the bin widths with a constant value.

Parameters

constBinWidth The constant value to set for all bin widths.

Note: Should not be called again after merging bins, since the bin widths won't be uniform.

Definition at line 248 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bDeviceSyncronizationT, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bHistogramInitT, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binWidths_m, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::numBins_m.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::init().

◆ initPostSum()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initPostSum ( )

inline

Initializes and computes the post-sum for the histogram.

This function initializes the post-sum by computing the fixed sum on the device view of the post-sum member. If the UseDualView constant is true, it modifies the device view and synchronizes it with the host.

Definition at line 276 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bDeviceSyncronizationT, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bHistogramInitT, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::postSum_m.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::init().

◆ initTimers()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initTimers ( )

inlineprivate

Initializes timers for various operations in the binning process.

Timers initialized:

bDeviceSyncronizationT: Measures the time taken for device synchronization.
bHistogramInitT: Measures the time taken to initialize histograms.
bMergeBinsT: Measures the time taken to merge bins.

Definition at line 519 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bDeviceSyncronizationT, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bHistogramInitT, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bMergeBinsT.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::Histogram().

◆ instantiateHistograms()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::instantiateHistograms ( )

inlineprivate

Instantiates the histogram, bin widths, and post-sum views (Possibly DualView).

Definition at line 528 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binWidths_m, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::numBins_m, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::postSum_m.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::Histogram().

◆ mergeBins()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

hindex_transform_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::mergeBins ( )

Merges bins in a histogram to reduce the number of bins while minimizing a cost function.

This function performs adaptive binning by merging adjacent bins in a histogram. The merging process is guided by a cost function that evaluates the deviation introduced by merging bins. The goal is to minimize the total cost while reducing the number of bins.

Returns: A Kokkos View mapping old bin indices to new bin indices after merging.

The function performs the following steps:

Ensures the histogram is available on the host (if using DualView).
Computes prefix sums for bin counts and widths on the host.
Uses dynamic programming to find the optimal bin merging strategy that minimizes the total cost.
Reconstructs the boundaries of the merged bins based on the dynamic programming results.
Builds new arrays for the merged bins, including counts and widths.
Generates a lookup table mapping old bin indices to new bin indices.
Overwrites the old histogram arrays with the new merged ones.
If using DualView, marks the host data as modified and synchronizes with the device.
Recomputes the post-sum for the new merged histogram.

The cost function used for merging is defined by adaptiveBinningCostFunction(), which evaluates the deviation introduced by merging bins based on their counts and widths.

Note: This function assumes that the histogram has been generated with a sufficiently large number of bins (e.g., 128 bins). If the number of bins is too small (<= 1), merging is skipped.

Warning: If no feasible merges are found, the function falls back to a no-merge scenario and logs a warning.

◆ modify_device()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::modify_device ( )

inline

If a DualView is used, it sets the flag on the view that the device has been modified.

See also: sync() After this function you might call sync at some point.

Definition at line 365 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m.

◆ modify_host()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::modify_host ( )

inline

If a DualView is used, it sets the flag on the view that the host has been modified.

See also: sync() After this function you might call sync at some point.

Definition at line 375 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m.

◆ operator=()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

Histogram & ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::operator= ( const Histogram< size_type, bin_index_type, value_type, UseDualView, Properties > & other )

inline

Assignment operator for copying the fields from another Histogram object.

See also: copyFields() for more information on how the fields are copied (uses Kokkos shallow copy).

Definition at line 144 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::copyFields().

Here is the call graph for this function:

◆ printHistogram()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printHistogram ( std::ostream & os = std::cout )

inline

Prints a nicely formatted table of bin indices, counts, and widths.

Parameters

os	The output stream to write to (defaults to std::cout).

Definition at line 575 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binWidths_m, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::debug_name_m, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::numBins_m, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::totalBinWidth_m.

◆ printPythonArrays()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printPythonArrays ( ) const

inline

Definition at line 605 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binWidths_m, ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::numBins_m.

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

◆ sync()

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

void ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::sync ( )

inline

Synchronizes the histogram data between host and device.

This function checks if the histogram data needs to be synchronized between the host and the device. If both the host and device have modifications, it issues a warning and overwrites the changes on the host. It then performs the necessary synchronization based on where the modifications occurred.

Note: This function only performs synchronization if the UseDualView template parameter is true. Otherwise it does nothing.

Definition at line 342 of file BinHisto.h.

References ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bDeviceSyncronizationT, and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::init().

Member Data Documentation

◆ bDeviceSyncronizationT

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

IpplTimings::TimerRef ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bDeviceSyncronizationT

private

View storing the cumulative sum of bin counts (used in sorting, generating range policies).

Definition at line 561 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::copyBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initConstBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initPostSum(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initTimers(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::sync().

◆ bHistogramInitT

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

IpplTimings::TimerRef ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bHistogramInitT

private

Definition at line 562 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initConstBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initPostSum(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initTimers().

◆ binningAlpha_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

value_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binningAlpha_m

private

Total width of all bins combined.

Definition at line 549 of file BinHisto.h.

◆ binningBeta_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

value_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binningBeta_m

private

Alpha parameter for the adaptive binning (merging) cost function.

Definition at line 551 of file BinHisto.h.

◆ binWidths_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

width_view_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::binWidths_m

private

View storing the particle counts in each bin.

Definition at line 557 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::copyBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initConstBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::instantiateHistograms(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printHistogram(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printPythonArrays().

◆ bMergeBinsT

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

IpplTimings::TimerRef ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::bMergeBinsT

private

Definition at line 563 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initTimers().

◆ debug_name_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

std::string ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::debug_name_m

private

Definition at line 545 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printHistogram().

◆ desiredWidth_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

value_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::desiredWidth_m

private

Beta parameter for the adaptive binning (merging) cost function.

Definition at line 553 of file BinHisto.h.

◆ histogram_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

view_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::histogram_m

private

Desired width for the adaptive binning (merging) cost function.

Definition at line 556 of file BinHisto.h.

◆ numBins_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

bin_index_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::numBins_m

private

Debug name for identifying the histogram instance.

Definition at line 546 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getCurrentBinCount(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initConstBinWidths(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::instantiateHistograms(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printHistogram(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printPythonArrays().

◆ postSum_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

view_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::postSum_m

private

View storing the widths of the bins.

Definition at line 558 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getBinIterationPolicy(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::getPostSum(), ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::initPostSum(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::instantiateHistograms().

◆ totalBinWidth_m

template<typename size_type , typename bin_index_type , typename value_type , bool UseDualView = false, class... Properties>

value_type ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::totalBinWidth_m

private

Number of bins in the histogram.

Definition at line 547 of file BinHisto.h.

Referenced by ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::init(), and ParticleBinning::Histogram< size_type, bin_index_type, value_type, UseDualView, Properties >::printHistogram().

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

BinHisto.h

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ dindex_transform_type

◆ dview_type

◆ dwidth_view_type

◆ hindex_transform_type

◆ hview_type

◆ hwidth_view_type

◆ index_transform_type

◆ view_type

◆ width_view_type

Constructor & Destructor Documentation

◆ Histogram() [1/3]

◆ Histogram() [2/3]

◆ Histogram() [3/3]

Member Function Documentation

◆ adaptiveBinningCostFunction()

◆ copyBinWidths()

◆ copyFields()

◆ getBinIterationPolicy()

◆ getBinWidths()

◆ getCurrentBinCount()

◆ getDeviceView()

◆ getHistogram() [1/2]

◆ getHistogram() [2/2]

◆ getHostView()

◆ getNPartInBin()

◆ getPostSum()

◆ init()

◆ initConstBinWidths()

◆ initPostSum()

◆ initTimers()

◆ instantiateHistograms()

◆ mergeBins()

◆ modify_device()

◆ modify_host()

◆ operator=()

◆ printHistogram()

◆ printPythonArrays()

◆ sync()

Member Data Documentation

◆ bDeviceSyncronizationT

◆ bHistogramInitT

◆ binningAlpha_m

◆ binningBeta_m

◆ binWidths_m

◆ bMergeBinsT

◆ debug_name_m

◆ desiredWidth_m

◆ histogram_m

◆ numBins_m

◆ postSum_m

◆ totalBinWidth_m