mirror of
https://gitlab.com/libeigen/eigen.git
synced 2025-07-08 22:21:49 +08:00
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:
parent
13a17d968f
commit
fae2aa3fd9
@ -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 =
|
||||||
|
@ -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">
|
||||||
|
@ -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())
|
||||||
|
@ -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();
|
||||||
|
Loading…
x
Reference in New Issue
Block a user