Re: [eigen] Eigen2 to Eigen3 Migration Path

[Tully Foote <tfoote@xxxxxxxxxxxxxxxx>]

On Thu, Jan 20, 2011 at 8:00 AM, Benoit Jacob <jacob.benoit.1@xxxxxxxxx> wrote:

2011/1/20 Benoit Jacob <jacob.benoit.1@xxxxxxxxx>:

> 2011/1/19 Benoit Jacob <jacob.benoit.1@xxxxxxxxx>:
>> 2011/1/14 Benoit Jacob <jacob.benoit.1@xxxxxxxxx>:
>>> Great to see a solution on the horizon. Now we need to implement it. I
>>> filed a bug:
>>>
>>> http://eigen.tuxfamily.org/bz/show_bug.cgi?id=153
>>>
>>> I marked it as blocking 3.0, as it doesn't really need to be tested in
>>> a beta. Could even not block 3.0 actually, but I have a feeling that
>>> that can be implemented quickly.
>>
>> I have started implementing this. EIGEN2_SUPPORT is already expanded
>> as of today, the Eigen2 test suite has been imported into Eigen3, and
>> can be enabled with the CMake option EIGEN_TEST_EIGEN2, after which
>> you can do:
>>  make buildtests_eigen2
>> and
>>  make check_eigen2
>> (I'm going to make standard targets depend on them too, when
>> EIGEN_TEST_EIGEN2 is defined).
>>
>> Currently, only some core functionality tests compile.
>
> Lots more tests compile and fully succeed now; more work needed.
>
> I can already say what's going to be the most tricky issue in porting
> apps from eigen2 to eigen3:
>
> in eigen2, dot product was conjugating the right-hand side (linear in
> the first variable) while in eigen3 it's conjugating the left-hand
> side (linear in the second variable).
>
> This is going to play tricks on users who did dot products over complex numbers.
>
> in Eigen2 support mode, since the goal is full API compatibility with
> Eigen2, I'm switching this to eigen2 behavior.
>
> Of course we need to document this on the Eigen2To3 porting doc page,
> but I'm afraid this might not be enough.
>
> Should I put a static assert on dot products with complex numbers in
> EIGEN2_SUPPORT mode, forcing people to #define
> I_HAVE_READ_DOCS_ON_THIS_ISSUE or some such ?

OK here's a proposal:

we split the EIGEN2_SUPPORT mode into two separate modes:
EIGEN2_SUPPORT and EIGEN2_FULL_SUPPORT_BREAKING_EIGEN3.

EIGEN2_FULL_SUPPORT_BREAKING_EIGEN3 means that we guarantee 100% API
compatibility with Eigen2, which in the case of complex dot products
means we break the Eigen3 API (x.dot(y) giving a different result in
the complex case).

EIGEN2_SUPPORT means that we support Eigen2 API as much as possible,
while still guaranteeing 100% compatibility with Eigen3.

To the migration path would be:
1. Start with a Eigen2 project
2. Replace Eigen2 by Eigen3 + EIGEN2_FULL_SUPPORT_BREAKING_EIGEN3
     (this gives you the Eigen2 API with the Eigen3 ABI, so at this
stage you can recompile everything).
3. Then take care of your complex dot products, i.e.  x.dot(y) becomes
y.dot(x), and replace EIGEN2_FULL_SUPPORT_BREAKING_EIGEN3 by
EIGEN2_SUPPORT. At this stage, you have the Eigen3 API with just
convenience support for the rest of your Eigen2 code.
4. Now you can work incrementally to remove EIGEN2_SUPPORT file by file.

Of course it may sound crazy to do all this for a complex dot products
convention, but really it's not limited to that. There are other
places where the Eigen2 and EIgen3 APIs depart. Think of Transform for
instance.

I think that the two step change is necessary, since this API is conflicting.  With this proposal step 3 is a problem for large(aka non atomic) project because it requires every component to change at the same time. Which would break every piece of code using that method without any warning. 

I would like to suggest a slight variant of this proposal where there are two stages of support.  In the first stage, the old API is deprecated and an intermediate API is defined.  And in the 2nd stage the intermediate API is deprecated and the new API is restored. 


An example timeline is below:

1. Prexisting Eigen2 code:  x.dot(y)
2. Maintainers switch to Eigen3 with EIGEN2_STAGE1_SUPPORT
    -dot method is marked as deprecated and warns at compile time
3. Developers switch  x.dot(y)   to x.eigen2_dot(y)
4. Maintainers switch to Eigen3 with EIGEN2_STAGE2_SUPPORT
    - eigen2_dot method is marked as deprecated and warns at compile time, dot method is changed to Eigen3 functionality
5. Developers switch x.eigen2_dot(y) to y.dot(x)
6. Maintainers switch to Eigen3 natively. 

This approach is a little longer, however the atomic switch across a large project is almost impossible and would likely end up with the project never removing the EIGEN2_SUPPORT define.

Tully