eigen/doc/I15_StorageOrders.dox
Gael Guennebaud 93ee82b1fd Big changes in Eigen documentation:
- Organize the documentation into "chapters".
  - Each chapter include many documentation pages, reference pages organized as modules, and a quick reference page.
  - The "Chapters" tree is created using the defgroup/ingroup mechanism, even for the documentation pages (i.e., .dox files for which I added an \eigenManualPage macro that we can switch between \page or \defgroup ).
  - Add a "General topics" entry for all pages that do not fit well in the previous "chapters".
  - The highlevel struture is managed by a new eigendoxy_layout.xml file.
- remove the "index" and quite useless pages (namespace list, class hierarchy, member list, file list, etc.)
- add the javascript search-engine.
- add the "treeview" panel.
- remove \tableofcontents (replace them by a custom \eigenAutoToc macro to be able to easily re-enable if needed).
- add javascript to automatically generate a TOC from the h1/h2 tags of the current page, and put the TOC in the left side panel.
- overload various javascript function generated by doxygen to:
  - remove the root of the treeview
  - remove links to section/subsection from the treeview
  - automatically expand the "Chapters" section
  - automatically expand the current section
  - adjust the height of the treeview to take into account the TOC
- always use the default .css file, eigendoxy.css now only includes our modifications
- use Doxyfile to specify our logo
- remove cross references to unsupported modules (temporarily)
2013-01-05 16:37:11 +01:00

87 lines
4.0 KiB
Plaintext

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.
<table class="example">
<tr><th>Example</th><th>Output</th></tr>
<tr><td>
\include TopicStorageOrders_example.cpp
</td>
<td>
\verbinclude TopicStorageOrders_example.out
</td></tr></table>
\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.
*/
}