FAQ

From Eigen
Jump to: navigation, search
Owl faq.jpg

Contents

Licensing

Since the 3.1.1 release, Eigen is licensed under the MPL2. We refer to the MPL2 FAQ for initial questions.

Disabling non MPL2 features

Even though most of the Eigen code is under the MPL2, a few features are still under the LGPL license. This concerns: SimplicialCholesky, AMD ordering and constrained_cg. Non MPL2 features can be explicitly disabled by compiling with the EIGEN_MPL2_ONLY preprocessor token defined.

Eigen and other libraries

Should I use Eigen?

Probably, but check pit falls first.

Why another matrix library? What is the need for Eigen?

First of all, see the Overview. No other library provides all of the features and benefits listed there.

The Eigen project started when some hackers from the large KDE meta-project realized the need for a single unified matrix library.

Some other libraries do satisfy very well certain specialized needs, but none is as versatile as Eigen, has such a nice API, etc.

The fact that so many projects are quickly adopting Eigen 2, shows that it fills a gap.

The state of existing matrix libraries before Eigen is that:

However Eigen is the first library to satisfy all these criteria.

How does Eigen compare to BLAS/LAPACK?

Eigen covers many things that BLAS/LAPACK don't:

Using only one thread, Eigen compares very well performance-wise against the existing BLAS implementations. See the benchmark. It shows that:

However, currently Eigen parallelizes only general matrix-matrix products (bench), so it doesn't by itself take much advantage of parallel hardware.

Eigen has an incomparably better API than BLAS and LAPACK.

Miscellaneous advantages (not specifically against BLAS/LAPACK):

Compilation

I need help with compiler errors!

Known MSVC issues

Runtime

I need help with Assert crashes!

The asserts are there to protect you from later unexplained crashes due to bad memory accesses.

When you hit such an assert, rerun your program in a debugger and obtain a backtrace. Make sure that you have compiled your program with enough debugging info. This way, you will quickly be able to trace back to the root cause of the problem :)

The most dreaded assert is the "Unaligned array" assert. As you can see, that page is there to help you fix it. If however you are desperate about it, you can always get rid of it.

Other assertions are typically triggered when you have accessed coefficients with out-of-range indices in a matrix; or when you have mixed matrices of mismatched sizes.

Optimization

How do I get good performance?

There are many aspects to this question, but here are some points to get you started:

Where in my program are temporary objects created?

The Eigen library sometimes creates temporary matrices to hold intermediate results. This usually happens silently and may slow down your program, so it is useful to track down where temporary objects are created.

One possibility is to run your program under a debugger and set a break point which will be triggered when a temporary is created. For instance, you can set a break point in check_that_malloc_is_allowed() in Eigen/src/Core/util/Memory.h (this function is probably inlined if you compile with optimizations enabled).

Another possibility is to define the macro EIGEN_NO_MALLOC when compiling. This causes your program to abort whenever a temporary is created. More fine-grained checks are possible with the EIGEN_RUNTIME_NO_MALLOC macro. A minimal usage example follows:

#define EIGEN_RUNTIME_NO_MALLOC // Define this symbol to enable runtime tests for allocations
#include <Eigen/Dense>
 
int main(int argc, char** argv)
{
  // It's OK to allocate here
  Eigen::MatrixXd A = Eigen::MatrixXd::Random(20, 20);
 
  Eigen::internal::set_is_malloc_allowed(false);
  // It's NOT OK to allocate here
  // An assertion will be triggered if an Eigen-related heap allocation takes place
 
  Eigen::internal::set_is_malloc_allowed(true);
  // It's OK to allocate again
}

Vectorization

Which SIMD instruction sets are supported by Eigen?

Eigen supports SSE, AltiVec and ARM NEON.

With SSE, at least SSE2 is required. SSE3, SSSE3 and SSE4 are optional, and will automatically be used if they are enabled.

Of course vectorization is not mandatory -- you can use Eigen on any old CPU.

How can I enable vectorization?

You just need to tell your compiler to enable the corresponding instruction set, and Eigen will then detect it. If it is enabled by default, then you don't need to do anything.

On the x86 architecture, SSE is not enabled by default by most compilers. You need to enable SSE2 (or newer) manually. For example, with GCC, you would pass the -msse2 command-line option.

On the x86-64 architecture, SSE2 is generally enabled by default.

On PowerPC, you have to use the following flags: -maltivec -mabi=altivec.

On ARM NEON, the following: -mfpu=neon -mfloat-abi=softfp.

How can I disable vectorization?

You can disable Eigen's vectorization by defining the EIGEN_DONT_VECTORIZE preprocessor symbol.

If you also want to disable the "unaligned array" assertion or the 128bit alignment code, see the next entry below.

Also notice that your compiler may still be auto-vectorizing.

I disabled vectorization, but I'm still getting annoyed about alignment issues!

For example, you're still getting the "unaligned array" assertion.

If you want to get rid of it, you have two possibilities:

If you want to know why defining EIGEN_DONT_VECTORIZE doesn't by itself disable 128-bit alignment and the assertion, here's the explanation:

How does vectorization depend on the compiler?

Eigen has its own vectorization system, it does not at all rely on the compiler to automatically vectorize. However it still needs some support from the compiler, in the form of intrinsic functions representing a single SIMD instruction each.

Eigen will automatically enable its vectorization if a supported SIMD instruction set and a supported compiler are detected. Otherwise, Eigen will automatically disable its vectorization and go on.

Eigen vectorization supports the following compilers:

Of course the reason why we "support all other compilers" is that so far we haven't seen other examples of compilers on which we should disable Eigen vectorization. If you know some, please let us know.

What can't be vectorized?

SSE, AltiVec and NEON work with packets of 128 bits, or 16 bytes. This means 4 ints, or 4 floats, or 2 doubles. Moreover, it is often required that the packets themselves be 128-bit aligned. Eigen takes care automatically of all that for you, but there are a few cases where it really can't vectorize. It will then automatically fall back to non-vectorized code, so that again is transparent to you, except of course that the resulting code isn't as fast as if it were vectorized.

Now, there is a big difference between dynamic-size and fixed-size vectors and matrices.

The bad cases are fixed sizes that are not multiples of 16 bytes. For example, Vector2f, Vector3f, Vector3d, Matrix3f, Matrix3d.

However, you may be able to use Vector4f class to perform Vector3f operations and make use of vectorization if you can carefully ensure that the last component is always zero. .

All other cases are good cases and are successfully vectorized by Eigen:

Eigen also has some current limitations that can and will be overcome in the future. For instance, some advanced operations, such as visitors, aren't currently vectorized (this is on our to-do).

How can I check that vectorization is actually being used?

First you can check that Eigen vectorization is enabled: the EIGEN_VECTORIZE preprocessor symbol is then defined.

Then, you may want to check the resulting assembly code. This is the best way to check that vectorization actually happened for a specific operation. Add some asm comments in your code around a line of code you're interested in, and tell your compiler to output assembly code. With GCC you could do:

Vector4f a, b;
asm("#it begins here!")
a += b;
asm("#it ends here!")

See Studying assembly output for more information.

Algorithms

Is there a method to compute the (Moore-Penrose) pseudo inverse ?

There is no such method currently, but for plain matrices, you can do it easily using the SVD decomposition. Example by adding a method to the JacobiSVD class (you could do it from outside):

   void pinv( MatrixType& pinvmat) const
   {
     eigen_assert(m_isInitialized && "SVD is not initialized.");
     double  pinvtoler=1.e-6; // choose your tolerance wisely!
     SingularValuesType singularValues_inv=m_singularValues;
     for ( long i=0; i<m_workMatrix.cols(); ++i) {
        if ( m_singularValues(i) > pinvtoler )
           singularValues_inv(i)=1.0/m_singularValues(i);
       else singularValues_inv(i)=0;
     }
     pinvmat= (m_matrixV*singularValues_inv.asDiagonal()*m_matrixU.transpose());
   }    

See Bug 257 if there is any progress in natively providing this.

There's no pseudo inverse for sparse matrices (yet?) in Eigen.

How to implement IIR filters?

BTK propose an experimental module for Eigen implementing Infinite Impulse Response filters for 1D signals there.

Other languages

Can I use Eigen with Python?

Can I use Eigen with R?

Can I use Eigen with Java?

Personal tools
Namespaces
Variants
Actions
Navigation
Documentation
Toolbox