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/TutorialBlockOperations.dox | 228 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 doc/TutorialBlockOperations.dox (limited to 'doc/TutorialBlockOperations.dox') diff --git a/doc/TutorialBlockOperations.dox b/doc/TutorialBlockOperations.dox new file mode 100644 index 000000000..a2d8c97cc --- /dev/null +++ b/doc/TutorialBlockOperations.dox @@ -0,0 +1,228 @@ +namespace Eigen { + +/** \eigenManualPage TutorialBlockOperations Block operations + +This page explains the essentials of block operations. +A block is a rectangular part of a matrix or array. Blocks expressions can be used both +as rvalues and as lvalues. As usual with Eigen expressions, this abstraction has zero runtime cost +provided that you let your compiler optimize. + +\eigenAutoToc + +\section TutorialBlockOperationsUsing Using block operations + +The most general block operation in Eigen is called \link DenseBase::block() .block() \endlink. +There are two versions, whose syntax is as follows: + + + + + + + + +
\b %Block \b operation +Version constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
%Block of size (p,q), starting at (i,j)\code +matrix.block(i,j,p,q);\endcode \code +matrix.block(i,j);\endcode
+ +As always in Eigen, indices start at 0. + +Both versions can be used on fixed-size and dynamic-size matrices and arrays. +These two expressions are semantically equivalent. +The only difference is that the fixed-size version will typically give you faster code if the block size is small, +but requires this size to be known at compile time. + +The following program uses the dynamic-size and fixed-size versions to print the values of several blocks inside a +matrix. + + + + +
Example:Output:
+\include Tutorial_BlockOperations_print_block.cpp + +\verbinclude Tutorial_BlockOperations_print_block.out +
+ +In the above example the \link DenseBase::block() .block() \endlink function was employed as a \em rvalue, i.e. +it was only read from. However, blocks can also be used as \em lvalues, meaning that you can assign to a block. + +This is illustrated in the following example. This example also demonstrates blocks in arrays, which works exactly like the above-demonstrated blocks in matrices. + + + + +
Example:Output:
+\include Tutorial_BlockOperations_block_assignment.cpp + +\verbinclude Tutorial_BlockOperations_block_assignment.out +
+ +While the \link DenseBase::block() .block() \endlink method can be used for any block operation, there are +other methods for special cases, providing more specialized API and/or better performance. On the topic of performance, all what +matters is that you give Eigen as much information as possible at compile time. For example, if your block is a single whole column in a matrix, +using the specialized \link DenseBase::col() .col() \endlink function described below lets Eigen know that, which can give it optimization opportunities. + +The rest of this page describes these specialized methods. + +\section TutorialBlockOperationsSyntaxColumnRows Columns and rows + +Individual columns and rows are special cases of blocks. Eigen provides methods to easily address them: +\link DenseBase::col() .col() \endlink and \link DenseBase::row() .row()\endlink. + + + + + + + + + + +
%Block operationMethod
ith row + \link DenseBase::row() * \endlink\code +matrix.row(i);\endcode
jth column + \link DenseBase::col() * \endlink\code +matrix.col(j);\endcode
+ +The argument for \p col() and \p row() is the index of the column or row to be accessed. As always in Eigen, indices start at 0. + + + + +
Example:Output:
+\include Tutorial_BlockOperations_colrow.cpp + +\verbinclude Tutorial_BlockOperations_colrow.out +
+ +That example also demonstrates that block expressions (here columns) can be used in arithmetic like any other expression. + + +\section TutorialBlockOperationsSyntaxCorners Corner-related operations + +Eigen also provides special methods for blocks that are flushed against one of the corners or sides of a +matrix or array. For instance, \link DenseBase::topLeftCorner() .topLeftCorner() \endlink can be used to refer +to a block in the top-left corner of a matrix. + +The different possibilities are summarized in the following table: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
%Block \b operation +Version constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
Top-left p by q block \link DenseBase::topLeftCorner() * \endlink\code +matrix.topLeftCorner(p,q);\endcode \code +matrix.topLeftCorner();\endcode
Bottom-left p by q block + \link DenseBase::bottomLeftCorner() * \endlink\code +matrix.bottomLeftCorner(p,q);\endcode \code +matrix.bottomLeftCorner();\endcode
Top-right p by q block + \link DenseBase::topRightCorner() * \endlink\code +matrix.topRightCorner(p,q);\endcode \code +matrix.topRightCorner();\endcode
Bottom-right p by q block + \link DenseBase::bottomRightCorner() * \endlink\code +matrix.bottomRightCorner(p,q);\endcode \code +matrix.bottomRightCorner();\endcode
%Block containing the first q rows + \link DenseBase::topRows() * \endlink\code +matrix.topRows(q);\endcode \code +matrix.topRows();\endcode
%Block containing the last q rows + \link DenseBase::bottomRows() * \endlink\code +matrix.bottomRows(q);\endcode \code +matrix.bottomRows();\endcode
%Block containing the first p columns + \link DenseBase::leftCols() * \endlink\code +matrix.leftCols(p);\endcode \code +matrix.leftCols

();\endcode

%Block containing the last q columns + \link DenseBase::rightCols() * \endlink\code +matrix.rightCols(q);\endcode \code +matrix.rightCols();\endcode
+ +Here is a simple example illustrating the use of the operations presented above: + + + + +
Example:Output:
+\include Tutorial_BlockOperations_corner.cpp + +\verbinclude Tutorial_BlockOperations_corner.out +
+ + +\section TutorialBlockOperationsSyntaxVectors Block operations for vectors + +Eigen also provides a set of block operations designed specifically for the special case of vectors and one-dimensional arrays: + + + + + + + + + + + + + + + + + +
%Block operationVersion constructing a \n dynamic-size block expressionVersion constructing a \n fixed-size block expression
%Block containing the first \p n elements + \link DenseBase::head() * \endlink\code +vector.head(n);\endcode \code +vector.head();\endcode
%Block containing the last \p n elements + \link DenseBase::tail() * \endlink\code +vector.tail(n);\endcode \code +vector.tail();\endcode
%Block containing \p n elements, starting at position \p i + \link DenseBase::segment() * \endlink\code +vector.segment(i,n);\endcode \code +vector.segment(i);\endcode
+ + +An example is presented below: + + + +
Example:Output:
+\include Tutorial_BlockOperations_vector.cpp + +\verbinclude Tutorial_BlockOperations_vector.out +
+ +*/ + +} -- cgit v1.2.3