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 »

Josef Templ wrote:What is the ambiguity in the GO definition?
Isn't it clear what the intention is?
It comes down to the definition of ">=" or "≥", I don't care textural form is used.

With the Component Pascal definition of >=, the expression -0 >= +0 is TRUE, and the GO cases are not exclusive. To make them exclusive a new definition is required in which -0 >= +0 is FALSE. Such a definition is: missing, inconsistent with CP usage, inconsistent with IEEE 754 standard usage, confusing when used in conjunction with the standard usage, and I am totally against adopting such a definition here.
The table is incomplete
What values worry you? The pair (1.23, -4.56) is missing. Something has to be missing.
The pair (+2, -0) is missing. But the people concerned about this level of detail will be able to scale from (+1, -0).
NaNs are missing. I did this deliberately. The BlackBox coverage of NaNs is dreadful, so it is usually best to pretend they don't exist.

(I would very much like NaN coverage to be improved, but that is a different, and much bigger, issue.)
The table is very long
I think an improvement would be to use two columns, which would make it physically shorter. This would require Rulers in the Docu, something that seems to be generally avoided.
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: It comes down to the definition of ">=" or "≥", I don't care textural form is used.

With the Component Pascal definition of >=, the expression -0 >= +0 is TRUE, and the GO cases are not exclusive. To make them exclusive a new definition is required in which -0 >= +0 is FALSE. Such a definition is: missing, inconsistent with CP usage, inconsistent with IEEE 754 standard usage, confusing when used in conjunction with the standard usage, and I am totally against adopting such a definition here.
Using "≥" serves exactly that purpose. It signals to the reader that this is NOT the CP operator ">=".
If you are afraid that this is still not clear enough, which, sorry, seems a bit picky to me,
you can add a line at the beginning of the definitions explaining that
"≥" etc. here distinguish between +0 and -0.

Then you get a compact and complete table very much in line with common
practice in other languages. Also Java defines it in a similar way.

An additional advantage would be that it avoids any possible confusion
with the order of the arguments.
In your table you use x y, but ArcTan2 uses y x.
To me this is more dangerous than the >= operator.
Robert wrote:
The table is incomplete
What values worry you? The pair (1.23, -4.56) is missing. Something has to be missing.
The pair (+2, -0) is missing. But the people concerned about this level of detail will be able to scale from (+1, -0).
NaNs are missing. I did this deliberately. The BlackBox coverage of NaNs is dreadful, so it is usually best to pretend they don't exist.
Your table uses a "definition by example" approach.
This is very uncommon for mathematical functions and in my opinion not required.

I was not referring to the NaN cases. They are not specified for any other function so
they can of course be ignored for ArcTan2.

- 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:
Robert wrote:The problem with your table is that it defines only examples.
It is not complete. At the same time it is very long.
No (well almost no)! There are 4 examples which could be removed (as I originally suggested!). The other 32 lines are (to quote IEEE 754-2008) "Special values".

I included these primarily to clarify the values that are changed by this "extension" from the original Oms implementation. In retrospect that is probably an irrelevant consideration, and it is simpler to omit the entire "Post" conditions table.

These special values are listed in full in IEEE 754-2008, to which we could refer. But since the standard costs $97 such a reference would be of limited use to most readers, and we do not do this for the other functions, so I think it is best to say nothing here.

I observe that the IEEE standard defines the special values without using the "tricky" non-standard GO definition of ">=" (see section 9.2.1, pages 44 & 45). In a programmer's reference manual (the System Docu) it is far preferably to be "picky" than "tricky".

I also observe the inconsistency of Josef's stance: he wants to keep the large amount of unhelpful and irrelevant extra text in the Mod file, but objects to the relatively modest amount of extra, relevant, and helpful text in the Docu file. So be it. I can only assume he judges helpful & relevant by different criteria than me.
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:In your table you use x y, but ArcTan2 uses y x.
To me this is more dangerous than the >= operator.
I am tempted to spend the evening arguing this case.
Are you suggesting that the existing text should be changed to read
Returns the quadrant-correct principal value of the argument of the complex number iy + x in the range [-pi, pi].
I hate this x ~ y reversal (or z.re ~ z.im reversal) that dates back to the 1958 version of FORTRAN, and has been slavishly copied ever since.

But I know this is an argument I will loose, so more than enough said.
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: I also observe the inconsistency of Josef's stance: he wants to keep the large amount of unhelpful and irrelevant extra text in the Mod file, but objects to the relatively modest amount of extra, relevant, and helpful text in the Docu file.
The additional text in the Math module source is not read by normal users. It is only for developers.
The text in the Math docu is read by normal users. This makes the difference.

I was also trying to find a formulation that is nice and compact but have given up
because whatever I did it was not compact or not nice.
This is really an intricate task.

Anyway, here are some remarks that may us bring a step closer to a nice docu.
The first point is the formulation of the function's meaning:
"quadrant-correct principal value of the argument"
For me this is a very abstract scientific formulation; most simple minded users (including me!) know this as the "angle"
of the complex number. I would suggest to add this term as an alias such as:
"quadrant-correct principal value of the argument (the angle)"

The general post condition should remain, I think. This is simple and in line with the existing docu.
In addition I would add the reference to the IEEE 754-2008 standard indeed.
This saves at least the expert the time to compare all values in the table just to find
out that it is the same as everywhere.
Then comes the special cases table but with y first, i.e. same order as in the parameter list.
Non-special cases should be removed because this table lists the special cases.
Sample values +/-1 should be replaced by ranges PF and NF for positive finite and negative finite.
I would suggest to use the CP keyword INF instead of the infinity symbol.
It may be more beautiful for a mathematician but it contradicts existing conventions
used throughout the module's docu.
It's also easier for textual search, e.g. Search In Docu returns all instances of INF.
Same for pi.
There is nothing that speaks against using a ruler in the docu, as far as I know.
Don't forget to add another ruler after the table.

With these considerations the post condition would look like this:

Code: Select all

Post
-pi <= result <= pi
result follows IEEE 754-2008; special cases are listed below where
PF means the range (0, INF) and NF means the range (-INF, 0)):

  y       x         result                                   y       x         result 
−INF    −INF      − 3 pi / 4
NF      −INF        − pi
−0.     −INF        − pi
+0.     −INF          pi
...
The cases for all INF and all 0 may be reordered to keep them together.
Or should we go counter clockwise from +0. to -0.? What is the best order?
What was the old order? Was there one?
Another open detail is the notation for positive zero. Should it be 0 or +0 or 0. or +0.?
"0" is shortest and converted in CP to "+0.". "+0." is symmetric with "-0.".
"+0" and "0." are somewhere in between. I have a weak preference for "+0.".

- Josef
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 »

Side comment
Another open detail is the notation for positive zero. Should it be 0 or +0 or 0. or +0.?
"0" is shortest and converted in CP to "+0.". "+0." is symmetric with "-0.".
"+0" and "0." are somewhere in between. I have a weak preference for "+0.".
Putting a sign on 0 really only makes sense when dealing with limits.
I.e. one approaches 0 from positive values or from negative values.
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 »

DGDanforth wrote:Putting a sign on 0 really only makes sense when dealing with limits.
I.e. one approaches 0 from positive values or from negative values.
We are not talking mathematics here; we are talking about bit patterns with defined meanings in the IEEE 754 standard.

To me "+0" or "+0." refers to one pattern, "-0" or "-0." refers to the other, and "0" or "0." refers to either, or both; it is deliberately ambiguous.
I think it is possible to keep this simple, far simpler than limits, never mind one-sided limits.
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 »

Robert wrote:
DGDanforth wrote:Putting a sign on 0 really only makes sense when dealing with limits.
I.e. one approaches 0 from positive values or from negative values.
We are not talking mathematics here; we are talking about bit patterns with defined meanings in the IEEE 754 standard.

To me "+0" or "+0." refers to one pattern, "-0" or "-0." refers to the other, and "0" or "0." refers to either, or both; it is deliberately ambiguous.
I think it is possible to keep this simple, far simpler than limits, never mind one-sided limits.
Robert, yes I know. That is why I said "Side comment".
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 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!
Last edited by Robert on Tue Mar 14, 2017 10:50 pm, edited 1 time in total.
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 »

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).


PS - I will update the Docu proposal, but it may take a couple of days.
Post Reply