ground/gcs/src/libs/eigen/doc/PreprocessorDirectives.dox

   1 namespace Eigen {
   2
   3 /** \page TopicPreprocessorDirectives Preprocessor directives
   4
   5 You can control some aspects of %Eigen by defining the preprocessor tokens using \c \#define. These macros
   6 should be defined before any %Eigen headers are included. Often they are best set in the project options.
   7
   8 This page lists the preprocesor tokens recognised by %Eigen.
   9
  10 \eigenAutoToc
  11
  12
  13 \section TopicPreprocessorDirectivesMajor Macros with major effects
  14
  15 These macros have a major effect and typically break the API (Application Programming Interface) and/or the
  16 ABI (Application Binary Interface). This can be rather dangerous: if parts of your program are compiled with
  17 one option, and other parts (or libraries that you use) are compiled with another option, your program may
  18 fail to link or exhibit subtle bugs. Nevertheless, these options can be useful for people who know what they
  19 are doing.
  20
  21  - \b EIGEN2_SUPPORT - if defined, enables the Eigen2 compatibility mode. This is meant to ease the transition
  22    of Eigen2 to Eigen3 (see \ref Eigen2ToEigen3). Not defined by default.
  23  - \b EIGEN2_SUPPORT_STAGEnn_xxx (for various values of nn and xxx) - staged migration path from Eigen2 to
  24    Eigen3; see \ref Eigen2SupportModes.
  25  - \b EIGEN_DEFAULT_DENSE_INDEX_TYPE - the type for column and row indices in matrices, vectors and array
  26    (DenseBase::Index). Set to \c std::ptrdiff_t by default.
  27  - \b EIGEN_DEFAULT_IO_FORMAT - the IOFormat to use when printing a matrix if no %IOFormat is specified.
  28    Defaults to the %IOFormat constructed by the default constructor IOFormat::IOFormat().
  29  - \b EIGEN_INITIALIZE_MATRICES_BY_ZERO - if defined, all entries of newly constructed matrices and arrays are
  30    initialized to zero, as are new entries in matrices and arrays after resizing. Not defined by default.
  31  - \b EIGEN_INITIALIZE_MATRICES_BY_NAN - if defined, all entries of newly constructed matrices and arrays are
  32    initialized to NaN, as are new entries in matrices and arrays after resizing. This option is especially
  33    useful for debugging purpose, though a memory tool like <a href="http://valgrind.org/">valgrind</a> is
  34    preferable. Not defined by default.
  35  - \b EIGEN_NO_AUTOMATIC_RESIZING - if defined, the matrices (or arrays) on both sides of an assignment
  36    <tt>a = b</tt> have to be of the same size; otherwise, %Eigen automatically resizes \c a so that it is of
  37    the correct size. Not defined by default.
  38
  39
  40 \section TopicPreprocessorDirectivesAssertions Assertions
  41
  42 The %Eigen library contains many assertions to guard against programming errors, both at compile time and at
  43 run time. However, these assertions do cost time and can thus be turned off.
  44
  45  - \b EIGEN_NO_DEBUG - disables %Eigen's assertions if defined. Not defined by default, unless the
  46    \c NDEBUG macro is defined (this is a standard C++ macro which disables all asserts).
  47  - \b EIGEN_NO_STATIC_ASSERT - if defined, compile-time static assertions are replaced by runtime assertions;
  48    this saves compilation time. Not defined by default.
  49  - \b eigen_assert - macro with one argument that is used inside %Eigen for assertions. By default, it is
  50    basically defined to be \c assert, which aborts the program if the assertion is violated. Redefine this
  51    macro if you want to do something else, like throwing an exception.
  52  - \b EIGEN_MPL2_ONLY - disable non MPL2 compatible features, or in other words disable the features which
  53    are still under the LGPL.
  54
  55
  56 \section TopicPreprocessorDirectivesPerformance Alignment, vectorization and performance tweaking
  57
  58  - \b EIGEN_MALLOC_ALREADY_ALIGNED - Can be set to 0 or 1 to tell whether default system malloc already
  59    returns aligned buffers. In not defined, then this information is automatically deduced from the compiler
  60    and system preprocessor tokens.
  61  - \b EIGEN_DONT_ALIGN - disables alignment completely. %Eigen will not try to align its objects and does not
  62    expect that any objects passed to it are aligned. This will turn off vectorization. Not defined by default.
  63  - \b EIGEN_DONT_ALIGN_STATICALLY - disables alignment of arrays on the stack. Not defined by default, unless
  64    \c EIGEN_DONT_ALIGN is defined.
  65  - \b EIGEN_DONT_PARALLELIZE - if defined, this disables multi-threading. This is only relevant if you enabled OpenMP.
  66    See \ref TopicMultiThreading for details.
  67  - \b EIGEN_DONT_VECTORIZE - disables explicit vectorization when defined. Not defined by default, unless
  68    alignment is disabled by %Eigen's platform test or the user defining \c EIGEN_DONT_ALIGN.
  69  - \b EIGEN_FAST_MATH - enables some optimizations which might affect the accuracy of the result. This currently
  70    enables the SSE vectorization of sin() and cos(), and speedups sqrt() for single precision. Defined to 1 by default.
  71    Define it to 0 to disable.
  72  - \b EIGEN_UNROLLING_LIMIT - defines the size of a loop to enable meta unrolling. Set it to zero to disable
  73    unrolling. The size of a loop here is expressed in %Eigen's own notion of "number of FLOPS", it does not
  74    correspond to the number of iterations or the number of instructions. The default is value 100.
  75  - \b EIGEN_STACK_ALLOCATION_LIMIT - defines the maximum bytes for a buffer to be allocated on the stack. For internal
  76    temporary buffers, dynamic memory allocation is employed as a fall back. For fixed-size matrices or arrays, exceeding
  77    this threshold raises a compile time assertion. Use 0 to set no limit. Default is 128 KB.
  78
  79
  80 \section TopicPreprocessorDirectivesPlugins Plugins
  81
  82 It is possible to add new methods to many fundamental classes in %Eigen by writing a plugin. As explained in
  83 the section \ref ExtendingMatrixBase, the plugin is specified by defining a \c EIGEN_xxx_PLUGIN macro. The
  84 following macros are supported; none of them are defined by default.
  85
  86  - \b EIGEN_ARRAY_PLUGIN - filename of plugin for extending the Array class.
  87  - \b EIGEN_ARRAYBASE_PLUGIN - filename of plugin for extending the ArrayBase class.
  88  - \b EIGEN_CWISE_PLUGIN - filename of plugin for extending the Cwise class.
  89  - \b EIGEN_DENSEBASE_PLUGIN - filename of plugin for extending the DenseBase class.
  90  - \b EIGEN_DYNAMICSPARSEMATRIX_PLUGIN - filename of plugin for extending the DynamicSparseMatrix class.
  91  - \b EIGEN_MATRIX_PLUGIN - filename of plugin for extending the Matrix class.
  92  - \b EIGEN_MATRIXBASE_PLUGIN - filename of plugin for extending the MatrixBase class.
  93  - \b EIGEN_PLAINOBJECTBASE_PLUGIN - filename of plugin for extending the PlainObjectBase class.
  94  - \b EIGEN_MAPBASE_PLUGIN - filename of plugin for extending the MapBase class.
  95  - \b EIGEN_QUATERNIONBASE_PLUGIN - filename of plugin for extending the QuaternionBase class.
  96  - \b EIGEN_SPARSEMATRIX_PLUGIN - filename of plugin for extending the SparseMatrix class.
  97  - \b EIGEN_SPARSEMATRIXBASE_PLUGIN - filename of plugin for extending the SparseMatrixBase class.
  98  - \b EIGEN_SPARSEVECTOR_PLUGIN - filename of plugin for extending the SparseVector class.
  99  - \b EIGEN_TRANSFORM_PLUGIN - filename of plugin for extending the Transform class.
 100  - \b EIGEN_FUNCTORS_PLUGIN - filename of plugin for adding new functors and specializations of functor_traits.
 101
 102
 103 \section TopicPreprocessorDirectivesDevelopers Macros for Eigen developers
 104
 105 These macros are mainly meant for people developing %Eigen and for testing purposes. Even though, they might be useful for power users and the curious for debugging and testing purpose, they \b should \b not \b be \b used by real-word code.
 106
 107  - \b EIGEN_DEFAULT_TO_ROW_MAJOR - when defined, the default storage order for matrices becomes row-major
 108    instead of column-major. Not defined by default.
 109  - \b EIGEN_INTERNAL_DEBUGGING - if defined, enables assertions in %Eigen's internal routines. This is useful
 110    for debugging %Eigen itself. Not defined by default.
 111  - \b EIGEN_NO_MALLOC - if defined, any request from inside the %Eigen to allocate memory from the heap
 112    results in an assertion failure. This is useful to check that some routine does not allocate memory
 113    dynamically. Not defined by default.
 114  - \b EIGEN_RUNTIME_NO_MALLOC - if defined, a new switch is introduced which can be turned on and off by
 115    calling <tt>set_is_malloc_allowed(bool)</tt>. If malloc is not allowed and %Eigen tries to allocate memory
 116    dynamically anyway, an assertion failure results. Not defined by default.
 117
 118 */
 119
 120 }