Re: [eigen] Eigen2 to Eigen3 Migration Path

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

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

Implemented; will detail it in a fresh new thread, this one is
becoming too hairy.

Benoit

>
> Benoit
>
>>
>> Tully
>>
>>
>