[SciPy-dev] Numpy example for arctan2 perhaps wrong/misleading/confusing?

[Samuel John]

Hi David!

On Mon, Jun 9, 2008 at 3:56 PM, David Huard <david.huard at gmail.com> wrote:
> One thing that you should know is that all "ufunc" (universal functions) are
> defined as functions operating on scalars. Numpy then wraps these functions
> such that they can process ndarrays of any shape element by element. This is
> what is explained in the help(arctan2) documentation.

I see the point for arctan and other functions with a single argument, but not
for arctan2, especially. It needs two arguments and if I want to
compute the result of the vectors a=array([a1,a2]) and b=array([b1,b2]) like

arctan2(a,b)

what I get is are the two results as if I would have written:

array([ artcan2(a1,b1), arctan2(a2,b2) ])  #Note, this is NOT (a1,a2)
or (b1,b2) !!

If you know this and distribute your vector entries over two arrays, the
broadcasting may be very useful. (As it is for many other functions!)

It would be perhaps nice to call arctan2 with just ONE array argument
and have a broadcasting like this:
 arctan2( array([[a1,a2],[b1,b2],[c1,c2]]) )
 --> array([arctan2(a1,a2), arctan2(b1,b2), arctan2(c1,c2) ] )

and arctan2( array([x,y]) ) --> arctan2(x,y)

> As for the example, maybe a way to avoid confusion would be to give an
> example with scalar arguments first to show the basic behavior, and then an
> example using ndarray broadcasting.

I would argue to show just the scalar version in the example and leave out
the broadcasting version, because it makes less sense here, doesn't it?
Is there any fancy matrix-or-whatever notation, that really makes up a
good example for broadcasting with arctan2?

cheers,
 Samuel

PS: I am not against the current broadcasting scheme. It is perfectly ok.