summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorMiss Islington (bot) <31488909+miss-islington@users.noreply.github.com>2023-02-26 11:55:13 (GMT)
committerGitHub <noreply@github.com>2023-02-26 11:55:13 (GMT)
commit601c9db4550791125d7c3101c7028c49cc704e14 (patch)
tree3dfa92a826366accffe9cfb521fe72dcea68b53a /Doc
parent972396143f9cb2478ab933a5ede39fa840d514bf (diff)
downloadcpython-601c9db4550791125d7c3101c7028c49cc704e14.zip
cpython-601c9db4550791125d7c3101c7028c49cc704e14.tar.gz
cpython-601c9db4550791125d7c3101c7028c49cc704e14.tar.bz2
[3.10] gh-85417: Clarify behaviour on branch cuts in cmath module (GH-102046) (#102275)
gh-85417: Clarify behaviour on branch cuts in cmath module (GH-102046) This PR updates the cmath module documentation to reflect the reality that Python is almost always (and as far as I can tell, that "almost" can be omitted) running on a machine whose C double supports signed zeros. * Removes misleading references to functions being continuous from above / below / the left / the right at branch cuts * Expands the note on branch cuts at the top of the module documentation to explain the double-sided sign-of-zero-based behaviour (cherry picked from commit b513c46d998344dc07eb6d510782c2e23d2b859e) Co-authored-by: Mark Dickinson <dickinsm@gmail.com>
Diffstat (limited to 'Doc')
-rw-r--r--Doc/library/cmath.rst66
1 files changed, 38 insertions, 28 deletions
diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst
index 28cd96b..5ed7a09 100644
--- a/Doc/library/cmath.rst
+++ b/Doc/library/cmath.rst
@@ -15,11 +15,27 @@ the function is then applied to the result of the conversion.
.. note::
- On platforms with hardware and system-level support for signed
- zeros, functions involving branch cuts are continuous on *both*
- sides of the branch cut: the sign of the zero distinguishes one
- side of the branch cut from the other. On platforms that do not
- support signed zeros the continuity is as specified below.
+ For functions involving branch cuts, we have the problem of deciding how to
+ define those functions on the cut itself. Following Kahan's "Branch cuts for
+ complex elementary functions" paper, as well as Annex G of C99 and later C
+ standards, we use the sign of zero to distinguish one side of the branch cut
+ from the other: for a branch cut along (a portion of) the real axis we look
+ at the sign of the imaginary part, while for a branch cut along the
+ imaginary axis we look at the sign of the real part.
+
+ For example, the :func:`cmath.sqrt` function has a branch cut along the
+ negative real axis. An argument of ``complex(-2.0, -0.0)`` is treated as
+ though it lies *below* the branch cut, and so gives a result on the negative
+ imaginary axis::
+
+ >>> cmath.sqrt(complex(-2.0, -0.0))
+ -1.4142135623730951j
+
+ But an argument of ``complex(-2.0, 0.0)`` is treated as though it lies above
+ the branch cut::
+
+ >>> cmath.sqrt(complex(-2.0, 0.0))
+ 1.4142135623730951j
Conversions to and from polar coordinates
@@ -44,14 +60,11 @@ rectangular coordinates to polar coordinates and back.
.. function:: phase(x)
- Return the phase of *x* (also known as the *argument* of *x*), as a
- float. ``phase(x)`` is equivalent to ``math.atan2(x.imag,
- x.real)``. The result lies in the range [-\ *π*, *π*], and the branch
- cut for this operation lies along the negative real axis,
- continuous from above. On systems with support for signed zeros
- (which includes most systems in current use), this means that the
- sign of the result is the same as the sign of ``x.imag``, even when
- ``x.imag`` is zero::
+ Return the phase of *x* (also known as the *argument* of *x*), as a float.
+ ``phase(x)`` is equivalent to ``math.atan2(x.imag, x.real)``. The result
+ lies in the range [-\ *π*, *π*], and the branch cut for this operation lies
+ along the negative real axis. The sign of the result is the same as the
+ sign of ``x.imag``, even when ``x.imag`` is zero::
>>> phase(complex(-1.0, 0.0))
3.141592653589793
@@ -92,8 +105,8 @@ Power and logarithmic functions
.. function:: log(x[, base])
Returns the logarithm of *x* to the given *base*. If the *base* is not
- specified, returns the natural logarithm of *x*. There is one branch cut, from 0
- along the negative real axis to -∞, continuous from above.
+ specified, returns the natural logarithm of *x*. There is one branch cut,
+ from 0 along the negative real axis to -∞.
.. function:: log10(x)
@@ -112,9 +125,9 @@ Trigonometric functions
.. function:: acos(x)
- 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.
+ Return the arc cosine of *x*. There are two branch cuts: One extends right
+ from 1 along the real axis to ∞. The other extends left from -1 along the
+ real axis to -∞.
.. function:: asin(x)
@@ -125,9 +138,8 @@ Trigonometric functions
.. function:: atan(x)
Return the arc tangent of *x*. There are two branch cuts: One extends from
- ``1j`` along the imaginary axis to ``∞j``, continuous from the right. The
- other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
- from the left.
+ ``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j``
+ along the imaginary axis to ``-∞j``.
.. function:: cos(x)
@@ -151,23 +163,21 @@ Hyperbolic functions
.. function:: acosh(x)
Return the inverse hyperbolic cosine of *x*. There is one branch cut,
- extending left from 1 along the real axis to -∞, continuous from above.
+ extending left from 1 along the real axis to -∞.
.. function:: asinh(x)
Return the inverse hyperbolic sine of *x*. There are two branch cuts:
- One extends from ``1j`` along the imaginary axis to ``∞j``,
- continuous from the right. The other extends from ``-1j`` along
- the imaginary axis to ``-∞j``, continuous from the left.
+ One extends from ``1j`` along the imaginary axis to ``∞j``. The other
+ extends from ``-1j`` along the imaginary axis to ``-∞j``.
.. function:: atanh(x)
Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One
- extends from ``1`` along the real axis to ``∞``, continuous from below. The
- other extends from ``-1`` along the real axis to ``-∞``, continuous from
- above.
+ extends from ``1`` along the real axis to ``∞``. The other extends from
+ ``-1`` along the real axis to ``-∞``.
.. function:: cosh(x)