fuchsia / third_party / eigen / 64baccc877717d32db291a400c2d5726402fdeb9 / . / doc / StorageOrders.dox

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. | |

*/ | |

} |