[eigen] Re: introducing the Eigen2 support stages

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

another update:

* The following modules are completed: Core, Array, LU, Geometry, and
the QR decomposition part of the QR module
* remains to do (none of that is big): eigendecompositions (was in the
QR module in eigen2), SVD, LeastSquares, Cholesky, Sparse, StdVector.
* help welcome with those. Nothing hard remains to do, just go over
test build failures (cmake -DEIGEN_TEST_EIGEN2=ON) and fix them.

Tully, do you want me to prioritize what you're most interested in?

To test, define EIGEN2_SUPPORT_STAGE10_FULL_EIGEN2_API and try to
recompile your whole eigen2-based project.

Benoit

2011/1/24 Benoit Jacob <jacob.benoit.1@xxxxxxxxx>:
> Another update:
>
> The biggest remaining chunk was the Geometry module, as it is replete
> with hard API incompatibilities. I've solved this by importing a copy
> of Eigen2's Geometry module. So the RESOLVE_API_CONFLICTS stage
> becomes really, really useful here.
>
> By tomorrow, stuff should be mostly finished, except for the Sparse module.
>
> Benoit
>
> 2011/1/23 Benoit Jacob <jacob.benoit.1@xxxxxxxxx>:
>> A little update:
>>
>> the stage 2, RESOLVE_API_CONFLICTS, is now producing errors instead of
>> warnings, to help make sure that these very important issues are
>> caught.
>>
>> a new stage "1.5" has been introduced, doing what stage 2 used to do
>> (produce warnings). it's called RESOLVE_API_CONFLICTS_WARN.
>>
>> So i've multiplied all the constants by 10 to make room. The stages
>> currently are:
>>
>> EIGEN2_SUPPORT_STAGE10_FULL_EIGEN2_API
>> EIGEN2_SUPPORT_STAGE15_RESOLVE_API_CONFLICTS_WARN
>> EIGEN2_SUPPORT_STAGE20_RESOLVE_API_CONFLICTS
>> EIGEN2_SUPPORT_STAGE30_FULL_EIGEN3_API
>> EIGEN2_SUPPORT_STAGE40_FULL_EIGEN3_STRICTNESS
>>
>> On the implementation front, almost all the core functionality is
>> passing, but the 'triangular' test, covering things such as part(),
>> took me longer than anticipated. I still hope that by tomorrow I
>> should be almost done.
>>
>> Benoit
>>
>> 2011/1/21 Benoit Jacob <jacob.benoit.1@xxxxxxxxx>:
>>> Hi,
>>>
>>> As you may know, we are in the process of making the transition from
>>> eigen2 to 3 as easy as possible by making the EIGEN2_SUPPORT mode
>>> fully Eigen2 API compatible.
>>>
>>> However, as was discussed, there are a few corner cases where this is
>>> impossible, because eigen2 and 3 use different conventions for the
>>> same API.
>>>
>>> So it's been suggested to split EIGEN2_SUPPORT into multiple 'stages',
>>> and I have just dmplemented that.
>>>
>>> First of all, if you are currently doing #define EIGEN2_SUPPORT, don't
>>> worry: it stays supported, nothing changes. It just becomes a shortcut
>>> for what I'll call below "stage 3"
>>>
>>> So here are the different stages:
>>>
>>> 1)  #define EIGEN2_SUPPORT_STAGE1_FULL_EIGEN2_API
>>>
>>> When you #define this before including Eigen3 headers, you get 100%
>>> support of the Eigen2 API (once ongoing work is completed), so that
>>> Eigen2-using code compiles unchanged.
>>>
>>> That means that when a convention is different between eigen2 and
>>> eigen3, the eigen2 convention is used. For example, for complex
>>> vectors x and y,  x.dot(y)  conjugates y (dot product linear in the
>>> first variable x).
>>>
>>> For such cases where the eigen2 and eigen3 APIs conflict, we introduce
>>> eigen2_ prefixed functions, so you can replace
>>>  x.dot(y)
>>> by
>>>  x.eigen2_dot(y)
>>>
>>> 2)  #define EIGEN2_SUPPORT_STAGE2_RESOLVE_API_CONFLICTS
>>>
>>> This is identical to stage 1 except that the eigen2 API that conflicts
>>> with eigen3 is now deprecated. So when you do
>>>  x.dot(y)
>>> you get a 'deprecated' warning even though that would also compile in
>>> pure eigen3 (but with a different meaning). At this stage, you should
>>> go over these warnings and fix them by using eigen2_ prefixed
>>> functions:
>>>  x.eigen2_dot(y)
>>>
>>> 3) #define EIGEN2_SUPPORT_STAGE3_FULL_EIGEN3_API
>>>
>>> This is what you get when you just #define EIGEN_SUPPORT.
>>> This stage switches to eigen3 conventions everywhere. So now x.dot(y)
>>> is linear in the first variable. You may still use eigen2_ prefixed
>>> functions, and of course the rest of the Eigen2 API is still available
>>> unchanged.
>>>
>>> Also, where Eigen2 allows to do const-incorrect things (such as
>>> mapping const data as non-const Map), this stage still allows it.
>>>
>>> 4) #define EIGEN2_SUPPORT_STAGE4_FULL_EIGEN3_STRICTNESS
>>>
>>> This stage enables eigen3 strictness where eigen2 was laxist. In
>>> particular, it enforces const-correctness of Map.
>>>
>>> Notice that making the EIGEN2_SUPPORT_STAGE1_FULL_EIGEN2_API mode 100%
>>> API compatible is work in progress. I am still in the process of
>>> making the eigen2 test suite succeed. I'd say it should be completed
>>> during this weekend.
>>>
>>> Of course, I expect most small projects to just us EIGEN2_SUPPORT
>>> (which, again, is giving you stage 3) and not worry about this at all.
>>>
>>> Of course, this needs to be explained in the online 'porting from
>>> eigen 2 to eigen3' dox page.
>>>
>>> Benoit
>>>
>>
>