Difference between revisions of "FAQ"

From Eigen
Jump to: navigation, search
(Why another matrix library? What is the need for Eigen?)
Line 1: Line 1:
 
[[Image:owl_faq.jpg|right]]
 
[[Image:owl_faq.jpg|right]]
 +
 +
=Eigen and other libraries=
  
 
==Why another matrix library? What is the need for Eigen?==
 
==Why another matrix library? What is the need for Eigen?==
Line 40: Line 42:
 
* Eigen, compared to certain other C++ template libraries, is relatively easy on the compiler. Compilation times stay reasonable -- we are very careful about that.
 
* Eigen, compared to certain other C++ template libraries, is relatively easy on the compiler. Compilation times stay reasonable -- we are very careful about that.
 
* Eigen is small, so it is feasible to include a copy of it in your own source tree, if you want to.
 
* Eigen is small, so it is feasible to include a copy of it in your own source tree, if you want to.
 +
 +
=Compilation=
 +
 +
==I need help with compiler errors!==
 +
 +
* Did you forget to include a module? Certain Eigen features are not in Core but in other modules. Normally this is always explained in the documentation but we may have forgotten some places. For example, in order to use random matrices, you need to do:
 +
<code lang="cpp">
 +
#include <Eigen/Array>
 +
</code>
 +
 +
* Did you check if you triggered a ''static assertion'' ? These are compile-time checks guarding from programming mistakes. Eigen has many of those. So even if you got a kilometer of compiler output, you might still find useful information from static assertion messages. Search for "static_assert". The static assertion messages themselves are UPPERCASE_SO_THEY_REALLY_STAND_OUT.
 +
 +
=Vectorization=
 +
 +
==What SIMD instruction sets does Eigen support?==
 +
 +
Eigen supports SSE and AltiVec.
 +
 +
With SSE, at least SSE2 is required. SSE3 and SSSE3 are optional. SSE4 and newer are ignored.
 +
 +
==How do I enable vectorization?==
 +
 +
You just need to tell your compiler to enable the corresponding instruction set. 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.
 +
 +
==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.
 +
 +
Eigen will automatically enable its vectorization if a supported vectorization architecture and a supported compiler are detected. Otherwise, Eigen will automatically disable its vectorization and go on. You can also forcibly disable vectorization by defining EIGEN_DONT_VECTORIZE.
 +
 +
Eigen vectorization supports the following compilers:
 +
* GCC 4.2 and newer,
 +
* MSVC 2008 and newer,
 +
* All other compilers (for example it works with ICC).
 +
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.

Revision as of 19:30, 19 December 2008

Owl faq.jpg

Eigen and other libraries

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:

  • some are Free Software
  • some are fast
  • some have a decent API
  • some handle fixed-size matrices, some handle dynamic-size dense matrices, some handle sparse matrices
  • some provide linear algebra algorithms (LU, QR, ...)
  • some provide a geometry framework (quaternions, rotations...)

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:

  • Eigen handles fixed-size matrices and vectors, which are very widely used.
  • Eigen provides a lot of convenience features (see Geometry module, Array module, etc), which are also very widely used.

Eigen compares very well performance-wise against the existing BLAS implementations. See the benchmark. It shows that:

  • Eigen is much faster than every Free BLAS, such as ATLAS or Boost::uBlas.
  • Eigen is overall of comparable speed (faster or slower depending on what you do) to the best BLAS, namely Intel MKL and GOTO, both of which are non-Free.

Eigen has an incomparably better API than BLAS and LAPACK.

  • See the API Showcase.
  • For operations involving complex expressions, Eigen is inherently faster than any BLAS implementation because it can handle and optimize a whole operation globally -- while BLAS forces the programmer to split complex operations into small steps that match the BLAS fixed-function API, which incurs inefficiency due to introduction of temporaries.

Miscellaneous advantages:

  • Eigen is only a compile-time dependency for your project. No need to redistribute, or ask your user to install, any library.
  • Eigen is multi-platform, and is actually being used on a number of different operating systems, hardware platforms, and compilers.
  • Eigen, compared to certain other C++ template libraries, is relatively easy on the compiler. Compilation times stay reasonable -- we are very careful about that.
  • Eigen is small, so it is feasible to include a copy of it in your own source tree, if you want to.

Compilation

I need help with compiler errors!

  • Did you forget to include a module? Certain Eigen features are not in Core but in other modules. Normally this is always explained in the documentation but we may have forgotten some places. For example, in order to use random matrices, you need to do:

#include <Eigen/Array>

  • Did you check if you triggered a static assertion ? These are compile-time checks guarding from programming mistakes. Eigen has many of those. So even if you got a kilometer of compiler output, you might still find useful information from static assertion messages. Search for "static_assert". The static assertion messages themselves are UPPERCASE_SO_THEY_REALLY_STAND_OUT.

Vectorization

What SIMD instruction sets does Eigen support?

Eigen supports SSE and AltiVec.

With SSE, at least SSE2 is required. SSE3 and SSSE3 are optional. SSE4 and newer are ignored.

How do I enable vectorization?

You just need to tell your compiler to enable the corresponding instruction set. 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.

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.

Eigen will automatically enable its vectorization if a supported vectorization architecture and a supported compiler are detected. Otherwise, Eigen will automatically disable its vectorization and go on. You can also forcibly disable vectorization by defining EIGEN_DONT_VECTORIZE.

Eigen vectorization supports the following compilers:

  • GCC 4.2 and newer,
  • MSVC 2008 and newer,
  • All other compilers (for example it works with ICC).

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.