1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
// -*- mode: c++; mode: visual-line; mode: flyspell; fill-column: 100000 -*-
/***************************************************************************
* doc/tutorial_matrix.dox
*
* Usage Tutorial for STXXL
*
* Part of the STXXL. See http://stxxl.sourceforge.net
*
* Copyright (C) 2013 Daniel Feist <daniel.feist@student.kit.edu>
*
* Distributed under the Boost Software License, Version 1.0.
* (See accompanying file LICENSE_1_0.txt or copy at
* http://www.boost.org/LICENSE_1_0.txt)
**************************************************************************/
namespace stxxl {
/** \page tutorial_matrix STXXL Matrix
This section introduces into the STXXL matrix container (to learn more about the structure of stxxl::matrix, see section \ref design_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.
\code
// 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);
\endcode
Instanciate three new height x width (3 x 3 in this example) matrices A, B and C using a block schedular. \n
Note that all values are initially set to zero.
\code
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
\endcode
### 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.
\code
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
}
\endcode
### Determine size of matrix
To detect the height and width of a given matrix C, we can call:
\code
std::cout << "height: " << C.get_height() << " - " << "width: " << C.get_width() << std::endl;
\endcode
### Matrix Operations
The STXXL Matrix container provides the following arithmetic operations:
- Addition, Substraction and Multiplication of two matrices A and B.
\code
C = A + B;
C = A - B;
C = A * B;
\endcode
- Transposition and Zeroing of a matrix C.
\code
C.transpose();
C.set_zero();
\endcode
### A minimal working example of STXXL's Matrix
(See \ref examples/containers/matrix1.cpp for the sourcecode of the following example).
\snippet examples/containers/matrix1.cpp example
\example examples/containers/matrix1.cpp
This example code is explained in the \ref tutorial_matrix section
*/
} // namespace stxxl
|
