Home | History | Annotate | Download | only in doc
      1 namespace Eigen {
      2 
      3 /** \page TopicUnalignedArrayAssert Explanation of the assertion on unaligned arrays
      4 
      5 Hello! You are seeing this webpage because your program terminated on an assertion failure like this one:
      6 <pre>
      7 my_program: path/to/eigen/Eigen/src/Core/DenseStorage.h:44:
      8 Eigen::internal::matrix_array<T, Size, MatrixOptions, Align>::internal::matrix_array()
      9 [with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]:
     10 Assertion `(reinterpret_cast<size_t>(array) & 0xf) == 0 && "this assertion
     11 is explained here: http://eigen.tuxfamily.org/dox/UnalignedArrayAssert.html
     12 **** READ THIS WEB PAGE !!! ****"' failed.
     13 </pre>
     14 
     15 There are 4 known causes for this issue. Please read on to understand them and learn how to fix them.
     16 
     17 \b Table \b of \b contents
     18  - \ref where
     19  - \ref c1
     20  - \ref c2
     21  - \ref c3
     22  - \ref c4
     23  - \ref explanation
     24  - \ref getrid
     25 
     26 \section where Where in my own code is the cause of the problem?
     27 
     28 First 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:
     29 \code
     30 $ gdb ./my_program          # Start GDB on your program
     31 > run                       # Start running your program
     32 ...                         # Now reproduce the crash!
     33 > bt                        # Obtain the backtrace
     34 \endcode
     35 Now that you know precisely where in your own code the problem is happening, read on to understand what you need to change.
     36 
     37 \section c1 Cause 1: Structures having Eigen objects as members
     38 
     39 If you have code like this,
     40 
     41 \code
     42 class Foo
     43 {
     44   //...
     45   Eigen::Vector2d v;
     46   //...
     47 };
     48 //...
     49 Foo *foo = new Foo;
     50 \endcode
     51 
     52 then you need to read this separate page: \ref TopicStructHavingEigenMembers "Structures Having Eigen Members".
     53 
     54 Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
     55 
     56 \section c2 Cause 2: STL Containers
     57 
     58 If you use STL Containers such as std::vector, std::map, ..., with Eigen objects, or with classes containing Eigen objects, like this,
     59 
     60 \code
     61 std::vector<Eigen::Matrix2f> my_vector;
     62 struct my_class { ... Eigen::Matrix2f m; ... };
     63 std::map<int, my_class> my_map;
     64 \endcode
     65 
     66 then you need to read this separate page: \ref TopicStlContainers "Using STL Containers with Eigen".
     67 
     68 Note that here, Eigen::Matrix2f 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".
     69 
     70 \section c3 Cause 3: Passing Eigen objects by value
     71 
     72 If some function in your code is getting an Eigen object passed by value, like this,
     73 
     74 \code
     75 void func(Eigen::Vector4d v);
     76 \endcode
     77 
     78 then you need to read this separate page: \ref TopicPassingByValue "Passing Eigen objects by value to functions".
     79 
     80 Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
     81 
     82 \section c4 Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows)
     83 
     84 This 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:
     85 
     86 \code
     87 void foo()
     88 {
     89   Eigen::Quaternionf q;
     90   //...
     91 }
     92 \endcode
     93 
     94 then you need to read this separate page: \ref TopicWrongStackAlignment "Compiler making a wrong assumption on stack alignment".
     95 
     96 Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
     97 
     98 \section explanation General explanation of this assertion
     99 
    100 \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions adressing them will crash.
    101 
    102 Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new".
    103 
    104 However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion.
    105 
    106 \section getrid I don't care about vectorization, how do I get rid of that stuff?
    107 
    108 Two possibilities:
    109 <ul>
    110   <li>Define EIGEN_DONT_ALIGN_STATICALLY. That disables all 128-bit static alignment code, while keeping 128-bit heap alignment. This has the effect of
    111       disabling vectorization for fixed-size objects (like Matrix4d) while keeping vectorization of dynamic-size objects
    112       (like MatrixXd). But do note that this breaks ABI compatibility with the default behavior of 128-bit static alignment.</li>
    113   <li>Or define both EIGEN_DONT_VECTORIZE and EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT. This keeps the
    114       128-bit alignment code and thus preserves ABI compatibility, but completely disables vectorization.</li>
    115 </ul>
    116 
    117 For more information, see <a href="http://eigen.tuxfamily.org/index.php?title=FAQ#I_disabled_vectorization.2C_but_I.27m_still_getting_annoyed_about_alignment_issues.21">this FAQ</a>.
    118 
    119 */
    120 
    121 }
    122