3

Playing with the NumPy concatenation and range building object r_ I stumbled over the following behavior: apparently, a complex step no matter whether real, imaginary or proper complex has its absolute value taken as the number of steps in a linspace like way.

>>> import numpy as np
>>> 
>>> np.r_[0:12:4]           # start : stop : step
array([0, 4, 8])            # that's expected
>>> np.r_[0:12:4j]          # start : stop : imaginary step
array([ 0.,  4.,  8., 12.]) # that's in the docs
>>> np.r_[0:12:4+0j]        # real step of complex type ?
array([ 0.,  4.,  8., 12.]) # this is not as far as I can tell
# you can even do stuff like
>>> np.r_[0:12:-4+3j]        # proper complex step ?
array([ 0.,  3.,  6.,  9., 12.])

Question: I just wanted to know whether that's an official feature, because I couldn't find it documented.

Why is it relevant? Well, r_ primarily being a keystroke saving convenience there are a few cases where this feature could save you a few characters.

smci
  • 32,567
  • 20
  • 113
  • 146
Paul Panzer
  • 51,835
  • 3
  • 54
  • 99
  • 1
    Here is the source code for this: https://github.com/numpy/numpy/blob/22d917776b80dc7cef683fc17f4ea15b1ce98fcc/numpy/lib/index_tricks.py#L279 – HYRY Feb 23 '18 at 03:38
  • Is this in the docs for an ordinary numpy slice? I was surprised by code like `np.mgrid[xmin:xmax:5j, ymin:ymax:5j]`. Oh, it's a [feature of the command](https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.mgrid.html). – Josiah Yoder Aug 13 '18 at 16:46

1 Answers1

4

The code does take the absolute value:

if isinstance(step, complex):
    size.append(int(abs(step)))

but this is not a documented guarantee. The docs only guarantee behavior for imaginary numbers, not arbitrary complex numbers:

if step is an imaginary number (i.e. 100j) then its integer portion is interpreted as a number-of-points desired and the start and stop are inclusive

You should not rely on the behavior for not-purely-imaginary complex inputs, as it is not a documented guarantee.

That said, it is possible that it was intended to be a guarantee. The furthest back I've been able to trace numpy.r_'s code is this commit. (That's not where it originated - I can find references to scipy.r_ dating back even further - but despite finding references to scipy.r_, I have not been able to locate the code for scipy.r_, and I suspect neither the SciPy nor NumPy GitHub repositories contain the original code. It seems like this would be the right commit, except that GitHub seems to only have a fragment of the original non-Git commit.)

r_ was not documented in the earliest commit I can trace it to, but mgrid was also present in that commit, and mgrid's similar behavior for complex numbers was documented in that commit as

However, if the step length is a COMPLEX NUMBER (e.g. 5j), then the integer
part of it's magnitude is interpreted as specifying the number of points to
create between the start and stop values, where the stop value
IS INCLUSIVE.

The furthest I've been able to trace numpy.r_'s documentation is this commit 7 years later, labelled "Merge from doc wiki". I believe the doc wiki is now gone, and I have been unable to determine who originally contributed those docs, but it seems likely that those docs were not based on the original intent of numpy.r_'s author.

user2357112
  • 260,549
  • 28
  • 431
  • 505
  • Hm, I'm not 100% convinced by that. If the code assumes "correct" input using `abs` strikes me as both wasteful and totally nonobvious. Why not simply `.imag`? – Paul Panzer Feb 23 '18 at 03:44
  • Unless we can find developers' discussions (bug/issue, push, lists), we can only infer intentions, especially when the documentation and code don't exactly mesh. Here, for example, one developer might have used `.imag`, and and other might have decided the `int(abs(...))` approach was more general. – hpaulj Feb 23 '18 at 03:51
  • 1
    @PaulPanzer: I dug into the history some more. It looks like it may have originally been specifically intended to take the magnitude, but it appears not to have been documented until much later, probably by someone else; the documentation appears to originate from a documentation wiki that seems to no longer exist. – user2357112 Feb 23 '18 at 03:53