<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Eigen: Storage orders</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<!-- -->
<script type="text/javascript" src="eigen_navtree_hacks.js"></script>
<!-- <script type="text/javascript"> -->
<!-- </script> -->
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!-- <a name="top"></a> -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="Eigen_Silly_Professor_64x64.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname"><a href="http://eigen.tuxfamily.org">Eigen</a>
 <span id="projectnumber">3.2.0</span>
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__TopicStorageOrders.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Storage orders<div class="ingroups"><a class="el" href="group__DenseMatrixManipulation__chapter.html">Dense matrix and array manipulation</a></div></div> </div>
</div><!--header-->
<div class="contents">
<p>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.</p>
<h1><a class="anchor" id="TopicStorageOrdersIntro"></a>
Column-major and row-major storage</h1>
<p>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.</p>
<p>We say that a matrix is stored in <b>row-major</b> 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</p>
<p class="formulaDsp">
<img class="formulaDsp" alt="\[ A = \begin{bmatrix} 8 & 2 & 2 & 9 \\ 9 & 1 & 4 & 4 \\ 3 & 5 & 4 & 5 \end{bmatrix}. \]" src="form_176.png"/>
</p>
<p>If this matrix is stored in row-major order, then the entries are laid out in memory as follows:</p>
<div class="fragment"><div class="line">8 2 2 9 9 1 4 4 3 5 4 5 </div>
</div><!-- fragment --><p>On the other hand, a matrix is stored in <b>column-major</b> 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:</p>
<div class="fragment"><div class="line">8 9 3 2 1 5 2 4 4 9 4 5 </div>
</div><!-- fragment --><p>This example is illustrated by the following <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> code. It uses the <a class="el" href="classEigen_1_1PlainObjectBase.html#a4663159a1450fa89214b1ab71f7ef5bf">PlainObjectBase::data()</a> function, which returns a pointer to the memory location of the first entry of the matrix.</p>
<table class="example">
<tr>
<th>Example</th><th>Output </th></tr>
<tr>
<td><div class="fragment"><div class="line">Matrix<int, 3, 4, ColMajor> Acolmajor;</div>
<div class="line">Acolmajor << 8, 2, 2, 9,</div>
<div class="line"> 9, 1, 4, 4,</div>
<div class="line"> 3, 5, 4, 5;</div>
<div class="line">cout << <span class="stringliteral">"The matrix A:"</span> << endl;</div>
<div class="line">cout << Acolmajor << endl << endl; </div>
<div class="line"></div>
<div class="line">cout << <span class="stringliteral">"In memory (column-major):"</span> << endl;</div>
<div class="line"><span class="keywordflow">for</span> (<span class="keywordtype">int</span> i = 0; i < Acolmajor.size(); i++)</div>
<div class="line"> cout << *(Acolmajor.data() + i) << <span class="stringliteral">" "</span>;</div>
<div class="line">cout << endl << endl;</div>
<div class="line"></div>
<div class="line">Matrix<int, 3, 4, RowMajor> Arowmajor = Acolmajor;</div>
<div class="line">cout << <span class="stringliteral">"In memory (row-major):"</span> << endl;</div>
<div class="line"><span class="keywordflow">for</span> (<span class="keywordtype">int</span> i = 0; i < Arowmajor.size(); i++)</div>
<div class="line"> cout << *(Arowmajor.data() + i) << <span class="stringliteral">" "</span>;</div>
<div class="line">cout << endl;</div>
<div class="line"></div>
</div><!-- fragment --> </td><td><pre class="fragment">The matrix A:
8 2 2 9
9 1 4 4
3 5 4 5
In memory (column-major):
8 9 3 2 1 5 2 4 4 9 4 5
In memory (row-major):
8 2 2 9 9 1 4 4 3 5 4 5
</pre> </td></tr>
</table>
<h1><a class="anchor" id="TopicStorageOrdersInEigen"></a>
Storage orders in Eigen</h1>
<p>The storage order of a matrix or a two-dimensional array can be set by specifying the <code>Options</code> template parameter for <a class="el" href="classEigen_1_1Matrix.html" title="The matrix class, also used for vectors and row-vectors. ">Matrix</a> or <a class="el" href="classEigen_1_1Array.html" title="General-purpose arrays with easy API for coefficient-wise operations. ">Array</a>. As <a class="el" href="group__TutorialMatrixClass.html">The Matrix class</a> explains, the Matrix class template has six template parameters, of which three are compulsory (<code>Scalar</code>, <code>RowsAtCompileTime</code> and <code>ColsAtCompileTime</code>) and three are optional (<code>Options</code>, <code>MaxRowsAtCompileTime</code> and <code>MaxColsAtCompileTime</code>). If the <code>Options</code> parameter is set to <code>RowMajor</code>, then the matrix or array is stored in row-major order; if it is set to <code>ColMajor</code>, then it is stored in column-major order. This mechanism is used in the above <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> program to specify the storage order.</p>
<p>If the storage order is not specified, then <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> defaults to storing the entry in column-major. This is also the case if one of the convenience typedefs (<code>Matrix3f</code>, <code>ArrayXXd</code>, etc.) is used.</p>
<p>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 <code>Arowmajor</code> is initialized using <code>Acolmajor</code>. <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> will reorder the entries automatically. More generally, row-major and column-major matrices can be mixed in an expression as we want.</p>
<h1><a class="anchor" id="TopicStorageOrdersWhich"></a>
Which storage order to choose?</h1>
<p>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:</p>
<ul>
<li>Your users may expect you to use a specific storage order. Alternatively, you may use other libraries than <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a>, 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.</li>
<li>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.</li>
<li>The default in <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> is column-major. Naturally, most of the development and testing of the <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> 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 <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> library may well work best with column-major matrices. </li>
</ul>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Mon Oct 28 2013 11:04:27 for Eigen by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
</ul>
</div>
<!-- Piwik -->
<!--
<script type="text/javascript">
var pkBaseURL = (("https:" == document.location.protocol) ? "https://stats.sylphide-consulting.com/piwik/" : "http://stats.sylphide-consulting.com/piwik/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
try {
var piwikTracker = Piwik.getTracker(pkBaseURL + "piwik.php", 20);
piwikTracker.trackPageView();
piwikTracker.enableLinkTracking();
} catch( err ) {}
</script><noscript><p><img src="http://stats.sylphide-consulting.com/piwik/piwik.php?idsite=20" style="border:0" alt="" /></p></noscript>
-->
<!-- End Piwik Tracking Code -->
</body>
</html>
