mirror of
https://gitlab.com/libeigen/eigen.git
synced 2025-06-04 18:54:00 +08:00
93ee82b1fd
- 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)
87 lines
4.0 KiB
Plaintext
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.
|
|
|
|
*/
|
|
}
|