Template Numerical Library: TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize > Class Template Reference

Template Numerical Library version\ main:16b9213d5

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize > Class Template Reference

Data structure for Bisection Ellpack segments. More...

`#include <TNL/Algorithms/Segments/BiEllpack.h>`

Inheritance diagram for TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >:
[legend]
Collaboration diagram for TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >:
[legend]

## 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 >
template<typename Device_ = Device, typename Index_ = Index, typename IndexAllocator_ = typename Allocators::Default< Device_ >::template Allocator< Index_ >, ElementsOrganization Organization_ = Organization, int WarpSize_ = WarpSize>
using | Self = BiEllpack< Device_, Index_, IndexAllocator_, Organization_, WarpSize_ >
| Templated type for creating BiEllpack segments with different template parameters.
template<typename Device_ = Device, typename Index_ = Index>
using | ViewTemplate = BiEllpackView< Device_, Index_, Organization, WarpSize >
| Templated view type.
using | ViewType = BiEllpackView< Device, Index, Organization, WarpSize >
| Type of segments view.
Public Types inherited from TNL::Algorithms::Segments::BiEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization(), 32 >
using | ConstOffsetsView
| The type for representing the constant vector view with offsets of the BiEllpack groups.
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 offsets of the BiEllpack groups.
using | SegmentViewType
| Accessor type for one particular segment.

## Public Member Functions
| BiEllpack ()=default
| Constructor with no parameters to create empty segments.
| BiEllpack (BiEllpack &&segments) noexcept=default
| Move constructor.
| BiEllpack (const BiEllpack &segments)
| Copy constructor (makes deep copy).
template<typename SizesContainer, std::enable_if_t< IsArrayType< SizesContainer >::value, bool > = true>
| BiEllpack (const SizesContainer &segmentsSizes)
| Constructor that initializes segments based on their sizes.
template<typename ListIndex>
| BiEllpack (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.
template<typename SizesHolder>
void | initGroupPointers (const SizesHolder &segmentsSizes)
void | load (File &file)
| Method for loading the segments from a file in a binary form.
BiEllpack & | operator= (BiEllpack &&segments) noexcept(false)
| Move-assignment operator.
BiEllpack & | operator= (const BiEllpack &segments)
| Copy-assignment operator (makes a deep copy).
template<typename Device_, typename Index_, typename IndexAllocator_, ElementsOrganization Organization_>
BiEllpack & | operator= (const BiEllpack< Device_, Index_, IndexAllocator_, Organization_, WarpSize > &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 SizesHolder>
void | setSegmentsSizes (const SizesHolder &sizes)
| Set sizes of particular segments.
Public Member Functions inherited from TNL::Algorithms::Segments::BiEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization(), 32 >
__cuda_callable__ | BiEllpackBase ()=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 | getElementCount () const
| Returns the number of elements managed by all segments.
__cuda_callable__ IndexType | getGlobalIndex (Index segmentIdx, Index localIdx) const
| Computes the global index of an element managed by the segments.
__cuda_callable__ OffsetsView | getGroupPointersView ()
| Returns a view containing the pointers to the beginning of each segment.
__cuda_callable__ IndexType | getSegmentCount () const
| Returns the number of segments.
__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 | getSegmentsPermutationView ()
| Returns a view containing the permutation of segments.
__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__ IndexType | getStorageSize () const
| Returns number of elements that needs to be allocated by a container connected to this segments.
__cuda_callable__ IndexType | getVirtualSegments () const
BiEllpackBase & | operator= (const BiEllpackBase &)=delete
| Copy-assignment operator.
void | printStructure (std::ostream &str) const
| Prints the structure of the segments to the specified output stream.

## Protected Member Functions
Index | getStripLength (Index strip) const
template<typename SizesHolder>
void | initSegmentsPermutation (const SizesHolder &segmentsSize)
template<typename SizesHolder>
void | verifySegmentLengths (const SizesHolder &segmentsSizes)
template<typename SizesHolder>
void | verifySegmentPerm (const SizesHolder &segmentsSizes)
Protected Member Functions inherited from TNL::Algorithms::Segments::BiEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization(), 32 >
__cuda_callable__ void | bind (IndexType size, IndexType storageSize, OffsetsView segmentsPermutation, OffsetsView groupPointers)
| Re-initializes the internal attributes of the base class.

## Protected Attributes
OffsetsContainer | groupPointers
OffsetsContainer | segmentsPermutation
Protected Attributes inherited from TNL::Algorithms::Segments::BiEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization(), 32 >
OffsetsView | groupPointers
OffsetsView | segmentsPermutation
IndexType | size
IndexType | storageSize

## Additional Inherited Members
Static Public Member Functions inherited from TNL::Algorithms::Segments::BiEllpackBase< Device, Index, DefaultElementsOrganization< Device >::getOrganization(), 32 >
static constexpr int | getLogWarpSize ()
| Returns the log2 of the warp size used for the segments.
static constexpr ElementsOrganization | getOrganization ()
| Returns the data layout for the biellpack 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 int | getWarpSize ()
| Returns the warp size used for the segments.
static constexpr bool | havePadding ()
| This function denotes that the biellpack 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(), int WarpSize = 32>
class TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >

Data structure for Bisection Ellpack segments.

Bisection Ellpack segments are inspired by the following paper:

[C. Zheng, S. Gu, T.-X. Gu, B. Yang, X.-P. Liu, BiELL: A bisection ELLPACK-based storage format for optimizing SpMV on GPUs, Journal of Parallel and Distributed Computing, Volume 74, Issue 7, 2014, pp. 2639-2647](https://www.sciencedirect.com/science/article/pii/S0743731514000458).

This format is designed to improve load balancing for segments with unevenly distributed sizes. It uses more meta-information compared to, for example, TNL::Algorithms::Segments::CSR, which can introduce overhead. However, it can be beneficial for reduction operations, particularly for longer segments with significant size variations.

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.
  WarpSize | The warp size used for the segments.

## Member Typedef Documentation

## ◆ Self

template<typename Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>
template<typename Device_ = Device, typename Index_ = Index, typename IndexAllocator_ = typename Allocators::Default< Device_ >::template Allocator< Index_ >, ElementsOrganization Organization_ = Organization, int WarpSize_ = WarpSize>

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

Templated type for creating BiEllpack segments with different template parameters.

Template Parameters

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

## ◆ ViewTemplate

template<typename Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>
template<typename Device_ = Device, typename Index_ = Index>

using TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >::ViewTemplate = BiEllpackView< Device_, Index_, Organization, WarpSize >

Templated view type.

Template Parameters

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

## Constructor & Destructor Documentation

## ◆ BiEllpack() [1/2]

template<typename Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>
template<typename SizesContainer, std::enable_if_t< IsArrayType< SizesContainer >::value, bool > = true>

TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >::BiEllpack | ( | 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:

1#include <iostream>
2#include <TNL/Containers/Vector.h>
3#include <TNL/Algorithms/Segments/traverse.h>
4#include <TNL/Devices/Host.h>
5#include <TNL/Devices/Cuda.h>
6
7template< typename Segments >
8void
9SegmentsExample()
10{
11 using Device = typename Segments::DeviceType;
12
13 /***
14 * Create segments with given segments sizes.
15 */
16 TNL::Containers::Vector< int, Device > segmentsSizes{ 1, 2, 3, 4, 5 };
17 Segments segments( segmentsSizes );
18 std::cout << "Segments sizes are: " << segments << '\n';
19
20 /***
21 * Allocate array for the segments;
22 */
23 TNL::Containers::Array< double, Device > data( segments.getStorageSize(), 0.0 );
24
25 /***
26 * Insert data into particular segments.
27 */
28 auto data_view = data.getView();
29 TNL::Algorithms::Segments::forAllElements(
30 segments,
31 [ = ] __cuda_callable__( int segmentIdx, int localIdx, int globalIdx ) mutable
32 {
33 if( localIdx <= segmentIdx )
34 data_view[ globalIdx ] = segmentIdx;
35 } );
36
37 /***
38 * Print the data managed by the segments.
39 */
40 auto fetch = [ = ] __cuda_callable__( int globalIdx ) -> double
41 {
42 return data_view[ globalIdx ];
43 };
44 std::cout << TNL::Algorithms::Segments::print( segments, fetch ) << '\n';
45}
46
47int
48main( int argc, char* argv[] )
49{
50 std::cout << "Example of CSR segments on host:\n";
51 SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Host, int > >();
52
53 std::cout << "Example of Ellpack segments on host:\n";
54 SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Host, int > >();
55
56#ifdef __CUDACC__
57 std::cout << "Example of CSR segments on CUDA GPU:\n";
58 SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Cuda, int > >();
59
60 std::cout << "Example of Ellpack segments on CUDA GPU:\n";
61 SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Cuda, int > >();
62#endif
63 return EXIT_SUCCESS;
64}
__cuda_callable__
#define __cuda_callable__
Definition Macros.h:49
std::cout
TNL::Containers::Array
Array is responsible for memory management, access to array elements, and general array operations.
Definition Array.h:65
TNL::Containers::Vector
Vector extends Array with algebraic operations.
Definition Vector.h:37
TNL::Algorithms::Segments
Namespace for the segments data structures.
Definition _NamespaceDoxy.h:7
TNL::Algorithms::Segments::print
SegmentsPrinter< typename Segments::ConstViewType, Fetch > print(const Segments &segments, Fetch fetch)
Print segments sizes, i.e. the segments setup.
TNL::Algorithms::Segments::forAllElements
void forAllElements(const Segments &segments, Function &&function, LaunchConfiguration launchConfig=Algorithms::Segments::LaunchConfiguration())
Iterates in parallel over all elements of all segments and applies the specified lambda function.

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 ]

## ◆ BiEllpack() [2/2]

template<typename Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>
template<typename ListIndex>

TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >::BiEllpack | ( | 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:

1#include <iostream>
2#include <TNL/Containers/Vector.h>
3#include <TNL/Algorithms/Segments/traverse.h>
4#include <TNL/Devices/Host.h>
5#include <TNL/Devices/Cuda.h>
6
7template< typename Segments >
8void
9SegmentsExample()
10{
11 using Device = typename Segments::DeviceType;
12
13 /***
14 * Create segments with given segments sizes.
15 */
16 Segments segments{ 1, 2, 3, 4, 5 };
17 std::cout << "Segments sizes are: " << segments << '\n';
18
19 /***
20 * Allocate array for the segments;
21 */
22 TNL::Containers::Array< double, Device > data( segments.getStorageSize(), 0.0 );
23
24 /***
25 * Insert data into particular segments.
26 */
27 auto data_view = data.getView();
28 TNL::Algorithms::Segments::forAllElements(
29 segments,
30 [ = ] __cuda_callable__( int segmentIdx, int localIdx, int globalIdx ) mutable
31 {
32 if( localIdx <= segmentIdx )
33 data_view[ globalIdx ] = segmentIdx;
34 } );
35
36 /***
37 * Print the data managed by the segments.
38 */
39 auto fetch = [ = ] __cuda_callable__( int globalIdx ) -> double
40 {
41 return data_view[ globalIdx ];
42 };
43 std::cout << TNL::Algorithms::Segments::print( segments, fetch ) << '\n';
44}
45
46int
47main( int argc, char* argv[] )
48{
49 std::cout << "Example of CSR segments on host:\n";
50 SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Host, int > >();
51
52 std::cout << "Example of Ellpack segments on host:\n";
53 SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Host, int > >();
54
55#ifdef __CUDACC__
56 std::cout << "Example of CSR segments on CUDA GPU:\n";
57 SegmentsExample< TNL::Algorithms::Segments::CSR< TNL::Devices::Cuda, int > >();
58
59 std::cout << "Example of Ellpack segments on CUDA GPU:\n";
60 SegmentsExample< TNL::Algorithms::Segments::Ellpack< TNL::Devices::Cuda, int > >();
61#endif
62 return EXIT_SUCCESS;
63}

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 ]

## Member Function Documentation

## ◆ load()

template<typename Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>

void TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >::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 = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>
template<typename Device_, typename Index_, typename IndexAllocator_, ElementsOrganization Organization_>

BiEllpack & TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >::operator= | ( | const BiEllpack< Device_, Index_, IndexAllocator_, Organization_, WarpSize > & | 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()

template<typename Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>

void TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >::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 Device, typename Index, typename IndexAllocator = typename Allocators::Default< Device >::template Allocator< Index >, ElementsOrganization Organization = DefaultElementsOrganization< Device >::getOrganization(), int WarpSize = 32>
template<typename SizesHolder>

void TNL::Algorithms::Segments::BiEllpack< Device, Index, IndexAllocator, Organization, WarpSize >::setSegmentsSizes | ( | const SizesHolder & | sizes | ) |

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

  sizes | is an instance of the container with segments sizes.

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

- src/TNL/Algorithms/Segments/BiEllpack.h