Vector Types

Table of Contents


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 file

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

template< typename Type, size_t N, bool TF >
class StaticVector;

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 a 6-dimensional double precision row vector


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 file

The type of the elements and the transpose flag of the vector can be specified via the two template parameters:

template< typename Type, bool TF >
class DynamicVector;

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


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 file

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

template< typename Type, size_t N, bool TF >
class HybridVector;

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 double precision row vector with size 0 and a maximum size of 6


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 file

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

template< typename Type, bool AF, bool PF, bool TF >
class CustomVector;

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
typedef CustomVector<int,unaligned,unpadded,columnVector> UnalignedUnpadded;
std::vector<int> vec( 7UL );
UnalignedUnpadded a( &vec[0], 7UL );
// Definition of a managed custom column vector for unaligned but padded 'float' arrays
typedef CustomVector<float,unaligned,padded,columnVector> UnalignedPadded;
UnalignedPadded b( new float[16], 9UL, 16UL, blaze::ArrayDelete() );
// Definition of a managed custom row vector for aligned, unpadded 'double' arrays
typedef CustomVector<double,aligned,unpadded,rowVector> AlignedUnpadded;
AlignedUnpadded c( blaze::allocate<double>( 7UL ), 7UL, blaze::Deallocate() );
// Definition of a managed custom row vector for aligned, padded 'complex<double>' arrays
typedef CustomVector<complex<double>,aligned,padded,columnVector> AlignedPadded;
AlignedPadded d( allocate< complex<double> >( 8UL ), 5UL, 8UL, blaze::Deallocate() );

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


Copy Operations

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

typedef CustomVector<int,unaligned,unpadded> CustomType;
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:

typedef CustomVector<double,aligned,padded> CustomType;
std::unique_ptr<int[],Deallocate> memory1( allocate<double>( 4UL ) );
std::unique_ptr<int[],Deallocate> memory2( allocate<double>( 4UL ) );
std::unique_ptr<int[],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:

typedef CustomVector<double,aligned,unpadded> CustomType;
std::unique_ptr<int[],Deallocate> memory1( allocate<double>( 3UL ) );
std::unique_ptr<int[],Deallocate> memory2( allocate<double>( 3UL ) );
std::unique_ptr<int[],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!


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 file

The type of the elements and the transpose flag of the vector can be specified via the two template parameters:

template< typename Type, bool TF >
class CompressedVector;

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


Previous: Vectors     Next: Vector Operations