Template Numerical Library: TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization

Data structure for Chunked Ellpack segments. More...

#include <TNL/Algorithms/Segments/ChunkedEllpack.h>

Inheritance diagram for TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >:

Collaboration diagram for TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >:

Public Types
using	ConstViewType = typename ViewType::ConstViewType
	Type of constant segments view.
using	IndexAllocatorType = IndexAllocator
using	OffsetsContainer = Containers::Vector< Index, Device, typename Base::IndexType, IndexAllocator >
	Type of container storing offsets of particular segments.
template<typename Device_ = Device, typename Index_ = Index, typename IndexAllocator_ = typename Allocators::Default< Device_ >::template Allocator< Index_ >, ElementsOrganization Organization_ = Organization>
using	Self = ChunkedEllpack< Device_, Index_, IndexAllocator_, Organization_ >
	Templated type for creating ChunkedEllpack segments with different template parameters.
using	SliceInfoAllocator = typename Allocators::Default< Device >::template Allocator< typename Base::SliceInfoType >
using	SliceInfoContainer
template<typename Device_, typename Index_>
using	ViewTemplate = ChunkedEllpackView< Device_, Index_, Organization >
	Templated view type.
using	ViewType = ChunkedEllpackView< Device, Index, Organization >
	Type of segments view.
Public Types inherited from TNL::Algorithms::Segments::ChunkedEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization() >
using	ConstOffsetsView
	The type for representing the constant vector view with segment offsets.
using	ConstSliceInfoContainerView
using	DeviceType
	The device where the segments are operating.
using	IndexType
	The type used for indexing of segments elements.
using	OffsetsView
	The type for representing the vector view with segment offsets.
using	SegmentViewType
	Accessor type for one particular segment.
using	SliceInfoContainerView
using	SliceInfoType
using	ViewTemplate
	Templated view type.

Public Member Functions
	ChunkedEllpack ()=default
	Constructor with no parameters to create empty segments.
	ChunkedEllpack (ChunkedEllpack &&segments) noexcept=default
	Move constructor.
	ChunkedEllpack (const ChunkedEllpack &segments)
	Copy constructor (makes deep copy).
template<typename SizesContainer, std::enable_if_t< IsArrayType< SizesContainer >::value, bool > = true>
	ChunkedEllpack (const SizesContainer &segmentsSizes)
	Constructor that initializes segments based on their sizes.
template<typename ListIndex>
	ChunkedEllpack (const std::initializer_list< ListIndex > &segmentsSizes)
	Constructor that initializes segments using an initializer list.
ConstViewType	getConstView () const
	Returns a constant view for this instance of segments which can by used for example in lambda functions running in GPU kernels.
ViewType	getView ()
	Returns a view for this instance of segments which can by used for example in lambda functions running in GPU kernels.
void	load (File &file)
	Method for loading the segments from a file in a binary form.
ChunkedEllpack &	operator= (ChunkedEllpack &&) noexcept(false)
	Move-assignment operator.
ChunkedEllpack &	operator= (const ChunkedEllpack &segments)
	Copy-assignment operator (makes a deep copy).
template<typename Device_, typename Index_, typename IndexAllocator_, ElementsOrganization Organization_>
ChunkedEllpack &	operator= (const ChunkedEllpack< Device_, Index_, IndexAllocator_, Organization_ > &segments)
	Assignment operator for segments with different template parameters.
void	reset ()
	Reset the segments to empty states (it means that there is no segment in the segments).
void	save (File &file) const
	Method for saving the segments to a file in a binary form.
template<typename SizesContainer>
void	setSegmentsSizes (const SizesContainer &segmentsSizes)
	Set sizes of particular segments.
Public Member Functions inherited from TNL::Algorithms::Segments::ChunkedEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization() >
__cuda_callable__	ChunkedEllpackBase ()=default
	Default constructor with no parameters to create empty segments view.
void	forAllElements (Function &&function) const
void	forAllElementsIf (Condition condition, Function function) const
void	forAllSegments (Function &&function) const
void	forElements (IndexType begin, IndexType end, Function &&function) const
void	forElementsIf (IndexType begin, IndexType end, Condition condition, Function function) const
void	forSegments (IndexType begin, IndexType end, Function &&function) const
__cuda_callable__ IndexType	getChunksInSlice () const
	Returns the number of chunks in a slice.
__cuda_callable__ OffsetsView	getChunksToSegmentsMappingView ()
	Returns a modifiable vector view with mapping of chunks to segments.
__cuda_callable__ IndexType	getDesiredChunkSize () const
	Returns the desired chunk size.
__cuda_callable__ IndexType	getElementCount () const
	Returns the number of elements managed by all segments.
__cuda_callable__ IndexType	getGlobalIndex (IndexType segmentIdx, IndexType localIdx) const
	Computes the global index of an element managed by the segments.
__cuda_callable__ IndexType	getNumberOfSlices () const
	Returns the number of slices.
__cuda_callable__ IndexType	getSegmentCount () const
	Returns the number of segments.
__cuda_callable__ OffsetsView	getSegmentPointersView ()
	Returns a modifiable vector view with segment pointers.
__cuda_callable__ IndexType	getSegmentsCount () const
	Returns the number of segments. Deprecated, use getSegmentCount().
__cuda_callable__ IndexType	getSegmentSize (IndexType segmentIdx) const
	Returns the size of a particular segment denoted by segmentIdx.
__cuda_callable__ OffsetsView	getSegmentToChunkMappingView ()
	Returns a modifiable vector view with mapping of segments to chunks.
__cuda_callable__ OffsetsView	getSegmentToSliceMappingView ()
	Returns a modifiable vector view with mapping of segments to slices.
__cuda_callable__ SegmentViewType	getSegmentView (IndexType segmentIdx) const
	Returns a segment view (i.e., a segment accessor) for the specified segment index.
__cuda_callable__ IndexType	getSize () const
	Returns the number of elements managed by all segments.
__cuda_callable__ SliceInfoContainerView	getSlicesView ()
	Returns a modifiable view with slice information.
__cuda_callable__ IndexType	getStorageSize () const
	Returns number of elements that needs to be allocated by a container connected to this segments.
ChunkedEllpackBase &	operator= (const ChunkedEllpackBase &)=delete
	Copy-assignment operator.
void	printStructure (std::ostream &str) const
	Prints the structure of the segments to the output stream.

Protected Member Functions
template<typename SizesContainer>
void	resolveSliceSizes (SizesContainer &segmentsSizes)
template<typename SizesContainer>
bool	setSlice (SizesContainer &segmentsSizes, Index sliceIndex, Index &elementsToAllocation)
Protected Member Functions inherited from TNL::Algorithms::Segments::ChunkedEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization() >
__cuda_callable__ void	bind (IndexType size, IndexType storageSize, IndexType numberOfSlices, IndexType chunksInSlice, IndexType desiredChunkSize, OffsetsView segmentToChunkMapping, OffsetsView segmentToSliceMapping, OffsetsView chunksToSegmentsMapping, OffsetsView segmentPointers, SliceInfoContainerView slices)
	Re-initializes the internal attributes of the base class.

Protected Attributes
OffsetsContainer	chunksToSegmentsMapping
OffsetsContainer	segmentPointers
	Keeps index of the first segment index.
OffsetsContainer	segmentToChunkMapping
	For each segment, this keeps index of the first chunk within a slice.
OffsetsContainer	segmentToSliceMapping
	For each segment, this keeps index of the slice which contains the segment.
SliceInfoContainer	slices
Protected Attributes inherited from TNL::Algorithms::Segments::ChunkedEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization() >
IndexType	chunksInSlice
OffsetsView	chunksToSegmentsMapping
IndexType	desiredChunkSize
IndexType	numberOfSlices
OffsetsView	segmentPointers
	Keeps index of the first segment index.
OffsetsView	segmentToChunkMapping
	For each segment, this keeps index of the first chunk within a slice.
OffsetsView	segmentToSliceMapping
	For each segment, this keeps index of the slice which contains the segment.
IndexType	size
SliceInfoContainerView	slices
IndexType	storageSize

Additional Inherited Members
Static Public Member Functions inherited from TNL::Algorithms::Segments::ChunkedEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization() >
static constexpr ElementsOrganization	getOrganization ()
	Returns the data layout for the chunked ellpack format (it is always row-major order).
static std::string	getSegmentsType ()
	Returns string with the segments type.
static std::string	getSerializationType ()
	Returns string with the serialization type.
static constexpr bool	havePadding ()
	This function denotes that the chunked ellpack format uses padding elements.

Detailed Description

template<typename Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization()>
class TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >

Data structure for Chunked Ellpack segments.

Chunked Ellpack segments are inspired by the paper [Heller M., Oberhuber T., Improved Row-grouped CSR Format for Storing of Sparse Matrices on GPU, Proceedings of Algoritmy 2012, 2012, Handlovičová A., Minarechová Z. and Ševčovič D. (ed.), pages 282-290](https://geraldine.fjfi.cvut.cz/~oberhuber/data/vyzkum/publikace/12-heller-oberhuber-improved-rgcsr-format.pdf).

See TNL::Algorithms::Segments for more details about segments.

Template Parameters

Device	The type of device on which the segments will operate.
Index	The type used for indexing elements managed by the segments.
IndexAllocator	The allocator used for managing index containers.
Organization	The organization of the elements in the segments—either row-major or column-major order.

Member Typedef Documentation

◆ Self

template<typename Device_ = Device, typename Index_ = Index, typename IndexAllocator_ = typename Allocators::Default< Device_ >::template Allocator< Index_ >, ElementsOrganization Organization_ = Organization>

using TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::Self = ChunkedEllpack< Device_, Index_, IndexAllocator_, Organization_ >

Templated type for creating ChunkedEllpack segments with different template parameters.

Template Parameters

Device_	is alternative device type.
Index_	is alternative index type.
IndexAllocator_	is alternative index allocator type.

◆ SliceInfoContainer

using TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::SliceInfoContainer

Initial value:

Containers::Array<
     typename TNL::copy_const< typename Base::SliceInfoType >::template from< Index >::type,
     Device,
     Index,
     SliceInfoAllocator >

◆ ViewTemplate

template<typename Device_, typename Index_>

using TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::ViewTemplate = ChunkedEllpackView< Device_, Index_, Organization >

Templated view type.

Template Parameters

Device_	is alternative device type for the view.
Index_	is alternative index type for the view.

Constructor & Destructor Documentation

◆ ChunkedEllpack() [1/2]

template<typename SizesContainer, std::enable_if_t< IsArrayType< SizesContainer >::value, bool > = true>

TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::ChunkedEllpack ( const SizesContainer & segmentsSizes )

Constructor that initializes segments based on their sizes.

The number of segments is determined by the size of segmentsSizes. Each element in this container specifies the size of a corresponding segment.

Template Parameters

SizesContainer The type of container used to store segment sizes. It can be, for example, TNL::Containers::Array or TNL::Containers::Vector.

Parameters

segmentsSizes An instance of the container holding the sizes of the segments.

See the following example:

#include <iostream>
#include <TNL/Containers/Vector.h>
#include <TNL/Algorithms/Segments/traverse.h>
#include <TNL/Devices/Host.h>
#include <TNL/Devices/Cuda.h>
 
template< typename Segments >
void
SegmentsExample()
{
   using Device = typename Segments::DeviceType;
 
   /***
    * Create segments with given segments sizes.
    */
   TNL::Containers::Vector< int, Device > segmentsSizes{ 1, 2, 3, 4, 5 };
   Segments segments( segmentsSizes );
   std::cout << "Segments sizes are: " << segments << '\n';
 
   /***
    * Allocate array for the segments;
    */
   TNL::Containers::Array< double, Device > data( segments.getStorageSize(), 0.0 );
 
   /***
    * Insert data into particular segments.
    */
   auto data_view = data.getView();
   TNL::Algorithms::Segments::forAllElements(
      segments,
      [ = ] __cuda_callable__( int segmentIdx, int localIdx, int globalIdx ) mutable
      {
         if( localIdx <= segmentIdx )
            data_view[ globalIdx ] = segmentIdx;
      } );
 
   /***
    * Print the data managed by the segments.
    */
   auto fetch = [ = ] __cuda_callable__( int globalIdx ) -> double
   {
      return data_view[ globalIdx ];
   };
   std::cout << TNL::Algorithms::Segments::print( segments, fetch ) << '\n';
}
 
int
main( int argc, char* argv[] )
{
   std::cout << "Example of CSR segments on host:\n";
   SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Host, int > >();
 
   std::cout << "Example of Ellpack segments on host:\n";
   SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Host, int > >();
 
#ifdef __CUDACC__
   std::cout << "Example of CSR segments on CUDA GPU:\n";
   SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Cuda, int > >();
 
   std::cout << "Example of Ellpack segments on CUDA GPU:\n";
   SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Cuda, int > >();
#endif
   return EXIT_SUCCESS;
}

The expected output is:

Example of CSR segments on host:
Segments sizes are:  [ 1, 2, 3, 4, 5 ] 
Segment 0: [ 0 ]
Segment 1: [ 1, 1 ]
Segment 2: [ 2, 2, 2 ]
Segment 3: [ 3, 3, 3, 3 ]
Segment 4: [ 4, 4, 4, 4, 4 ]
Example of Ellpack segments on host:
Segments sizes are:  [ 5, 5, 5, 5, 5 ] 
Segment 0: [ 0, 0, 0, 0, 0 ]
Segment 1: [ 1, 1, 0, 0, 0 ]
Segment 2: [ 2, 2, 2, 0, 0 ]
Segment 3: [ 3, 3, 3, 3, 0 ]
Segment 4: [ 4, 4, 4, 4, 4 ]
Example of CSR segments on CUDA GPU:
Segments sizes are:  [ 1, 2, 3, 4, 5 ] 
Segment 0: [ 0 ]
Segment 1: [ 1, 1 ]
Segment 2: [ 2, 2, 2 ]
Segment 3: [ 3, 3, 3, 3 ]
Segment 4: [ 4, 4, 4, 4, 4 ]
Example of Ellpack segments on CUDA GPU:
Segments sizes are:  [ 5, 5, 5, 5, 5 ] 
Segment 0: [ 0, 0, 0, 0, 0 ]
Segment 1: [ 1, 1, 0, 0, 0 ]
Segment 2: [ 2, 2, 2, 0, 0 ]
Segment 3: [ 3, 3, 3, 3, 0 ]
Segment 4: [ 4, 4, 4, 4, 4 ]

◆ ChunkedEllpack() [2/2]

template<typename ListIndex>

TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::ChunkedEllpack ( const std::initializer_list< ListIndex > & segmentsSizes )

Constructor that initializes segments using an initializer list.

The number of segments is determined by the size of segmentsSizes. Each element in this initializer list specifies the size of a corresponding segment.

Template Parameters

ListIndex The type used for indexing elements in the initializer list.

Parameters

segmentsSizes An initializer list defining the sizes of the segments.

See the following example:

#include <iostream>
#include <TNL/Containers/Vector.h>
#include <TNL/Algorithms/Segments/traverse.h>
#include <TNL/Devices/Host.h>
#include <TNL/Devices/Cuda.h>
 
template< typename Segments >
void
SegmentsExample()
{
   using Device = typename Segments::DeviceType;
 
   /***
    * Create segments with given segments sizes.
    */
   Segments segments{ 1, 2, 3, 4, 5 };
   std::cout << "Segments sizes are: " << segments << '\n';
 
   /***
    * Allocate array for the segments;
    */
   TNL::Containers::Array< double, Device > data( segments.getStorageSize(), 0.0 );
 
   /***
    * Insert data into particular segments.
    */
   auto data_view = data.getView();
   TNL::Algorithms::Segments::forAllElements(
      segments,
      [ = ] __cuda_callable__( int segmentIdx, int localIdx, int globalIdx ) mutable
      {
         if( localIdx <= segmentIdx )
            data_view[ globalIdx ] = segmentIdx;
      } );
 
   /***
    * Print the data managed by the segments.
    */
   auto fetch = [ = ] __cuda_callable__( int globalIdx ) -> double
   {
      return data_view[ globalIdx ];
   };
   std::cout << TNL::Algorithms::Segments::print( segments, fetch ) << '\n';
}
 
int
main( int argc, char* argv[] )
{
   std::cout << "Example of CSR segments on host:\n";
   SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Host, int > >();
 
   std::cout << "Example of Ellpack segments on host:\n";
   SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Host, int > >();
 
#ifdef __CUDACC__
   std::cout << "Example of CSR segments on CUDA GPU:\n";
   SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Cuda, int > >();
 
   std::cout << "Example of Ellpack segments on CUDA GPU:\n";
   SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Cuda, int > >();
#endif
   return EXIT_SUCCESS;
}

The expected output is:

Example of CSR segments on host:
Segments sizes are:  [ 1, 2, 3, 4, 5 ] 
Segment 0: [ 0 ]
Segment 1: [ 1, 1 ]
Segment 2: [ 2, 2, 2 ]
Segment 3: [ 3, 3, 3, 3 ]
Segment 4: [ 4, 4, 4, 4, 4 ]
Example of Ellpack segments on host:
Segments sizes are:  [ 5, 5, 5, 5, 5 ] 
Segment 0: [ 0, 0, 0, 0, 0 ]
Segment 1: [ 1, 1, 0, 0, 0 ]
Segment 2: [ 2, 2, 2, 0, 0 ]
Segment 3: [ 3, 3, 3, 3, 0 ]
Segment 4: [ 4, 4, 4, 4, 4 ]
Example of CSR segments on CUDA GPU:
Segments sizes are:  [ 1, 2, 3, 4, 5 ] 
Segment 0: [ 0 ]
Segment 1: [ 1, 1 ]
Segment 2: [ 2, 2, 2 ]
Segment 3: [ 3, 3, 3, 3 ]
Segment 4: [ 4, 4, 4, 4, 4 ]
Example of Ellpack segments on CUDA GPU:
Segments sizes are:  [ 5, 5, 5, 5, 5 ] 
Segment 0: [ 0, 0, 0, 0, 0 ]
Segment 1: [ 1, 1, 0, 0, 0 ]
Segment 2: [ 2, 2, 2, 0, 0 ]
Segment 3: [ 3, 3, 3, 3, 0 ]
Segment 4: [ 4, 4, 4, 4, 4 ]

Member Function Documentation

◆ load()

void TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::load ( File & file )

Method for loading the segments from a file in a binary form.

Parameters

file	is the source file.

◆ operator=()

template<typename Device_, typename Index_, typename IndexAllocator_, ElementsOrganization Organization_>

ChunkedEllpack & TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::operator= ( const ChunkedEllpack< Device_, Index_, IndexAllocator_, Organization_ > & segments )

Assignment operator for segments with different template parameters.

Performs a deep copy of the source segments.

Template Parameters

Device_	The device type of the source segments.
Index_	The index type of the source segments.
IndexAllocator_	The index allocator type of the source segments.

Parameters

segments The source segments object.

Returns: A reference to this instance.

◆ save()

void TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::save ( File & file ) const

Method for saving the segments to a file in a binary form.

Parameters

file	is the target file.

◆ setSegmentsSizes()

template<typename SizesContainer>

void TNL::Algorithms::Segments::ChunkedEllpack< Device, Index, IndexAllocator, Organization >::setSegmentsSizes ( const SizesContainer & segmentsSizes )

Set sizes of particular segments.

Template Parameters

SizesContainer is a container with segments sizes. It can be TNL::Containers::Array or TNL::Containers::Vector for example.

Parameters

segmentsSizes is an instance of the container with segments sizes.

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

src/TNL/Algorithms/Segments/ChunkedEllpack.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Self

◆ SliceInfoContainer

◆ ViewTemplate

Constructor & Destructor Documentation

◆ ChunkedEllpack() [1/2]

◆ ChunkedEllpack() [2/2]

Member Function Documentation

◆ load()

◆ operator=()

◆ save()

◆ setSegmentsSizes()