[PATCH v3] math: Refactor how to use libm-test-ulps

[Adhemerval Zanella Netto]

On 28/01/25 12:23, Paul Zimmermann wrote:
>        Dear Adhemerval,
> 
>> The manual error table is also removed, Paul Zimmermann has been
> 
> it would be more accurate to write "Paul Zimmermann and others have been"
> since I initiated this comparison, but now we are 4 co-authors

Ack.

> 
>> Changes from v2:
>> * Expanded the manual entry for accuracy papers and added the complex
>>   analysis one.
>> * More type fixes in commit message.
> 
> type -> typo :-)

Ack.

> 
>> +A more comprehensive analysis of @theglibc{} math functions precision could
>> +be found in 'Accuracy of Mathematical Functions in Single, Double, Double
>> +Extended, and Quadruple Precision'; Brian Gladman, Vincenzo Innocente,
>> +John Mather, and Paul Zimmermann at 
>> +@url{<https://inria.hal.science/hal-03141101>}.  It does cover complex
> 
> you mean "It does not cover" ?

Yes, I will fix it.

> 
>> +functions, or @code{jn}/@code{yn}, and it is only for x86_64, and for
> 
> or -> nor ?

Ack.

> 
>> +rounding to nearest, and does not cover any architecture variations (in
>> +particular IBM long double is out of scope).
> 
> also some results might differ on other x86_64's, due to the use of fma or not
> for example (but we might ignore this level of detail)

I think we can assume that our current fma fallback is correctly rounded, so
this would influence more performance than correctness.

> 
>> +For complex functions, some analysis of @theglibc{} math functions can be
>> +found in 'Accuracy of Complex Mathematical Operations and Functions in Single
>> +and Double Precision'; Paul Caprioli, Vincenzo Innocente, Paul Zimmermann
>> +at @url{https://inria.hal.science/hal-04714173}.  It is only for x86_64,
>> +and for rounding to nearest, and does not cover any architecture
>> +variations.
> 
> ok
> 
>> +A "libm-test-ulps" is required only to test for extra constraints in
>> +the math tests.  The file contains lines for maximal errors of single
>> +functions, like:
>> +
>> +Function "yn":
>> +float: 2
>> +double: 6
>> +
>> +It means that if the "yn" shows error larger than 2 ULP for float
>> +or 6 ULP for double, the related test for "symbol" will fail.  It can
>> +be useful to check for correctly rounded implementation, where the
>> +expected ULP is 0.
>> +
>> +The function is tested with default FE_TONEAREST rounding mode.  To
>> +check with a differnt ione, the function definition name should be
> 
> differnt ione -> different one

Ack.

> 
>> +prepended with an underline plus the rounding mode 'downward' (FE_DOWNWARD),
>> +'towardzero' (FE_TOWARDZERO), or 'upward' (FE_UPWARD).  For instance,
>> +
>> +Function "yn_downward":
>> +float: 3
>> +double: 7
>> +
>> +It means that 'yn' will be check with FE_TOWARDZERO rounding mode
> 
> check -> checked
> FE_TOWARDZERO -> FE_DOWNWARD

Ack.

> 
>>  Note that the test drivers have an option "-u" to output an unsorted
>>  list of all epsilons that the functions have.  The output can be read
> 
> it might be useful to output all inputs that yield the largest ulp error
> (if not already available, this might be in a later patch)

Yeah, it would require to keep track of the tested values in a list (doable,
but I think it should be a different patch).

> 
> Paul