SVN commit 891007 by bjacob: add internal documentation M +2 -2 Dot.h M +3 -4 Matrix.h M +22 -4 util/Constants.h M +5 -2 util/Macros.h M +22 -0 util/XprHelper.h --- trunk/kdesupport/eigen2/Eigen/src/Core/Dot.h #891006:891007 @@ -273,7 +273,7 @@ /** \returns the squared norm of *this, i.e. the dot product of *this with itself. * - * \note This is \em not the \em l2 norm. + * \note This is \em not the \em l2 norm, but its square. * * \deprecated Use squaredNorm() instead. This norm2() function is kept only for compatibility and will be removed in Eigen 2.0. * @@ -282,7 +282,7 @@ * \sa dot(), norm() */ template -inline typename NumTraits::Scalar>::Real MatrixBase::norm2() const +EIGEN_DEPRECATED inline typename NumTraits::Scalar>::Real MatrixBase::norm2() const { return ei_real(dot(*this)); } --- trunk/kdesupport/eigen2/Eigen/src/Core/Matrix.h #891006:891007 @@ -44,11 +44,11 @@ * * \note Fixed-size versus dynamic-size: * Fixed-size means that the numbers of rows and columns are known are compile-time. In this case, Eigen allocates the array - * of coefficients as a fixed-size array on the stack. This makes sense for very small matrices, typically up to 4x4, sometimes up + * of coefficients as a fixed-size array, as a class member. This makes sense for very small matrices, typically up to 4x4, sometimes up * to 16x16. Larger matrices should be declared as dynamic-size even if one happens to know their size at compile-time. * * Dynamic-size means that the numbers of rows or columns are not necessarily known at compile-time. In this case they are runtime variables, - * and the array of coefficients is allocated dynamically, typically on the heap (See note on heap allocation below). + * and the array of coefficients is allocated dynamically, typically on the heap (See note on Usage of alloca() below). * * Note that dense matrices, be they Fixed-size or Dynamic-size, do not expand dynamically in the sense of a std::map. * If you want this behavior, see the Sparse module. @@ -60,7 +60,7 @@ * exceed a certain value. This happens when taking dynamic-size blocks inside fixed-size matrices: in this case _MaxRows and _MaxCols * are the dimensions of the original matrix, while _Rows and _Cols are Dynamic. * - * \note Heap allocation: + * \note Usage of alloca(): * On the Linux platform, for small enough arrays, Eigen will avoid heap allocation and instead will use alloca() to perform a dynamic * allocation on the stack. * @@ -85,7 +85,6 @@ * v[1] = 0.2; * v(0) = 0.1; * v(1) = 0.2; - * * Eigen::MatrixXi m(10, 10); * m(0, 1) = 1; --- trunk/kdesupport/eigen2/Eigen/src/Core/util/Constants.h #891006:891007 @@ -26,7 +26,25 @@ #ifndef EIGEN_CONSTANTS_H #define EIGEN_CONSTANTS_H +/** This value means that a quantity is not known at compile-time, and that instead the value is + * stored in some runtime variable. + * + * Explanation for the choice of this value: + * - It should be positive and larger than any reasonable compile-time-fixed number of rows or columns. + * This means that it should be at least 128 or so. + * - It should be smaller than the sqrt of INT_MAX. Indeed, we often multiply a number of rows with a number + * of columns in order to compute a number of coefficients. Even if we guard that with an "if" checking whether + * the values are Dynamic, we still get a compiler warning "integer overflow". So the only way to get around + * it would be a meta-selector. Doing this everywhere would reduce code readability and lenghten compilation times. + * Also, disabling compiler warnings for integer overflow, sounds like a bad idea. + * + * If you wish to port Eigen to a platform where sizeof(int)==2, it is perfectly possible to set Dynamic to, say, 250. + */ const int Dynamic = 10000; + +/** This value means +Infinity; it is currently used only as the p parameter to MatrixBase::lpNorm(). + * The value Infinity there means the L-infinity norm. + */ const int Infinity = -1; /** \defgroup flags flags @@ -199,9 +217,9 @@ }; enum { - CompleteUnrolling, + NoUnrolling, InnerUnrolling, - NoUnrolling + CompleteUnrolling }; enum { @@ -211,9 +229,9 @@ enum { IsDense = 0, + IsSparse = SparseBit, NoDirectAccess = 0, - HasDirectAccess = DirectAccessBit, - IsSparse = SparseBit + HasDirectAccess = DirectAccessBit }; const int FullyCoherentAccessPattern = 0x1; --- trunk/kdesupport/eigen2/Eigen/src/Core/util/Macros.h #891006:891007 @@ -28,7 +28,10 @@ #undef minor -/** \internal Defines the maximal loop size to enable meta unrolling of loops */ +/** \internal Defines the maximal loop size to enable meta unrolling of loops. + * Note that the value here is expressed in Eigen's own notion of "number of FLOPS", + * it does not correspond to the number of iterations or the number of instructions + */ #ifndef EIGEN_UNROLLING_LIMIT #define EIGEN_UNROLLING_LIMIT 100 #endif @@ -36,7 +39,7 @@ /** \internal Define the maximal size in Bytes of L2 blocks. * The current value is set to generate blocks of 256x256 for float */ #ifndef EIGEN_TUNE_FOR_L2_CACHE_SIZE -#define EIGEN_TUNE_FOR_L2_CACHE_SIZE (1024*256) +#define EIGEN_TUNE_FOR_L2_CACHE_SIZE (sizeof(float)*256*256) #endif #define USING_PART_OF_NAMESPACE_EIGEN \ --- trunk/kdesupport/eigen2/Eigen/src/Core/util/XprHelper.h #891006:891007 @@ -41,6 +41,10 @@ ei_no_assignment_operator& operator=(const ei_no_assignment_operator&); }; +/** \internal If the template parameter Value is Dynamic, this class is just a wrapper around an int variable that + * can be accessed using value() and setValue(). + * Otherwise, this class is an empty structure and value() just returns the template parameter Value. + */ template class ei_int_if_dynamic EIGEN_EMPTY_STRUCT { public: @@ -136,6 +140,24 @@ template struct ei_must_nest_by_value { enum { ret = false }; }; template struct ei_must_nest_by_value > { enum { ret = true }; }; +/** \internal Determines how a given expression should be nested into another one. + * For example, when you do a * (b+c), Eigen will determine how the expression b+c should be + * nested into the bigger product expression. The choice is between nesting the expression b+c as-is, or + * evaluating that expression b+c into a temporary variable d, and nest d so that the resulting expression is + * a*d. Evaluating can be beneficial for example if every coefficient access in the resulting expression causes + * many coefficient accesses in the nested expressions -- as is the case with matrix product for example. + * + * \param T the type of the expression being nested + * \param n the number of coefficient accesses in the nested expression for each coefficient access in the bigger expression. + * + * Example. Suppose that a, b, and c are of type Matrix3d. The user forms the expression a*(b+c). + * b+c is an expression "sum of matrices", which we will denote by S. In order to determine how to nest it, + * the Product expression uses: ei_nested::ret, which turns out to be Matrix3d because the internal logic of + * ei_nested determined that in this case it was better to evaluate the expression b+c into a temporary. On the other hand, + * since a is of type Matrix3d, the Product expression nests it as ei_nested::ret, which turns out to be + * const Matrix3d&, because the internal logic of ei_nested determined that since a was already a matrix, there was no point + * in copying it into another matrix. + */ template::type> struct ei_nested { enum {