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