RE: Transcendental function tables: comments welcome!

["Eric Postpischil" <stds-754+ieee.org@xxxxxxx>]

Here is my response to David James' original post in this thread.  Many
comments have passed by since then.  I apologize for any repeats, but this
is the first opportunity I have had to sit down with his document.

These comments address David James' tables document for the transcendental
functions, but not whether I prefer it over the text version.  By and large,
I favor the text version.  (The latest text version I have seen is that in
Draft 1.3.0, which is the latest in PDF form in
http://754r.ucbtest.org/drafts/.  There seemed to be a later document with
extension .odt, but I have not examined that yet.)

                                -- edp (Eric Postpischil)
                                http://edp.org

"The sweetest of all things is knowledge." -- Aristotle



General.

The inexact exception is not mentioned.  Here, I will not get into what it
should say, but it should say something.

Some of the statements of the text draft are missing, such as:

        All the directives in this annex are optional.

        ... conformance is attained for each function individually.

        Implementations should provide correct rounding versions of as many
        of these functions as permits efficient implementation...

        An implementation may choose to implement functions not listed here...


D.2.1.

This says, "Should be provided for each support non-storage binary format."
In general, it is unclear to speak of the floating-point format of a
function, since there may be several different formats associated with a
function, in its inputs and outputs.  Two of the following sentences
explicitly specify the formats of the operand and the result.  That seems
sufficient to me.  So if the text I quoted above adds nothing, it could be
removed.  Alternatively, since these functions have homogeneous formats in
their inputs and outputs, we might define the format of these functions to
be the format of their inputs and outputs, and then keep the function
sentence (actually sentence fragment) and delete the operand and result
sentences.

The text "Might signal exceptions (see text below)" can mean too many
things.  It could mean the function might signal because you might pass it
something with an underflowed result, but it might not because you might
pass it something with a non-underflowed result.  It could mean the function
might signal underflow because the implementor is allowed but not required
to signal underflow when the answer is underflowed.  It could mean the
function might signal underflow because the implementor is allowed to signal
underflow even when the answer does not underflow.  The "text below" does
not help me distinguish these possibilities; the notes also say "Might".  I
suggest changing things like "Might signal underflow" to "Signals underflow
when the result underflows."

The description (beginning "This group of...") seems somewhat wordy and
indirect to me.  Also, note that it says "group... involves a
transformation."  To be precise, that is incorrect; there are several
transformations in the group; each operation performs a different function.
Rather than:

        This group of transcendental functions involves a transformation
        on a single operand to produce an infinitely precise intermediate
        value, as specified by Table D.1.  The rounding operation (see
        Table xx) is dependent on the prevailing rounding-direction mode.

how about:

        Each of these operations produces a result as if the corresponding
        function in Table D.1 were calculated with unbounded range and
        precision and then rounded to the destination format.

One of the properties says, "If supported, shall be performed as specified."
If this is not a tautology, it is close.  I think it is trying to capture
the earlier draft's flexibility, which allowed an implementation to support
or not support each function individually.  I suggestion removing this
statement and "Should be provided for each support non-storage binary
format" and adding one statement for all of this annex saying that each
implementation may support or not support each function with each format
individually.


D.2.2.

Same comments as D.2.1.  In addition, I see no difference between D.2.1 and
D.2.2, except that D.2.1 refers to Table D.1 and D.2.2 refers to Table D.2
and Table D.3.  So I do not see why they are not just one section that
refers to all three tables.


Table D.1, Table D.2, and Table D.3 (and other tables).

I prefer to say "x < +infinity" rather than "x < +huge".  Infinity is well
known, and there is no definition of "huge" here.  Later, Table D.6 defines
"huge" as the largest finite representable number.  With that definition, "x
< +huge" is wrong; it should be "x <= +huge".  However, there is no need for
"huge"; "x < +infinity" serves well and makes it clear there is no gap
between the infininty column and the less-than-infinity column.

Similarly, "nit" is used but not defined here but is defined in Table D.6,
and there is the same error; "nit < x" is wrong; it should be "nit <= x".
As with "huge", "nit" is unnecessary, since "0 < x < +1" serves as well or
better than "nit <= x < +1".

Some of the columns have joined cells (no separating lines) showing a single
value for several rows, but some have separated sells with the same value
repeated.  For example, under "+/-qNaN" for the log and exponent functions,
"+/-x" appears once, but under "+infinity", "+infinity" is repeated.

One of the columns is labeled "CRD" without explanation.

Since the correctly rounded domain for each function is the entire domain
for which it returns any numerical result (that is, the entire domain for
which the mathematical function is defined), there is no point in listing
it.  The annex can simply say that each (supported) function must be
correctly rounded, period.

Notes for Table D.2 and Table D.3 define "n" as "Any nonzero positive
integer."  "Nonzero" is redundant (+0 notwithstanding).

In Table D.3, "cos" appears twice in roman where it should be italic.

Some of the notes say "Might signal an underflow exception" or the same
thing for other exceptions and combinations of exceptions.  These need to be
made perfectly clear, stating whether the determination is made by the
mathematical properties of the function, the choice of the implementation,
or both.

Tables D.2 and D.3 contain a note marked "*" saying "Signals an invalid
exception", but none of the entries are marked with "*".


D.2.3 and D.2.4.

These sections do not contain the "If supported, shall be performed as
specified" that appeared in earlier sections.

As with D.2.1 and D.2.2, I do not see why these are not merged with those,
except that D.2.4 discusses a function with two operands.

D.2.4 only mentions the format of operand x and says nothing about y's
format.

In "The atan2 transcendental functions involves", "functions" should be
"function".  Also, "transcendental" is redundant.


Table D.4.

"acos" appears in italic where it should be roman, and "acosh" appears in
roman where it should be italic.

The definitions of P1 and P2 use different terminology for the same thing
("with roundTowardsZero" and "rounded towards zero").


Table D.6.

Unlike previous tables, which label columns with things such as "x < huge",
this one labels columns with "+huge >= atan2(|x|, y) >= +P1" -- the
criterion is on the function result, rather than its operand.  There are
some problems here.  First, does this "atan2" mean the mathematical function
or the computational operation?  It is in roman, not italic, which suggests
the operation.  But then we need to know the result of the operation before
we can identify which table column tells us the result of the operation.
And sometimes the result, and which column to use, will depend on the
rounding mode.

My first thought was that "atan2" in the column headers referred to the
mathematical function.  But then some cases are not specified -- what
happens when atan2(|x|, y) is finite and greater than huge or positive and
less than nit?  So much for tables exposing missing cases -- all the table
cells are filled in, yet the specification is incomplete.  (The former
occurs only in degenerate formats, but the latter occurs when x is small and
y is large.)

If "atan2" is retained in the column headers, then the text above it that
says, "atan2(x, y) when y is:" should change -- these columns are not saying
what y is.

"P2" appears in the notes but not in the table.

Four entries define the result with atan2 and various combinations of signs,
such as "atan(x/y)" and "-atan(x/-y)".  These are insufficient unless
atan2(x) is defined to be the number in [0, pi) whose tangent is x, instead
of the more common definition using -pi/2 to pi/2.


D.2.5.

Comments from previous sections apply.

"The atan2 transcendental functions" should be "hypot".

If "hypot" is included in this annex, the annex should not be called
"Transcendental functions".

Two cells are empty in the x is "+/- 0" row.  These should likely contain
"y", with no footnote marker.

In the "-nit >= x >= -huge" row, the "+/- 0" column contains only a footnote
marker.  This should likely be "x", with no marker.

The note about "Might signal..." should be clear about whether exceptions
can be signaled if intermediate calculations underflow or overflow even if
the final result does not.


D.2.6.

Comments from previous sections apply.

I did not check the table here since I am not prepared to step into that
fray.


More General Notes.

There was a note before that some functions could signal an exception in
degenerate cases, where an implementation provided a format with a large
precision and a small exponent.  That note is missing in this version.
(cosPi and log were mentioned.  Other susceptible functions include log2,
log10, and acos.)

Did we discuss previously the possibility that cos could signal underflow in
some as-yet unimplemented format, if a representable number happened to be
extraordinarily close to an odd multiple of pi/2?  Conceivably, it could
happen in some non-degenerate format.  It may be that for completeness we
should have a note about that.  tan and sin are also susceptible but are
already noted to possibly underflow normally.  It is even conceivable that
logp1 could underflow -- maybe there is a huge sequence of zeroes or ones
somewhere in the binary representation of 1/e.  Suppose that after n bits of
precision, there were m zeroes.  Then in a format with n bits of precision,
logp1(1/e) would be around -(2^-m).  If that were in the denormal exponent
range, then there would be underflow.  (We should have a prize for the first
person to implement such a format.)


Petty Preferences.

It might be nice if the footnote symbols were converted to something more
directly meaningful.  E.g., change the entry "e^x <squiggly>" to "e^x (uo)"
to show this particular entry might generate underflow or overflow.

I prefer writing the table columns from lesser values to greater, so
that -infinity is on the left and +infinity is on the right.  It simply
matches the most common way of labeling graphs and diagrams.  Similarly, I
prefer to write inequalities using "<" or "<=" rather than ">" or ">=" when
there is no reason for the latter.  Obviously, there is no mathematical or
semantic difference, but using consistent conventions can decrease human
errors.