From 9ac68e40a0fa84419e95674c07bb773d054558c8 Mon Sep 17 00:00:00 2001 From: Jitse Niesen Date: Sat, 12 Feb 2011 17:43:29 +0000 Subject: Write topic page for storage orders. --- doc/I08_StorageOrders.dox | 11 ---- doc/I15_StorageOrders.dox | 91 +++++++++++++++++++++++++++++ doc/Overview.dox | 1 + doc/snippets/TopicStorageOrders_example.cpp | 18 ++++++ 4 files changed, 110 insertions(+), 11 deletions(-) delete mode 100644 doc/I08_StorageOrders.dox create mode 100644 doc/I15_StorageOrders.dox create mode 100644 doc/snippets/TopicStorageOrders_example.cpp (limited to 'doc') diff --git a/doc/I08_StorageOrders.dox b/doc/I08_StorageOrders.dox deleted file mode 100644 index 0ceb771d3..000000000 --- a/doc/I08_StorageOrders.dox +++ /dev/null @@ -1,11 +0,0 @@ -namespace Eigen { - -/** \page TopicStorageOrders Storage orders - - -TODO: write this dox page! - -Is linked from the tutorial on the Matrix class. - -*/ -} diff --git a/doc/I15_StorageOrders.dox b/doc/I15_StorageOrders.dox new file mode 100644 index 000000000..6b56ca8f8 --- /dev/null +++ b/doc/I15_StorageOrders.dox @@ -0,0 +1,91 @@ +namespace Eigen { + +/** \page TopicStorageOrders Storage orders + +There are two different storage orders for matrices and two-dimensional arrays: column-major and row-major. +This page explains these storage orders and how to specify which one should be used. + +Table of contents + - \ref TopicStorageOrdersIntro + - \ref TopicStorageOrdersInEigen + - \ref TopicStorageOrdersWhich + + +\section TopicStorageOrdersIntro Column-major and row-major storage + +The entries of a matrix form a two-dimensional grid. However, when the matrix is stored in memory, the entries +have to somehow be laid out linearly. There are two main ways to do this, by row and by column. + +We say that a matrix is stored in \b row-major order if it is stored row by row. The entire first row is +stored first, followed by the entire second row, and so on. Consider for example the matrix + +\f[ +A = \begin{bmatrix} +8 & 2 & 2 & 9 \\ +9 & 1 & 4 & 4 \\ +3 & 5 & 4 & 5 +\end{bmatrix}. +\f] + +If this matrix is stored in row-major order, then the entries are laid out in memory as follows: + +\code 8 2 2 9 9 1 4 4 3 5 4 5 \endcode + +On the other hand, a matrix is stored in \b column-major order if it is stored column by column, starting with +the entire first column, followed by the entire second column, and so on. If the above matrix is stored in +column-major order, it is laid out as follows: + +\code 8 9 3 2 1 5 2 4 4 9 4 5 \endcode + +This example is illustrated by the following Eigen code. It uses the PlainObjectBase::data() function, which +returns a pointer to the memory location of the first entry of the matrix. + + + + +
ExampleOutput
+\include TopicStorageOrders_example.cpp + +\verbinclude TopicStorageOrders_example.out +
+ + +\section TopicStorageOrdersInEigen Storage orders in Eigen + +The storage order of a matrix or a two-dimensional array can be set by specifying the \c Options template +parameter for Matrix or Array. As \ref TutorialMatrixClass explains, the %Matrix class template has six +template parameters, of which three are compulsory (\c Scalar, \c RowsAtCompileTime and \c ColsAtCompileTime) +and three are optional (\c Options, \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime). If the \c Options +parameter is set to \c RowMajor, then the matrix or array is stored in row-major order; if it is set to +\c ColMajor, then it is stored in column-major order. This mechanism is used in the above Eigen program to +specify the storage order. + +If the storage order is not specified, then Eigen normally defaults to storing the entry in column-major +order. This is also the case if one of the convenience typedefs (\c Matrix3f, \c ArrayXXd, etc.) is +used. However, it is possible to change the default to row-major order by defining the +\c EIGEN_DEFAULT_TO_ROW_MAJOR \ref TopicPreprocessorDirectives "preprocessor directive". + +Matrices and arrays using one storage order can be assigned to matrices and arrays using the other storage +order, as happens in the above program when \c Arowmajor is initialized using \c Acolmajor. Eigen will reorder +the entries automatically. More generally, row-major and column-major matrices can be mixed in an expression +as we want. + + +\section TopicStorageOrdersWhich Which storage order to choose? + +So, which storage order should you use in your program? There is no simple answer to this question; it depends +on your application. Here are some points to keep in mind: + + - Your users may expect you to use a specific storage order. Alternatively, you may use other libraries than + Eigen, and these other libraries may expect a certain storage order. In these cases it may be easiest and + fastest to use this storage order in your whole program. + - Algorithms that traverse a matrix row by row will go faster when the matrix is stored in row-major order + because of better data locality. Similarly, column-by-column traversal is faster for column-major + matrices. It may be worthwhile to experiment a bit to find out what is faster for your particular + application. + - The default in Eigen is column-major. Naturally, most of the development and testing of the Eigen library + is thus done with column-major matrices. This means that, even though we aim to support column-major and + row-major storage orders transparently, the Eigen library may well work best with column-major matrices. + +*/ +} diff --git a/doc/Overview.dox b/doc/Overview.dox index a4c4cde5d..04bc075f0 100644 --- a/doc/Overview.dox +++ b/doc/Overview.dox @@ -34,6 +34,7 @@ For a first contact with Eigen, the best place is to have a look at the \ref Get - \ref TopicLinearAlgebraDecompositions - \ref TopicCustomizingEigen - \ref TopicPreprocessorDirectives + - \ref TopicStorageOrders - \ref TopicInsideEigenExample - \ref TopicWritingEfficientProductExpression - \ref TopicClassHierarchy diff --git a/doc/snippets/TopicStorageOrders_example.cpp b/doc/snippets/TopicStorageOrders_example.cpp new file mode 100644 index 000000000..0623ef0c2 --- /dev/null +++ b/doc/snippets/TopicStorageOrders_example.cpp @@ -0,0 +1,18 @@ +Matrix Acolmajor; +Acolmajor << 8, 2, 2, 9, + 9, 1, 4, 4, + 3, 5, 4, 5; +cout << "The matrix A:" << endl; +cout << Acolmajor << endl << endl; + +cout << "In memory (column-major):" << endl; +for (int i = 0; i < Acolmajor.size(); i++) + cout << *(Acolmajor.data() + i) << " "; +cout << endl << endl; + +Matrix Arowmajor = Acolmajor; +cout << "In memory (row-major):" << endl; +for (int i = 0; i < Arowmajor.size(); i++) + cout << *(Arowmajor.data() + i) << " "; +cout << endl; + -- cgit v1.2.3