[v2,3/3] manual: Cube roots are rarely representable

  Link: <https://lore.kernel.org/linux-man/ZeYKUOKYS7G90SaV@debian/T/#mff0ab388000c6afdb5e5162804d4a0073de481de>
Reported-by: Morten Welinder <mwelinder@gmail.com>
Cowritten-by: Morten Welinder <mwelinder@gmail.com>
Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
Cc: Vincent Lefevre <vincent@vinc17.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 manual/math.texi | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
  

Alejandro Colomar <alx@kernel.org> writes:

> -These functions return the cube root of @var{x}.  They cannot
> -fail; every representable real value has a representable real cube root.

> +These functions return the cube root of @var{x}.  They cannot
> +fail; every representable real value has a real cube root,
> +and rounding it to a representable value
> +never causes overflow nor underflow.

Wording is OK but the $subject says the exact opposite...
  

> From: DJ Delorie <dj@redhat.com>
> Cc: libc-alpha@sourceware.org
> Date: Fri, 29 Mar 2024 20:27:44 -0400
> 
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > -These functions return the cube root of @var{x}.  They cannot
> > -fail; every representable real value has a representable real cube root.
> 
> > +These functions return the cube root of @var{x}.  They cannot
> > +fail; every representable real value has a real cube root,
> > +and rounding it to a representable value
> > +never causes overflow nor underflow.
> 
> Wording is OK but the $subject says the exact opposite...

It is fine to me. The subject says that the cube root of a floating-point
number is rarely a floating-point number, which is true: for a p-bit format,
only about 2^(p/3) numbers have an exact cube root.

Paul
  

Paul Zimmermann <Paul.Zimmermann@inria.fr> writes:
>> From: DJ Delorie <dj@redhat.com>
>> Cc: libc-alpha@sourceware.org
>> Date: Fri, 29 Mar 2024 20:27:44 -0400
>> 
>> Alejandro Colomar <alx@kernel.org> writes:
>> 
>> > -These functions return the cube root of @var{x}.  They cannot
>> > -fail; every representable real value has a representable real cube root.
>> 
>> > +These functions return the cube root of @var{x}.  They cannot
>> > +fail; every representable real value has a real cube root,
>> > +and rounding it to a representable value
>> > +never causes overflow nor underflow.
>> 
>> Wording is OK but the $subject says the exact opposite...
>
> It is fine to me. The subject says that the cube root of a floating-point
> number is rarely a floating-point number, which is true: for a p-bit format,
> only about 2^(p/3) numbers have an exact cube root.

Let me rephrase: The $subject does not convey the intent of the patch.
If the patch adds wording that "the result never errors" the subject
should reflect that change, not some other aspect of the issue.

Something like "Note why cube roots always give representable results."
  

Hi DJ,

On Sat, Mar 30, 2024 at 12:51:35PM -0400, DJ Delorie wrote:
> Paul Zimmermann <Paul.Zimmermann@inria.fr> writes:
> >> From: DJ Delorie <dj@redhat.com>
> >> Cc: libc-alpha@sourceware.org
> >> Date: Fri, 29 Mar 2024 20:27:44 -0400
> >> 
> >> Alejandro Colomar <alx@kernel.org> writes:
> >> 
> >> > -These functions return the cube root of @var{x}.  They cannot
> >> > -fail; every representable real value has a representable real cube root.
> >> 
> >> > +These functions return the cube root of @var{x}.  They cannot
> >> > +fail; every representable real value has a real cube root,
> >> > +and rounding it to a representable value
> >> > +never causes overflow nor underflow.
> >> 
> >> Wording is OK but the $subject says the exact opposite...
> >
> > It is fine to me. The subject says that the cube root of a floating-point
> > number is rarely a floating-point number, which is true: for a p-bit format,
> > only about 2^(p/3) numbers have an exact cube root.
> 
> Let me rephrase: The $subject does not convey the intent of the patch.
> If the patch adds wording that "the result never errors" the subject
> should reflect that change, not some other aspect of the issue.
> 
> Something like "Note why cube roots always give representable results."

Hmmm.  The rationale for the $subject was that the old text, which I'm
removing, claimed that "every representable real value has a
representable real cube root".  I was confronting that claim with
reality: cube roots are rarely representable, since they tend to be real
numbers, which cannot be represented exactly.

What you can do is approximate them to something that can be represented
without failing.  It's guaranteed that they won't overflow nor
underflow, because a cube root is always closer to 1 in absolute value
than the number it roots.

If you can think of a better subject, please let me know.  I have some
comments on your suggested one ("Note why cube roots always give
representable results"):

-  It's actually contrary to the intent of the commit, which is removing
   text that claims that cube roots are representable, which is false.

-  I admit my commit $subject didn't specify (nor imply) what the
   new text says.  It only says what it does not say (what I'm
   removing).  Also, if I read your intentions, not just your literal
   text, I think you wanted to say something like

	Note why cube roots are not always representable, but still
	these functions always succeed returning an approximation.

   While that text would not be lying mathematically: it doesn't claim
   that cube roots are representable while they aren't; it claims that I
   note _why_.  I've explained why in this email: the root is closer to
   1 (in absolute value) than the cube, and numbers closer to 1 (and in
   general, small integers) are the farthest from a float and double
   overflow or underflow (I won't give more details, as my knowledge of
   floating point numbers in C begins to end there :) ).  But the commit
   doesn't actually introduce any text to clarify why that happens.  It
   only notes _what_ happens.

Have a lovely night!
Alex
  

Alejandro Colomar <alx@kernel.org> writes:
> -  It's actually contrary to the intent of the commit, which is removing
>    text that claims that cube roots are representable, which is false.

I meant that the function's return value is always representable, i.e.,
doesn't overflow, underflow, or produce NaNs.

I'm not trying to be mathematically pedantic here.  I'm just suggesting
that the patch subject should reflect the change, so that someone
searching for it has something relevent to look for.  Even something as
trivial as "Cube roots: clarify return values" would be better.
  

On Sat, Mar 30, 2024 at 02:50:58PM -0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > -  It's actually contrary to the intent of the commit, which is removing
> >    text that claims that cube roots are representable, which is false.
> 
> I meant that the function's return value is always representable, i.e.,
> doesn't overflow, underflow, or produce NaNs.
> 
> I'm not trying to be mathematically pedantic here.  I'm just suggesting
> that the patch subject should reflect the change, so that someone
> searching for it has something relevent to look for.  Even something as
> trivial as "Cube roots: clarify return values" would be better.

Hmmm.  How about "manual: Clarify return value of cbrt(3)"?
I'll send a revision of the patch set with it.