[Bug libfortran/49336] New: ATAN2 values differ from those specified in documentation

[Bug libfortran/49336] New: ATAN2 values differ from those specified in documentation

[ahn567 at gmail dot com]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=49336

           Summary: ATAN2  values differ from those specified in
                    documentation
           Product: gcc
           Version: unknown
            Status: UNCONFIRMED
          Severity: minor
          Priority: P3
         Component: libfortran
        AssignedTo: unassigned@gcc.gnu.org
        ReportedBy: ahn567@gmail.com


The documentation for ATAN2(Y,X) says:  

"If Y is zero, then the return value is zero if X is positive and pi if X is
negative."

However, the value returned by  ATAN2(-0d0, -1d0)  is  -pi  (not +pi).
This is for gfortran 4.4.5.

So either the documentation needs fixing (and signed zero explained), 
or the function ATAN2 should be redefined to return values in (-pi,pi]. 

...I'm not sure which is more standard for Fortran.

[Bug libfortran/49336] ATAN2 values differ from those specified in documentation

[kargl at gcc dot gnu.org]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=49336

kargl at gcc dot gnu.org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |kargl at gcc dot gnu.org

--- Comment #1 from kargl at gcc dot gnu.org 2011-06-09 02:44:07 UTC ---
The documentation is correct for a Fortran 95 compiler.  Try
adding -std=f95 to your command line.

gfortran implements most of the Fortran 2003 and some Fortran
2008 features.  With F2003, one finds in Sec. 1.6.1.

   If the processor can distinguish between positive and negative
   real zero, this standard requires different returned values for
   ATAN2(Y,X) when X < 0 and Y is negative real zero and for LOG(X)
   and SQRT(X) when X is complex with REAL(X) < 0 and negative zero
   imaginary part.

If you want to be hero, you are more than welcomed to submit a 
patch.  F2003 says the results are

   If Y = 0 and X > 0, the result is Y.  If Y = 0 and X < 0, then
   the result is pi if Y is positive real zero or the processor
   cannot distinguish between positive and negative real zero, and
   −pi if Y is negative real zero.

[Bug libfortran/49336] ATAN2 values differ from those specified in documentation

[burnus at gcc dot gnu.org]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=49336

Tobias Burnus <burnus at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |documentation
                 CC|                            |burnus at gcc dot gnu.org

--- Comment #2 from Tobias Burnus <burnus at gcc dot gnu.org> 2011-06-09 06:04:41 UTC ---
(In reply to comment #0)
> the value returned by  ATAN2(-0d0, -1d0)  is  -pi  (not +pi).

The result matches POSIX:
       If y is ±0 and x is < 0, ±pi shall be returned.
       If y is ±0 and x is > 0, ±0 shall be returned.

Thus, from POSIX I would expect the result one obtains with gfortran.

Looking at IEEE 754:2008, one finds (9.2.1 Special values):
"atan2 (y, x) [...] atan2(±0, x) is ±π for x < 0"

>From the Steve's quote of the Fortran 2003 standard (comment 1) one sees that
gfortran's result is also in line with Fortran 2003.


> The documentation for ATAN2(Y,X) says:
> "If Y is zero, then the return value is zero if X is positive and pi if X is
> negative."

We should indeed update http://gcc.gnu.org/onlinedocs/gfortran/ATAN2.html -
thus, I have marked it now as documentation bug.


ahn567: Do you rely on atan (+/-0, x< 0) returning PI instead of -PI? If it is
really needed, on could add a special handling for -fno-signed-zeros. However,
that would be slower - and other compilers also follow IEEE/POSIX/F2003 - even
if they do not print signed zeros by default. Hence, I would prefer to just
update the gfortran documentation.

[Bug libfortran/49336] ATAN2 values differ from those specified in documentation

[ahn567 at gmail dot com]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=49336

--- Comment #3 from ahn567 at gmail dot com 2011-06-10 00:33:41 UTC ---
(In reply to comment #2)

> ahn567: Do you rely on atan (+/-0, x< 0) returning PI instead of -PI? If it is
> really needed, on could add a special handling for -fno-signed-zeros. However,
> that would be slower - and other compilers also follow IEEE/POSIX/F2003 - even
> if they do not print signed zeros by default. Hence, I would prefer to just
> update the gfortran documentation.

No, I do not rely on this. I was just surprised that the following program
would ever output "T F"

program main
double precision :: y1, y2
y1 = +0d0
y2 = -0d0
write(*,*) y1==y2, atan2(y1,-1d0)==atan2(y2,-1d0)
end program

The output is "T F" for both of these compilation commands,
gfortran prog.f90
gfortran -std=f95 prog.f90

Apparently this is correct standard Fortran behaviour, eg. according to 
ISO/IEC JTC 1/SC 22/WG 5/N1826. 

I had not come across signed zero before. For anyone interested... 
http://en.wikipedia.org/wiki/Signed_zero 

Updating the gfortran documentation would seem to be the proper thing to do
eg., as per page 331 of the above standard. (The docs for SQRT, SIGN, LOG,...
might also need checking.)

[Bug libfortran/49336] ATAN2 values differ from those specified in documentation

[fxcoudert at gcc dot gnu.org]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=49336

Francois-Xavier Coudert <fxcoudert at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |RESOLVED
                 CC|                            |fxcoudert at gcc dot
                   |                            |gnu.org
         Resolution|                            |FIXED
   Target Milestone|---                         |4.7.0

--- Comment #5 from Francois-Xavier Coudert <fxcoudert at gcc dot gnu.org> 2011-11-07 22:24:25 UTC ---
Fixed on trunk.

[Bug libfortran/49336] ATAN2 values differ from those specified in documentation

[fxcoudert at gcc dot gnu.org]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=49336

--- Comment #4 from Francois-Xavier Coudert <fxcoudert at gcc dot gnu.org> 2011-11-07 22:22:02 UTC ---
Author: fxcoudert
Date: Mon Nov  7 22:21:54 2011
New Revision: 181127

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=181127
Log:
    PR libfortran/49188
    PR libfortran/49336
    * invoke.texi: Fix documentation of fsign-zero option. Remove
    contractions.
    * intrinsic.texi: Fix ATAN2 documentation for signed zeros.
    Remove contractions.
    * gfortran.texi: Remove contractions.

Modified:
    trunk/gcc/fortran/ChangeLog
    trunk/gcc/fortran/gfortran.texi
    trunk/gcc/fortran/intrinsic.texi
    trunk/gcc/fortran/invoke.texi