1namespace Eigen { 2 3/** \page TopicPreprocessorDirectives Preprocessor directives 4 5You can control some aspects of %Eigen by defining the preprocessor tokens using \c \#define. These macros 6should be defined before any %Eigen headers are included. Often they are best set in the project options. 7 8This page lists the preprocessor tokens recognized by %Eigen. 9 10\eigenAutoToc 11 12 13\section TopicPreprocessorDirectivesMajor Macros with major effects 14 15These macros have a major effect and typically break the API (Application Programming Interface) and/or the 16ABI (Application Binary Interface). This can be rather dangerous: if parts of your program are compiled with 17one option, and other parts (or libraries that you use) are compiled with another option, your program may 18fail to link or exhibit subtle bugs. Nevertheless, these options can be useful for people who know what they 19are doing. 20 21 - \b EIGEN2_SUPPORT and \b EIGEN2_SUPPORT_STAGEnn_xxx are disabled starting from the 3.3 release. 22 Defining one of these will raise a compile-error. If you need to compile Eigen2 code, 23 <a href="http://eigen.tuxfamily.org/index.php?title=Eigen2">check this site</a>. 24 - \b EIGEN_DEFAULT_DENSE_INDEX_TYPE - the type for column and row indices in matrices, vectors and array 25 (DenseBase::Index). Set to \c std::ptrdiff_t by default. 26 - \b EIGEN_DEFAULT_IO_FORMAT - the IOFormat to use when printing a matrix if no %IOFormat is specified. 27 Defaults to the %IOFormat constructed by the default constructor IOFormat::IOFormat(). 28 - \b EIGEN_INITIALIZE_MATRICES_BY_ZERO - if defined, all entries of newly constructed matrices and arrays are 29 initialized to zero, as are new entries in matrices and arrays after resizing. Not defined by default. 30 \warning The unary (resp. binary) constructor of \c 1x1 (resp. \c 2x1 or \c 1x2) fixed size matrices is 31 always interpreted as an initialization constructor where the argument(s) are the coefficient values 32 and not the sizes. For instance, \code Vector2d v(2,1); \endcode will create a vector with coeficients [2,1], 33 and \b not a \c 2x1 vector initialized with zeros (i.e., [0,0]). If such cases might occur, then it is 34 recommended to use the default constructor with a explicit call to resize: 35 \code 36 Matrix<?,SizeAtCompileTime,1> v; 37 v.resize(size); 38 Matrix<?,RowsAtCompileTime,ColsAtCompileTime> m; 39 m.resize(rows,cols); 40 \endcode 41 - \b EIGEN_INITIALIZE_MATRICES_BY_NAN - if defined, all entries of newly constructed matrices and arrays are 42 initialized to NaN, as are new entries in matrices and arrays after resizing. This option is especially 43 useful for debugging purpose, though a memory tool like <a href="http://valgrind.org/">valgrind</a> is 44 preferable. Not defined by default. 45 \warning See the documentation of \c EIGEN_INITIALIZE_MATRICES_BY_ZERO for a discussion on a limitations 46 of these macros when applied to \c 1x1, \c 1x2, and \c 2x1 fixed-size matrices. 47 - \b EIGEN_NO_AUTOMATIC_RESIZING - if defined, the matrices (or arrays) on both sides of an assignment 48 <tt>a = b</tt> have to be of the same size; otherwise, %Eigen automatically resizes \c a so that it is of 49 the correct size. Not defined by default. 50 51 52\section TopicPreprocessorDirectivesCppVersion C++ standard features 53 54By default, %Eigen strive to automatically detect and enable language features at compile-time based on 55the information provided by the compiler. 56 57 - \b EIGEN_MAX_CPP_VER - disables usage of C++ features requiring a version greater than EIGEN_MAX_CPP_VER. 58 Possible values are: 03, 11, 14, 17, etc. If not defined (the default), %Eigen enables all features supported 59 by the compiler. 60 61Individual features can be explicitly enabled or disabled by defining the following token to 0 or 1 respectively. 62For instance, one might limit the C++ version to C++03 by defining EIGEN_MAX_CPP_VER=03, but still enable C99 math 63functions by defining EIGEN_HAS_C99_MATH=1. 64 65 - \b EIGEN_HAS_C99_MATH - controls the usage of C99 math functions such as erf, erfc, lgamma, etc. 66 Automatic detection disabled if EIGEN_MAX_CPP_VER<11. 67 - \b EIGEN_HAS_CXX11_MATH - controls the implementation of some functions such as round, logp1, isinf, isnan, etc. 68 Automatic detection disabled if EIGEN_MAX_CPP_VER<11. 69 - \b EIGEN_HAS_RVALUE_REFERENCES - defines whether rvalue references are supported 70 Automatic detection disabled if EIGEN_MAX_CPP_VER<11. 71 - \b EIGEN_HAS_STD_RESULT_OF - defines whether std::result_of is supported 72 Automatic detection disabled if EIGEN_MAX_CPP_VER<11. 73 - \b EIGEN_HAS_VARIADIC_TEMPLATES - defines whether variadic templates are supported 74 Automatic detection disabled if EIGEN_MAX_CPP_VER<11. 75 - \b EIGEN_HAS_CONSTEXPR - defines whether relaxed const expression are supported 76 Automatic detection disabled if EIGEN_MAX_CPP_VER<14. 77 - \b EIGEN_HAS_CXX11_CONTAINERS - defines whether STL's containers follows C++11 specifications 78 Automatic detection disabled if EIGEN_MAX_CPP_VER<11. 79 - \b EIGEN_HAS_CXX11_NOEXCEPT - defines whether noexcept is supported 80 Automatic detection disabled if EIGEN_MAX_CPP_VER<11. 81 - \b EIGEN_NO_IO - Disables any usage and support for `<iostreams>`. 82 83\section TopicPreprocessorDirectivesAssertions Assertions 84 85The %Eigen library contains many assertions to guard against programming errors, both at compile time and at 86run time. However, these assertions do cost time and can thus be turned off. 87 88 - \b EIGEN_NO_DEBUG - disables %Eigen's assertions if defined. Not defined by default, unless the 89 \c NDEBUG macro is defined (this is a standard C++ macro which disables all asserts). 90 - \b EIGEN_NO_STATIC_ASSERT - if defined, compile-time static assertions are replaced by runtime assertions; 91 this saves compilation time. Not defined by default. 92 - \b eigen_assert - macro with one argument that is used inside %Eigen for assertions. By default, it is 93 basically defined to be \c assert, which aborts the program if the assertion is violated. Redefine this 94 macro if you want to do something else, like throwing an exception. 95 - \b EIGEN_MPL2_ONLY - disable non MPL2 compatible features, or in other words disable the features which 96 are still under the LGPL. 97 98 99\section TopicPreprocessorDirectivesPerformance Alignment, vectorization and performance tweaking 100 101 - \b \c EIGEN_MALLOC_ALREADY_ALIGNED - Can be set to 0 or 1 to tell whether default system \c malloc already 102 returns aligned buffers. In not defined, then this information is automatically deduced from the compiler 103 and system preprocessor tokens. 104 - \b \c EIGEN_MAX_ALIGN_BYTES - Must be a power of two, or 0. Defines an upper bound on the memory boundary in bytes on which dynamically and statically allocated data may be aligned by %Eigen. If not defined, a default value is automatically computed based on architecture, compiler, and OS. 105 This option is typically used to enforce binary compatibility between code/libraries compiled with different SIMD options. For instance, one may compile AVX code and enforce ABI compatibility with existing SSE code by defining \c EIGEN_MAX_ALIGN_BYTES=16. In the other way round, since by default AVX implies 32 bytes alignment for best performance, one can compile SSE code to be ABI compatible with AVX code by defining \c EIGEN_MAX_ALIGN_BYTES=32. 106 - \b \c EIGEN_MAX_STATIC_ALIGN_BYTES - Same as \c EIGEN_MAX_ALIGN_BYTES but for statically allocated data only. By default, if only \c EIGEN_MAX_ALIGN_BYTES is defined, then \c EIGEN_MAX_STATIC_ALIGN_BYTES == \c EIGEN_MAX_ALIGN_BYTES, otherwise a default value is automatically computed based on architecture, compiler, and OS (can be smaller than the default value of EIGEN_MAX_ALIGN_BYTES on architectures that do not support stack alignment). 107 Let us emphasize that \c EIGEN_MAX_*_ALIGN_BYTES define only a diserable upper bound. In practice data is aligned to largest power-of-two common divisor of \c EIGEN_MAX_STATIC_ALIGN_BYTES and the size of the data, such that memory is not wasted. 108 - \b \c EIGEN_DONT_PARALLELIZE - if defined, this disables multi-threading. This is only relevant if you enabled OpenMP. 109 See \ref TopicMultiThreading for details. 110 - \b \c EIGEN_DONT_VECTORIZE - disables explicit vectorization when defined. Not defined by default, unless 111 alignment is disabled by %Eigen's platform test or the user defining \c EIGEN_DONT_ALIGN. 112 - \b \c EIGEN_UNALIGNED_VECTORIZE - disables/enables vectorization with unaligned stores. Default is 1 (enabled). 113 If set to 0 (disabled), then expression for which the destination cannot be aligned are not vectorized (e.g., unaligned 114 small fixed size vectors or matrices) 115 - \b \c EIGEN_FAST_MATH - enables some optimizations which might affect the accuracy of the result. This currently 116 enables the SSE vectorization of sin() and cos(), and speedups sqrt() for single precision. Defined to 1 by default. 117 Define it to 0 to disable. 118 - \b \c EIGEN_UNROLLING_LIMIT - defines the size of a loop to enable meta unrolling. Set it to zero to disable 119 unrolling. The size of a loop here is expressed in %Eigen's own notion of "number of FLOPS", it does not 120 correspond to the number of iterations or the number of instructions. The default is value 110. 121 - \b \c EIGEN_STACK_ALLOCATION_LIMIT - defines the maximum bytes for a buffer to be allocated on the stack. For internal 122 temporary buffers, dynamic memory allocation is employed as a fall back. For fixed-size matrices or arrays, exceeding 123 this threshold raises a compile time assertion. Use 0 to set no limit. Default is 128 KB. 124 - \b \c EIGEN_NO_CUDA - disables CUDA support when defined. Might be useful in .cu files for which Eigen is used on the host only, 125 and never called from device code. 126 - \b \c EIGEN_STRONG_INLINE - This macro is used to qualify critical functions and methods that we expect the compiler to inline. 127 By default it is defined to \c __forceinline for MSVC and ICC, and to \c inline for other compilers. A tipical usage is to 128 define it to \c inline for MSVC users wanting faster compilation times, at the risk of performance degradations in some rare 129 cases for which MSVC inliner fails to do a good job. 130 - \b \c EIGEN_DEFAULT_L1_CACHE_SIZE - Sets the default L1 cache size that is used in Eigen's GEBP kernel when the correct cache size cannot be determined at runtime. 131 - \b \c EIGEN_DEFAULT_L2_CACHE_SIZE - Sets the default L2 cache size that is used in Eigen's GEBP kernel when the correct cache size cannot be determined at runtime. 132 - \b \c EIGEN_DEFAULT_L3_CACHE_SIZE - Sets the default L3 cache size that is used in Eigen's GEBP kernel when the correct cache size cannot be determined at runtime. 133 134 - \c EIGEN_DONT_ALIGN - Deprecated, it is a synonym for \c EIGEN_MAX_ALIGN_BYTES=0. It disables alignment completely. %Eigen will not try to align its objects and does not expect that any objects passed to it are aligned. This will turn off vectorization if \b \c EIGEN_UNALIGNED_VECTORIZE=1. Not defined by default. 135 - \c EIGEN_DONT_ALIGN_STATICALLY - Deprecated, it is a synonym for \c EIGEN_MAX_STATIC_ALIGN_BYTES=0. It disables alignment of arrays on the stack. Not defined by default, unless \c EIGEN_DONT_ALIGN is defined. 136 137 138\section TopicPreprocessorDirectivesPlugins Plugins 139 140It is possible to add new methods to many fundamental classes in %Eigen by writing a plugin. As explained in 141the section \ref TopicCustomizing_Plugins, the plugin is specified by defining a \c EIGEN_xxx_PLUGIN macro. The 142following macros are supported; none of them are defined by default. 143 144 - \b EIGEN_ARRAY_PLUGIN - filename of plugin for extending the Array class. 145 - \b EIGEN_ARRAYBASE_PLUGIN - filename of plugin for extending the ArrayBase class. 146 - \b EIGEN_CWISE_PLUGIN - filename of plugin for extending the Cwise class. 147 - \b EIGEN_DENSEBASE_PLUGIN - filename of plugin for extending the DenseBase class. 148 - \b EIGEN_DYNAMICSPARSEMATRIX_PLUGIN - filename of plugin for extending the DynamicSparseMatrix class. 149 - \b EIGEN_FUNCTORS_PLUGIN - filename of plugin for adding new functors and specializations of functor_traits. 150 - \b EIGEN_MAPBASE_PLUGIN - filename of plugin for extending the MapBase class. 151 - \b EIGEN_MATRIX_PLUGIN - filename of plugin for extending the Matrix class. 152 - \b EIGEN_MATRIXBASE_PLUGIN - filename of plugin for extending the MatrixBase class. 153 - \b EIGEN_PLAINOBJECTBASE_PLUGIN - filename of plugin for extending the PlainObjectBase class. 154 - \b EIGEN_QUATERNION_PLUGIN - filename of plugin for extending the Quaternion class. 155 - \b EIGEN_QUATERNIONBASE_PLUGIN - filename of plugin for extending the QuaternionBase class. 156 - \b EIGEN_SPARSEMATRIX_PLUGIN - filename of plugin for extending the SparseMatrix class. 157 - \b EIGEN_SPARSEMATRIXBASE_PLUGIN - filename of plugin for extending the SparseMatrixBase class. 158 - \b EIGEN_SPARSEVECTOR_PLUGIN - filename of plugin for extending the SparseVector class. 159 - \b EIGEN_TRANSFORM_PLUGIN - filename of plugin for extending the Transform class. 160 - \b EIGEN_VECTORWISEOP_PLUGIN - filename of plugin for extending the VectorwiseOp class. 161 162\section TopicPreprocessorDirectivesDevelopers Macros for Eigen developers 163 164These 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. 165 166 - \b EIGEN_DEFAULT_TO_ROW_MAJOR - when defined, the default storage order for matrices becomes row-major 167 instead of column-major. Not defined by default. 168 - \b EIGEN_INTERNAL_DEBUGGING - if defined, enables assertions in %Eigen's internal routines. This is useful 169 for debugging %Eigen itself. Not defined by default. 170 - \b EIGEN_NO_MALLOC - if defined, any request from inside the %Eigen to allocate memory from the heap 171 results in an assertion failure. This is useful to check that some routine does not allocate memory 172 dynamically. Not defined by default. 173 - \b EIGEN_RUNTIME_NO_MALLOC - if defined, a new switch is introduced which can be turned on and off by 174 calling <tt>set_is_malloc_allowed(bool)</tt>. If malloc is not allowed and %Eigen tries to allocate memory 175 dynamically anyway, an assertion failure results. Not defined by default. 176 177*/ 178 179} 180