Re: Issue in man page clog.3

G. Branden Robinson
2023-11-01T16:56:49Z

[-- 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.