[Numpy-discussion] Experimental `like=` attribute for array creation functions

Thu Aug 13 10:13:07 EDT 2020

On Thu, Aug 13, 2020 at 2:47 PM Peter Andreas Entschev <peter at entschev.com>
wrote:

> > We adapted the NEP template [6] several times last year to try and
> improve this. And specified in there as well that NEP content set to the
> mailing list should only contain the sections: Abstract, Motivation and
> Scope, Usage and Impact, and Backwards compatibility. This to ensure we
> fully understand the "why" and "what" before the "how". Unfortunately that
> template and procedure hasn't been exercised much yet, only in NEP 38 [7]
> and partially in NEP 41 [8].
> >
> > If we have long-time maintainers of SciPy (Ilhan and myself),
> scikit-image (Juan) and CuPy (Leo, on the PR review) all saying they don't
> understand the goals, relevance, target audience, or how they're supposed
> to use a new feature, that indicates that the people doing the writing and
> having the discussion are doing something wrong at a very fundamental level.
>
> I'm more than happy to edit the NEP and try to clarify all the
> concerns.

Thanks Peter. Let me reiterate, you did a lot of things right, have been
happy to adapt when given feedback, and your willingness to go back and fix
things up now is much appreciated (and I'm happy to help). No criticism of
your work or attitude intended, on the contract.

> However, it gets pretty difficult to do so when I as an
> author don't understand where the difficulty is. Ilhan, Juan and Ralf
> now pointed out things that are missing/unclear, but no comment was
> made in that regard when I sent the NEP, my point being: I couldn't
> fix what I didn't know was a problem to others.
>

Yes of course, I totally understand that.

> > At this point I'm pretty disappointed in and tired of how we write and
> discuss NEPs on technical topics like dispatching, dtypes and the like.
> People literally refuse to write down concrete motivations, goals and
> non-goals, code that's problematic now and will be better/working post-NEP
> and usage examples before launching into extensive discussion of the gory
> details of the internals. I'm not sure what to do about it.
>
> Honestly, I don't really understand this. From my perspective, there
> are two ways to deal with such things:
>
> 1. Templates are to be taken mainly as _guidelines_ rather than
> _hardlines_, and the current text of NEP-35 definitely falls in the
> first category;
> 2. Templates are _hardlines_ and to be guided/enforced by maintainers
> at some point (maybe before merging the PR?).
>
> If 2 is the desired case for NumPy, which sounds a lot like what is
> wanted from NEP-35 and other NEPs generally, maintainers should let
> the authors know as early as possible that something isn't following
> the template's hardlines and it should be corrected.

Yes agreed, maintainers should do this. It was always meant as something in
between, "please follow but deviate if needed". If essential elements are
missing, I think that should be flagged earlier going forward.

As a concrete example: Stephan (the main author of __array_function__) was
still fuzzy on the functions covered and whether it solves array coercion,
in the last 24 hours*. You answered by pointing to concrete code in Dask
and Xarray. That code, why it doesn't work well now but will work with
like=, should be at the top of the NEP as concrete problem statement / code
examples. It's quite unfortunate that no maintainer explicitly requested
this many months ago.

* https://github.com/numpy/numpy/pull/16935#issuecomment-673379038

I don't mean any of this to remove myself of any responsibility, but would
> like to
> express my frustration that a 10 month-old NEP is only now getting so
> much pushback for being unclear after its implementation is nearing
> completion.
>

Totally understandable. I think part of the problem is that people only
weigh in when they see concrete "this part is for you, and here's how you
use it to solve problem X".

As for me personally, if I'm saying things now that I didn't manage to
respond to earlier (specific to your NEP), I apologize. 10 months ago I was
in the middle of an intercontinental move and a new-ish job getting busier
fast. Again, apologies and no criticism of your work.

>
> > I want to make an exception for merging the current NEP, for which the
> plan is to merge it as experimental to try in downstream PRs and get more
> experience. That does mean that master will be in an unreleasable state by
> the way, which is unusual and it'd be nice to get Chuck's explicit OK for
> that.
>
> I don't quite understand this either, why would that leave master in
> an unreleasable state?
>

That's what Sebastian proposed yesterday: let's merge right now, open
issues for all the things being brought up right now, and deal with them
pre-1.20-release. I'm saying I'm fine with that, but then we actually need
to go back and finalize the discussions before the next release.

Cheers,
Ralf

> Best,
> Peter
>
> On Thu, Aug 13, 2020 at 2:21 PM Ralf Gommers <ralf.gommers at gmail.com>
> wrote:
> >
> > Thanks for raising these concerns Ilhan and Juan, and for answering
> Peter. Let me give my perspective as well.
> >
> > To start with, this is not specifically about Peter's NEP and PR. NEP 35
> simply follows the pattern set by previous PRs, and given its tight scope
> is less difficult to understand than other NEPs on such technical topics.
> Peter has done a lot of things right, and is close to the finish line.
> >
> >
> > On Thu, Aug 13, 2020 at 12:02 PM Peter Andreas Entschev <
> peter at entschev.com> wrote:
> >>
> >>
> >> > I think, arriving to an agreement would be much faster if there is an
> executive summary of who this is intended for and what the regular usage
> is. Because with no offense, all I see is "dispatch", "_array_function_"
> and a lot of technical details of which I am absolutely ignorant.
> >>
> >> This is what I intended to do in the Usage Guidance [2] section. Could
> >> you elaborate on what more information you'd want to see there? Or is
> >> it just a matter of reorganizing the NEP a bit to try and summarize
> >> such things right at the top?
> >
> >
> > We adapted the NEP template [6] several times last year to try and
> improve this. And specified in there as well that NEP content set to the
> mailing list should only contain the sections: Abstract, Motivation and
> Scope, Usage and Impact, and Backwards compatibility. This to ensure we
> fully understand the "why" and "what" before the "how". Unfortunately that
> template and procedure hasn't been exercised much yet, only in NEP 38 [7]
> and partially in NEP 41 [8].
> >
> > If we have long-time maintainers of SciPy (Ilhan and myself),
> scikit-image (Juan) and CuPy (Leo, on the PR review) all saying they don't
> understand the goals, relevance, target audience, or how they're supposed
> to use a new feature, that indicates that the people doing the writing and
> having the discussion are doing something wrong at a very fundamental level.
> >
> > At this point I'm pretty disappointed in and tired of how we write and
> discuss NEPs on technical topics like dispatching, dtypes and the like.
> People literally refuse to write down concrete motivations, goals and
> non-goals, code that's problematic now and will be better/working post-NEP
> and usage examples before launching into extensive discussion of the gory
> details of the internals. I'm not sure what to do about it. Completely
> separate API and behavior proposals from implementation proposals? Make
> separate "API" and "internals" teams with the likes of Juan, Ilhan and Leo
> on the API team which then needs to approve every API change in new NEPs?
> Offer to co-write NEPs if someone is willing but doesn't understand how to
> go about it? Keep the current structure/process but veto further approvals
> until NEP authors get it right?
> >
> > I want to make an exception for merging the current NEP, for which the
> plan is to merge it as experimental to try in downstream PRs and get more
> experience. That does mean that master will be in an unreleasable state by
> the way, which is unusual and it'd be nice to get Chuck's explicit OK for
> that. But after that, I think we need a change here. I would like to hear
> what everyone thinks is the shape that change should take - any of my above
> suggestions, or something else?
> >
> >
> >>
> >> > Finally as a minor point, I know we are mostly (ex-)academics but
> this necessity of formal language on NEPs is self-imposed (probably PEPs
> are to blame) and not quite helping. It can be a bit more descriptive in my
> external opinion.
> >>
> >> TBH, I don't really know how to solve that point, so if you have any
> >> specific suggestions, that's certainly welcome. I understand the
> >> frustration for a reader trying to understand all the details, with
> >> many being only described in NEP-18 [3], but we also strive to avoid
> >> rewriting things that are written elsewhere, which would also
> >> overburden those who are aware of what's being discussed.
> >>
> >>
> >> > I also share Ilhan’s concern (and I mentioned this in a previous NEP
> discussion) that NEPs are getting pretty inaccessible. In a sense these are
> difficult topics and readers should be expected to have *some* familiarity
> with the topics being discussed, but perhaps more effort should be put into
> the context/motivation/background of a NEP before accepting it. One way to
> ensure this might be to require a final proofreading step by someone who
> has not been involved at all in the discussions, like peer review does for
> papers.
> >
> >
> > Some variant of this proposal would be my preference.
> >
> > Cheers,
> > Ralf
> >
> >>
> >> [1] https://github.com/numpy/numpy/issues/14441#issuecomment-529969572
> >> [2]
> https://numpy.org/neps/nep-0035-array-creation-dispatch-with-array-function.html#usage-guidance
> >> [3] https://numpy.org/neps/nep-0018-array-function-protocol.html
> >> [4] https://numpy.org/neps/nep-0000.html#nep-workflow
> >> [5]
> https://mail.python.org/pipermail/numpy-discussion/2019-October/080176.html
> >
> >
> > [6] https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst
> > [7]
> https://github.com/numpy/numpy/blob/master/doc/neps/nep-0038-SIMD-optimizations.rst
> > [8]
> https://github.com/numpy/numpy/blob/master/doc/neps/nep-0041-improved-dtype-support.rst
> >
> >
> >>
> >>
> >>
> >> On Thu, Aug 13, 2020 at 3:44 AM Juan Nunez-Iglesias <jni at fastmail.com>
> wrote:
> >> >
> >> > I’ve generally been on the “let the NumPy devs worry about it” side
> of things, but I do agree with Ilhan that `like=` is confusing and
> `typeof=` would be a much more appropriate name for that parameter.
> >> >
> >> > I do think library writers are NumPy users and so I wouldn’t really
> make that distinction, though. Users writing their own analysis code could
> very well be interested in writing code using numpy functions that will
> transparently work when the input is a CuPy array or whatever.
> >> >
> >> > I also share Ilhan’s concern (and I mentioned this in a previous NEP
> discussion) that NEPs are getting pretty inaccessible. In a sense these are
> difficult topics and readers should be expected to have *some* familiarity
> with the topics being discussed, but perhaps more effort should be put into
> the context/motivation/background of a NEP before accepting it. One way to
> ensure this might be to require a final proofreading step by someone who
> has not been involved at all in the discussions, like peer review does for
> papers.
> >> >
> >> > Food for thought.
> >> >
> >> > Juan.
> >> >
> >> > On 13 Aug 2020, at 9:24 am, Ilhan Polat <ilhanpolat at gmail.com> wrote:
> >> >
> >> > For what is worth, as a potential consumer in SciPy, it really
> doesn't say anything (both in NEP and the PR) about how the regular users
> of NumPy will benefit from this. If only and only 3rd parties are going to
> benefit from it, I am not sure adding a new keyword to an already confusing
> function is the right thing to do.
> >> >
> >> > Let me clarify,
> >> >
> >> > - This is already a very (I mean extremely very) easy keyword name to
> confuse with ones_like, zeros_like and by its nature any other
> interpretation. It is not signalling anything about the functionality that
> is being discussed. I would seriously consider reserving such obvious names
> for really obvious tasks. Because you would also expect the shape and ndim
> would be mimicked by the "like"d argument but it turns out it is acting
> more like "typeof=" and not "like=" at all. Because if we follow the
> semantics it reads as "make your argument asarray like the other thing" but
> it is actually doing, "make your argument an array with the other thing's
> type" which might not be an array after all.
> >> >
> >> > - Again, if this is meant for downstream libraries (because that's
> what I got out of the PR discussion, cupy, dask, and JAX were the only
> examples I could read) then hiding it in another function and writing with
> capital letters "this is not meant for numpy users" would be a much more
> convenient way to separate the target audience and regular users.
> numpy.astypedarray([[some data], [...]], type_of=x) or whatever else it may
> be would be quite clean and to the point with no ambiguous keywords.
> >> >
> >> > I think, arriving to an agreement would be much faster if there is an
> executive summary of who this is intended for and what the regular usage
> is. Because with no offense, all I see is "dispatch", "_array_function_"
> and a lot of technical details of which I am absolutely ignorant.
> >> >
> >> > Finally as a minor point, I know we are mostly (ex-)academics but
> this necessity of formal language on NEPs is self-imposed (probably PEPs
> are to blame) and not quite helping. It can be a bit more descriptive in my
> external opinion.
> >
> > _______________________________________________
> > NumPy-Discussion mailing list
> > NumPy-Discussion at python.org
> > https://mail.python.org/mailman/listinfo/numpy-discussion
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20200813/a28e018e/attachment-0001.html>