1 // This file is part of Eigen, a lightweight C++ template library 2 // for linear algebra. 3 // 4 // Copyright (C) 2008-2015 Gael Guennebaud <gael.guennebaud (at) inria.fr> 5 // Copyright (C) 2007-2009 Benoit Jacob <jacob.benoit.1 (at) 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 /** This value means that the cost to evaluate an expression coefficient is either very expensive or 34 * cannot be known at compile time. 35 * 36 * This value has to be positive to (1) simplify cost computation, and (2) allow to distinguish between a very expensive and very very expensive expressions. 37 * It thus must also be large enough to make sure unrolling won't happen and that sub expressions will be evaluated, but not too large to avoid overflow. 38 */ 39 const int HugeCost = 10000; 40 41 /** \defgroup flags Flags 42 * \ingroup Core_Module 43 * 44 * These are the possible bits which can be OR'ed to constitute the flags of a matrix or 45 * expression. 46 * 47 * It is important to note that these flags are a purely compile-time notion. They are a compile-time property of 48 * an expression type, implemented as enum's. They are not stored in memory at runtime, and they do not incur any 49 * runtime overhead. 50 * 51 * \sa MatrixBase::Flags 52 */ 53 54 /** \ingroup flags 55 * 56 * for a matrix, this means that the storage order is row-major. 57 * If this bit is not set, the storage order is column-major. 58 * For an expression, this determines the storage order of 59 * the matrix created by evaluation of that expression. 60 * \sa \blank \ref TopicStorageOrders */ 61 const unsigned int RowMajorBit = 0x1; 62 63 /** \ingroup flags 64 * means the expression should be evaluated by the calling expression */ 65 const unsigned int EvalBeforeNestingBit = 0x2; 66 67 /** \ingroup flags 68 * \deprecated 69 * means the expression should be evaluated before any assignment */ 70 EIGEN_DEPRECATED 71 const unsigned int EvalBeforeAssigningBit = 0x4; // FIXME deprecated 72 73 /** \ingroup flags 74 * 75 * Short version: means the expression might be vectorized 76 * 77 * Long version: means that the coefficients can be handled by packets 78 * and start at a memory location whose alignment meets the requirements 79 * of the present CPU architecture for optimized packet access. In the fixed-size 80 * case, there is the additional condition that it be possible to access all the 81 * coefficients by packets (this implies the requirement that the size be a multiple of 16 bytes, 82 * and that any nontrivial strides don't break the alignment). In the dynamic-size case, 83 * there is no such condition on the total size and strides, so it might not be possible to access 84 * all coeffs by packets. 85 * 86 * \note This bit can be set regardless of whether vectorization is actually enabled. 87 * To check for actual vectorizability, see \a ActualPacketAccessBit. 88 */ 89 const unsigned int PacketAccessBit = 0x8; 90 91 #ifdef EIGEN_VECTORIZE 92 /** \ingroup flags 93 * 94 * If vectorization is enabled (EIGEN_VECTORIZE is defined) this constant 95 * is set to the value \a PacketAccessBit. 96 * 97 * If vectorization is not enabled (EIGEN_VECTORIZE is not defined) this constant 98 * is set to the value 0. 99 */ 100 const unsigned int ActualPacketAccessBit = PacketAccessBit; 101 #else 102 const unsigned int ActualPacketAccessBit = 0x0; 103 #endif 104 105 /** \ingroup flags 106 * 107 * Short version: means the expression can be seen as 1D vector. 108 * 109 * Long version: means that one can access the coefficients 110 * of this expression by coeff(int), and coeffRef(int) in the case of a lvalue expression. These 111 * index-based access methods are guaranteed 112 * to not have to do any runtime computation of a (row, col)-pair from the index, so that it 113 * is guaranteed that whenever it is available, index-based access is at least as fast as 114 * (row,col)-based access. Expressions for which that isn't possible don't have the LinearAccessBit. 115 * 116 * If both PacketAccessBit and LinearAccessBit are set, then the 117 * packets of this expression can be accessed by packet(int), and writePacket(int) in the case of a 118 * lvalue expression. 119 * 120 * Typically, all vector expressions have the LinearAccessBit, but there is one exception: 121 * Product expressions don't have it, because it would be troublesome for vectorization, even when the 122 * Product is a vector expression. Thus, vector Product expressions allow index-based coefficient access but 123 * not index-based packet access, so they don't have the LinearAccessBit. 124 */ 125 const unsigned int LinearAccessBit = 0x10; 126 127 /** \ingroup flags 128 * 129 * Means the expression has a coeffRef() method, i.e. is writable as its individual coefficients are directly addressable. 130 * This rules out read-only expressions. 131 * 132 * Note that DirectAccessBit and LvalueBit are mutually orthogonal, as there are examples of expression having one but note 133 * the other: 134 * \li writable expressions that don't have a very simple memory layout as a strided array, have LvalueBit but not DirectAccessBit 135 * \li Map-to-const expressions, for example Map<const Matrix>, have DirectAccessBit but not LvalueBit 136 * 137 * Expressions having LvalueBit also have their coeff() method returning a const reference instead of returning a new value. 138 */ 139 const unsigned int LvalueBit = 0x20; 140 141 /** \ingroup flags 142 * 143 * Means that the underlying array of coefficients can be directly accessed as a plain strided array. The memory layout 144 * of the array of coefficients must be exactly the natural one suggested by rows(), cols(), 145 * outerStride(), innerStride(), and the RowMajorBit. This rules out expressions such as Diagonal, whose coefficients, 146 * though referencable, do not have such a regular memory layout. 147 * 148 * See the comment on LvalueBit for an explanation of how LvalueBit and DirectAccessBit are mutually orthogonal. 149 */ 150 const unsigned int DirectAccessBit = 0x40; 151 152 /** \deprecated \ingroup flags 153 * 154 * means the first coefficient packet is guaranteed to be aligned. 155 * An expression cannot has the AlignedBit without the PacketAccessBit flag. 156 * In other words, this means we are allow to perform an aligned packet access to the first element regardless 157 * of the expression kind: 158 * \code 159 * expression.packet<Aligned>(0); 160 * \endcode 161 */ 162 EIGEN_DEPRECATED const unsigned int AlignedBit = 0x80; 163 164 const unsigned int NestByRefBit = 0x100; 165 166 /** \ingroup flags 167 * 168 * for an expression, this means that the storage order 169 * can be either row-major or column-major. 170 * The precise choice will be decided at evaluation time or when 171 * combined with other expressions. 172 * \sa \blank \ref RowMajorBit, \ref TopicStorageOrders */ 173 const unsigned int NoPreferredStorageOrderBit = 0x200; 174 175 /** \ingroup flags 176 * 177 * Means that the underlying coefficients can be accessed through pointers to the sparse (un)compressed storage format, 178 * that is, the expression provides: 179 * \code 180 inline const Scalar* valuePtr() const; 181 inline const Index* innerIndexPtr() const; 182 inline const Index* outerIndexPtr() const; 183 inline const Index* innerNonZeroPtr() const; 184 \endcode 185 */ 186 const unsigned int CompressedAccessBit = 0x400; 187 188 189 // list of flags that are inherited by default 190 const unsigned int HereditaryBits = RowMajorBit 191 | EvalBeforeNestingBit; 192 193 /** \defgroup enums Enumerations 194 * \ingroup Core_Module 195 * 196 * Various enumerations used in %Eigen. Many of these are used as template parameters. 197 */ 198 199 /** \ingroup enums 200 * Enum containing possible values for the \c Mode or \c UpLo parameter of 201 * MatrixBase::selfadjointView() and MatrixBase::triangularView(), and selfadjoint solvers. */ 202 enum UpLoType { 203 /** View matrix as a lower triangular matrix. */ 204 Lower=0x1, 205 /** View matrix as an upper triangular matrix. */ 206 Upper=0x2, 207 /** %Matrix has ones on the diagonal; to be used in combination with #Lower or #Upper. */ 208 UnitDiag=0x4, 209 /** %Matrix has zeros on the diagonal; to be used in combination with #Lower or #Upper. */ 210 ZeroDiag=0x8, 211 /** View matrix as a lower triangular matrix with ones on the diagonal. */ 212 UnitLower=UnitDiag|Lower, 213 /** View matrix as an upper triangular matrix with ones on the diagonal. */ 214 UnitUpper=UnitDiag|Upper, 215 /** View matrix as a lower triangular matrix with zeros on the diagonal. */ 216 StrictlyLower=ZeroDiag|Lower, 217 /** View matrix as an upper triangular matrix with zeros on the diagonal. */ 218 StrictlyUpper=ZeroDiag|Upper, 219 /** Used in BandMatrix and SelfAdjointView to indicate that the matrix is self-adjoint. */ 220 SelfAdjoint=0x10, 221 /** Used to support symmetric, non-selfadjoint, complex matrices. */ 222 Symmetric=0x20 223 }; 224 225 /** \ingroup enums 226 * Enum for indicating whether a buffer is aligned or not. */ 227 enum AlignmentType { 228 Unaligned=0, /**< Data pointer has no specific alignment. */ 229 Aligned8=8, /**< Data pointer is aligned on a 8 bytes boundary. */ 230 Aligned16=16, /**< Data pointer is aligned on a 16 bytes boundary. */ 231 Aligned32=32, /**< Data pointer is aligned on a 32 bytes boundary. */ 232 Aligned64=64, /**< Data pointer is aligned on a 64 bytes boundary. */ 233 Aligned128=128, /**< Data pointer is aligned on a 128 bytes boundary. */ 234 AlignedMask=255, 235 Aligned=16, /**< \deprecated Synonym for Aligned16. */ 236 #if EIGEN_MAX_ALIGN_BYTES==128 237 AlignedMax = Aligned128 238 #elif EIGEN_MAX_ALIGN_BYTES==64 239 AlignedMax = Aligned64 240 #elif EIGEN_MAX_ALIGN_BYTES==32 241 AlignedMax = Aligned32 242 #elif EIGEN_MAX_ALIGN_BYTES==16 243 AlignedMax = Aligned16 244 #elif EIGEN_MAX_ALIGN_BYTES==8 245 AlignedMax = Aligned8 246 #elif EIGEN_MAX_ALIGN_BYTES==0 247 AlignedMax = Unaligned 248 #else 249 #error Invalid value for EIGEN_MAX_ALIGN_BYTES 250 #endif 251 }; 252 253 /** \ingroup enums 254 * Enum used by DenseBase::corner() in Eigen2 compatibility mode. */ 255 // FIXME after the corner() API change, this was not needed anymore, except by AlignedBox 256 // TODO: find out what to do with that. Adapt the AlignedBox API ? 257 enum CornerType { TopLeft, TopRight, BottomLeft, BottomRight }; 258 259 /** \ingroup enums 260 * Enum containing possible values for the \p Direction parameter of 261 * Reverse, PartialReduxExpr and VectorwiseOp. */ 262 enum DirectionType { 263 /** For Reverse, all columns are reversed; 264 * for PartialReduxExpr and VectorwiseOp, act on columns. */ 265 Vertical, 266 /** For Reverse, all rows are reversed; 267 * for PartialReduxExpr and VectorwiseOp, act on rows. */ 268 Horizontal, 269 /** For Reverse, both rows and columns are reversed; 270 * not used for PartialReduxExpr and VectorwiseOp. */ 271 BothDirections 272 }; 273 274 /** \internal \ingroup enums 275 * Enum to specify how to traverse the entries of a matrix. */ 276 enum TraversalType { 277 /** \internal Default traversal, no vectorization, no index-based access */ 278 DefaultTraversal, 279 /** \internal No vectorization, use index-based access to have only one for loop instead of 2 nested loops */ 280 LinearTraversal, 281 /** \internal Equivalent to a slice vectorization for fixed-size matrices having good alignment 282 * and good size */ 283 InnerVectorizedTraversal, 284 /** \internal Vectorization path using a single loop plus scalar loops for the 285 * unaligned boundaries */ 286 LinearVectorizedTraversal, 287 /** \internal Generic vectorization path using one vectorized loop per row/column with some 288 * scalar loops to handle the unaligned boundaries */ 289 SliceVectorizedTraversal, 290 /** \internal Special case to properly handle incompatible scalar types or other defecting cases*/ 291 InvalidTraversal, 292 /** \internal Evaluate all entries at once */ 293 AllAtOnceTraversal 294 }; 295 296 /** \internal \ingroup enums 297 * Enum to specify whether to unroll loops when traversing over the entries of a matrix. */ 298 enum UnrollingType { 299 /** \internal Do not unroll loops. */ 300 NoUnrolling, 301 /** \internal Unroll only the inner loop, but not the outer loop. */ 302 InnerUnrolling, 303 /** \internal Unroll both the inner and the outer loop. If there is only one loop, 304 * because linear traversal is used, then unroll that loop. */ 305 CompleteUnrolling 306 }; 307 308 /** \internal \ingroup enums 309 * Enum to specify whether to use the default (built-in) implementation or the specialization. */ 310 enum SpecializedType { 311 Specialized, 312 BuiltIn 313 }; 314 315 /** \ingroup enums 316 * Enum containing possible values for the \p _Options template parameter of 317 * Matrix, Array and BandMatrix. */ 318 enum StorageOptions { 319 /** Storage order is column major (see \ref TopicStorageOrders). */ 320 ColMajor = 0, 321 /** Storage order is row major (see \ref TopicStorageOrders). */ 322 RowMajor = 0x1, // it is only a coincidence that this is equal to RowMajorBit -- don't rely on that 323 /** Align the matrix itself if it is vectorizable fixed-size */ 324 AutoAlign = 0, 325 /** 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 326 DontAlign = 0x2 327 }; 328 329 /** \ingroup enums 330 * Enum for specifying whether to apply or solve on the left or right. */ 331 enum SideType { 332 /** Apply transformation on the left. */ 333 OnTheLeft = 1, 334 /** Apply transformation on the right. */ 335 OnTheRight = 2 336 }; 337 338 /* the following used to be written as: 339 * 340 * struct NoChange_t {}; 341 * namespace { 342 * EIGEN_UNUSED NoChange_t NoChange; 343 * } 344 * 345 * on the ground that it feels dangerous to disambiguate overloaded functions on enum/integer types. 346 * However, this leads to "variable declared but never referenced" warnings on Intel Composer XE, 347 * and we do not know how to get rid of them (bug 450). 348 */ 349 350 enum NoChange_t { NoChange }; 351 enum Sequential_t { Sequential }; 352 enum Default_t { Default }; 353 354 /** \internal \ingroup enums 355 * Used in AmbiVector. */ 356 enum AmbiVectorMode { 357 IsDense = 0, 358 IsSparse 359 }; 360 361 /** \ingroup enums 362 * Used as template parameter in DenseCoeffBase and MapBase to indicate 363 * which accessors should be provided. */ 364 enum AccessorLevels { 365 /** Read-only access via a member function. */ 366 ReadOnlyAccessors, 367 /** Read/write access via member functions. */ 368 WriteAccessors, 369 /** Direct read-only access to the coefficients. */ 370 DirectAccessors, 371 /** Direct read/write access to the coefficients. */ 372 DirectWriteAccessors 373 }; 374 375 /** \ingroup enums 376 * Enum with options to give to various decompositions. */ 377 enum DecompositionOptions { 378 /** \internal Not used (meant for LDLT?). */ 379 Pivoting = 0x01, 380 /** \internal Not used (meant for LDLT?). */ 381 NoPivoting = 0x02, 382 /** Used in JacobiSVD to indicate that the square matrix U is to be computed. */ 383 ComputeFullU = 0x04, 384 /** Used in JacobiSVD to indicate that the thin matrix U is to be computed. */ 385 ComputeThinU = 0x08, 386 /** Used in JacobiSVD to indicate that the square matrix V is to be computed. */ 387 ComputeFullV = 0x10, 388 /** Used in JacobiSVD to indicate that the thin matrix V is to be computed. */ 389 ComputeThinV = 0x20, 390 /** Used in SelfAdjointEigenSolver and GeneralizedSelfAdjointEigenSolver to specify 391 * that only the eigenvalues are to be computed and not the eigenvectors. */ 392 EigenvaluesOnly = 0x40, 393 /** Used in SelfAdjointEigenSolver and GeneralizedSelfAdjointEigenSolver to specify 394 * that both the eigenvalues and the eigenvectors are to be computed. */ 395 ComputeEigenvectors = 0x80, 396 /** \internal */ 397 EigVecMask = EigenvaluesOnly | ComputeEigenvectors, 398 /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should 399 * solve the generalized eigenproblem \f$ Ax = \lambda B x \f$. */ 400 Ax_lBx = 0x100, 401 /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should 402 * solve the generalized eigenproblem \f$ ABx = \lambda x \f$. */ 403 ABx_lx = 0x200, 404 /** Used in GeneralizedSelfAdjointEigenSolver to indicate that it should 405 * solve the generalized eigenproblem \f$ BAx = \lambda x \f$. */ 406 BAx_lx = 0x400, 407 /** \internal */ 408 GenEigMask = Ax_lBx | ABx_lx | BAx_lx 409 }; 410 411 /** \ingroup enums 412 * Possible values for the \p QRPreconditioner template parameter of JacobiSVD. */ 413 enum QRPreconditioners { 414 /** Do not specify what is to be done if the SVD of a non-square matrix is asked for. */ 415 NoQRPreconditioner, 416 /** Use a QR decomposition without pivoting as the first step. */ 417 HouseholderQRPreconditioner, 418 /** Use a QR decomposition with column pivoting as the first step. */ 419 ColPivHouseholderQRPreconditioner, 420 /** Use a QR decomposition with full pivoting as the first step. */ 421 FullPivHouseholderQRPreconditioner 422 }; 423 424 #ifdef Success 425 #error The preprocessor symbol 'Success' is defined, possibly by the X11 header file X.h 426 #endif 427 428 /** \ingroup enums 429 * Enum for reporting the status of a computation. */ 430 enum ComputationInfo { 431 /** Computation was successful. */ 432 Success = 0, 433 /** The provided data did not satisfy the prerequisites. */ 434 NumericalIssue = 1, 435 /** Iterative procedure did not converge. */ 436 NoConvergence = 2, 437 /** The inputs are invalid, or the algorithm has been improperly called. 438 * When assertions are enabled, such errors trigger an assert. */ 439 InvalidInput = 3 440 }; 441 442 /** \ingroup enums 443 * Enum used to specify how a particular transformation is stored in a matrix. 444 * \sa Transform, Hyperplane::transform(). */ 445 enum TransformTraits { 446 /** Transformation is an isometry. */ 447 Isometry = 0x1, 448 /** Transformation is an affine transformation stored as a (Dim+1)^2 matrix whose last row is 449 * assumed to be [0 ... 0 1]. */ 450 Affine = 0x2, 451 /** Transformation is an affine transformation stored as a (Dim) x (Dim+1) matrix. */ 452 AffineCompact = 0x10 | Affine, 453 /** Transformation is a general projective transformation stored as a (Dim+1)^2 matrix. */ 454 Projective = 0x20 455 }; 456 457 /** \internal \ingroup enums 458 * Enum used to choose between implementation depending on the computer architecture. */ 459 namespace Architecture 460 { 461 enum Type { 462 Generic = 0x0, 463 SSE = 0x1, 464 AltiVec = 0x2, 465 VSX = 0x3, 466 NEON = 0x4, 467 #if defined EIGEN_VECTORIZE_SSE 468 Target = SSE 469 #elif defined EIGEN_VECTORIZE_ALTIVEC 470 Target = AltiVec 471 #elif defined EIGEN_VECTORIZE_VSX 472 Target = VSX 473 #elif defined EIGEN_VECTORIZE_NEON 474 Target = NEON 475 #else 476 Target = Generic 477 #endif 478 }; 479 } 480 481 /** \internal \ingroup enums 482 * Enum used as template parameter in Product and product evaluators. */ 483 enum ProductImplType 484 { DefaultProduct=0, LazyProduct, AliasFreeProduct, CoeffBasedProductMode, LazyCoeffBasedProductMode, OuterProduct, InnerProduct, GemvProduct, GemmProduct }; 485 486 /** \internal \ingroup enums 487 * Enum used in experimental parallel implementation. */ 488 enum Action {GetAction, SetAction}; 489 490 /** The type used to identify a dense storage. */ 491 struct Dense {}; 492 493 /** The type used to identify a general sparse storage. */ 494 struct Sparse {}; 495 496 /** The type used to identify a general solver (factored) storage. */ 497 struct SolverStorage {}; 498 499 /** The type used to identify a permutation storage. */ 500 struct PermutationStorage {}; 501 502 /** The type used to identify a permutation storage. */ 503 struct TranspositionsStorage {}; 504 505 /** The type used to identify a matrix expression */ 506 struct MatrixXpr {}; 507 508 /** The type used to identify an array expression */ 509 struct ArrayXpr {}; 510 511 // An evaluator must define its shape. By default, it can be one of the following: 512 struct DenseShape { static std::string debugName() { return "DenseShape"; } }; 513 struct SolverShape { static std::string debugName() { return "SolverShape"; } }; 514 struct HomogeneousShape { static std::string debugName() { return "HomogeneousShape"; } }; 515 struct DiagonalShape { static std::string debugName() { return "DiagonalShape"; } }; 516 struct BandShape { static std::string debugName() { return "BandShape"; } }; 517 struct TriangularShape { static std::string debugName() { return "TriangularShape"; } }; 518 struct SelfAdjointShape { static std::string debugName() { return "SelfAdjointShape"; } }; 519 struct PermutationShape { static std::string debugName() { return "PermutationShape"; } }; 520 struct TranspositionsShape { static std::string debugName() { return "TranspositionsShape"; } }; 521 struct SparseShape { static std::string debugName() { return "SparseShape"; } }; 522 523 namespace internal { 524 525 // random access iterators based on coeff*() accessors. 526 struct IndexBased {}; 527 528 // evaluator based on iterators to access coefficients. 529 struct IteratorBased {}; 530 531 /** \internal 532 * Constants for comparison functors 533 */ 534 enum ComparisonName { 535 cmp_EQ = 0, 536 cmp_LT = 1, 537 cmp_LE = 2, 538 cmp_UNORD = 3, 539 cmp_NEQ = 4, 540 cmp_GT = 5, 541 cmp_GE = 6 542 }; 543 } // end namespace internal 544 545 } // end namespace Eigen 546 547 #endif // EIGEN_CONSTANTS_H 548
