1namespace Eigen { 2 3/** \eigenManualPage TopicUnalignedArrayAssert Explanation of the assertion on unaligned arrays 4 5Hello! You are seeing this webpage because your program terminated on an assertion failure like this one: 6<pre> 7my_program: path/to/eigen/Eigen/src/Core/DenseStorage.h:44: 8Eigen::internal::matrix_array<T, Size, MatrixOptions, Align>::internal::matrix_array() 9[with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]: 10Assertion `(reinterpret_cast<size_t>(array) & (sizemask)) == 0 && "this assertion 11is explained here: http://eigen.tuxfamily.org/dox-devel/group__TopicUnalignedArrayAssert.html 12**** READ THIS WEB PAGE !!! ****"' failed. 13</pre> 14 15There are 4 known causes for this issue. 16If you can target \cpp17 only with a recent compiler (e.g., GCC>=7, clang>=5, MSVC>=19.12), then you're lucky: enabling c++17 should be enough (if not, please <a href="http://eigen.tuxfamily.org/bz/">report</a> to us). 17Otherwise, please read on to understand those issues and learn how to fix them. 18 19\eigenAutoToc 20 21\section where Where in my own code is the cause of the problem? 22 23First of all, you need to find out where in your own code this assertion was triggered from. At first glance, the error message doesn't look helpful, as it refers to a file inside Eigen! However, since your program crashed, if you can reproduce the crash, you can get a backtrace using any debugger. For example, if you're using GCC, you can use the GDB debugger as follows: 24\code 25$ gdb ./my_program # Start GDB on your program 26> run # Start running your program 27... # Now reproduce the crash! 28> bt # Obtain the backtrace 29\endcode 30Now that you know precisely where in your own code the problem is happening, read on to understand what you need to change. 31 32\section c1 Cause 1: Structures having Eigen objects as members 33 34If you have code like this, 35 36\code 37class Foo 38{ 39 //... 40 Eigen::Vector4d v; 41 //... 42}; 43//... 44Foo *foo = new Foo; 45\endcode 46 47then you need to read this separate page: \ref TopicStructHavingEigenMembers "Structures Having Eigen Members". 48 49Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". 50 51\section c2 Cause 2: STL Containers or manual memory allocation 52 53If you use STL Containers such as std::vector, std::map, ..., with %Eigen objects, or with classes containing %Eigen objects, like this, 54 55\code 56std::vector<Eigen::Matrix2d> my_vector; 57struct my_class { ... Eigen::Matrix2d m; ... }; 58std::map<int, my_class> my_map; 59\endcode 60 61then you need to read this separate page: \ref TopicStlContainers "Using STL Containers with Eigen". 62 63Note that here, Eigen::Matrix2d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member". 64 65The same issue will be exhibited by any classes/functions by-passing operator new to allocate memory, that is, by performing custom memory allocation followed by calls to the placement new operator. This is for instance typically the case of \c `std::make_shared` or `std::allocate_shared` for which is the solution is to use an \ref aligned_allocator "aligned allocator" as detailed in the \ref TopicStlContainers "solution for STL containers". 66 67\section c3 Cause 3: Passing Eigen objects by value 68 69If some function in your code is getting an %Eigen object passed by value, like this, 70 71\code 72void func(Eigen::Vector4d v); 73\endcode 74 75then you need to read this separate page: \ref TopicPassingByValue "Passing Eigen objects by value to functions". 76 77Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". 78 79\section c4 Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows) 80 81This is a must-read for people using GCC on Windows (like MinGW or TDM-GCC). If you have this assertion failure in an innocent function declaring a local variable like this: 82 83\code 84void foo() 85{ 86 Eigen::Quaternionf q; 87 //... 88} 89\endcode 90 91then you need to read this separate page: \ref TopicWrongStackAlignment "Compiler making a wrong assumption on stack alignment". 92 93Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types". 94 95 96\section explanation General explanation of this assertion 97 98\ref TopicFixedSizeVectorizable "Fixed-size vectorizable Eigen objects" must absolutely be created at properly aligned locations, otherwise SIMD instructions addressing them will crash. 99For instance, SSE/NEON/MSA/Altivec/VSX targets will require 16-byte-alignment, whereas AVX and AVX512 targets may require up to 32 and 64 byte alignment respectively. 100 101%Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their `operator new`. 102 103However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion. 104 105\section getrid I don't care about optimal vectorization, how do I get rid of that stuff? 106 107Three possibilities: 108<ul> 109 <li>Use the \c DontAlign option to Matrix, Array, Quaternion, etc. objects that gives you trouble. This way %Eigen won't try to over-align them, and thus won"t assume any special alignment. On the down side, you will pay the cost of unaligned loads/stores for them, but on modern CPUs, the overhead is either null or marginal. See \link StructHavingEigenMembers_othersolutions here \endlink for an example.</li> 110 <li>Define \link TopicPreprocessorDirectivesPerformance EIGEN_MAX_STATIC_ALIGN_BYTES \endlink to 0. That disables all 16-byte (and above) static alignment code, while keeping 16-byte (or above) heap alignment. This has the effect of 111 vectorizing fixed-size objects (like Matrix4d) through unaligned stores (as controlled by \link TopicPreprocessorDirectivesPerformance EIGEN_UNALIGNED_VECTORIZE \endlink), while keeping unchanged the vectorization of dynamic-size objects 112 (like MatrixXd). On 64 bytes systems, you might also define it 16 to disable only 32 and 64 bytes of over-alignment. But do note that this breaks ABI compatibility with the default behavior of static alignment.</li> 113 <li>Or define both \link TopicPreprocessorDirectivesPerformance EIGEN_DONT_VECTORIZE \endlink and `EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT`. This keeps the 114 16-byte (or above) alignment code and thus preserves ABI compatibility, but completely disables vectorization.</li> 115</ul> 116 117If you want to know why defining `EIGEN_DONT_VECTORIZE` does not by itself disable 16-byte (or above) alignment and the assertion, here's the explanation: 118 119It doesn't disable the assertion, because otherwise code that runs fine without vectorization would suddenly crash when enabling vectorization. 120It doesn't disable 16-byte (or above) alignment, because that would mean that vectorized and non-vectorized code are not mutually ABI-compatible. This ABI compatibility is very important, even for people who develop only an in-house application, as for instance one may want to have in the same application a vectorized path and a non-vectorized path. 121 122\section checkmycode How can I check my code is safe regarding alignment issues? 123 124Unfortunately, there is no possibility in c++ to detect any of the aforementioned shortcoming at compile time (though static analyzers are becoming more and more powerful and could detect some of them). 125Even at runtime, all we can do is to catch invalid unaligned allocation and trigger the explicit assertion mentioned at the beginning of this page. 126Therefore, if your program runs fine on a given system with some given compilation flags, then this does not guarantee that your code is safe. For instance, on most 64 bits systems buffer are aligned on 16 bytes boundary and so, if you do not enable AVX instruction set, then your code will run fine. On the other hand, the same code may assert if moving to a more exotic platform, or enabling AVX instructions that required 32 bytes alignment by default. 127 128The situation is not hopeless though. Assuming your code is well covered by unit test, then you can check its alignment safety by linking it to a custom malloc library returning 8 bytes aligned buffers only. This way all alignment shortcomings should pop-up. To this end, you must also compile your program with \link TopicPreprocessorDirectivesPerformance EIGEN_MALLOC_ALREADY_ALIGNED=0 \endlink. 129 130 131*/ 132 133} 134