Blaze 3.9
Vector Types


Dense Vectors


StaticVector

The blaze::StaticVector class template is the representation of a fixed size vector with statically allocated elements of arbitrary type. It can be included via the header files

#include <blaze/Blaze.h>
// or
#include <blaze/Math.h>
// or
Primary include file of the Blaze library.
Header file for the inclusion of the math module of the Blaze library.
Header file for the complete StaticVector implementation.

and forward declared via the header file

#include <blaze/Forward.h>
Header file for all forward declarations of the Blaze library.

The type of the elements, the number of elements, the transpose flag, the alignment, the padding, and the group tag of the vector can be specified via the six template parameters:

namespace blaze {
template< typename Type, size_t N, bool TF, AlignmentFlag AF, PaddingFlag PF, typename Tag >
class StaticVector;
} // namespace blaze
  • Type: specifies the type of the vector elements. StaticVector can be used with any non-cv-qualified, non-reference, non-pointer element type.
  • N : specifies the total number of vector elements. It is expected that StaticVector is only used for tiny and small vectors.
  • TF : specifies whether the vector is a row vector (blaze::rowVector) or a column vector (blaze::columnVector). The default value is blaze::defaultTransposeFlag.
  • AF : specifies whether the first element of the vector is properly aligned with respect to the available instruction set (SSE, AVX, ...). Possible values are blaze::aligned and blaze::unaligned. The default value is blaze::defaultAlignmentFlag.
  • PF : specifies whether the vector should be padded to maximize the efficiency of vectorized operations. Possible values are blaze::padded and blaze::unpadded. The default value is blaze::defaultPaddingFlag.
  • Tag : optional type parameter to tag the vector. The default type is blaze::Group0. See Grouping/Tagging for details.

The blaze::StaticVector is perfectly suited for small to medium vectors whose size is known at compile time:

// Definition of a 3-dimensional integral column vector
// Definition of a 4-dimensional single precision column vector
// Definition of an unaligned, unpadded 6-dimensional double precision row vector
Efficient implementation of a fixed-sized vector.
Definition: StaticVector.h:230

Alignment

In case AF is set to blaze::aligned, the elements of a blaze::StaticVector are possibly over-aligned to meet the alignment requirements of the available instruction set (SSE, AVX, AVX-512, ...). The alignment for fundamental types (short, int, float, double, ...) and complex types (complex<float>, complex<double>, ...) is 16 bytes for SSE, 32 bytes for AVX, and 64 bytes for AVX-512. All other types are aligned according to their intrinsic alignment:

struct Int { int i; };
alignof( VT1 ); // Evaluates to 16 for SSE, 32 for AVX, and 64 for AVX-512
alignof( VT2 ); // Evaluates to 16 for SSE, 32 for AVX, and 64 for AVX-512
alignof( VT3 ); // Evaluates to 'alignof( Int )'

Note that an aligned blaze::StaticVector instance may be bigger than the sum of its data elements:

sizeof( VT1 ); // Evaluates to 32 for both SSE and AVX
sizeof( VT2 ); // Evaluates to 16 for SSE and 32 for AVX
sizeof( VT3 ); // Evaluates to 20; no special alignment requirements

Please note that for this reason an aligned blaze::StaticVector cannot be used in containers using dynamic memory such as std::vector without additionally providing an allocator that can provide over-aligned memory:

std::vector<Type> v1; // Might be misaligned for AVX or AVX-512
std::vector<Type,Allocator> v2; // Properly aligned for AVX or AVX-512
Allocator for type-specific aligned memory.
Definition: AlignedAllocator.h:72

Padding

Adding padding elements to the end of a blaze::StaticVector can have a significant impact on the performance. For instance, assuming that AVX is available, then two padded 3-dimensional vectors of double precision values can be added via a single SIMD addition operation:

StaticVector<double,3UL,columnVector,aligned,padded> a1, b1, c1;
StaticVector<double,3UL,columnVector,unaligned,unpadded> a2, b2, c2;
// ... Initialization
c1 = a1 + b1; // AVX-based vector addition; maximum performance
c2 = a2 + b2; // Scalar vector addition; limited performance
sizeof( a1 ); // Evaluates to 32 for SSE and AVX, and 64 for AVX-512
sizeof( a2 ); // Evaluates to 24 for SSE, AVX, and AVX-512 (minimum size)
@ padded
Flag for padded vectors and matrices.
Definition: PaddingFlag.h:79
@ unpadded
Flag for unpadded vectors and matrices.
Definition: PaddingFlag.h:78
@ unaligned
Flag for unaligned vectors and matrices.
Definition: AlignmentFlag.h:64
@ aligned
Flag for aligned vectors and matrices.
Definition: AlignmentFlag.h:65
constexpr bool columnVector
Transpose flag for column vectors.
Definition: TransposeFlag.h:58

Due to padding, the first addition will run at maximum performance. On the flip side, the size of each vector instance is increased due to the padding elements. The total size of an instance depends on the number of elements and width of the available instruction set (16 bytes for SSE, 32 bytes for AVX, and 64 bytes for AVX-512).

The second addition will be limited in performance since due to the number of elements some of the elements need to be handled in a scalar operation. However, the size of an unaligned, unpadded blaze::StaticVector instance is guaranteed to be the sum of its elements.

Please also note that Blaze will zero initialize the padding elements in order to achieve maximum performance!


DynamicVector

The blaze::DynamicVector class template is the representation of an arbitrary sized vector with dynamically allocated elements of arbitrary type. It can be included via the header files

#include <blaze/Blaze.h>
// or
#include <blaze/Math.h>
// or
Header file for the complete DynamicVector implementation.

and forward declared via the header file

#include <blaze/Forward.h>

The type of the elements, the transpose flag, the type of the allocator, and the group tag of the vector can be specified via the four template parameters:

namespace blaze {
template< typename Type, bool TF, typename Alloc, typename Tag >
class DynamicVector;
} // namespace blaze
  • Type : specifies the type of the vector elements. DynamicVector can be used with any non-cv-qualified, non-reference, non-pointer element type.
  • TF : specifies whether the vector is a row vector (blaze::rowVector) or a column vector (blaze::columnVector). The default value is blaze::defaultTransposeFlag.
  • Alloc: specifies the type of allocator used to allocate dynamic memory. The default type of allocator is blaze::AlignedAllocator.
  • Tag : optional type parameter to tag the vector. The default type is blaze::Group0. See Grouping/Tagging for details.

The blaze::DynamicVector is the default choice for all kinds of dense vectors and the best choice for medium to large vectors. Its size can be modified at runtime:

// Definition of a 3-dimensional integral column vector
// Definition of a 4-dimensional single precision column vector
// Definition of a double precision row vector with size 0
Efficient implementation of an arbitrary sized vector.
Definition: DynamicVector.h:223

Allocators

Via the third template parameter it is possible to customize the memory allocation of a blaze::DynamicVector. The provided allocator is expected to represent an implementation of the allocator concept of the standard library (see for instance std::vector and std::allocator). In addition, the provided allocator is also required to provide properly (over-)aligned memory for fundamental and complex numbers. For instance, in case SSE vectorization is possible, the returned memory must be at least 16-byte aligned. In case AVX is active, the memory must be at least 32-byte aligned, and in case of AVX-512 the memory must be even 64-byte aligned.


HybridVector

The blaze::HybridVector class template combines the advantages of the blaze::StaticVector and the blaze::DynamicVector class templates. It represents a fixed size vector with statically allocated elements, but still can be dynamically resized (within the bounds of the available memory). It can be included via the header files

#include <blaze/Blaze.h>
// or
#include <blaze/Math.h>
// or
Header file for the complete HybridVector implementation.

and forward declared via the header file

#include <blaze/Forward.h>

The type of the elements, the maximum number of elements, the transpose flag, the alignment, the padding, and the group tag of the vector can be specified via the six template parameters:

namespace blaze {
template< typename Type, size_t N, bool TF, AlignmentFlag AF, PaddingFlag PF, typename Tag >
class HybridVector;
} // namespace blaze
  • Type: specifies the type of the vector elements. HybridVector can be used with any non-cv-qualified, non-reference, non-pointer element type.
  • N : specifies the maximum number of vector elements. It is expected that HybridVector is only used for tiny and small vectors.
  • TF : specifies whether the vector is a row vector (blaze::rowVector) or a column vector (blaze::columnVector). The default value is blaze::defaultTransposeFlag.
  • AF : specifies whether the first element of the vector is properly aligned with respect to the available instruction set (SSE, AVX, ...). Possible values are blaze::aligned and blaze::unaligned. The default value is blaze::defaultAlignmentFlag.
  • PF : specifies whether the vector should be padded to maximize the efficiency of vectorized operations. Possible values are blaze::padded and blaze::unpadded. The default value is blaze::defaultPaddingFlag.
  • Tag : optional type parameter to tag the vector. The default type is blaze::Group0. See Grouping/Tagging for details.

The blaze::HybridVector is a suitable choice for small to medium vectors, whose size is not known at compile time or not fixed at runtime, but whose maximum size is known at compile time:

// Definition of a 3-dimensional integral column vector with a maximum size of 6
// Definition of a 4-dimensional single precision column vector with a maximum size of 16
// Definition of a unaligned, unpadded double precision row vector with size 0 and a maximum size of 6
Efficient implementation of a dynamically sized vector with static memory.
Definition: HybridVector.h:222

Alignment

In case AF is set to blaze::aligned, the elements of a blaze::HybridVector are possibly over-aligned to meet the alignment requirements of the available instruction set (SSE, AVX, AVX-512, ...). The alignment for fundamental types (short, int, float, double, ...) and complex types (complex<float>, complex<double>, ...) is 16 bytes for SSE, 32 bytes for AVX, and 64 bytes for AVX-512. All other types are aligned according to their intrinsic alignment:

struct Int { int i; };
alignof( VT1 ); // Evaluates to 16 for SSE, 32 for AVX, and 64 for AVX-512
alignof( VT2 ); // Evaluates to 16 for SSE, 32 for AVX, and 64 for AVX-512
alignof( VT3 ); // Evaluates to 'alignof( Int )'

Note that an aligned blaze::HybridVector instance may be bigger than an according unaligned blaze::HybridVector:

sizeof( VT1 ); // Evaluates to 32 for both SSE and AVX
sizeof( VT2 ); // Evaluates to 16 for SSE and 32 for AVX
sizeof( VT3 ); // Evaluates to 20; no special alignment requirements

Please note that for this reason an aligned blaze::HybridVector cannot be used in containers using dynamic memory such as std::vector without additionally providing an allocator that can provide over-aligned memory:

std::vector<Type> v1; // Might be misaligned for AVX or AVX-512
std::vector<Type,Allocator> v2; // Properly aligned for AVX or AVX-512

Padding

Adding padding elements to the end of a blaze::HybridVector can have a significant impact on the performance. For instance, assuming that AVX is available, then two padded 3-dimensional vectors of double precision values can be added via a single SIMD addition operation:

HybridVector<double,3UL,columnVector,aligned,padded> a1, b1, c1;
HybridVector<double,3UL,columnVector,unaligned,unpadded> a2, b2, c2;
// ... Resizing and initialization
c1 = a1 + b1; // AVX-based vector addition; maximum performance
c2 = a2 + b2; // Scalar vector addition; limited performance
sizeof( a1 ); // Evaluates to 48 for SSE, 64 and AVX, and 128 for AVX-512
sizeof( a2 ); // Evaluates to 32 for SSE, AVX, and AVX-512 (minimum size)

Due to padding, the first addition will run at maximum performance. On the flip side, the size of each vector instance is increased due to the padding elements. The total size of an instance depends on the number of elements and width of the available instruction set (16 bytes for SSE, 32 bytes for AVX, and 64 bytes for AVX-512).

The second addition will be limited in performance since due to the number of elements some of the elements need to be handled in a scalar operation. However, the size of an unaligned, unpadded blaze::HybridVector instance is guaranteed to be the sum of its elements plus the necessary data members to store the current size.

Please also note that Blaze will zero initialize the padding elements in order to achieve maximum performance!


CustomVector

The blaze::CustomVector class template provides the functionality to represent an external array of elements of arbitrary type and a fixed size as a native Blaze dense vector data structure. Thus in contrast to all other dense vector types a custom vector does not perform any kind of memory allocation by itself, but it is provided with an existing array of element during construction. A custom vector can therefore be considered an alias to the existing array. It can be included via the header files

#include <blaze/Blaze.h>
// or
#include <blaze/Math.h>
// or
Header file for the complete CustomVector implementation.

and forward declared via the header file

#include <blaze/Forward.h>

The type of the elements, the properties of the given array of elements, the transpose flag, and the group tag of the vector can be specified via the following five template parameters:

namespace blaze {
template< typename Type, AlignmentFlag AF, PaddingFlag PF, bool TF, typename Tag >
class CustomVector;
} // namespace blaze
  • Type: specifies the type of the vector elements. blaze::CustomVector can be used with any possibly cv-qualified, non-reference, non-pointer element type.
  • AF : specifies whether the represented, external arrays are properly aligned with respect to the available instruction set (SSE, AVX, ...) or not (blaze::aligned or blaze::unaligned).
  • PF : specified whether the represented, external arrays are properly padded with respect to the available instruction set (SSE, AVX, ...) or not (blaze::padded or blaze::unpadded).
  • TF : specifies whether the vector is a row vector (blaze::rowVector) or a column vector (blaze::columnVector). The default value is blaze::defaultTransposeFlag.
  • Tag : optional type parameter to tag the vector. The default type is blaze::Group0. See Grouping/Tagging for details.

The blaze::CustomVector is the right choice if any external array needs to be represented as a Blaze dense vector data structure or if a custom memory allocation strategy needs to be realized:

// Definition of an unmanaged custom column vector for unaligned, unpadded integer arrays
using UnalignedUnpadded = CustomVector<int,unaligned,unpadded,columnVector>;
std::vector<int> vec( 7UL );
UnalignedUnpadded a( &vec[0], 7UL );
// Definition of a managed custom column vector for unaligned but padded 'float' arrays
using UnalignedPadded = CustomVector<float,unaligned,padded,columnVector>;
std::unique_ptr<float[]> memory1( new float[16] );
UnalignedPadded b( memory1.get(), 9UL, 16UL );
// Definition of a managed custom row vector for aligned, unpadded 'double' arrays
using AlignedUnpadded = CustomVector<double,aligned,unpadded,rowVector>;
std::unique_ptr<double[],Deallocate> memory2( blaze::allocate<double>( 7UL ) );
AlignedUnpadded c( memory2.get(), 7UL );
// Definition of a managed custom row vector for aligned, padded 'complex<double>' arrays
using cplx = complex<double>;
using AlignedPadded = CustomVector<cplx,aligned,padded,columnVector>;
std::unique_ptr<cplx[],Deallocate> memory3( allocate<cplx>( 8UL ) );
AlignedPadded d( memory3.get(), 5UL, 8UL );
Efficient implementation of a customizable vector.
Definition: CustomVector.h:407
Complex data type of the Blaze library.
Deallocate policy class.
Definition: Deallocate.h:65

In comparison with the remaining Blaze dense vector types blaze::CustomVector has several special characteristics. All of these result from the fact that a custom vector is not performing any kind of memory allocation, but instead is given an existing array of elements. The following sections discuss all of these characteristics:

  1. Memory Management
  2. Copy Operations
  3. Alignment
  4. Padding

Memory Management

The blaze::CustomVector class template acts as an adaptor for an existing array of elements. As such it provides everything that is required to use the array just like a native Blaze dense vector data structure. However, this flexibility comes with the price that the user of a custom vector is responsible for the resource management.

The following examples give an impression of several possible types of custom vectors:

// Definition of a 3-dimensional custom vector with unaligned, unpadded and externally
// managed integer array. Note that the std::vector must be guaranteed to outlive the
// custom vector!
std::vector<int> vec( 3UL );
CustomVector<int,unaligned,unpadded> a( &vec[0], 3UL );
// Definition of a custom vector with size 3 and capacity 16 with aligned, padded and
// externally managed integer array. Note that the std::unique_ptr must be guaranteed
// to outlive the custom vector!
std::unique_ptr<int[],Deallocate> memory( allocate<int>( 16UL ) );
CustomVector<int,aligned,padded> b( memory.get(), 3UL, 16UL );
T * allocate(size_t size)
Aligned array allocation for built-in data types.
Definition: Memory.h:158

Copy Operations

As with all dense vectors it is possible to copy construct a custom vector:

using CustomType = CustomVector<int,unaligned,unpadded>;
std::vector<int> vec( 5UL, 10 ); // Vector of 5 integers of the value 10
CustomType a( &vec[0], 5UL ); // Represent the std::vector as Blaze dense vector
a[1] = 20; // Also modifies the std::vector
CustomType b( a ); // Creating a copy of vector a
b[2] = 20; // Also affects vector a and the std::vector

It is important to note that a custom vector acts as a reference to the specified array. Thus the result of the copy constructor is a new custom vector that is referencing and representing the same array as the original custom vector.

In contrast to copy construction, just as with references, copy assignment does not change which array is referenced by the custom vector, but modifies the values of the array:

std::vector<int> vec2( 5UL, 4 ); // Vector of 5 integers of the value 4
CustomType c( &vec2[0], 5UL ); // Represent the std::vector as Blaze dense vector
a = c; // Copy assignment: Set all values of vector a and b to 4.

Alignment

In case the custom vector is specified as aligned the passed array must be guaranteed to be aligned according to the requirements of the used instruction set (SSE, AVX, ...). For instance, if AVX is active an array of integers must be 32-bit aligned:

// Allocation of 32-bit aligned memory
std::unique_ptr<int[],Deallocate> memory( allocate<int>( 5UL ) );
CustomVector<int,aligned,unpadded> a( memory.get(), 5UL );

In case the alignment requirements are violated, a std::invalid_argument exception is thrown.

Padding

Adding padding elements to the end of an array can have a significant impact on the performance. For instance, assuming that AVX is available, then two aligned, padded, 3-dimensional vectors of double precision values can be added via a single SIMD addition operation:

using CustomType = CustomVector<double,aligned,padded>;
std::unique_ptr<double[],Deallocate> memory1( allocate<double>( 4UL ) );
std::unique_ptr<double[],Deallocate> memory2( allocate<double>( 4UL ) );
std::unique_ptr<double[],Deallocate> memory3( allocate<double>( 4UL ) );
// Creating padded custom vectors of size 3 and a capacity of 4
CustomType a( memory1.get(), 3UL, 4UL );
CustomType b( memory2.get(), 3UL, 4UL );
CustomType c( memory3.get(), 3UL, 4UL );
// ... Initialization
c = a + b; // AVX-based vector addition

In this example, maximum performance is possible. However, in case no padding elements are inserted, a scalar addition has to be used:

using CustomType = CustomVector<double,aligned,unpadded>;
std::unique_ptr<double[],Deallocate> memory1( allocate<double>( 3UL ) );
std::unique_ptr<double[],Deallocate> memory2( allocate<double>( 3UL ) );
std::unique_ptr<double[],Deallocate> memory3( allocate<double>( 3UL ) );
// Creating unpadded custom vector of size 3
CustomType a( allocate<double>( 3UL ), 3UL );
CustomType b( allocate<double>( 3UL ), 3UL );
CustomType c( allocate<double>( 3UL ), 3UL );
// ... Initialization
c = a + b; // Scalar vector addition

Note the different number of constructor parameters for unpadded and padded custom vectors: In contrast to unpadded vectors, where during the construction only the size of the array has to be specified, during the construction of a padded custom vector it is additionally necessary to explicitly specify the capacity of the array.

The number of padding elements is required to be sufficient with respect to the available instruction set: In case of an aligned padded custom vector the added padding elements must guarantee that the capacity is greater or equal than the size and a multiple of the SIMD vector width. In case of unaligned padded vectors the number of padding elements can be greater or equal the number of padding elements of an aligned padded custom vector. In case the padding is insufficient with respect to the available instruction set, a std::invalid_argument exception is thrown.

Please also note that Blaze will zero initialize the padding elements in order to achieve maximum performance!


UniformVector

The blaze::UniformVector class template is the representation of an arbitrary sized uniform vector with elements of arbitrary type. It can be included via the header files

#include <blaze/Blaze.h>
// or
#include <blaze/Math.h>
// or
Header file for the complete UniformVector implementation.

and forward declared via the header file

#include <blaze/Forward.h>

The type of the elements, the transpose flag, and the group tag of the vector can be specified via the three template parameters:

namespace blaze {
template< typename Type, bool TF, typename Tag >
class UniformVector;
} // namespace blaze
  • Type: specifies the type of the vector elements. UniformVector can be used with any non-cv-qualified, non-reference, non-pointer element type.
  • TF : specifies whether the vector is a row vector (blaze::rowVector) or a column vector (blaze::columnVector). The default value is blaze::defaultTransposeFlag.
  • Tag : optional type parameter to tag the vector. The default type is blaze::Group0. See Grouping/Tagging for details.

The blaze::UniformVector is the best choice for uniform vectors of any size. Its size can be modified at runtime:

// Definition of a 3-dimensional integral column vector
// Definition of a 4-dimensional single precision column vector
// Definition of a double precision row vector with size 0
Efficient implementation of a uniform vector.
Definition: UniformVector.h:186


Sparse Vectors


CompressedVector

The blaze::CompressedVector class is the representation of an arbitrarily sized sparse vector, which stores only non-zero elements of arbitrary type. It can be included via the header files

#include <blaze/Blaze.h>
// or
#include <blaze/Math.h>
// or
Header file for the complete CompressedVector implementation.

and forward declared via the header file

#include <blaze/Forward.h>

The type of the elements, the transpose flag, and the group tag of the vector can be specified via the three template parameters:

namespace blaze {
template< typename Type, bool TF, typename Tag >
class CompressedVector;
} // namespace blaze
  • Type: specifies the type of the vector elements. CompressedVector can be used with any non-cv-qualified, non-reference, non-pointer element type.
  • TF : specifies whether the vector is a row vector (blaze::rowVector) or a column vector (blaze::columnVector). The default value is blaze::defaultTransposeFlag.
  • Tag : optional type parameter to tag the vector. The default type is blaze::Group0. See Grouping/Tagging for details.

The blaze::CompressedVector is the right choice for all kinds of sparse vectors:

// Definition of a 3-dimensional integral column vector
// Definition of a 4-dimensional single precision column vector with capacity for 3 non-zero elements
// Definition of a double precision row vector with size 0
Efficient implementation of an arbitrary sized sparse vector.
Definition: CompressedVector.h:220


ZeroVector

The blaze::ZeroVector class template is the representation of an immutable, arbitrary sized zero vector with elements of arbitrary type. It can be included via the header files

#include <blaze/Blaze.h>
// or
#include <blaze/Math.h>
// or
Header file for the complete ZeroVector implementation.

and forward declared via the header file

#include <blaze/Forward.h>

The type of the elements, the transpose flag, and the group tag of the vector can be specified via the three template parameters:

namespace blaze {
template< typename Type, bool TF, typename Tag >
class ZeroVector;
} // namespace blaze
  • Type: specifies the type of the vector elements. ZeroVector can be used with any non-cv-qualified, non-reference, non-pointer element type.
  • TF : specifies whether the vector is a row vector (blaze::rowVector) or a column vector (blaze::columnVector). The default value is blaze::defaultTransposeFlag.
  • Tag : optional type parameter to tag the vector. The default type is blaze::Group0. See Grouping/Tagging for details.

The blaze::ZeroVector is the perfect choice to represent a zero vector:

// Definition of a 3-dimensional integral zero column vector
// Definition of a 6-dimensional single precision zero column vector
// Definition of a double precision row vector with size 0
Efficient implementation of an arbitrary sized zero vector.
Definition: ZeroVector.h:183


Previous: Vectors     Next: Vector Operations