1 // This file is part of Eigen, a lightweight C++ template library 2 // for linear algebra. 3 // 4 // Copyright (C) 2008-2009 Gael Guennebaud <gael.guennebaud@inria.fr> 5 // Copyright (C) 2007-2009 Benoit Jacob <jacob.benoit.1@gmail.com> 6 // 7 // This Source Code Form is subject to the terms of the Mozilla 8 // Public License v. 2.0. If a copy of the MPL was not distributed 9 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/. 10 11 #ifndef EIGEN_CONSTANTS_H 12 #define EIGEN_CONSTANTS_H 13 14 namespace Eigen { 15 16 /** This value means that a positive quantity (e.g., a size) is not known at compile-time, and that instead the value is 17 * stored in some runtime variable. 18 * 19 * Changing the value of Dynamic breaks the ABI, as Dynamic is often used as a template parameter for Matrix. 20 */ 21 const int Dynamic = -1; 22 23 /** This value means that a signed quantity (e.g., a signed index) is not known at compile-time, and that instead its value 24 * has to be specified at runtime. 25 */ 26 const int DynamicIndex = 0xffffff; 27 28 /** This value means +Infinity; it is currently used only as the p parameter to MatrixBase::lpNorm<int>(). 29 * The value Infinity there means the L-infinity norm. 30 */ 31 const int Infinity = -1; 32 33 /** \defgroup flags Flags 34 * \ingroup Core_Module 35 * 36 * These are the possible bits which can be OR'ed to constitute the flags of a matrix or 37 * expression. 38 * 39 * It is important to note that these flags are a purely compile-time notion. They are a compile-time property of 40 * an expression type, implemented as enum's. They are not stored in memory at runtime, and they do not incur any 41 * runtime overhead. 42 * 43 * \sa MatrixBase::Flags 44 */ 45 46 /** \ingroup flags 47 * 48 * for a matrix, this means that the storage order is row-major. 49 * If this bit is not set, the storage order is column-major. 50 * For an expression, this determines the storage order of 51 * the matrix created by evaluation of that expression. 52 * \sa \ref TopicStorageOrders */ 53 const unsigned int RowMajorBit = 0x1; 54 55 /** \ingroup flags 56 * 57 * means the expression should be evaluated by the calling expression */ 58 const unsigned int EvalBeforeNestingBit = 0x2; 59 60 /** \ingroup flags 61 * 62 * means the expression should be evaluated before any assignment */ 63 const unsigned int EvalBeforeAssigningBit = 0x4; 64 65 /** \ingroup flags 66 * 67 * Short version: means the expression might be vectorized 68 * 69 * Long version: means that the coefficients can be handled by packets 70 * and start at a memory location whose alignment meets the requirements 71 * of the present CPU architecture for optimized packet access. In the fixed-size 72 * case, there is the additional condition that it be possible to access all the 73 * coefficients by packets (this implies the requirement that the size be a multiple of 16 bytes, 74 * and that any nontrivial strides don't break the alignment). In the dynamic-size case, 75 * there is no such condition on the total size and strides, so it might not be possible to access 76 * all coeffs by packets. 77 * 78 * \note This bit can be set regardless of whether vectorization is actually enabled. 79 * To check for actual vectorizability, see \a ActualPacketAccessBit. 80 */ 81 const unsigned int PacketAccessBit = 0x8; 82 83 #ifdef EIGEN_VECTORIZE 84 /** \ingroup flags 85 * 86 * If vectorization is enabled (EIGEN_VECTORIZE is defined) this constant 87 * is set to the value \a PacketAccessBit. 88 * 89 * If vectorization is not enabled (EIGEN_VECTORIZE is not defined) this constant 90 * is set to the value 0. 91 */ 92 const unsigned int ActualPacketAccessBit = PacketAccessBit; 93 #else 94 const unsigned int ActualPacketAccessBit = 0x0; 95 #endif 96 97 /** \ingroup flags 98 * 99 * Short version: means the expression can be seen as 1D vector. 100 * 101 * Long version: means that one can access the coefficients 102 * of this expression by coeff(int), and coeffRef(int) in the case of a lvalue expression. These 103 * index-based access methods are guaranteed 104 * to not have to do any runtime computation of a (row, col)-pair from the index, so that it 105 * is guaranteed that whenever it is available, index-based access is at least as fast as 106 * (row,col)-based access. Expressions for which that isn't possible don't have the LinearAccessBit. 107 * 108 * If both PacketAccessBit and LinearAccessBit are set, then the 109 * packets of this expression can be accessed by packet(int), and writePacket(int) in the case of a 110 * lvalue expression. 111 * 112 * Typically, all vector expressions have the LinearAccessBit, but there is one exception: 113 * Product expressions don't have it, because it would be troublesome for vectorization, even when the 114 * Product is a vector expression. Thus, vector Product expressions allow index-based coefficient access but 115 * not index-based packet access, so they don't have the LinearAccessBit. 116 */ 117 const unsigned int LinearAccessBit = 0x10; 118 119 /** \ingroup flags 120 * 121 * Means the expression has a coeffRef() method, i.e. is writable as its individual coefficients are directly addressable. 122 * This rules out read-only expressions. 123 * 124 * Note that DirectAccessBit and LvalueBit are mutually orthogonal, as there are examples of expression having one but note 125 * the other: 126 * \li writable expressions that don't have a very simple memory layout as a strided array, have LvalueBit but not DirectAccessBit 127 * \li Map-to-const expressions, for example Map<const Matrix>, have DirectAccessBit but not LvalueBit 128 * 129 * Expressions having LvalueBit also have their coeff() method returning a const reference instead of returning a new value. 130 */ 131 const unsigned int LvalueBit = 0x20; 132 133 /** \ingroup flags 134 * 135 * Means that the underlying array of coefficients can be directly accessed as a plain strided array. The memory layout 136 * of the array of coefficients must be exactly the natural one suggested by rows(), cols(), 137 * outerStride(), innerStride(), and the RowMajorBit. This rules out expressions such as Diagonal, whose coefficients, 138 * though referencable, do not have such a regular memory layout. 139 * 140 * See the comment on LvalueBit for an explanation of how LvalueBit and DirectAccessBit are mutually orthogonal. 141 */ 142 const unsigned int DirectAccessBit = 0x40; 143 144 /** \ingroup flags 145 * 146 * means the first coefficient packet is guaranteed to be aligned */ 147 const unsigned int AlignedBit = 0x80; 148 149 const unsigned int NestByRefBit = 0x100; 150 151 // list of flags that are inherited by default 152 const unsigned int HereditaryBits = RowMajorBit 153 | EvalBeforeNestingBit 154 | EvalBeforeAssigningBit; 155 156 /** \defgroup enums Enumerations 157 * \ingroup Core_Module 158 * 159 * Various enumerations used in %Eigen. Many of these are used as template parameters. 160 */ 161 162 /** \ingroup enums 163 * Enum containing possible values for the \p Mode parameter of 164 * MatrixBase::selfadjointView() and MatrixBase::triangularView(). */ 165 enum { 166 /** View matrix as a lower triangular matrix. */ 167 Lower=0x1, 168 /** View matrix as an upper triangular matrix. */ 169 Upper=0x2, 170 /** %Matrix has ones on the diagonal; to be used in combination with #Lower or #Upper. */ 171 UnitDiag=0x4, 172 /** %Matrix has zeros on the diagonal; to be used in combination with #Lower or #Upper. */ 173 ZeroDiag=0x8, 174 /** View matrix as a lower triangular matrix with ones on the diagonal. */ 175 UnitLower=UnitDiag|Lower, 176 /** View matrix as an upper triangular matrix with ones on the diagonal. */ 177 UnitUpper=UnitDiag|Upper, 178 /** View matrix as a lower triangular matrix with zeros on the diagonal. */ 179 StrictlyLower=ZeroDiag|Lower, 180 /** View matrix as an upper triangular matrix with zeros on the diagonal. */ 181 StrictlyUpper=ZeroDiag|Upper, 182 /** Used in BandMatrix and SelfAdjointView to indicate that the matrix is self-adjoint. */ 183 SelfAdjoint=0x10, 184 /** Used to support symmetric, non-selfadjoint, complex matrices. */ 185 Symmetric=0x20 186 }; 187 188 /** \ingroup enums 189 * Enum for indicating whether an object is aligned or not. */ 190 enum { 191 /** Object is not correctly aligned for vectorization. */ 192 Unaligned=0, 193 /** Object is aligned for vectorization. */ 194 Aligned=1 195 }; 196 197 /** \ingroup enums 198 * Enum used by DenseBase::corner() in Eigen2 compatibility mode. */ 199 // FIXME after the corner() API change, this was not needed anymore, except by AlignedBox 200 // TODO: find out what to do with that. Adapt the AlignedBox API ? 201 enum CornerType { TopLeft, TopRight, BottomLeft, BottomRight }; 202 203 /** \ingroup enums 204 * Enum containing possible values for the \p Direction parameter of 205 * Reverse, PartialReduxExpr and VectorwiseOp. */ 206 enum DirectionType { 207 /** For Reverse, all columns are reversed; 208 * for PartialReduxExpr and VectorwiseOp, act on columns. */ 209 Vertical, 210 /** For Reverse, all rows are reversed; 211 * for PartialReduxExpr and VectorwiseOp, act on rows. */ 212 Horizontal, 213 /** For Reverse, both rows and columns are reversed; 214 * not used for PartialReduxExpr and VectorwiseOp. */ 215 BothDirections 216 }; 217 218 /** \internal \ingroup enums 219 * Enum to specify how to traverse the entries of a matrix. */ 220 enum { 221 /** \internal Default traversal, no vectorization, no index-based access */ 222 DefaultTraversal, 223 /** \internal No vectorization, use index-based access to have only one for loop instead of 2 nested loops */ 224 LinearTraversal, 225 /** \internal Equivalent to a slice vectorization for fixed-size matrices having good alignment 226 * and good size */ 227 InnerVectorizedTraversal, 228 /** \internal Vectorization path using a single loop plus scalar loops for the 229 * unaligned boundaries */ 230 LinearVectorizedTraversal, 231 /** \internal Generic vectorization path using one vectorized loop per row/column with some 232 * scalar loops to handle the unaligned boundaries */ 233 SliceVectorizedTraversal, 234 /** \internal Special case to properly handle incompatible scalar types or other defecting cases*/ 235 InvalidTraversal, 236 /** \internal Evaluate all entries at once */ 237 AllAtOnceTraversal 238 }; 239 240 /** \internal \ingroup enums 241 * Enum to specify whether to unroll loops when traversing over the entries of a matrix. */ 242 enum { 243 /** \internal Do not unroll loops. */ 244 NoUnrolling, 245 /** \internal Unroll only the inner loop, but not the outer loop. */ 246 InnerUnrolling, 247 /** \internal Unroll both the inner and the outer loop. If there is only one loop, 248 * because linear traversal is used, then unroll that loop. */ 249 CompleteUnrolling 250 }; 251 252 /** \internal \ingroup enums 253 * Enum to specify whether to use the default (built-in) implementation or the specialization. */ 254 enum { 255 Specialized, 256 BuiltIn 257 }; 258 259 /** \ingroup enums 260 * Enum containing possible values for the \p _Options template parameter of 261 * Matrix, Array and BandMatrix. */ 262 enum { 263 /** Storage order is column major (see \ref TopicStorageOrders). */ 264 ColMajor = 0, 265 /** Storage order is row major (see \ref TopicStorageOrders). */ 266 RowMajor = 0x1, // it is only a coincidence that this is equal to RowMajorBit -- don't rely on that 267 /** Align the matrix itself if it is vectorizable fixed-size */ 268 AutoAlign = 0, 269 /** Don't require alignment for the matrix itself (the array of coefficients, if dynamically allocated, may still be requested to be aligned) */ // FIXME --- clarify the situation 270 DontAlign = 0x2 271 }; 272 273 /** \ingroup enums 274 * Enum for specifying whether to apply or solve on the left or right. */ 275 enum { 276 /** Apply transformation on the left. */ 277 OnTheLeft = 1, 278 /** Apply transformation on the right. */ 279 OnTheRight = 2 280 }; 281 282 /* the following used to be written as: 283 * 284 * struct NoChange_t {}; 285 * namespace { 286 * EIGEN_UNUSED NoChange_t NoChange; 287 * } 288 * 289 * on the ground that it feels dangerous to disambiguate overloaded functions on enum/integer types. 290 * However, this leads to "variable declared but never referenced" warnings on Intel Composer XE, 291 * and we do not know how to get rid of them (bug 450). 292 */ 293 294 enum NoChange_t { NoChange }; 295 enum Sequential_t { Sequential }; 296 enum Default_t { Default }; 297 298 /** \internal \ingroup enums 299 * Used in AmbiVector. */ 300 enum { 301 IsDense = 0, 302 IsSparse 303 }; 304 305 /** \ingroup enums 306 * Used as template parameter in DenseCoeffBase and MapBase to indicate 307 * which accessors should be provided. */ 308 enum AccessorLevels { 309 /** Read-only access via a member function. */ 310 ReadOnlyAccessors, 311 /** Read/write access via member functions. */ 312 WriteAccessors, 313 /** Direct read-only access to the coefficients. */ 314 DirectAccessors, 315 /** Direct read/write access to the coefficients. */ 316 DirectWriteAccessors 317 }; 318 319 /** \ingroup enums 320 * Enum with options to give to various decompositions. */ 321 enum DecompositionOptions { 322 /** \internal Not used (meant for LDLT?). */ 323 Pivoting = 0x01, 324 /** \internal Not used (meant for LDLT?). */ 325 NoPivoting = 0x02, 326 /** Used in JacobiSVD to indicate that the square matrix U is to be computed. */ 327 ComputeFullU = 0x04, 328 /** Used in JacobiSVD to indicate that the thin matrix U is to be computed. */ 329 ComputeThinU = 0x08, 330 /** Used in JacobiSVD to indicate that the square matrix V is to be computed. */ 331 ComputeFullV = 0x10, 332 /** Used in JacobiSVD to indicate that the thin matrix V is to be computed. */ 333 ComputeThinV = 0x20, 334 /** Used in SelfAdjointEigenSolver and GeneralizedSelfAdjointEigenSolver to specify 335 * that only the eigenvalues are to be computed and not the eigenvectors. */ 336 EigenvaluesOnly = 0x40, 337 /** Used in SelfAdjointEigenSolver and GeneralizedSelfAdjointEigenSolver to specify 338 * that both the eigenvalues and the eigenvectors are to be computed. */ 339 ComputeEigenvectors = 0x80, 340 /** \internal */ 341 EigVecMask = EigenvaluesOnly | ComputeEigenvectors, 342 /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should 343 * solve the generalized eigenproblem \f$ Ax = \lambda B x \f$. */ 344 Ax_lBx = 0x100, 345 /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should 346 * solve the generalized eigenproblem \f$ ABx = \lambda x \f$. */ 347 ABx_lx = 0x200, 348 /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should 349 * solve the generalized eigenproblem \f$ BAx = \lambda x \f$. */ 350 BAx_lx = 0x400, 351 /** \internal */ 352 GenEigMask = Ax_lBx | ABx_lx | BAx_lx 353 }; 354 355 /** \ingroup enums 356 * Possible values for the \p QRPreconditioner template parameter of JacobiSVD. */ 357 enum QRPreconditioners { 358 /** Do not specify what is to be done if the SVD of a non-square matrix is asked for. */ 359 NoQRPreconditioner, 360 /** Use a QR decomposition without pivoting as the first step. */ 361 HouseholderQRPreconditioner, 362 /** Use a QR decomposition with column pivoting as the first step. */ 363 ColPivHouseholderQRPreconditioner, 364 /** Use a QR decomposition with full pivoting as the first step. */ 365 FullPivHouseholderQRPreconditioner 366 }; 367 368 #ifdef Success 369 #error The preprocessor symbol 'Success' is defined, possibly by the X11 header file X.h 370 #endif 371 372 /** \ingroup enums 373 * Enum for reporting the status of a computation. */ 374 enum ComputationInfo { 375 /** Computation was successful. */ 376 Success = 0, 377 /** The provided data did not satisfy the prerequisites. */ 378 NumericalIssue = 1, 379 /** Iterative procedure did not converge. */ 380 NoConvergence = 2, 381 /** The inputs are invalid, or the algorithm has been improperly called. 382 * When assertions are enabled, such errors trigger an assert. */ 383 InvalidInput = 3 384 }; 385 386 /** \ingroup enums 387 * Enum used to specify how a particular transformation is stored in a matrix. 388 * \sa Transform, Hyperplane::transform(). */ 389 enum TransformTraits { 390 /** Transformation is an isometry. */ 391 Isometry = 0x1, 392 /** Transformation is an affine transformation stored as a (Dim+1)^2 matrix whose last row is 393 * assumed to be [0 ... 0 1]. */ 394 Affine = 0x2, 395 /** Transformation is an affine transformation stored as a (Dim) x (Dim+1) matrix. */ 396 AffineCompact = 0x10 | Affine, 397 /** Transformation is a general projective transformation stored as a (Dim+1)^2 matrix. */ 398 Projective = 0x20 399 }; 400 401 /** \internal \ingroup enums 402 * Enum used to choose between implementation depending on the computer architecture. */ 403 namespace Architecture 404 { 405 enum Type { 406 Generic = 0x0, 407 SSE = 0x1, 408 AltiVec = 0x2, 409 #if defined EIGEN_VECTORIZE_SSE 410 Target = SSE 411 #elif defined EIGEN_VECTORIZE_ALTIVEC 412 Target = AltiVec 413 #else 414 Target = Generic 415 #endif 416 }; 417 } 418 419 /** \internal \ingroup enums 420 * Enum used as template parameter in GeneralProduct. */ 421 enum { CoeffBasedProductMode, LazyCoeffBasedProductMode, OuterProduct, InnerProduct, GemvProduct, GemmProduct }; 422 423 /** \internal \ingroup enums 424 * Enum used in experimental parallel implementation. */ 425 enum Action {GetAction, SetAction}; 426 427 /** The type used to identify a dense storage. */ 428 struct Dense {}; 429 430 /** The type used to identify a matrix expression */ 431 struct MatrixXpr {}; 432 433 /** The type used to identify an array expression */ 434 struct ArrayXpr {}; 435 436 namespace internal { 437 /** \internal 438 * Constants for comparison functors 439 */ 440 enum ComparisonName { 441 cmp_EQ = 0, 442 cmp_LT = 1, 443 cmp_LE = 2, 444 cmp_UNORD = 3, 445 cmp_NEQ = 4 446 }; 447 } 448 449 } // end namespace Eigen 450 451 #endif // EIGEN_CONSTANTS_H 452