Re: [eigen] Eigen2 to Eigen3 Migration Path

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

2011/1/20 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.

This is a very good plan, I'm implementing it.

Benoit

>
> Tully
>
>