[SciPy-Dev] docstring standard: parameter shape description

[Joe Harrington]

On Tue, 29 Jan 2013 10:09:54 -0500, Jonathan Guyer <guyer at nist.gov> wrote:
> On Jan 28, 2013, at 7:35 PM, Joe Harrington wrote:
> 
> > On Mon, 28 Jan 2013 13:47:26 -0800 Nathaniel Smith <njs at pobox.com> wrote:
> > 
> >> "any size" should mean 0+. "absent" is not a size. If a function does
> >> accept an optional final dimension, can we write that like 'shape (N,
> >> D) or shape (N,)'?
> > 
> > An array dimension cannot have 0 elements (the total size is the product
> > of the shape tuple's elements).
> 
> That's not true. An array dimension certainly can have 0 elements:
> 
> >>> import numpy as np
> >>> a = np.zeros((0,))
> >>> b = np.zeros((1, 0))
> >>> c = np.zeros((1, 0, 3))
> >>> a.shape, b.shape, c.shape
> ((0,), (1, 0), (1, 0, 3))
> 
> For most applications, there is little utility in being able to
> declare an "empty" array, but you can certainly do it (and for us,
> it's handy for FiPy to partition PDE solutions across multiple
> processors without having to special-case any processors that don't
> get any solution nodes).
> 
> As we reported in http://projects.scipy.org/numpy/ticket/1171, the
> treatment of 0-length dimensions is buggy, but NumPy nonetheless
> allows for it.

I did the following test before I posted:

>>> import numpy as np
>>> a=np.array(((2,3),(3,4)))
>>> a
array([[2, 3],
       [3, 4]])
>>> a.shape
(2, 2)
>>> a.shape=(2,0,2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged

So, you can't have a 0-element dimension in an array that is not already
0-size.  I didn't think about 0-size arrays having some non-zero
dimensions.  I guess that makes mathematical sense, but then what is the
point?

Between this and your bug report, I wonder whether a 0-element array
dimension is a feature you can rely on.  Can a developer let us know if
it's an accident that it works at all?  I'll leave it to you to start a
new thread on this and get the inconsistencies resolved, since you're
the one using the feature.  The report was last touched 3 years ago...

--jh--