Home | History | Annotate | Download | only in util
      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 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