STXXL  1.4-dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
STXXL Matrix

This section introduces into the STXXL matrix container (to learn more about the structure of stxxl::matrix, see section Matrix).

Create a STXXL Matrix

Before using a STXXL matrix, we initially have to define and then to instantiate a matrix object. Two template parameters are required to define a stxxl::matrix container. ValueType defines the type of the contained objects (must be a POD with no references to internal memory) and BlockSizeLength specifies the side length of the square submatrices (blocks). BlockSizeLength is given in bits and must be a multiple of k assuming a valueType of k bits. The block schedular is used for swapping of blocks and provide blocks for temporary storage and expects the type of swappable_blocks to manage as a parameter. Can be some specialized subclass. We used matrix_swappable_block as a subclass which holds the same template parameters as the aforementioned stxxl::matrix container.

// Define integer matrix
// template paramter <ValueType, BlockSideLength>
// template paramter <ValueType, BlockSideLength>
typedef stxxl::matrix<int, 32> matrix_type;
// construct block schedular object which uses 64 MiB internal memory for caching
block_schedular_type my_bs(64*1024*1024);

Instanciate three new height x width (3 x 3 in this example) matrices A, B and C using a block schedular.
Note that all values are initially set to zero.

int height = 3;
int width = 3;
matrix_type A(my_bs, height, width); // creates a new matrix A of given dimensions. Elements' values are set to zero.
matrix_type B(my_bs, height, width); // B
matrix_type C(my_bs, height, width); // C

Insert / Access elements

To insert and access elements, the STXXL matrix container intends different iterators. Iterate for example row-by-row beginning with the top row can be done with the row_major_iterator. The operator * accesses a single element the iterator points to just now.

typedef matrix_type::row_major_iterator row_iterator;
// let it_A point to the first element of matrix A and advance till the very last element of matrix A is reached
for (row_iterator it_A = A.begin(); it_A != A.end(); ++it_A)
*it_A = 1; // set current matrix element to 1

Determine size of matrix

To detect the height and width of a given matrix C, we can call:

std::cout << "height: " << C.get_height() << " - " << "width: " << C.get_width() << std::endl;

Matrix Operations

The STXXL Matrix container provides the following arithmetic operations:

  • Addition, Substraction and Multiplication of two matrices A and B.
    C = A + B;
    C = A - B;
    C = A * B;
  • Transposition and Zeroing of a matrix C.

A minimal working example of STXXL's Matrix

(See examples/containers/matrix1.cpp for the sourcecode of the following example).

#include <iostream>
int main()
// Matrix dimensions
int height = 3;
int width = 3;
int internal_memory = 64 * 1024 * 1024;
const int small_block_order = 32; // must be multiple of matrix valueType in bits
block_schedular_type my_bs(internal_memory);
// Create 3 matrices with given dimensions
matrix_type A(my_bs, height, width);
matrix_type B(my_bs, height, width);
matrix_type C(my_bs, height, width);
typedef matrix_type::row_major_iterator row_iterator;
int i = 0;
// Fill matrix A with values 0,1,2,3,...
for (row_iterator it_A = A.begin(); it_A != A.end(); ++it_A, ++i)
*it_A = i;
i = 0;
// Fill matrix B with values 0,2,4,8,...
for (row_iterator it_B = B.begin(); it_B != B.end(); ++it_B, ++i)
*it_B = i * 2;
// Multiply matrix A and B and store result in matrix C
C = A * B;
// Print out matrix C
for (row_iterator it_C = C.begin(); it_C != C.end(); ++it_C)
std::cout << *it_C << " ";
return 0;