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>
typedef stxxl::block_scheduler<stxxl::matrix_swappable_block<int, 32> > block_schedular_type;

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

  C.transpose();
  C.set_zero();

A minimal working example of STXXL's Matrix

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

#include <stxxl/bits/containers/matrix.h>
#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

 typedef stxxl::block_scheduler<stxxl::matrix_swappable_block<int, small_block_order> > block_schedular_type;
 typedef stxxl::matrix<int, small_block_order> matrix_type;

 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;

 C.transpose();

 // Print out matrix C
 for (row_iterator it_C = C.begin(); it_C != C.end(); ++it_C)
 {
 std::cout << *it_C << " ";
 }

 return 0;
}