Eigen  3.3.90 (mercurial changeset d63bd3cb7378)
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Explanation of the assertion on unaligned arrays

Hello! You are seeing this webpage because your program terminated on an assertion failure like this one:

my_program: path/to/eigen/Eigen/src/Core/DenseStorage.h:44:
Eigen::internal::matrix_array<T, Size, MatrixOptions, Align>::internal::matrix_array()
[with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]:
Assertion `(reinterpret_cast<size_t>(array) & (sizemask)) == 0 && "this assertion
is explained here: http://eigen.tuxfamily.org/dox-devel/group__TopicUnalignedArrayAssert.html
     READ THIS WEB PAGE !!! ****"' failed.

There are 4 known causes for this issue. Please read on to understand them and learn how to fix them.

Where in my own code is the cause of the problem?

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:

$ gdb ./my_program # Start GDB on your program
> run # Start running your program
... # Now reproduce the crash!
> bt # Obtain the backtrace

Now that you know precisely where in your own code the problem is happening, read on to understand what you need to change.

Cause 1: Structures having Eigen objects as members

If you have code like this,

class Foo
Foo *foo = new Foo;

then you need to read this separate page: Structures Having Eigen Members.

Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all fixed-size vectorizable Eigen types.

Cause 2: STL Containers or manual memory allocation

If you use STL Containers such as std::vector, std::map, ..., with Eigen objects, or with classes containing Eigen objects, like this,

std::vector<Eigen::Matrix2f> my_vector;
struct my_class { ... Eigen::Matrix2f m; ... };
std::map<int, my_class> my_map;

then you need to read this separate page: Using STL Containers with Eigen.

Note that here, Eigen::Matrix2f is only used as an example, more generally the issue arises for all fixed-size vectorizable Eigen types and structures having such Eigen objects as member.

The 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 std::make_shared or std::allocate_shared for which is the solution is to use an aligned allocator as detailed in the solution for STL containers.

Cause 3: Passing Eigen objects by value

If some function in your code is getting an Eigen object passed by value, like this,

void func(Eigen::Vector4d v);

then you need to read this separate page: Passing Eigen objects by value to functions.

Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all fixed-size vectorizable Eigen types.

Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows)

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:

void foo()

then you need to read this separate page: Compiler making a wrong assumption on stack alignment.

Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all fixed-size vectorizable Eigen types.

General explanation of this assertion

fixed-size vectorizable Eigen objects must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions addressing them will crash.

Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new".

However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion.

I don't care about optimal vectorization, how do I get rid of that stuff?

Three possibilities:

If you want to know why defining EIGEN_DONT_VECTORIZE does not by itself disable 16-byte alignment and the assertion, here's the explanation:

It doesn't disable the assertion, because otherwise code that runs fine without vectorization would suddenly crash when enabling vectorization. It doesn't disable 16-byte 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.

How can I check my code is safe regarding alignment issues?

Unfortunately, there is no possibility in C++ to detect any of the aformentioned shortcoming at compile time (though static analysers are becoming more and more powerful and could detect some of them). Even at runtime, all we can do is to catch invalid unaligned allocation and trigger the explicit assertion mentioned at the begining of this page. Therefore, 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.

The 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 EIGEN_MALLOC_ALREADY_ALIGNED=0 .