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