C++ API stability & backward compatiblity

[Bob Carpenter]

This is something I'd like to discuss at the next Stan
meeting if Daniel and Michael will be around.

As is, with our habit of reorganizing the C++ code
every few releases, I have to agree with Ben that an external
developer has no reason to trust us to not break backward
compatiblity in any given release --- our major release numbers
are meaningless at the C+ API level.

This is not only an issue for external developers, but
also ones working on branches within stan-dev/stan, as
well as RStan and PyStan. I'm pretty much having to rely
on grep now to find anything with the latest reorganization.
I'd strongly prefer this not to be a permanent state.

Daniel: Is there a time when we can declare pencils down
on all the refactoring of the math library? Is the plan still
to pull it out into its own repo? Maybe that's when we
should plan to advertise more stability and we should discourage
anyone from using the API until then.

- Bob

[Daniel Lee]

I'll be at the meeting tomorrow. Happy to talk about it and make some decisions.

On Mon, Mar 16, 2015 at 2:33 AM, Bob Carpenter <ca...@alias-i.com> wrote:
> As is, with our habit of reorganizing the C++ code
> every few releases, I have to agree with Ben that an external
> developer has no reason to trust us to not break backward
> compatiblity in any given release --- our major release numbers
> are meaningless at the C+ API level.
>
> This is not only an issue for external developers, but
> also ones working on branches within stan-dev/stan, as
> well as RStan and PyStan. I'm pretty much having to rely
> on grep now to find anything with the latest reorganization.
> I'd strongly prefer this not to be a permanent state

All good points and I also don't want this to be a permanent state.

> Daniel: Is there a time when we can declare pencils down
> on all the refactoring of the math library?

Yes, I don't know when that is, but it can be soon. Just not yet. I
think we treat the C++ api as in a development state for now.

If you want me to put a line in the sand, I'd say end of June. That'll
give us two months after Bob gets back to hash out whatever final
details we need to consider before we freeze the API.

I also think we should put the agrad::rev paper out around that time.

> Is the plan still
> to pull it out into its own repo? Maybe that's when we
> should plan to advertise more stability and we should discourage
> anyone from using the API until then.

I think it's the smart thing to do. We can decouple the math library
from the rest of Stan. I think we encourage people to use the API when
we get the paper out detailing how to use it.


Anyone else have any thoughts?

[Joshua N Pritikin]

On Mon, Mar 16, 2015 at 01:17:19PM -0400, Daniel Lee wrote:
> > Daniel: Is there a time when we can declare pencils down
> > on all the refactoring of the math library?
>
> Yes, I don't know when that is, but it can be soon. Just not yet. I
> think we treat the C++ api as in a development state for now.
>
> If you want me to put a line in the sand, I'd say end of June. That'll
> give us two months after Bob gets back to hash out whatever final
> details we need to consider before we freeze the API.

To better ensure long-term success, I think you should aim for getting
this merged into Eigen or at least officially acknowledged by the Eigen
team.

--
Joshua N. Pritikin
Department of Psychology
University of Virginia
485 McCormick Rd, Gilmer Hall Room 102
Charlottesville, VA 22904
http://people.virginia.edu/~jnp3bc

[Daniel Lee]

On Mon, Mar 16, 2015 at 1:30 PM, Joshua N Pritikin <jpri...@pobox.com> wrote:
> On Mon, Mar 16, 2015 at 01:17:19PM -0400, Daniel Lee wrote:
>> > Daniel: Is there a time when we can declare pencils down
>> > on all the refactoring of the math library?
>>
>> Yes, I don't know when that is, but it can be soon. Just not yet. I
>> think we treat the C++ api as in a development state for now.
>>
>> If you want me to put a line in the sand, I'd say end of June. That'll
>> give us two months after Bob gets back to hash out whatever final
>> details we need to consider before we freeze the API.
>
> To better ensure long-term success, I think you should aim for getting
> this merged into Eigen or at least officially acknowledged by the Eigen
> team.

What is "this"?

[Joshua N Pritikin]

On Mon, Mar 16, 2015 at 01:40:10PM -0400, Daniel Lee wrote:
> On Mon, Mar 16, 2015 at 1:30 PM, Joshua N Pritikin <jpri...@pobox.com> wrote:
> > On Mon, Mar 16, 2015 at 01:17:19PM -0400, Daniel Lee wrote:
> >> > Daniel: Is there a time when we can declare pencils down
> >> > on all the refactoring of the math library?
> >

> > To better ensure long-term success, I think you should aim for getting
> > this merged into Eigen or at least officially acknowledged by the Eigen
> > team.
>
> What is "this"?

this = the math library

[Daniel Lee]

On Mon, Mar 16, 2015 at 1:55 PM, Joshua N Pritikin <jpri...@pobox.com> wrote:
> On Mon, Mar 16, 2015 at 01:40:10PM -0400, Daniel Lee wrote:
>> On Mon, Mar 16, 2015 at 1:30 PM, Joshua N Pritikin <jpri...@pobox.com> wrote:
>> > On Mon, Mar 16, 2015 at 01:17:19PM -0400, Daniel Lee wrote:
>> >> > Daniel: Is there a time when we can declare pencils down
>> >> > on all the refactoring of the math library?
>> >
>> > To better ensure long-term success, I think you should aim for getting
>> > this merged into Eigen or at least officially acknowledged by the Eigen
>> > team.
>>
>> What is "this"?
>
> this = the math library

Ok. Thanks for the clarification.

I don't think we're aiming to merge our math (which includes our
autodiff) library into Eigen.

[Bob Carpenter]

> On Mar 17, 2015, at 4:17 AM, Daniel Lee <bea...@alum.mit.edu> wrote:
>
> I'll be at the meeting tomorrow. Happy to talk about it and make some decisions.
>
> On Mon, Mar 16, 2015 at 2:33 AM, Bob Carpenter <ca...@alias-i.com> wrote:
>> As is, with our habit of reorganizing the C++ code
>> every few releases, I have to agree with Ben that an external
>> developer has no reason to trust us to not break backward
>> compatiblity in any given release --- our major release numbers
>> are meaningless at the C+ API level.
>>
>> This is not only an issue for external developers, but
>> also ones working on branches within stan-dev/stan, as
>> well as RStan and PyStan. I'm pretty much having to rely
>> on grep now to find anything with the latest reorganization.
>> I'd strongly prefer this not to be a permanent state
>
> All good points and I also don't want this to be a permanent state.
>
>
>> Daniel: Is there a time when we can declare pencils down
>> on all the refactoring of the math library?
>
> Yes, I don't know when that is, but it can be soon. Just not yet. I
> think we treat the C++ api as in a development state for now.
>
> If you want me to put a line in the sand, I'd say end of June.

No, I absolutely don't want that. Never trust a software plan that's
longer than a day and doesn't have a detailed plan of how long
it'll take at a one or two day level of granularity. And it's
work days you need to estimate, not calendar days, because all sorts
of emergencies can get in the way of calendar-based deadlines.

> That'll
> give us two months after Bob gets back to hash out whatever final
> details we need to consider before we freeze the API.
>
> I also think we should put the agrad::rev paper out around that time.

I don't want to wait on that. We need to get it under submission.
The job market and future grants beckon and getting papers out is
important on both those fronts. The Stan paper itself is still
being reviewed for the third time, and it's over a year behind at
this point (though still backward compatible).

>> Is the plan still
>> to pull it out into its own repo? Maybe that's when we
>> should plan to advertise more stability and we should discourage
>> anyone from using the API until then.
>
> I think it's the smart thing to do. We can decouple the math library
> from the rest of Stan. I think we encourage people to use the API when
> we get the paper out detailing how to use it.
>

Sounds good to me.

I think Joshua Pritikin's the most effected by this one.

- Bob

[Bob Carpenter]

I believe Boost would be a deal breaker. At most
we'd be able to get into their unsupported branch like
the other autodiff efforts there, but even then, I'm
doubtful.

Trying to get it into Boost would also be problematic
because of the Eigen dependency and because they have their
own distribution and matrix libs (we lean heavily on
the former for RNGs, but had to specialize densities and CDFs).

I also do not want to cede control to an even larger group
of developers --- it's too difficult to manage already!

- Bob

> --
> You received this message because you are subscribed to the Google Groups "stan development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to stan-dev+u...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

[Daniel Lee]

Let's get back on track with this thread.

Consider my line in the sand erased. We'll lock down the math API
asap, but we won't treat it as locked for a little longer.


Daniel