eigen/doc/Mainpage.dox

o /** @mainpage Eigen

<h2>Table of contents</h2>
<a href="#overview">Overview</a><br/>
<a href="#license">License</a><br/>
<a href="#features">Features</a><br/>
<a href="#todo">To-do wiki</a><br/>
<a href="#compiler_support">Compiler Support</a><br/>
<a href="#news">News</a><br/>
<a href="#download">Download</a><br/>
<a href="#kde">Relation to KDE</a><br/>
<a href="#examples">Examples</a><br/>
<a href="#applications">Applications using Eigen</a><br/>
<a href="#credits">Credits</a><br/>
<a href="#contact">Contact us</a><br/>
<a href="#mailinglist">Mailing list</a><br/>

<a name="overview"></a>
<h2>Overview</h2>

Eigen is a C++ template library for vector and matrix math, a.k.a. linear algebra. It aims to concile speed, ease of use, and completeness.

<a name="license"></a>
<h2>License</h2>

Eigen is dual-licensed: it can be redistributed and/or modified, at your choice,
<ul>
  <li> either under the <a href="http://www.gnu.org/copyleft/lgpl.html">LGPL</a>, version 3 or later,</li>
  <li> or under the <a href="http://www.gnu.org/copyleft/gpl.html">GPL</a>, version 2 or later.</li>
</ul>

Note that this is an OR, not an AND. You do not need to conform to both licenses, you just pick the one that you prefer. Typically, GPL projects will regard Eigen as GPL-licensed while non-GPL projects will regard Eigen as LGPL-licensed.

Short licensing FAQ:

<b>Question:</b> Why not just license under the LGPL, since anyway it is more liberal than the GPL?<br>
<b>Answer:</b> A library licensed under the LGPL3 cannot be used by a program licensed under the GPL2 (<a href="http://www.fsf.org/licensing/licenses/gpl-faq.html#AllCompatibility">see here for details</a>). Therefore, we offer the GPL2 as an alternative license choice for Eigen, in order to allow GPL2 programs to use it.

<b>Question:</b> Why require the LGPL version to be at least 3?<br>
<b>Answer:</b> Because up to version 2.1, the LGPL does not handle the case of C++ template libraries, where all the code is in headers. This problem was solved in version 3 of the LGPL.

<a name="features"></a>
<h2>Features</h2>

WARNING: this alpha release is NOT feature complete -- far from it! It contains only the Core module, while several other modules are planned.

Here are general features of Eigen and more specific features of the Core module:

<ul>
  <li><a href="http://ubiety.uwaterloo.ca/~tveldhui/papers/Expression-Templates/exprtmpl.html">Expression templates</a> everywhere. This is an optimization (elimination of temporaries, lazy evaluation), but more importantly this allows for a much nicer API, especially as Eigen supports lvalue expressions. For example, the following is valid with Eigen and compiles to optimized code:
  \code matrix.row(i) += factor * matrix.row(j); \endcode</li>
  <li>Both fixed-size and dynamic-size objects are supported, with uniform API,
      in a way that allows Eigen to make
      all usual optimizations in the case of fixed size, such as loop unrolling. Moreover
      special care is used to ensure that the fixed-size types never cause dynamic memory
      allocations. Even when the dimensions of an expression at not known at compile-time,
      if a fixed bound is known (e.g. when taking a block in a fixed-size matrix) then
      Eigen uses it to allocate a static array instead of a dynamic one.</li>
  <li>Both column-vectors and row-vectors are supported, as special cases of matrices.</li>
  <li>The following scalar types are supported and well tested: \c int, \c float, \c double,
      \c std::complex<float>, \c std::complex<double>. </li>
</ul>

<a name="todo"></a>
<h2>To-do wiki</h2>

The To-do wiki for Eigen is here: <a href="http://techbase.kde.org/index.php?title=Projects/Eigen/TODO">http://techbase.kde.org/index.php?title=Projects/Eigen/TODO</a>.

<a name="compiler_support"></a>
<h2>Compiler Support</h2>

Eigen is standard C++98 and so should theoretically be compatible with any compliant compiler. Of course, in practice, things are slightly different.

Eigen is well tested with recent versions of GCC and ICC. Both GCC 4.2 and ICC gives very good performance. ICC might provide even better performance when the auto-vectorization makes sense. For some reason the performance is not so great with GCC 4.1.

Eigen is also known to compile with GCC 3.4 and 4.0. However, these later ones seems to not correctly handle friend class with the CRT design pattern. Therefore, at the moment, for any GCC versions earlier than 4.1, all private members of Eigen's classes are made public. It is up to the user to take care to access public members only.

For best performance, we recommend the following compilation flags:
<ul>
  <li>\b GCC: \c -O3 \c -DNDEBUG \c -finline-limit=10000 \c -falign-functions=64 </li>
  <li>\b ICC: \c -O3 \c -DNDEBUG \c -xT \c -ipo \c -no-prec-div \c -no-inline-max-size </li>
</ul>


<a name="news"></a>
<h2>News</h2>

If you want to stay informed of Eigen news and releases, please subscribe to our <a href="#mailinglist">mailing list</a>. You can also browse the <a href="http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/">archive</a>.

<a name="download"></a>
<h2>Download</h2>
The source code of the latest release is here: <a href="http://download.tuxfamily.org/eigen/eigen-2.0-alpha4.tar.gz">eigen-2.0-alpha4.tar.gz</a><br/>

Alternatively, you can checkout the development tree by anonymous svn, by doing:
<pre>svn co svn://anonsvn.kde.org/home/kde/branches/work/eigen2</pre>
or view it online at this address:
<a href="http://websvn.kde.org/branches/work/eigen2">http://websvn.kde.org/branches/work/eigen2</a>

<a name="kde"></a>
<h2>Relation to KDE</h2>

First of all: Eigen doesn't have any dependency. In particular, it doesn't depend on any part of KDE or on Qt.<br/>

Eigen is part of the KDE project, in the sense that:
<ul>
  <li>Its <a href="http://websvn.kde.org/trunk/kdesupport/eigen/">development tree</a> is hosted in the <a href="http://websvn.kde.org">KDE repository</a>.</li>
  <li>It has been founded by, and is developed by KDE people.</li>
  <li>It has originally been designed for the needs of KDE applications, especially <a href="http://edu.kde.org/kalzium">Kalzium</a>.</li>
</ul>
However, we quickly realized that Eigen could be useful for non-KDE projects, whence our decision to make sure that it has no dependency on KDE or Qt.

Although Eigen itself doesn't have any dependency, the unit-tests require Qt.

<a name="examples"></a>
<h2>Examples</h2>

There are a lot of small examples throughout the documentation. TODO: write more interesting,
standalone "demos".

<a name="applications"></a>
<h2>Applications using Eigen</h2>

TODO: update this section; make web links

Currently: Kalzium, Avogadro, KSpread(a bit), Krita(a bit)
Planned: much more use in KOffice 2.1, Step (if we make Eigen good enough!)

Please tell us if you know of other interesting projects using Eigen!

<a name="credits"></a>
<h2>Credits</h2>

<ul>
  <li>Benoit Jacob (jacob at math jussieu fr) : Main developer</li>
  <li>Gael Guennebaud (gael guennebaud at gmail com) : Large contributions</li>
  <li>Christian Mayer (mail at christianmayer de) : reviewed the source code, made many useful suggestions</li>
  <li>Michael Olbrich (michael olbrich at gmx net) : initial loop-unrolling metaprogram</li>
  <li>and thanks to everyone on the <a href="#mailinglist">mailing list</a> for your input!
</ul>

<a name="contact"></a>
<h2>Contact us</h2>

The best way to contact us is by means of our <a href="#mailinglist">mailing list</a>.<br/>
IRC Channel: \#eigen on Freenode.<br/>
Website (you're here): <a href="http://eigen.tuxfamily.org">http://eigen.tuxfamily.org</a><br/>

<a name="mailinglist"></a>
<h2>Mailing list</h2>

The Mailing list for Eigen is: eigen at lists tuxfamily org.<br/>

To subscribe, send a mail with subject "subscribe" to eigen-request at lists tuxfamily org.<br/>
To unsubscribe, send a mail with subject "unsubscribe" to eigen-request at lists tuxfamily org.<br/>

You can also browse the <a href="http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/">archive</a>.

*/