Issue in man page clog.3

Issue in man page clog.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?

"The logarithm B<clog>()  is the inverse function of the exponential "
"B<cexp>(3).  Thus, if I<y\\ =\\ clog(z)>, then I<z\\ =\\ cexp(y)>.  The "
"imaginary part of I<y> is chosen in the interval [-pi,pi]."

Re: Issue in man page clog.3

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 642 bytes --]

Hi Helge,

On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?
> 
> "The logarithm B<clog>()  is the inverse function of the exponential "
> "B<cexp>(3).  Thus, if I<y\\ =\\ clog(z)>, then I<z\\ =\\ cexp(y)>.  The "
> "imaginary part of I<y> is chosen in the interval [-pi,pi]."

I don't know this function.  Please suggest a fix, and CC glibc so that
they can review the change.

Thanks,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page clog.3

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1235 bytes --]

Hello Alejandro,
Am Wed, Nov 01, 2023 at 04:00:16PM +0100 schrieb Alejandro Colomar:
> On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?
> > 
> > "The logarithm B<clog>()  is the inverse function of the exponential "
> > "B<cexp>(3).  Thus, if I<y\\ =\\ clog(z)>, then I<z\\ =\\ cexp(y)>.  The "
> > "imaginary part of I<y> is chosen in the interval [-pi,pi]."
> 
> I don't know this function.  Please suggest a fix, and CC glibc so that
> they can review the change.

From a mathematical point of view either -pi or pi needs to be
excluded. I'm not a programmer, so the I cannot tell which is the case
here.

So you need to contact the person who wrote or who maintains this
function / man page.

Greetings

        Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page clog.3

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 5272 bytes --]

Hi Alex,

At 2023-11-01T16:00:16+0100, Alejandro Colomar wrote:
> On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    [-pi,pi] means both -pi and pi are included, this does not
> > make sense, either one must be out of the interval?
> > 
> > "The logarithm B<clog>()  is the inverse function of the exponential
> > " "B<cexp>(3).  Thus, if I<y\\ =\\ clog(z)>, then I<z\\ =\\
> > cexp(y)>.  The " "imaginary part of I<y> is chosen in the interval
> > [-pi,pi]."
> 
> I don't know this function.  Please suggest a fix, and CC glibc so
> that they can review the change.

The complex logarithm is the inverse function of the complex
exponential, with which you may be familiar if you've taken a course in
ordinary differential equations.

Euler's formula famously relates the trigonometric and exponential
functions.

exp(i*x) = cos x + i sin x

While the exponential function is aperiodic, that is for y=exp(x), no
value of y ever occurs more than once for any real x, this is not true
of a complex x or (equivalently[1]), the complex exponential, or real x
multiplied by the imaginary unit i as seen in Euler's formula.

(Recall that for any x, sin(x) and cos(x) take on values in the interval
[-1, 1], and i is a constant imaginary unit that we can interpret as a
y axis.  Thus the complex exponential maps any real x to a point on the
unit circle.)

In other words, for us to have an inverse function for the complex
exponential, we must impose a restriction on its range, lest it give us
an infinite vector of solutions.  Geometrically, the complex logarithm
asks, "given a point on the unit circle, which value of x to the complex
exponential corresponds to it?"  But there is so single answer to that
question.  It is still a useful one to ask, so we can apply a constraint
on the range of the solution which will make the complex logarithm
one-to-one.

We do a similar thing for the arc sine function.  Given a value c in
[-1, 1], what angle theta has c as its sine?  There is an unbounded
number of answers.  If you plot y=sin(x), you will see that y takes on
every real value from -1 to 1,[2] repeatedly and unendingly.

At any rate, I think this statement:

> > Issue:    [-pi,pi] means both -pi and pi are included, this does not
> >           make sense, either one must be out of the interval?

Needs more support.  clog(1) = pi and clog(-1) = -pi.  The limits of
machine representation are applicable here, so you'll only ever get
values "close to" ±pi anyway.

Also, POSIX and the ISO C committee didn't seem troubled by this;
the same closed interval is issued in POSIX Issue 8 Draft 3, which says
(in so many words) that the function's definition comes from ISO C99.

Oh, now that I'm about ready to send this, I see Jakub Wilk made the
same point far more concisely.  Who's surprised?

Regards,
Branden

[1] ...by applying of properties of powers such as x^(ab) = x^a * x^b.

[2] I, uh, don't actually have a proof of the claim "every value".  And
    in fact I am unlikely to ever have one.  Per Niven's theorem, the
    elementary trigonometric functions never take any rational values
    _except_ 0, ±1, and ±1/2.[3]  This may be a startling result to
    insightful students of elementary calculus, as, if one is paying
    attention, one should then wonder why we can say with certainty that
    any of these functions are differentiable, since there are jump
    discontinuities in them--in fact a countably infinite number of
    such discontinuities.[4]

    Since our domain of discourse is computer arithmetic with finite
    precision, it's an academic question, as with sufficient precision
    you can have a sine function that will produce every representable
    value within the function's range[5].

[3] https://en.wikipedia.org/wiki/Niven%27s_theorem

[4] I think it's a set of measure zero but I am now exceeding the limits
    of my training.  I need more topology and theory of functions of a
    real variable.  And to learn Lebesgue integration.

[5] I don't actually have a proof of that, either.  It seems not
    impossible to me that the way IEEE floating point is defined means
    that functions with the properties that trig functions have might
    skip some representable values due to the nonlinearity of that
    representation (the magnitude of error in floating-point math is not
    constant, which is a reason some applications prefer fixed-point).
    An "obvious" possibility is the set of rational values that have a
    precise floating point representation in base 2, so 1/4th, -1/8th,
    and so.  I need more numerical analysis, too.[6]  Anyway, one
    counterexample disproves my claim, so let's settle for "almost
    every", where we are using "almost" in a hand-wavy manner, not the
    way someone studying the Dirichlet indicator function might.

[6] Obligatory citation of mandatory reading (Goldberg 1991):

    https://ece.uwaterloo.ca/~dwharder/NumericalAnalysis/02Numerics/Double/paper.pdf

    Press et al.'s books on numerical methods ("numerical recipes in
    $LANG") are surprisingly controversial.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page clog.3

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 6526 bytes --]

Hi Branden,

On Wed, Nov 01, 2023 at 11:56:32AM -0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-11-01T16:00:16+0100, Alejandro Colomar wrote:
> > On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > > 
> > > Issue:    [-pi,pi] means both -pi and pi are included, this does not
> > > make sense, either one must be out of the interval?
> > > 
> > > "The logarithm B<clog>()  is the inverse function of the exponential
> > > " "B<cexp>(3).  Thus, if I<y\\ =\\ clog(z)>, then I<z\\ =\\
> > > cexp(y)>.  The " "imaginary part of I<y> is chosen in the interval
> > > [-pi,pi]."
> > 
> > I don't know this function.  Please suggest a fix, and CC glibc so
> > that they can review the change.
> 
> The complex logarithm is the inverse function of the complex
> exponential, with which you may be familiar if you've taken a course in
> ordinary differential equations.

Yup, I have.  This reminds me of some old TODO I had: take a course on
multivariable calculus from a professor I like:
<https://www2.math.upenn.edu/~ghrist/BLUE.html>

The course on single-variable calculus from him was quite good.
<https://www2.math.upenn.edu/~ghrist/calculus.html>

> 
> Euler's formula famously relates the trigonometric and exponential
> functions.
> 
> exp(i*x) = cos x + i sin x
> 
> While the exponential function is aperiodic, that is for y=exp(x), no
> value of y ever occurs more than once for any real x, this is not true
> of a complex x or (equivalently[1]), the complex exponential, or real x
> multiplied by the imaginary unit i as seen in Euler's formula.
> 
> (Recall that for any x, sin(x) and cos(x) take on values in the interval
> [-1, 1], and i is a constant imaginary unit that we can interpret as a
> y axis.  Thus the complex exponential maps any real x to a point on the
> unit circle.)

e^(ix) is something I can visualize thanks to Euler, and e^(ix + y),
well, not so much, but by combination of e^(ix) and e^y I can
understand, but

> 
> In other words, for us to have an inverse function for the complex
> exponential, we must impose a restriction on its range, lest it give us
> an infinite vector of solutions.  Geometrically, the complex logarithm
> asks, "given a point on the unit circle, which value of x to the complex
> exponential corresponds to it?"  But there is so single answer to that
> question.  It is still a useful one to ask, so we can apply a constraint
> on the range of the solution which will make the complex logarithm
> one-to-one.

I can't yet visualize a complex or simple imaginary logarithm.  I'm not
so imaginative at the moment.  :|

> 
> We do a similar thing for the arc sine function.  Given a value c in
> [-1, 1], what angle theta has c as its sine?  There is an unbounded
> number of answers.  If you plot y=sin(x), you will see that y takes on
> every real value from -1 to 1,[2] repeatedly and unendingly.
> 
> At any rate, I think this statement:
> 
> > > Issue:    [-pi,pi] means both -pi and pi are included, this does not
> > >           make sense, either one must be out of the interval?
> 
> Needs more support.  clog(1) = pi and clog(-1) = -pi.  The limits of
> machine representation are applicable here, so you'll only ever get
> values "close to" ±pi anyway.
> 
> Also, POSIX and the ISO C committee didn't seem troubled by this;
> the same closed interval is issued in POSIX Issue 8 Draft 3, which says
> (in so many words) that the function's definition comes from ISO C99.
> 
> Oh, now that I'm about ready to send this, I see Jakub Wilk made the
> same point far more concisely.  Who's surprised?
> 
> Regards,
> Branden
> 
> [1] ...by applying of properties of powers such as x^(ab) = x^a * x^b.
> 
> [2] I, uh, don't actually have a proof of the claim "every value".  And
>     in fact I am unlikely to ever have one.  Per Niven's theorem, the
>     elementary trigonometric functions never take any rational values
>     _except_ 0, ±1, and ±1/2.[3]  This may be a startling result to
>     insightful students of elementary calculus, as, if one is paying
>     attention, one should then wonder why we can say with certainty that
>     any of these functions are differentiable, since there are jump
>     discontinuities in them--in fact a countably infinite number of
>     such discontinuities.[4]

You mean discontinuities in the representation, right?  Not in the
function, I presume.

Students should have in mind that a representation cannot be perfect in
some cases.  You can ask the same student to measure the rope that
circles a circumference of radius 1; it'll have a hard time with the
ruler.  :P

Cheers,
Alex

> 
>     Since our domain of discourse is computer arithmetic with finite
>     precision, it's an academic question, as with sufficient precision
>     you can have a sine function that will produce every representable
>     value within the function's range[5].
> 
> [3] https://en.wikipedia.org/wiki/Niven%27s_theorem
> 
> [4] I think it's a set of measure zero but I am now exceeding the limits
>     of my training.  I need more topology and theory of functions of a
>     real variable.  And to learn Lebesgue integration.
> 
> [5] I don't actually have a proof of that, either.  It seems not
>     impossible to me that the way IEEE floating point is defined means
>     that functions with the properties that trig functions have might
>     skip some representable values due to the nonlinearity of that
>     representation (the magnitude of error in floating-point math is not
>     constant, which is a reason some applications prefer fixed-point).
>     An "obvious" possibility is the set of rational values that have a
>     precise floating point representation in base 2, so 1/4th, -1/8th,
>     and so.  I need more numerical analysis, too.[6]  Anyway, one
>     counterexample disproves my claim, so let's settle for "almost
>     every", where we are using "almost" in a hand-wavy manner, not the
>     way someone studying the Dirichlet indicator function might.
> 
> [6] Obligatory citation of mandatory reading (Goldberg 1991):
> 
>     https://ece.uwaterloo.ca/~dwharder/NumericalAnalysis/02Numerics/Double/paper.pdf
> 
>     Press et al.'s books on numerical methods ("numerical recipes in
>     $LANG") are surprisingly controversial.



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page clog.3

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1144 bytes --]

On Wed, Nov 01, 2023 at 03:25:46PM +0000, Helge Kreutzmann wrote:
> Hello Alejandro,
> Am Wed, Nov 01, 2023 at 04:00:16PM +0100 schrieb Alejandro Colomar:
> > On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > > 
> > > Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?
> > > 
> > > "The logarithm B<clog>()  is the inverse function of the exponential "
> > > "B<cexp>(3).  Thus, if I<y\\ =\\ clog(z)>, then I<z\\ =\\ cexp(y)>.  The "
> > > "imaginary part of I<y> is chosen in the interval [-pi,pi]."
> > 
> > I don't know this function.  Please suggest a fix, and CC glibc so that
> > they can review the change.
> 
> From a mathematical point of view either -pi or pi needs to be
> excluded. I'm not a programmer, so the I cannot tell which is the case
> here.
> 
> So you need to contact the person who wrote or who maintains this
> function / man page.

Hi,

I'm CCing glibc, in case they want to say something.

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page clog.3

[Nikolaos Chatzikonstantinou]

It just says that the value is in that interval, so it is not wrong.
There is no canonical way to cut the plane into strips, either the top
is half-open or the bottom.

On Wed, Nov 1, 2023 at 1:08 PM Alejandro Colomar via Libc-help
<libc-help@sourceware.org> wrote:
>
> On Wed, Nov 01, 2023 at 03:25:46PM +0000, Helge Kreutzmann wrote:
> > Hello Alejandro,
> > Am Wed, Nov 01, 2023 at 04:00:16PM +0100 schrieb Alejandro Colomar:
> > > On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> > > > Without further ado, the following was found:
> > > >
> > > > Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?
> > > >
> > > > "The logarithm B<clog>()  is the inverse function of the exponential "
> > > > "B<cexp>(3).  Thus, if I<y\\ =\\ clog(z)>, then I<z\\ =\\ cexp(y)>.  The "
> > > > "imaginary part of I<y> is chosen in the interval [-pi,pi]."
> > >
> > > I don't know this function.  Please suggest a fix, and CC glibc so that
> > > they can review the change.
> >
> > From a mathematical point of view either -pi or pi needs to be
> > excluded. I'm not a programmer, so the I cannot tell which is the case
> > here.
> >
> > So you need to contact the person who wrote or who maintains this
> > function / man page.
>
> Hi,
>
> I'm CCing glibc, in case they want to say something.
>
> Cheers,
> Alex
>
> --
> <https://www.alejandro-colomar.es/>

Re: Issue in man page clog.3

[Jakub Wilk]

* Helge Kreutzmann <debian@helgefjell.de>, 2023-11-01 14:02:
>Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?

The man page is consistent with the C standard, which says the return 
value is "in the interval [−iπ, +iπ] along the imaginary axis".

I think they mean π rounded to the nearest representable value.
And indeed, the imaginary part of clog(-1 - DBL_EPSILON * I) is -M_PI, 
and the imaginary part of clog(-1 + DBL_EPSILON * I) is +M_PI.

-- 
Jakub Wilk

Re: Issue in man page clog.3

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1002 bytes --]

Hello Jakub,
Am Wed, Nov 01, 2023 at 05:15:00PM +0100 schrieb Jakub Wilk:
> * Helge Kreutzmann <debian@helgefjell.de>, 2023-11-01 14:02:
> > Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?
> 
> The man page is consistent with the C standard, which says the return value
> is "in the interval [−iπ, +iπ] along the imaginary axis".
> 
> I think they mean π rounded to the nearest representable value.
> And indeed, the imaginary part of clog(-1 - DBL_EPSILON * I) is -M_PI, and
> the imaginary part of clog(-1 + DBL_EPSILON * I) is +M_PI.

Then disregard this report, thanks for checking.

Greetings

            Helge
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page clog.3

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 711 bytes --]

On Wed, Nov 01, 2023 at 05:15:00PM +0100, Jakub Wilk wrote:
> * Helge Kreutzmann <debian@helgefjell.de>, 2023-11-01 14:02:
> > Issue:    [-pi,pi] means both -pi and pi are included, this does not make sense, either one must be out of the interval?
> 
> The man page is consistent with the C standard, which says the return value
> is "in the interval [−iπ, +iπ] along the imaginary axis".
> 
> I think they mean π rounded to the nearest representable value.
> And indeed, the imaginary part of clog(-1 - DBL_EPSILON * I) is -M_PI, and
> the imaginary part of clog(-1 + DBL_EPSILON * I) is +M_PI.

Ahh, thanks a lot, Jakub!

> 
> -- 
> Jakub Wilk

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]