J3/02-228r1

Date:     28 July 2002
To:       J3
From:     Dan Nagle
Subject:  Atan2 & Log

In comp.lang.fortran, James Giles complained that the specified
return values for atan2 & log were wrong.  There was no subsequent
discussion on the mailing list to clarify the issue.  So I
guess everybody's happy with Giles' words.  The edits
below use Giles' words from his comp.lang.fortran posting.

Van commented:
<VAN>
I'm not happy with Giles's words.  The sentence "It lies in the range
-pi <= ATAN2(Y,X) <= pi and is equal to a processor dependent approximation
to a value of arctan(y/x) if X /= 0" is confusing.  (1)  Does the "X /= 0"
part apply to the entire remainder of the sentence?  Later text suggests
the "X /= 0" part applies only to the second phrase, i.e., ATAN2(Y,0) is
+pi/2 or -pi/2, which is within the range specified.  (2) Why "approximation
to _a_ value" not "approximation to _the_ value?"

What's with the absolute value stuff in the "If Y = 0..." sentence?  The
previous sentence appears to say the sign of the result depends only on
the sign of Y.  I suppose it's conceivable that ATAN2(-0,ABS(X)) should
produce -0 for the answer, while ATAN2(+0,X) should produce +0 for the
answer.  But does it produce -pi for ATAN2(-0,-ABS(X))?  The "If Y is
positive..." and "If Y is negative..." sentences don't cover the cases
of signed zeroes.  It may be better to use the same double-negative
construction as in 02-227 (modulo my objections thereto).

What are ATAN2(0,0), ATAN2(-0,0), ATAN2(0,-0) and ATAN2(-0,-0)?
</VAN>

The following edits attempt to respond to Van's ideas
to polish James Giles' original porposed edits.

Edits:

301:24-29 Replace the result value paragraph with the following:
"The result has a value equal to a processor-dependent
approximation to the principal value of the argument
of the complex number (X, Y), expressed in radians.
It lies in the range -pi <= ATAN2(Y,X) <= pi, and if X /= 0
is equal to a processor-dependent approximation to the value
of arctan(Y/X).  If Y is positive, the result is positive.
If Y is negative, the result is negative.  If Y = 0,
the result is zero if X is positive
and the absolute value of the result is pi if X is negative.
If X = 0, the absolute value of the result is pi/2."

324:13-16 Replace the result value paragraph with the following:
"The result has a value equal to a processor-dependent
approximation to LOG(X).  A result of type complex is the
principal value with the real part equal to LOG(ABS(X)) and
the imaginary part equal to ATAN2( AIMAG(x), REAL(x))."