From 2abe7d8c6e11a02fc345f6ae464b4b759b092a67 Mon Sep 17 00:00:00 2001 From: Gael Guennebaud Date: Sun, 6 Jan 2013 23:57:54 +0100 Subject: Rename the dox files: the number prefixes are not needed anymore --- doc/StorageOrders.dox | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 doc/StorageOrders.dox (limited to 'doc/StorageOrders.dox') diff --git a/doc/StorageOrders.dox b/doc/StorageOrders.dox new file mode 100644 index 000000000..61645313e --- /dev/null +++ b/doc/StorageOrders.dox @@ -0,0 +1,86 @@ +namespace Eigen { + +/** \eigenManualPage 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. + +\eigenAutoToc + + +\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 defaults to storing the entry in column-major. This is also +the case if one of the convenience typedefs (\c Matrix3f, \c ArrayXXd, etc.) is used. + +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. + +*/ +} -- cgit v1.2.3