# blaze / 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 file

```#include <blaze/math/StaticVector.h>
```

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

```template< typename Type, size_t N, bool TF, AlignmentFlag AF, PaddingFlag PF >
class StaticVector;
```
• `Type` : specifies the type of the vector elements. `StaticVector` can be used with any non-cv-qualified element type, including other vector or matrix types.
• `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::columnVector`.
• `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::aligned`.
• `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::padded`.

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
blaze::StaticVector<int,3UL> a;

// Definition of a 4-dimensional single precision column vector
blaze::StaticVector<float,4UL,blaze::columnVector> b;

// Definition of an unaligned, unpadded 6-dimensional double precision row vector
```
###### Alignment

In case `AF` is set to `blaze::aligned`, the elements of a `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; };

using VT1 = blaze::StaticVector<double,3UL>;
using VT2 = blaze::StaticVector<complex<float>,2UL>;
using VT3 = blaze::StaticVector<Int,5UL>;

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 `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 `StaticVector` cannot be used in containers using dynamic memory such as `std::vector` without additionally providing an allocator that can provide over-aligned memory:

```using Type = blaze::StaticVector<double,3UL>;
using Allocator = blaze::AlignedAllocator<Type>;

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

Adding padding elements to the end of a `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:

```using blaze::StaticVector;
using blaze::columnVector;
using blaze::aligned;
using blaze::unaligned;

// ... 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)
```

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` `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 arbitrarily sized vector with dynamically allocated elements of arbitrary type. It can be included via the header file

```#include <blaze/math/DynamicVector.h>
```

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;
```
• `Type` : specifies the type of the vector elements. `DynamicVector` can be used with any non-cv-qualified element type, including other vector or matrix types.
• `TF` : specifies whether the vector is a row vector (`blaze::rowVector`) or a column vector (`blaze::columnVector`). The default value is `blaze::columnVector`.

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
blaze::DynamicVector<int> a( 3UL );

// Definition of a 4-dimensional single precision column vector
blaze::DynamicVector<float,blaze::columnVector> b( 4UL );

// Definition of a double precision row vector with size 0
blaze::DynamicVector<double,blaze::rowVector> c;
```

#### 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 can still be dynamically resized (within the bounds of the available memory). It can be included via the header file

```#include <blaze/math/HybridVector.h>
```

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

```template< typename Type, size_t N, bool TF, AlignmentFlag AF, PaddingFlag PF >
class HybridVector;
```
• `Type` : specifies the type of the vector elements. `HybridVector` can be used with any non-cv-qualified element type, including other vector or matrix types.
• `N` : specifies the total 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::columnVector`.
• `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::aligned`.
• `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::padded`.

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
blaze::HybridVector<int,6UL> a( 3UL );

// Definition of a 4-dimensional single precision column vector with a maximum size of 16
blaze::HybridVector<float,16UL,blaze::columnVector> b( 4UL );

// Definition of a unaligned, unpadded double precision row vector with size 0 and a maximum size of 6
```
###### Alignment

In case `AF` is set to `blaze::aligned`, the elements of a `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; };

using VT1 = blaze::HybridVector<double,3UL>;
using VT2 = blaze::HybridVector<complex<float>,2UL>;
using VT3 = blaze::HybridVector<Int,5UL>;

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 `HybridVector` instance may be bigger than an according unaligned `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 `HybridVector` cannot be used in containers using dynamic memory such as `std::vector` without additionally providing an allocator that can provide over-aligned memory:

```using Type = blaze::HybridVector<double,3UL>;
using Allocator = blaze::AlignedAllocator<Type>;

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

Adding padding elements to the end of a `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:

```using blaze::HybridVector;
using blaze::columnVector;
using blaze::aligned;
using blaze::unaligned;

// ... 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` `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 file

```#include <blaze/math/CustomVector.h>
```

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;
```
• `Type` : specifies the type of the vector elements. `CustomVector` can be used with any non-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.
• `PF` : specified whether the represented, external arrays are properly padded with respect to the available instruction set (SSE, AVX, ...) or not.
• `TF` : specifies whether the vector is a row vector (`blaze::rowVector`) or a column vector (`blaze::columnVector`). The default value is `blaze::columnVector`.

The `blaze::CustomVector` is the right choice if any external array needs to be represented as a Blaze dense vector data structure:

```using blaze::CustomVector;
using blaze::Deallocate;
using blaze::aligned;
using blaze::unaligned;

// Definition of an unmanaged custom column vector for unaligned, unpadded integer arrays
std::vector<int> vec( 7UL );

// Definition of a managed custom column vector for unaligned but padded 'float' arrays
std::unique_ptr<float[]> memory1( new float );
UnalignedPadded b( memory1.get(), 9UL, 16UL );

// Definition of a managed custom row vector for aligned, unpadded 'double' arrays
std::unique_ptr<double[],Deallocate> memory2( blaze::allocate<double>( 7UL ) );

// Definition of a managed custom row vector for aligned, padded 'complex<double>' arrays
using cplx = complex<double>;
std::unique_ptr<cplx[],Deallocate> memory3( allocate<cplx>( 8UL ) );
AlignedPadded d( memory3.get(), 5UL, 8UL );
```

In comparison with the remaining Blaze dense vector types `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:

###### Memory Management

The `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:

```using blaze::CustomVector;
using blaze::Deallocate;
using blaze::allocate;
using blaze::aligned;
using blaze::unaligned;

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

// 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:

```using blaze::CustomVector;
using blaze::unaligned;

std::vector<int> vec( 5UL, 10 );  // Vector of 5 integers of the value 10
CustomType a( &vec, 5UL );     // Represent the std::vector as Blaze dense vector
a = 20;                        // Also modifies the std::vector

CustomType b( a );  // Creating a copy of vector a
b = 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, 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:

```using blaze::CustomVector;
using blaze::Deallocate;
using blaze::aligned;

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

```

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

Adding padding elements to the end of an array can have a significant impact on 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 instruction:

```using blaze::CustomVector;
using blaze::Deallocate;
using blaze::allocate;
using blaze::aligned;

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 blaze::CustomVector;
using blaze::Deallocate;
using blaze::allocate;
using blaze::aligned;

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 file

```#include <blaze/math/UniformVector.h>
```

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 UniformVector;
```
• `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::columnVector`.

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
blaze::UniformVector<int> a( 3UL );

// Definition of a 4-dimensional single precision column vector
blaze::UniformVector<float,blaze::columnVector> b( 4UL );

// Definition of a double precision row vector with size 0
blaze::UniformVector<double,blaze::rowVector> c;
```

## 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 file

```#include <blaze/math/CompressedVector.h>
```

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;
```
• `Type` : specifies the type of the vector elements. `CompressedVector` can be used with any non-cv-qualified element type (including other vector or matrix types).
• `TF` : specifies whether the vector is a row vector (`blaze::rowVector`) or a column vector (`blaze::columnVector`). The default value is `blaze::columnVector`.

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

```// Definition of a 3-dimensional integral column vector
blaze::CompressedVector<int> a( 3UL );

// Definition of a 4-dimensional single precision column vector with capacity for 3 non-zero elements
blaze::CompressedVector<float,blaze::columnVector> b( 4UL, 3UL );

// Definition of a double precision row vector with size 0
blaze::CompressedVector<double,blaze::rowVector> c;
```

#### 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 file

```#include <blaze/math/ZeroVector.h>
```

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 ZeroVector;
```
• `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::columnVector`.

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

```// Definition of a 3-dimensional integral zero column vector
blaze::ZeroVector<int> a( 3UL );

// Definition of a 6-dimensional single precision zero column vector
blaze::ZeroVector<float,blaze::columnVector> b( 6UL );

// Definition of a double precision row vector with size 0
blaze::ZeroVector<double,blaze::rowVector> c;
```

Previous: Vectors ---- Next: Vector Operations

Updated