Relatively straightforward changes to wording of documentation, focusing particularly on the sparse and (to a lesser extent) geometry pages.

(transplanted from 16a2d896bc77f42102fef5f6407a4eb64cb4b62d
)
This commit is contained in:
Tim Holy 2011-06-20 22:47:58 -05:00
parent 13a17d968f
commit fae2aa3fd9
4 changed files with 15 additions and 15 deletions

View File

@ -63,7 +63,7 @@ The output is as follows:
The second example starts by declaring a 3-by-3 matrix \c m which is initialized using the \link DenseBase::Random(Index,Index) Random() \endlink method with random values between -1 and 1. The next line applies a linear mapping such that the values are between 10 and 110. The function call \link DenseBase::Constant(Index,Index,const Scalar&) MatrixXd::Constant\endlink(3,3,1.2) returns a 3-by-3 matrix expression having all coefficients equal to 1.2. The rest is standard arithmetics. The second example starts by declaring a 3-by-3 matrix \c m which is initialized using the \link DenseBase::Random(Index,Index) Random() \endlink method with random values between -1 and 1. The next line applies a linear mapping such that the values are between 10 and 110. The function call \link DenseBase::Constant(Index,Index,const Scalar&) MatrixXd::Constant\endlink(3,3,1.2) returns a 3-by-3 matrix expression having all coefficients equal to 1.2. The rest is standard arithmetics.
The next line of the \c main function introduces a new type: \c VectorXd. This represents a (column) vector of arbitrary size. Here, the vector \c v is created to contains \c 3 coefficients which are left unitialized. The one but last line uses the so-called comma-initializer, explained in \ref TutorialAdvancedInitialization, to set all coefficients of the vector \c v to be as follows: The next line of the \c main function introduces a new type: \c VectorXd. This represents a (column) vector of arbitrary size. Here, the vector \c v is created to contain \c 3 coefficients which are left unitialized. The one but last line uses the so-called comma-initializer, explained in \ref TutorialAdvancedInitialization, to set all coefficients of the vector \c v to be as follows:
\f[ \f[
v = v =

View File

@ -93,7 +93,7 @@ Array.
The arguments passed to a visitor are pointers to the variables where the The arguments passed to a visitor are pointers to the variables where the
row and column position are to be stored. These variables should be of type row and column position are to be stored. These variables should be of type
\link DenseBase::Index Index \endlink (FIXME: link ok?), as shown below: \link DenseBase::Index Index \endlink, as shown below:
<table class="example"> <table class="example">
<tr><th>Example:</th><th>Output:</th></tr> <tr><th>Example:</th><th>Output:</th></tr>
@ -141,7 +141,7 @@ return a 'column-vector'</b>
\subsection TutorialReductionsVisitorsBroadcastingPartialReductionsCombined Combining partial reductions with other operations \subsection TutorialReductionsVisitorsBroadcastingPartialReductionsCombined Combining partial reductions with other operations
It is also possible to use the result of a partial reduction to do further processing. It is also possible to use the result of a partial reduction to do further processing.
Here is another example that aims to find the column whose sum of elements is the maximum Here is another example that finds the column whose sum of elements is the maximum
within a matrix. With column-wise partial reductions this can be coded as: within a matrix. With column-wise partial reductions this can be coded as:
<table class="example"> <table class="example">

View File

@ -6,7 +6,7 @@ namespace Eigen {
\li \b Previous: \ref TutorialReductionsVisitorsBroadcasting \li \b Previous: \ref TutorialReductionsVisitorsBroadcasting
\li \b Next: \ref TutorialSparse \li \b Next: \ref TutorialSparse
In this tutorial, we will shortly introduce the many possibilities offered by the \ref Geometry_Module "geometry module", namely 2D and 3D rotations and projective or affine transformations. In this tutorial, we will briefly introduce the many possibilities offered by the \ref Geometry_Module "geometry module", namely 2D and 3D rotations and projective or affine transformations.
\b Table \b of \b contents \b Table \b of \b contents
- \ref TutorialGeoElementaryTransformations - \ref TutorialGeoElementaryTransformations
@ -78,7 +78,7 @@ representations are rotation matrices, while for other usages Quaternion is the
representation of choice as they are compact, fast and stable. Finally Rotation2D and representation of choice as they are compact, fast and stable. Finally Rotation2D and
AngleAxis are mainly convenient types to create other rotation objects. AngleAxis are mainly convenient types to create other rotation objects.
<strong>Notes on Translation and Scaling</strong>\n Likewise AngleAxis, these classes were <strong>Notes on Translation and Scaling</strong>\n Like AngleAxis, these classes were
designed to simplify the creation/initialization of linear (Matrix) and affine (Transform) designed to simplify the creation/initialization of linear (Matrix) and affine (Transform)
transformations. Nevertheless, unlike AngleAxis which is inefficient to use, these classes transformations. Nevertheless, unlike AngleAxis which is inefficient to use, these classes
might still be interesting to write generic and efficient algorithms taking as input any might still be interesting to write generic and efficient algorithms taking as input any
@ -186,7 +186,7 @@ matNxN = t.extractRotation();
While transformation objects can be created and updated concatenating elementary transformations, While transformation objects can be created and updated concatenating elementary transformations,
the Transform class also features a procedural API: the Transform class also features a procedural API:
<table class="manual"> <table class="manual">
<tr><th></th><th>procedurale API</th><th>equivalent natural API </th></tr> <tr><th></th><th>procedural API</th><th>equivalent natural API </th></tr>
<tr><td>Translation</td><td>\code <tr><td>Translation</td><td>\code
t.translate(Vector_(tx,ty,..)); t.translate(Vector_(tx,ty,..));
t.pretranslate(Vector_(tx,ty,..)); t.pretranslate(Vector_(tx,ty,..));
@ -234,7 +234,7 @@ t = Translation_(..) * t * RotationType(..) * Translation_(..) * Scaling_(..);
<table class="manual"> <table class="manual">
<tr><td style="max-width:30em;"> <tr><td style="max-width:30em;">
Euler angles might be convenient to create rotation objects. Euler angles might be convenient to create rotation objects.
On the other hand, since there exist 24 differents convension,they are pretty confusing to use. This example shows how On the other hand, since there exist 24 different conventions, they are pretty confusing to use. This example shows how
to create a rotation matrix according to the 2-1-2 convention.</td><td>\code to create a rotation matrix according to the 2-1-2 convention.</td><td>\code
Matrix3f m; Matrix3f m;
m = AngleAxisf(angle1, Vector3f::UnitZ()) m = AngleAxisf(angle1, Vector3f::UnitZ())

View File

@ -55,17 +55,17 @@ and its internal representation using the Compressed Column Storage format:
</table> </table>
Outer indices:<table class="manual"><tr><td>0</td><td>2</td><td>4</td><td>5</td><td>6</td><td>\em 7 </td></tr></table> Outer indices:<table class="manual"><tr><td>0</td><td>2</td><td>4</td><td>5</td><td>6</td><td>\em 7 </td></tr></table>
As you can guess, here the storage order is even more important than with dense matrix. We will therefore often make a clear difference between the \em inner and \em outer dimensions. For instance, it is easy to loop over the coefficients of an \em inner \em vector (e.g., a column of a column-major matrix), but completely inefficient to do the same for an \em outer \em vector (e.g., a row of a col-major matrix). As you might guess, here the storage order is even more important than with dense matrices. We will therefore often make a clear difference between the \em inner and \em outer dimensions. For instance, it is efficient to loop over the coefficients of an \em inner \em vector (e.g., a column of a column-major matrix), but completely inefficient to do the same for an \em outer \em vector (e.g., a row of a column-major matrix).
The SparseVector class implements the same compressed storage scheme but, of course, without any outer index buffer. The SparseVector class implements the same compressed storage scheme but, of course, without any outer index buffer.
Since all nonzero coefficients of such a matrix are sequentially stored in memory, random insertion of new nonzeros can be extremely costly. To overcome this limitation, Eigen's sparse module provides a DynamicSparseMatrix class which is basically implemented as an array of SparseVector. In other words, a DynamicSparseMatrix is a SparseMatrix where the values and inner-indices arrays have been splitted into multiple small and resizable arrays. Assuming the number of nonzeros per inner vector is relatively low, this slight modification allow for very fast random insertion at the cost of a slight memory overhead and a lost of compatibility with other sparse libraries used by some of our highlevel solvers. Note that the major memory overhead comes from the extra memory preallocated by each inner vector to avoid an expensive memory reallocation at every insertion. Since all nonzero coefficients of such a matrix are sequentially stored in memory, inserting a new nonzero near the "beginning" of the matrix can be extremely costly. As described below (\ref TutorialSparseFilling), one strategy is to fill nonzero coefficients in order. In cases where this is not possible, Eigen's sparse module also provides a DynamicSparseMatrix class which allows efficient random insertion. DynamicSparseMatrix is essentially implemented as an array of SparseVector, where the values and inner-indices arrays have been split into multiple small and resizable arrays. Assuming the number of nonzeros per inner vector is relatively small, this modification allows for very fast random insertion at the cost of a slight memory overhead (due to extra memory preallocated by each inner vector to avoid an expensive memory reallocation at every insertion) and a loss of compatibility with other sparse libraries used by some of our high-level solvers. Once complete, a DynamicSparseMatrix can be converted to a SparseMatrix to permit usage of these sparse libraries.
To summarize, it is recommanded to use a SparseMatrix whenever this is possible, and reserve the use of DynamicSparseMatrix for matrix assembly purpose when a SparseMatrix is not flexible enough. The respective pro/cons of both representations are summarized in the following table: To summarize, it is recommended to use SparseMatrix whenever possible, and reserve the use of DynamicSparseMatrix to assemble a sparse matrix in cases when a SparseMatrix is not flexible enough. The respective pros/cons of both representations are summarized in the following table:
<table class="manual"> <table class="manual">
<tr><td></td> <td>SparseMatrix</td><td>DynamicSparseMatrix</td></tr> <tr><td></td> <td>SparseMatrix</td><td>DynamicSparseMatrix</td></tr>
<tr><td>memory usage</td><td>***</td><td>**</td></tr> <tr><td>memory efficiency</td><td>***</td><td>**</td></tr>
<tr><td>sorted insertion</td><td>***</td><td>***</td></tr> <tr><td>sorted insertion</td><td>***</td><td>***</td></tr>
<tr><td>random insertion \n in sorted inner vector</td><td>**</td><td>**</td></tr> <tr><td>random insertion \n in sorted inner vector</td><td>**</td><td>**</td></tr>
<tr><td>sorted insertion \n in random inner vector</td><td>-</td><td>***</td></tr> <tr><td>sorted insertion \n in random inner vector</td><td>-</td><td>***</td></tr>
@ -82,7 +82,7 @@ To summarize, it is recommanded to use a SparseMatrix whenever this is possible,
\b Matrix \b and \b vector \b properties \n \b Matrix \b and \b vector \b properties \n
Here mat and vec represents any sparse-matrix and sparse-vector types respectively. Here mat and vec represent any sparse-matrix and sparse-vector type, respectively.
<table class="manual"> <table class="manual">
<tr><td>Standard \n dimensions</td><td>\code <tr><td>Standard \n dimensions</td><td>\code
@ -96,7 +96,7 @@ mat.innerSize()
mat.outerSize()\endcode</td> mat.outerSize()\endcode</td>
<td></td> <td></td>
</tr> </tr>
<tr><td>Number of non \n zero coefficiens</td><td>\code <tr><td>Number of non \n zero coefficients</td><td>\code
mat.nonZeros() \endcode</td> mat.nonZeros() \endcode</td>
<td>\code <td>\code
vec.nonZeros() \endcode</td></tr> vec.nonZeros() \endcode</td></tr>
@ -105,12 +105,12 @@ vec.nonZeros() \endcode</td></tr>
\b Iterating \b over \b the \b nonzero \b coefficients \n \b Iterating \b over \b the \b nonzero \b coefficients \n
Iterating over the coefficients of a sparse matrix can be done only in the same order than the storage order. Here is an example: Iterating over the coefficients of a sparse matrix can be done only in the same order as the storage order. Here is an example:
<table class="manual"> <table class="manual">
<tr><td> <tr><td>
\code \code
SparseMatrixType mat(rows,cols); SparseMatrixType mat(rows,cols);
for (int k=0; k\<m1.outerSize(); ++k) for (int k=0; k<m1.outerSize(); ++k)
for (SparseMatrixType::InnerIterator it(mat,k); it; ++it) for (SparseMatrixType::InnerIterator it(mat,k); it; ++it)
{ {
it.value(); it.value();