**Purpose:** Help on the math function 'atan2'.

The call

[expr {atan2($y, $x)}]

returns the inverse tangent (expressed in radians) of the quantity,

($y / $x)

It never divides by zero, and is careful about the quadrant of the result (which conventional *atan()* can't be, since the division prior to feeding the quotient into *atan()* would lose information about which, if any, of *$x* and *$y* are negative. In practice, this doubles the range of the result.)

RS notes (testing functional imaging): Contrary to the above claim, on Sun computers the call atan2(0,0) raises the error:

% expr atan2(0,0) domain error: argument not in valid range

Fix: check that at least one coordinate is non-zero:

proc toPolars p { foreach {x y} $p break # for Sun, we have to make sure atan2 gets no two 0's list [expr {hypot($x,$y)}] [expr {$x||$y? atan2($y,$x): 0}] }

Arjen Markus I tested this feature in a small C program on an HPUX and a SGI machine with native compilers. The results were quite similar:

- HPUX reports a Nan and errno = 0
- SGI reports a value 0.0 and a Domain error.

Tcl 8.3.1 on SGI responds with a domain error as well, so that is quite consistent!

AMG: GNU (glibc) atan2() is defined [L1 ] to return 0 when both arguments are 0.

The most common use of atan2 is in Converting between rectangular and polar co-ordinates.

atan2 is also available as a command in Tclx.

AM (28 april 2008) Interesting feature:

- atan2(y,x) will give the
*mathematical*angle, that is, the angle with the positive x axis, oriented counter-clockwise - atan2(x,y) (so the arguments in just the opposite order) will give the
*nautical*angle, that is, the angle with the positive y-axis, oriented clockwise (or if you like: the angle on the compass)

AMG: When dealing with maps and geospatial data, I greatly prefer to orient north along the positive X axis and east along the positive Y axis. This way atan2(y,x) gives me a compass heading. Well, atan2(y,x)*180/acos(-1) does. :^) I am told this is standard GIS convention.

GWM (28 april 2008) note that Excel uses the reverse convention from C, Fortran, Tcl (and probably most other languages),

atan2(0,1) = 0; atan2(1,0) = 1.570796 etc.

Have all other spreadsheets been infected by Excel? Does SLK insist on Excel ordered atan2? Take care when translating a formula that works in Excel to other languages (and vice versa).

AMG: OpenOffice.org Calc uses the same backwards convention. Sigh. It stinks when the *de facto* standard is exactly backwards from the *de jure* standard. (Maybe I should say "*du jour* standard", hehehe.)

RS 2015-11-26 I see the same behavior, so what is "backwards"?:

$ tclsh % info pa 8.5.9 % expr atan2(1,0) 1.5707963267948966 % expr atan2(0,1) 0.0

But while we're at it, the Tcl manpage *mathfunc* has a bug there:

**atan** *arg*

Returns the arc tangent of arg, in the range -pi/2,pi/2 radians.

**atan2** *y x*

Returns the arc tangent of y/x, in the range -pi,pi radians. x and y cannot both be 0. If x is greater than 0, this is equivalent to “atan expr {y/x}”.

...

To be equivalent (which I tested), the range of atan2 is equally -pi/2...pi/2.

DKF: Tcl just uses the same convention as C, because it uses the same function.

AMG: Which explains why it accepts two arguments.