Classes | Functions

Classes

struct  blaze::BandData< CBAs >
 Auxiliary class template for the data members of the Band class.The auxiliary BandData class template represents an abstraction of the data members of the Band class template. The necessary set of data member is selected depending on the number of compile time band arguments. More...
 

Functions

template<ptrdiff_t I, typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band (Matrix< MT, SO > &matrix, RBAs... args)
 Creating a view on a specific band of the given matrix. More...
 
template<ptrdiff_t I, typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band (const Matrix< MT, SO > &matrix, RBAs... args)
 Creating a view on a specific band of the given constant matrix. More...
 
template<ptrdiff_t I, typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band (Matrix< MT, SO > &&matrix, RBAs... args)
 Creating a view on a specific band of the given temporary matrix. More...
 
template<typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band (Matrix< MT, SO > &matrix, ptrdiff_t index, RBAs... args)
 Creating a view on a specific band of the given matrix. More...
 
template<typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band (const Matrix< MT, SO > &matrix, ptrdiff_t index, RBAs... args)
 Creating a view on a specific band of the given constant matrix. More...
 
template<typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band (Matrix< MT, SO > &&matrix, ptrdiff_t index, RBAs... args)
 Creating a view on a specific band of the given temporary matrix. More...
 
template<typename MT , bool SO, typename... RDAs>
decltype(auto) blaze::diagonal (Matrix< MT, SO > &matrix, RDAs... args)
 Creating a view on the diagonal of the given matrix. More...
 
template<typename MT , bool SO, typename... RDAs>
decltype(auto) blaze::diagonal (const Matrix< MT, SO > &matrix, RDAs... args)
 Creating a view on the diagonal of the given constant matrix. More...
 
template<typename MT , bool SO, typename... RDAs>
decltype(auto) blaze::diagonal (Matrix< MT, SO > &&matrix, RDAs... args)
 Creating a view on the diagonal of the given temporary matrix. More...
 

Detailed Description

Bands provide views on a specific band of a dense or sparse matrix (e.g. the diagonal, the subdiagonal, ...). As such, bands act as a reference to a specific band. This reference is valid and can be used in every way any other vector can be used as long as the matrix containing the band is not resized or entirely destroyed. The band also acts as an alias to the band elements: Changes made to the elements (e.g. modifying values, inserting or erasing elements) are immediately visible in the matrix and changes made via the matrix are immediately visible in the band.


Setup of Bands

band.png

A reference to a dense or sparse band can be created very conveniently via the band() function. It can be included via the header file

The band index must be in the range from $[1-M..N-1]$, where M is the total number of rows and N is the total number of columns, and can be specified both at compile time or at runtime:

// ... Resizing and initialization
// Creating a reference to the 1st lower band of matrix A (compile time index)
auto band1 = band<-1L>( A );
// Creating a reference to the 2nd upper band of matrix A (runtime index)
auto band2 = band( A, 2L );

The band() function returns an expression representing the band view. The type of this expression depends on the given band arguments, primarily the type of the matrix and the compile time arguments. If the type is required, it can be determined via decltype specifier:

using MatrixType = blaze::DynamicMatrix<int>;
using BandType = decltype( blaze::band<1L>( std::declval<MatrixType>() ) );

The resulting view can be treated as any other vector, i.e. it can be assigned to, it can be copied from, and it can be used in arithmetic operations. By default, bands are considered column vectors, but this setting can be changed via the defaultTransposeFlag switch. The reference can also be used on both sides of an assignment: The band can either be used as an alias to grant write access to a specific band of a matrix primitive on the left-hand side of an assignment or to grant read-access to a specific band of a matrix primitive or expression on the right-hand side of an assignment. The following example demonstrates this in detail:

// ... Resizing and initialization
// Setting the 2nd upper band of matrix A to x
auto band2 = band( A, 2L );
band2 = x;
// Setting the 3rd upper band of matrix B to y
band( B, 3L ) = y;
// Setting x to the 2nd lower band of the result of the matrix multiplication
x = band( A * B, -2L );
// Setting y to the 2nd upper band of the result of the sparse matrix multiplication
y = band( C * D, 2L );


Element access

The elements of a band can be directly accessed with the subscript operator:

// ... Resizing and initialization
// Creating a view on the 4th upper band of matrix A
auto band4 = band( A, 4L );
// Setting the 1st element of the dense band, which corresponds
// to the 1st element in the 4th upper band of matrix A
band4[1] = 2.0;

The numbering of the band elements is

\[\left(\begin{array}{*{5}{c}} 0 & 1 & 2 & \cdots & N-1 \\ \end{array}\right),\]

where N is the number of elements of the referenced band. Alternatively, the elements of a band can be traversed via iterators. Just as with vectors, in case of non-const band, begin() and end() return an iterator, which allows to manipulate the elements, in case of constant bands an iterator to immutable elements is returned:

// ... Resizing and initialization
// Creating a reference to the 5th upper band of matrix A
auto band5 = band( A, 5L );
// Traversing the elements via iterators to non-const elements
for( auto it=band5.begin(); it!=band5.end(); ++it ) {
*it = ...; // OK; Write access to the dense band value
... = *it; // OK: Read access to the dense band value.
}
// Traversing the elements via iterators to const elements
for( auto it=band5.cbegin(); it!=band5.cend(); ++it ) {
*it = ...; // Compilation error: Assignment to the value via iterator-to-const is invalid.
... = *it; // OK: Read access to the dense band value.
}
// ... Resizing and initialization
// Creating a reference to the 5th band of matrix A
auto band5 = band( A, 5L );
// Traversing the elements via iterators to non-const elements
for( auto it=band5.begin(); it!=band5.end(); ++it ) {
it->value() = ...; // OK: Write access to the value of the non-zero element.
... = it->value(); // OK: Read access to the value of the non-zero element.
it->index() = ...; // Compilation error: The index of a non-zero element cannot be changed.
... = it->index(); // OK: Read access to the index of the sparse element.
}
// Traversing the elements via iterators to const elements
for( auto it=band5.cbegin(); it!=band5.cend(); ++it ) {
it->value() = ...; // Compilation error: Assignment to the value via iterator-to-const is invalid.
... = it->value(); // OK: Read access to the value of the non-zero element.
it->index() = ...; // Compilation error: The index of a non-zero element cannot be changed.
... = it->index(); // OK: Read access to the index of the sparse element.
}


Element Insertion

Inserting/accessing elements in a sparse band can be done by several alternative functions. The following example demonstrates all options:

blaze::CompressedMatrix<double,blaze::rowMajor> A( 10UL, 100UL ); // Non-initialized 10x100 matrix
auto diag( band( A, 0L ) ); // Reference to the diagonal of A
// The subscript operator provides access to all possible elements of the sparse band,
// including the zero elements. In case the subscript operator is used to access an element
// that is currently not stored in the sparse band, the element is inserted into the band.
diag[42] = 2.0;
// The second operation for inserting elements is the set() function. In case the element
// is not contained in the band it is inserted into the band, if it is already contained in
// the band its value is modified.
diag.set( 45UL, -1.2 );
// An alternative for inserting elements into the band is the insert() function. However,
// it inserts the element only in case the element is not already contained in the band.
diag.insert( 50UL, 3.7 );


Common Operations

A band view can be used like any other column vector. For instance, the current number of band elements can be obtained via the size() function, the current capacity via the capacity() function, and the number of non-zero elements via the nonZeros() function. However, since bands are references to specific bands of a matrix, several operations are not possible, such as resizing and swapping. The following example shows this by means of a dense band view:

// ... Resizing and initialization
// Creating a reference to the 2nd upper band of matrix A
auto band2 = band( A, 2L );
band2.size(); // Returns the number of elements in the band
band2.capacity(); // Returns the capacity of the band
band2.nonZeros(); // Returns the number of non-zero elements contained in the band
band2.resize( 84UL ); // Compilation error: Cannot resize a single band of a matrix
auto band3 = band( A, 3L );
swap( band2, band3 ); // Compilation error: Swap operation not allowed


Arithmetic Operations

Both dense and sparse bands can be used in all arithmetic operations that any other dense or sparse vector can be used in. The following example gives an impression of the use of dense bands within arithmetic operations. All operations (addition, subtraction, multiplication, scaling, ...) can be performed on all possible combinations of dense and sparse bands with fitting element types:

c[1] = 3.0;
blaze::DynamicMatrix<double,blaze::rowMajor> A( 4UL, 2UL ); // Non-initialized 4x2 matrix
auto band1( band( A, 1L ) ); // Reference to the 1st upper band of A
auto diag ( band( A, 0L ) ); // Reference to the diagonal of A
band1[0] = 0.0; // Manual initialization of the 1st upper band of A
diag = 1.0; // Homogeneous initialization of the diagonal of A
band( A, -1L ) = a; // Dense vector initialization of the 1st lower band of A
band( A, -2L ) = c; // Sparse vector initialization of the 2nd lower band of A
b = diag + a; // Dense vector/dense vector addition
b = c + band( A, -1L ); // Sparse vector/dense vector addition
b = diag * band( A, -2L ); // Component-wise vector multiplication
band( A, -1L ) *= 2.0; // In-place scaling of the 1st upper band
b = band( A, -1L ) * 2.0; // Scaling of the 1st upper band
b = 2.0 * band( A, -1L ); // Scaling of the 1st upper band
band( A, -2L ) += a; // Addition assignment
band( A, -2L ) -= c; // Subtraction assignment
band( A, -2L ) *= band( A, 0L ); // Multiplication assignment
double scalar = trans( c ) * band( A, -1L ); // Scalar/dot/inner product between two vectors
A = band( A, -1L ) * trans( c ); // Outer product between two vectors

Function Documentation

◆ band() [1/6]

template<ptrdiff_t I, typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band ( Matrix< MT, SO > &  matrix,
RBAs...  args 
)
inline

Creating a view on a specific band of the given matrix.

Parameters
matrixThe matrix containing the band.
argsOptional band arguments.
Returns
View on the specified band of the matrix.
Exceptions
std::invalid_argumentInvalid band access index.

This function returns an expression representing the specified band of the given matrix.

// ... Resizing and initialization
// Creating a view on the upper secondary diagonal of the dense matrix D
auto ub1 = band<1L>( D );
// Creating a view on the lower secondary diagonal of the sparse matrix S
auto lb1 = band<-1L>( S );

By default, the provided band arguments are checked at runtime. // In case the band is not properly specified (i.e. if the specified index does not correspond to a valid band in the given matrix) a std::invalid_argument exception is thrown. The checks can be skipped by providing the optional blaze::unchecked argument.

auto ub1 = band<1L>( D, unchecked );
auto lb1 = band<-1L>( S, unchecked );

◆ band() [2/6]

template<ptrdiff_t I, typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band ( const Matrix< MT, SO > &  matrix,
RBAs...  args 
)
inline

Creating a view on a specific band of the given constant matrix.

Parameters
matrixThe constant matrix containing the band.
argsOptional band arguments.
Returns
View on the specified band of the matrix.
Exceptions
std::invalid_argumentInvalid band access index.

This function returns an expression representing the specified band of the given constant matrix.

// Creating a view on the upper secondary diagonal of the dense matrix D
auto ub1 = band<1L>( D );
// Creating a view on the lower secondary diagonal of the sparse matrix S
auto lb1 = band<-1L>( S );

By default, the provided band arguments are checked at runtime. // In case the band is not properly specified (i.e. if the specified index does not correspond to a valid band in the given matrix) a std::invalid_argument exception is thrown. The checks can be skipped by providing the optional blaze::unchecked argument.

auto ub1 = band<1L>( D, unchecked );
auto lb1 = band<-1L>( S, unchecked );

◆ band() [3/6]

template<ptrdiff_t I, typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band ( Matrix< MT, SO > &&  matrix,
RBAs...  args 
)
inline

Creating a view on a specific band of the given temporary matrix.

Parameters
matrixThe temporary matrix containing the band.
argsOptional band arguments.
Returns
View on the specified band of the matrix.
Exceptions
std::invalid_argumentInvalid band access index.

This function returns an expression representing the specified band of the given temporary matrix. In case the band is not properly specified (i.e. if the specified index does not correspond to a valid band in the given matrix) a std::invalid_argument exception is thrown.

◆ band() [4/6]

template<typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band ( Matrix< MT, SO > &  matrix,
ptrdiff_t  index,
RBAs...  args 
)
inline

Creating a view on a specific band of the given matrix.

Parameters
matrixThe matrix containing the band.
indexThe band index.
argsOptional band arguments.
Returns
View on the specified band of the matrix.
Exceptions
std::invalid_argumentInvalid band access index.

This function returns an expression representing the specified band of the given matrix.

// ... Resizing and initialization
// Creating a view on the upper secondary diagonal of the dense matrix D
auto ub1 = band( D, 1L );
// Creating a view on the lower secondary diagonal of the sparse matrix S
auto lb1 = band( S, -1L );

By default, the provided band arguments are checked at runtime. // In case the band is not properly specified (i.e. if the specified index does not correspond to a valid band in the given matrix) a std::invalid_argument exception is thrown. The checks can be skipped by providing the optional blaze::unchecked argument.

auto ub1 = band( D, 1L, unchecked );
auto lb1 = band( S, -1L, unchecked );

◆ band() [5/6]

template<typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band ( const Matrix< MT, SO > &  matrix,
ptrdiff_t  index,
RBAs...  args 
)
inline

Creating a view on a specific band of the given constant matrix.

Parameters
matrixThe constant matrix containing the band.
indexThe band index.
argsOptional band arguments.
Returns
View on the specified band of the matrix.
Exceptions
std::invalid_argumentInvalid band access index.

This function returns an expression representing the specified band of the given constant matrix.

// Creating a view on the upper secondary diagonal of the dense matrix D
auto lb1 = band( D, 1L );
// Creating a view on the lower secondary diagonal of the sparse matrix S
auto ub1 = band( S, -1L );

By default, the provided band arguments are checked at runtime. // In case the band is not properly specified (i.e. if the specified index does not correspond to a valid band in the given matrix) a std::invalid_argument exception is thrown. The checks can be skipped by providing the optional blaze::unchecked argument.

auto ub1 = band( D, 1L, unchecked );
auto lb1 = band( S, -1L, unchecked );

◆ band() [6/6]

template<typename MT , bool SO, typename... RBAs>
decltype(auto) blaze::band ( Matrix< MT, SO > &&  matrix,
ptrdiff_t  index,
RBAs...  args 
)
inline

Creating a view on a specific band of the given temporary matrix.

Parameters
matrixThe temporary matrix containing the band.
indexThe band index.
argsOptional band arguments.
Returns
View on the specified band of the matrix.
Exceptions
std::invalid_argumentInvalid band access index.

This function returns an expression representing the specified band of the given temporary matrix. In case the band is not properly specified (i.e. if the specified index does not correspond to a valid band in the given matrix) a std::invalid_argument exception is thrown.

◆ diagonal() [1/3]

template<typename MT , bool SO, typename... RDAs>
decltype(auto) blaze::diagonal ( Matrix< MT, SO > &  matrix,
RDAs...  args 
)
inline

Creating a view on the diagonal of the given matrix.

Parameters
matrixThe matrix containing the diagonal.
argsOptional diagonal arguments.
Returns
View on the diagonal of the matrix.

This function returns an expression representing the diagonal of the given matrix.

// ... Resizing and initialization
// Creating a view on the diagonal of the dense matrix D
auto diag1 = diagonal( D );
// Creating a view on the diagonal of the sparse matrix S
auto diag2 = diagonal( S );

◆ diagonal() [2/3]

template<typename MT , bool SO, typename... RDAs>
decltype(auto) blaze::diagonal ( const Matrix< MT, SO > &  matrix,
RDAs...  args 
)
inline

Creating a view on the diagonal of the given constant matrix.

Parameters
matrixThe constant matrix containing the diagonal.
argsOptional diagonal arguments.
Returns
View on the diagonal of the matrix.

This function returns an expression representing the diagonal of the given constant matrix.

// Creating a view on the diagonal of the dense matrix D
auto diag1 = diagonal( D );
// Creating a view on the diagonal of the sparse matrix S
auto diag2 = diagonal( S );

◆ diagonal() [3/3]

template<typename MT , bool SO, typename... RDAs>
decltype(auto) blaze::diagonal ( Matrix< MT, SO > &&  matrix,
RDAs...  args 
)
inline

Creating a view on the diagonal of the given temporary matrix.

Parameters
matrixThe temporary matrix containing the diagonal.
argsOptional diagonal arguments.
Returns
View on the diagonal of the matrix.

This function returns an expression representing the diagonal of the given temporary matrix. In case the diagonal is not properly specified (i.e. in case the given matrix has zero rows or zero columns) a std::invalid_argument exception is thrown.