Document libm accuracy goals

[Carlos O'Donell]

On 11/28/2013 12:57 PM, Joseph S. Myers wrote:
> This patch documents my understanding of glibc's accuracy goals for
> libm functions - as discussed at
> <https://sourceware.org/ml/libc-alpha/2013-05/msg00132.html>, except
> for giving more details on IBM long double values with discontiguous
> mantissa bits and specifically mentioning the lack of monotonicity in
> the goals.
> 
> This is intended to make clear that the following bugs are INVALID as
> outside of our libm goals: 14163 14759 (+ duplicates) 15898 15899.
> (I'm not proposing cutting out slow cases from existing functions that
> try to be correctly rounding in order to speed them up - though I do
> hope that at some point we'll have good ways of automatically
> generating some functions with well-defined error bounds and at that
> point can move correctly-rounding functions - adjusted as needed to
> round the final result according to the correct rounding direction -
> to names such as crsin, or put new automatically generated
> correctly-rounding functions there, and put functions with
> well-defined error bounds but not correctly rounding at the default
> names, as discussed in
> <https://sourceware.org/ml/libc-alpha/2013-07/msg00444.html>.)

I agree that 14163 is out of scope (cosf is not decreasing).

I agree that 14759 is presently out of scope (correctly rounding
is very difficult and most people don't understand that).

I agree that 15898 is out of scope (acoshf is not monotonic).

I agree that 15899 is out of scope (exp2f is not monotonic).

Could you please add an entry to the FAQ for the libm goals and
specifically call out monotonicity?

> 2013-11-28  Joseph Myers  <joseph@codesourcery.com>
> 
> 	* manual/math.texi (Errors in Math Functions): Document accuracy
> 	goals.
> 
> diff --git a/manual/math.texi b/manual/math.texi
> index 57cf24f..5e7c90e 100644
> --- a/manual/math.texi
> +++ b/manual/math.texi
> @@ -1227,10 +1227,80 @@ $${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$
>  @noindent
>  where @math{p} is the number of bits in the mantissa of the
>  floating-point number representation.  Ideally the error for all
> -functions is always less than 0.5ulps.  Using rounding bits this is also
> -possible and normally implemented for the basic operations.  To achieve
> -the same for the complex math functions requires a lot more work and
> -this has not yet been done.
> +functions is always less than 0.5ulps in round-to-nearest mode.  Using
> +rounding bits this is also
> +possible and normally implemented for the basic operations.  Except
> +for certain functions such as @code{sqrt}, @code{fma} and @code{rint}
> +whose results are fully specified by reference to corresponding IEEE
> +754 floating-point operations, and conversions between strings and
> +floating point, @theglibc{} does not aim for correctly rounded results
> +for functions in the math library, and does not aim for correctness in
> +whether ``inexact'' exceptions are raised.  Instead, the goals for
> +accuracy of functions without fully specified results are as follows;
> +some functions have bugs meaning they do not meet these goals in all
> +cases.  In future, @theglibc{} may provide some other correctly
> +rounding functions under the names such as @code{crsin} proposed for
> +an extension to ISO C.

OK.

> +
> +@itemize @bullet
> +
> +@item
> +Each function with a floating-point result behaves as if it computes
> +an infinite-precision result that is within a few ulp (in both real
> +and complex parts, for functions with complex results) of the
> +mathematically correct value of the function (interpreted together
> +with ISO C or POSIX semantics for the function in question) at the
> +exact value passed as the input.  Exceptions are raised appropriately
> +for this value and in accordance with IEEE 754 / ISO C / POSIX
> +semantics, and it is then rounded according to the current rounding
> +direction to the result that is returned to the user.  @code{errno}
> +may also be set (@pxref{Math Error Reporting}).

OK.

> +
> +@item
> +For the IBM @code{long double} format, as used on PowerPC GNU/Linux,

Is it sufficient to say "PowerPC GNU/Linux" when we mean both the 32-bit
and 64-bit runtimes?

> +the accuracy goal is weaker for input values not exactly representable
> +in 106 bits of precision; it is as if the input value is some value
> +within 0.5ulp of the value actually passed, where ``ulp'' is
> +interpreted in terms of a fixed-precision 106-bit mantissa, but not
> +necessarily the exact value actually passed with discontiguous
> +mantissa bits.

OK.

> +
> +@item
> +Functions behave as if the infinite-precision result computed is zero,
> +infinity or NaN if and only if that is the mathematically correct
> +infinite-precision result.  They behave as if the infinite-precision
> +result computed always has the same sign as the mathematically correct
> +result.

OK.

> +
> +@item
> +If the mathematical result is more than a few ulp above the overflow
> +threshold for the current rounding direction, the value returned is
> +the appropriate overflow value for the current rounding direction,
> +with the overflow exception raised.

OK.

> +
> +@item
> +If the mathematical result has magnitude well below half the least
> +subnormal magnitude, the returned value is either zero or the least
> +subnormal (in each case, with the correct sign), according to the
> +current rounding direction and with the underflow exception raised.

OK.

> +
> +@item
> +Where the mathematical result underflows and is not exactly
> +representable as a floating-point value, the underflow exception is
> +raised (so there may be spurious underflow exceptions in cases where
> +the underflowing result is exact, but not missing underflow exceptions
> +in cases where it is inexact).

OK.

> +
> +@item
> +@Theglibc{} does not aim for functions to satisfy other properties of
> +the underlying mathematical function, such as monotonicity, where not
> +implied by the above goals.

Aside from montonicity what other properties might we call out explicitly
here as things we don't plan to satisfy?

> +
> +@item
> +All the above applies to both real and complex parts, for complex
> +functions.

OK.

> +
> +@end itemize
>  
>  Therefore many of the functions in the math library have errors.  The
>  table lists the maximum error for each function which is exposed by one
> 

Cheers,
Carlos.