Issue-#151 Extending the domain of Math.ArcTan2

Merged to the master branch
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Robert »

Robert wrote:PS - I will update the Docu proposal, but it may take a couple of days.
This is where I have got to: (formatted version, not quite up to date, below)
I do not like NF for negative finite - it looks too similar to INF.

Code: Select all

PROCEDURE ArcTan2 (y, x: REAL): REAL
Returns the argument (angle) of the complex number x + iy measured anti-clockwise from the positive real axis.
All input pairs, including (0., 0.), are valid.

Post
-pi <= result <= pi
The following table lists the IEEE 754-2008 "special values" of the function:

	y	x	result	y	x	result

	-INF	-INF	-3 pi / 4	-INF	INF	-pi / 4
	neg	-INF	-pi	neg	INF	-0
	-0	-INF	-pi	-0	INF	-0
	+0	-INF	pi	+0	INF	+0
	pos	-INF	pi	pos	INF	+0
	INF	-INF	3 pi / 4	INF	INF	pi / 4

	-INF	+0	-pi / 2	-INF	-0	-pi / 2
	neg	+0	-pi / 2	neg	-0	-pi / 2
	-0	+0	-0	-0	-0	-pi
	+0	+0	+0	+0	-0	pi
	pos	+0	pi / 2	pos	-0	pi / 2
	INF	+0	pi / 2	INF	-0	pi / 2

	-INF	neg	-pi / 2	-INF	pos	-pi / 2
	-0	neg	-pi	-0	pos	-0
	+0	neg	pi	+0	pos	+0
	INF	neg	pi / 2	INF	pos	pi / 2

Key:
	+0	The zero with a positive sign bit (0)
	-0	The zero with a negative sign bit (1)
	pos	Any finite positive number	in (0 ... INF)
	neg	Any finite negative number	in (-INF ... 0)
StdCoder.Decode ..,, ..9Z....3Qw7uP5PRPPNR9Rbf9b8R79FTvMf1GomCrlAy2xhX,Cb2x
hXhC6FU1xhiZiVBhihgmRiioedhgrZcZRiXFfaqmSrtuGfa4700zdGrr8rmCLLCJuyKtYcZRiX
7.2.s,6oF.,k,5TWyql.bnayKmKKqGomC5XzET1.PuP.MHT9N9ntumaU2,CJuyKtQC98P9PP7O
NbXmb.2.oX6k2E9W.,6.cUGpmWLuOpoKqvCbHZiYpedhA704TeKKw.bHfEWUmL.6..D.,y,6.,
sUGpmWbBxhYhAbndMHT9NY6Mw.sQq2Y6cwB.0.zd,w,wa4E.2.Im0U00.bnUGLu8ro8quGrmCL
WKqtE0E.kJE.0.x6.2U.U,U.AcmBhVZBl6w1.0E65.I,AU0KyB.,UkU.USU.2.AU.U,,.2UwK.
s,kXE,8Mtr.2.m10.u,2.A.ME.M.6YE.O.YB2.EJKr8GJYPU0CyIVGhighgmRiiQeodIf9PYcZ
RiX3Ul1UnpZGhighA70,cw5.,6.wSw.QO2U.sU.ktumdsIdPSNPN7ONbH.4D.o3aLq.,cwD.0.
E2E3V.E,,.RNEd1.6.G.0..6J6.36.6.6MtxKE.mGi5U.5JWMP9U1U46ExP,0uRrU.xiPEtjWU
xZokp5Y,U,.6.,.M.E.o6AUKU.Ar,.,.J,Etv.2.U5UZ,,k,9T66.,.E2kZ6.0.3gwZ.0..242
U,2.2.2gw00EK..k,2wjJ,,TCbE.vSPUuWz5eGxd1hc2heGhcUAcmRgIBgiJaU2ZtZZU2ju2YG
hc,ZddIbUIe3l48pmGru8LrCLEGLoKKE4KtSquqqm66FNMRvNNPNH76TfN,7RFPNCqrqKsmqmW
LEuquqKlKKt0Gw0mJ0moaLEqqm4qtKLtKKm0mkuKuaqKCKqyqliqvaqtKKEOKtyqq0GuWqm2ij
RidZidpiZ3YmhgVZhUAgsBhnpZBAcgZhUAhi3ipZiU2iVBhmRig2YdphXZhpZgdphb3Yc2aiYZ
U2aiAZg2YVJiZ3YqBggBhYpZBgVExhnZiBIUI3BOqrmKqyqvaKrSKEGrk8KqKKEmqoCLuCLEGL
oMG9OF9863tQVPN5PO19P,dR19PfPNbf6,tPB96EnKLrCKuaqruKRqk4akwaEwaEtKqtKLqGr2
ar2W5UBgV7gZ7pd4BVhAdCVn2YkBhUwZUYa7gZ7p7aIbOYh2id3Yjk4aErKqnakKaIb.HcP9X7
pd4FMqk2qGMakKa22CqGMAdCp601L7AHM9H0VPOHs8VlYu2L7APM0VvPbP0PNG6Q2ijlYu2L,H
eHBmKa2CHE05M0HeHA72C,,PM1q0Q3HM9VPO,VmAVhA7gZkAVh2Ck4aErK4L7AH.k2uqmSah2a
7.M1qGMQZkA,VN0P7AUkN1Hs8VlJ01UhEsaq42ijlJ0XkBhUU72ijRCP7A.qU7p7i0.HMGRWh.
k4qk2q0ohZVkBhUU7g36QT1V1gV7g3uqmS4AVhEsyqt6AP.uqm6QHP0LVkxBiWBEbcPUUU7AdC
FsEsa4gVBIU9hgtJbBAVf24d8O996pPNZvP,tRH9RF96196VvP.CroSKr0GlaKu0GI0nIqk2qG
MYec,.ErKqn4KuaKv..4nIqk2054IraLEOqouqoGrm0Gs.cPfPPM0HfP,78V76Rd9R76HeHBO8
PM0RPNAci,YCuqm...qmYuIX0GLuGLgZkAZBgV0CyIhACoruKu8rrmKqKKtCLLCZYRcoJigZcZ
RiX3Ul1.UiQcjpho,Y62.5011.85...CLL.U2V.IS2U.UI6.0.aE.0.,..1cUu.0E.MM2U5UNV
.2.520E..2,wb.U.E,,0..Y22U,2.,E.Ek.0EKA..U.6.IEP.0..o10U.U,.10.,U.2m,.,.E4
WDN.Ntarmx5MqIklb6MNQC5uP..g06..E2E.U76.2kLRCNN65J.nT32kwL,,sKFHKHGA,FX1..
.
--- end of encoding ---
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Josef Templ »

Robert wrote:
Josef Templ wrote:The first point is the formulation of the function's meaning:
"quadrant-correct principal value of the argument"
I thought I would look this up, as I vaguely thought that it was a commonly used expression in this context. (I agree it sounds quite pretentious, and isn't even correct here as ArcTan2 allows both +Pi & -Pi.).
The first site I checked was Wolfram (http://functions.wolfram.com/Elementary ... s/ArcTan2/).
Wow!
Spot the argument order: x, y.
And I thought that for the last 15+ years I was the only person on the planet who considered the y, x order as crazy!
In all general purpose languages I have looked up there is the parameter order (y, x).
This is very common and it is not possible (and not needed) to change that, I believe.

The docu looks good to me now.

- Josef
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Josef Templ »

Sorry for disturbing again.
Just made some experiments with the table order
and noticed that it would be easy to cut the table size
by a factor of two, i.e. a single column would be sufficient.
The table below is sorted by result and it is really easy to see the symmetry
within the table this way (sign of result changes with sign of y, x remains the same).
Equal results are sorted by y.
The table size is reduced by enumerating all x values with equal results
in the x column. 0 is used for +0, -0 for shorter enumeration lists,
this is a matter of taste.

Code: Select all

	   y   	x	  result  
	+0	+0, pos, INF	+0
	pos	INF	+0
	INF	INF	pi / 4
	pos	0	pi / 2
	INF	neg, 0, pos	pi / 2
	INF	-INF	3 pi / 4
	+0	-INF, neg, -0	pi
	pos	-INF	pi
	neg	-INF	-pi
	-0	-INF, neg, -0	-pi
	-INF	-INF	-3 pi / 4
	-INF	neg, 0, pos	-pi / 2
	neg	0	-pi / 2
	-INF	INF	-pi / 4
	neg	INF	-0
	-0	+0, pos, INF	-0	
Here is the encoded text:

StdCoder.Decode ..,, ..8Q....3QwdONl9RhOO9vRbf9b8R7fJHPNGomCrlAyIhgs,CbKBhZ
xi2,CoruKu4qouqm8rtuGfa4.hOO9vRb1Y66wb8RTfQ9vQRtIdvPZHWKqtCa.E.U5ULq.6.5Qw
dONlnayKmKKqCLLCJuGqayKm6F9vQ5nsH3.bnayKmKa2,Cor.kay4.qorGqmQCU2,CJuyKtQC9
8P9PP7ONbXmb.2.Aw2k5kgH.,6.EQ9.86.QC18RdfQHfMf9R9vQ7ONb1E.ENE.0.x.0.4.AcmB
hVZBl6w1.0E65.2.c8fP3d8mBE,5TeEdKLqKKtCLLCJuIepZBGomCrl0ksH3.bf9ZORNPNG20E
tD.0E.6rs,so6.,k,,UnpZHldGrwmqmGomCb.AS.c9Ajg,0EtX.0.U6U80,U00.umUG5.E.Y.2
..EeE.8.2.2gwS96.N7r1EUX8Fgh3k,E12cyh.,iSVEUbuCcwLFkyGOsu1m.k..2U..A.6.1cU
Zj0E.s86.,US.,.16.ME.M.6YE.4.8E,9T3U.kOE.0.x.0.4.A6.Q.2GE8k.4.AHQU0Ky8.,Us
U.UO.,.16.2Ue2Uwpr,.,6YU,.D2,6.EJK5Etj.2.U5UZ,,k,9z46.0.E2kZE.0.3gwT.0..24
2U,.,.,9jU.Y3..QU.2wjJ,,TCbE.vSPUSXzLU72YU2Yt3YU2Y72j72YUIiZRipZho3YUgV7QZ
kAVf2ag2YkxhnZZUAdCpc7QZkgV72ijRi7AdCpc7.HeHBmYuIX2id3Yj2YogV72C2a72id328n
4akYu2RPND99,7AN76VX72id32.gZ7pd4tA,7QH96TFOs8gZ7p7N76RPND99qGMaEsgV72ijlK
aIbAVkN1uqmSq2qmYkK0roqUh2a7gZ7FK.kK0rokYuY7MGkN0Gs.gZ7ViFK24.VPO,VmErKa72
a7g3.qmYkYkK05Y4uqmMGR0VN1HM9VlJ0169.ak4qE,iomaLRqk2iGMYechgUIjZJij3YrBho3
hUAgU2ijRidZidpiZ3YnBhbphUIgdZiU2ZkAZBA,VFeW4..RPNDPMdPOh1.MAHN1H6AHME,dS9
1.RPS,tQH1Uk2YjJiUAadg,V11ePn96BPORPOdPN,7QT1ErKrq8qm8LEohU2Zk2YioZi2Y7pd4
BZBAViV,pBUoFrK4..kKaIbOIEuGLuWh2adgV0CyIhACoruKu8rrmKqKKtCLLCZYRcoJigZcZR
iX3Ul1.UiQcjpho,Y62.5011.85...CLL.U2V.IS2U.UIU.U72U.E..k.8c9U.2.44S.a30E.Q
EU..2,w52U.E,,0..Y22U,2.,E.EECOhE.0Eyuv.wnjl.k.E.0.3I3U...p.0.4.IZ..,U.2m,
.,..j2,...
--- end of encoding ---

- Josef
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Robert »

Well why stop there ...

Code: Select all

PROCEDURE ArcTan2 (y, x: REAL): REAL
Returns the argument (angle) of the complex number x + iy measured anti-clockwise from the positive real axis.
All input pairs, including (0., 0.), are valid.

Post
-pi <= result <= pi
The following table lists the IEEE 754-2008 "special values" of the function:

       y           x          result  

      ±0       +0, pos, INF     ±0
     ±pos         INF           ±0

     ±INF         INF         ±pi / 4

     ±pos          0          ±pi / 2
     ±INF     neg, 0, pos     ±pi / 2

     ±INF        -INF        ±3 pi / 4

      ±0     -INF, neg, -0     ±pi
     ±pos         -INF         ±pi

Key:
     +0            The zero with a positive sign bit (0)
     -0            The zero with a negative sign bit (1)
      0            A zero with any sign bit (0 or 1)
     pos, +pos     Any finite positive number in (0 ... INF)
     neg, -pos     Any finite negative number in (-INF ... 0)
     ±             + or -, but both occurrances in a line are the same.
(The "code" above uses spaces to make it look roughly right; it is my intention to use rulers & tabs in the Docu.)
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Robert »

Robert wrote:2 - I have not tried to align the alternative code. Testing for -0, using only high level constructs, requires some expression such as

Code: Select all

xIsNegZero := 1. / x = -INF
By the time you have checked for all possibilities the code would be a monster.
Actually the code "xIsNegZero := 1. / x = -INF" is not really satisfactory. It sets the FPU "Divide by zero exception" flag, which is not set by FATAN, so is not an equivalent alternative.
One could probably access the sign bit using SYSTEM.VAL, but that is not exactly a "high level construct".

It seems that one needs something like one of the IEEE 754 mandated procedures isSignMinus (section 5.7.2) or copySign (section 5.5.1).
Possible implementations might be:

Code: Select all

	PROCEDURE IsSignMinus* (x: REAL): BOOLEAN;
	VAR
		s: SET; (* "isSignMinus" function, section 5.7.2  *)
	BEGIN
		FLD(x); FXAM; WAIT; s := FSWs(); FSTPst0; RETURN  9 IN s
	END IsSignMinus;

	PROCEDURE CopySign* (x, y: REAL): REAL;
	BEGIN (* "copySign" function, section 5.5.1  *)
		FLD(x); FXAM; WAIT;
		IF 9 IN  FSWs() THEN FSTPst0; RETURN -ABS (y) ELSE FSTPst0; RETURN ABS (y) END
	END CopySign;
but I'm not sure CopySign is correct for non-canonical representations.
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Robert »

Robert wrote:If you look at the proposed new code for ArcTan2 relative to ArcTan an obvious difference is the WAIT instruction.

With the removal of the ASSERTs I suspect that ArcTan2 cannot cause any unmasked exceptions, so the WAIT is now unnecessary. What do other people think?
(Leaving it in, even if unnecessary, causes very little harm).
Josef - do you have an opinion on this?
User avatar
DGDanforth
Posts: 1061
Joined: Tue Sep 17, 2013 1:16 am
Location: Palo Alto, California, USA
Contact:

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by DGDanforth »

The code
+0, pos, INF
is equivalent to pos
when you change the definition of pos to
pos Any finite positive number in [+0 ... INF]
which is then parallel to the definition of neg
neg Any finite negative number in [-INF ... -0]
Then
-INF, neg, -0
is equivalent to neg.
Also
neg, 0, pos
can be called "any" and
its definition given as
any Any finite number in [-INF ... +INF]
I have changed the bounds from exclusive "()" to inclusive "[]"

By making those small changes the column for x can be
reduced to a single word for each y.
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Josef Templ »

Robert wrote:
Robert wrote:If you look at the proposed new code for ArcTan2 relative to ArcTan an obvious difference is the WAIT instruction.

With the removal of the ASSERTs I suspect that ArcTan2 cannot cause any unmasked exceptions, so the WAIT is now unnecessary. What do other people think?
(Leaving it in, even if unnecessary, causes very little harm).
Josef - do you have an opinion on this?
Don't know exactly, I am not a WAITer:-)

Well, seriously, I would leave it in unless it is 100% sure that it is not required.
The ASSERT, I think is not related with the WAIT because ASSERT is not
dealing with floating point exceptions.
Only FPU instructions generate floating point exceptions, as far as I know.
The question is what happens with NaN, for example.
Doesn't it raise an unmasked FPU exception?
The WAIT probably doesn't use any extra cycles on modern CPUs.

- Josef
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Josef Templ »

DGDanforth wrote: I have changed the bounds from exclusive "()" to inclusive "[]"

By making those small changes the column for x can be
reduced to a single word for each y.
Doug, are you sure that this is correct for all cases?
This must be checked carefully.
My impression was that it does not work.
Can you show the complete table?

- Josef
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: Issue-#151 Extending the domain of Math.ArcTan2

Post by Robert »

Josef Templ wrote:The question is what happens with NaN, for example.
Doesn't it raise an unmasked FPU exception?
I tried (NaN, 0.3), (0.3, NaN), & (NaN, NaN). No exceptions raised at all.

The NaN I used was non-signalling.

I suspect the WAIT is unnecessary, but I will leave it in (for now). It is hard to image what exception ArcTan2 might occur that ArcTan would not.
Post Reply