The documentation for the cmath module is misleading on the behaviour near branch cuts. For example, the documentation for cmath.acos says:

   Return the arc cosine of x. There are two branch cuts: One
   extends right from 1 along the real axis to ∞, continuous
   from below. The other extends left from -1 along the real
   axis to -∞, continuous from above.

That "continuous from below" and "continuous from above" language is misleading; in fact what happens on the vast majority of systems (those for which the floating-point format used is IEEE 754 binary64), if the imaginary part of x is zero, the sign of x is used to determine which side of the branch cut x lies.

> the sign of x is used [...]

Correction: That should say "the sign of the imaginary part of x is used [...]"

+1 for changing the language to match the actual mechanics.


> "the sign of the imaginary part of x is used [...]"

I'm trying to see where this happens.  Is this part of cmath_sqrt?

    if (z.real >= 0.) {
        r.real = s;
        r.imag = copysign(d, z.imag); 
    } else {
        r.real = d;
        r.imag = copysign(s, z.imag);
    }


> "continuous from below" and "continuous from above" 
> language is misleading;

I'm curious, is that language incorrect?  My mental image of a branch cut is a helical graph with the edge cases being continuous from above and below.  Likewise, my mental model for branch cut logic is it resolves multiple possible output values in a way preserves continuity from one side or the other.

In other words, I think about branch cuts in terms of continuity rather than sign preservation.  Is that incorrect?

Yes, that looks like the right part of the sqrt code.

For the acos docstring, "continuous from below" implies that for any complex number z that lies exactly _on_ the branch cut, acos(z) is close to acos(w) for a nearby value w just _below_ the branch cut. But that's demonstrably not true: see the change of sign in the real part below:

>>> acos(complex(2.3, -1e-10))  # value just "below" the branch cut
(4.828045495852677e-11+1.475044781241425j)
>>> acos(complex(2.3, 0.0))  # nearby value exactly _on_ the branch cut
-1.475044781241425j

In effect, for a branch cut along the real axis, the sign of the zero in the imaginary part of the argument allows us to be continuous from both sides at once.

> [...] see the change of sign in the real part below [...]

Grr. Stupid fingers. That should say "imaginary part", not "real part"