Issue #6458: Reorganize cmath documentation into sections (similar to

the way that the math documentation is organized); clarify section on
conversions to and from polar coordinates.

Doc/library/cmath.rst

@@ -23,100 +23,112 @@ result of the conversion.
    support signed zeros the continuity is as specified below.
 
 
-Complex coordinates
--------------------
+Conversions to and from polar coordinates
+-----------------------------------------
 
-Complex numbers can be expressed by two important coordinate systems.
-Python's :class:`complex` type uses rectangular coordinates where a number
-on the complex plane is defined by two floats, the real part and the imaginary
-part.
+A Python complex number ``z`` is stored internally using *rectangular*
+or *Cartesian* coordinates.  It is completely determined by its *real
+part* ``z.real`` and its *imaginary part* ``z.imag``.  In other
+words::
 
-Definition::
+   z == z.real + z.imag*1j
 
-   z = x + 1j * y
+*Polar coordinates* give an alternative way to represent a complex
+number.  In polar coordinates, a complex number *z* is defined by the
+modulus *r* and the phase angle *phi*. The modulus *r* is the distance
+from *z* to the origin, while the phase *phi* is the counterclockwise
+angle from the positive x-axis to the line segment that joins the
+origin to *z*.
 
-   x := z.real
-   y := z.imag
+The following functions can be used to convert from the native
+rectangular coordinates to polar coordinates and back.
 
-In engineering the polar coordinate system is popular for complex numbers. In
-polar coordinates a complex number is defined by the radius *r* and the phase
-angle *phi*. The radius *r* is the absolute value of the complex, which can be
-viewed as distance from (0, 0). The radius *r* is always 0 or a positive float.
-The phase angle *phi* is the counter clockwise angle from the positive x axis,
-e.g. *1* has the angle *0*, *1j* has the angle *π/2* and *-1* the angle *-π*.
+.. function:: phase(x)
 
-.. note::
-   While :func:`phase` and func:`polar` return *+π* for a negative real they
-   may return *-π* for a complex with a very small negative imaginary
-   part, e.g. *-1-1E-300j*.
+   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::
 
+      >>> phase(complex(-1.0, 0.0))
+      3.1415926535897931
+      >>> phase(complex(-1.0, -0.0))
+      -3.1415926535897931
+
+   .. versionadded:: 2.6
 
-Definition::
 
-   z = r * exp(1j * phi)
-   z = r * cis(phi)
+.. note::
 
-   r := abs(z) := sqrt(real(z)**2 + imag(z)**2)
-   phi := phase(z) := atan2(imag(z), real(z))
-   cis(phi) := cos(phi) + 1j * sin(phi)
+   The modulus (absolute value) of a complex number *x* can be
+   computed using the built-in :func:`abs` function.  There is no
+   separate :mod:`cmath` module function for this operation.
 
 
-.. function:: phase(x)
+.. function:: polar(x)
 
-   Return phase, also known as the argument, of a complex.
+   Return the representation of *x* in polar coordinates.  Returns a
+   pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the
+   phase of *x*.  ``polar(x)`` is equivalent to ``(abs(x),
+   phase(x))``.
 
    .. versionadded:: 2.6
 
 
-.. function:: polar(x)
+.. function:: rect(r, phi)
 
-   Convert a :class:`complex` from rectangular coordinates to polar
-   coordinates. The function returns a tuple with the two elements
-   *r* and *phi*. *r* is the distance from 0 and *phi* the phase
-   angle.
+   Return the complex number *x* with polar coordinates *r* and *phi*.
+   Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``.
 
    .. versionadded:: 2.6
 
 
-.. function:: rect(r, phi)
+Power and logarithmic functions
+-------------------------------
 
-   Convert from polar coordinates to rectangular coordinates and return
-   a :class:`complex`.
+.. function:: exp(x)
 
-   .. versionadded:: 2.6
+   Return the exponential value ``e**x``.
 
 
+.. function:: log(x[, base])
 
-cmath functions
----------------
+   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.
 
-.. function:: acos(x)
+   .. versionchanged:: 2.4
+      *base* argument added.
 
-   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.
 
+.. function:: log10(x)
 
-.. function:: acosh(x)
+   Return the base-10 logarithm of *x*. This has the same branch cut as
+   :func:`log`.
 
-   Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
-   from 1 along the real axis to -∞, continuous from above.
 
+.. function:: sqrt(x)
 
-.. function:: asin(x)
+   Return the square root of *x*. This has the same branch cut as :func:`log`.
 
-   Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
 
+Trigonometric functions
+-----------------------
 
-.. function:: asinh(x)
+.. function:: acos(x)
 
-   Return the hyperbolic arc 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.
+   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.
 
-   .. versionchanged:: 2.6
-      branch cuts moved to match those recommended by the C99 standard
+
+.. function:: asin(x)
+
+   Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
 
 
 .. function:: atan(x)
@@ -130,88 +142,87 @@ cmath functions
       direction of continuity of upper cut reversed
 
 
-.. function:: atanh(x)
-
-   Return the hyperbolic arc 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.
-
-   .. versionchanged:: 2.6
-      direction of continuity of right cut reversed
-
-
 .. function:: cos(x)
 
    Return the cosine of *x*.
 
 
-.. function:: cosh(x)
+.. function:: sin(x)
 
-   Return the hyperbolic cosine of *x*.
+   Return the sine of *x*.
 
 
-.. function:: exp(x)
+.. function:: tan(x)
 
-   Return the exponential value ``e**x``.
+   Return the tangent of *x*.
 
 
-.. function:: isinf(x)
+Hyperbolic functions
+--------------------
 
-   Return *True* if the real or the imaginary part of x is positive
-   or negative infinity.
+.. function:: acosh(x)
 
-   .. versionadded:: 2.6
+   Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
+   from 1 along the real axis to -∞, continuous from above.
 
 
-.. function:: isnan(x)
+.. function:: asinh(x)
 
-   Return *True* if the real or imaginary part of x is not a number (NaN).
+   Return the hyperbolic arc 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.
 
-   .. versionadded:: 2.6
+   .. versionchanged:: 2.6
+      branch cuts moved to match those recommended by the C99 standard
 
 
-.. function:: log(x[, base])
+.. function:: atanh(x)
 
-   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.
+   Return the hyperbolic arc 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.
 
-   .. versionchanged:: 2.4
-      *base* argument added.
+   .. versionchanged:: 2.6
+      direction of continuity of right cut reversed
 
 
-.. function:: log10(x)
+.. function:: cosh(x)
 
-   Return the base-10 logarithm of *x*. This has the same branch cut as
-   :func:`log`.
+   Return the hyperbolic cosine of *x*.
 
 
-.. function:: sin(x)
+.. function:: sinh(x)
 
-   Return the sine of *x*.
+   Return the hyperbolic sine of *x*.
 
 
-.. function:: sinh(x)
+.. function:: tanh(x)
 
-   Return the hyperbolic sine of *x*.
+   Return the hyperbolic tangent of *x*.
 
 
-.. function:: sqrt(x)
+Classification functions
+------------------------
 
-   Return the square root of *x*. This has the same branch cut as :func:`log`.
+.. function:: isinf(x)
 
+   Return *True* if the real or the imaginary part of x is positive
+   or negative infinity.
 
-.. function:: tan(x)
+   .. versionadded:: 2.6
 
-   Return the tangent of *x*.
 
+.. function:: isnan(x)
 
-.. function:: tanh(x)
+   Return *True* if the real or imaginary part of x is not a number (NaN).
+
+   .. versionadded:: 2.6
 
-   Return the hyperbolic tangent of *x*.
 
-The module also defines two mathematical constants:
+Constants
+---------
 
 
 .. data:: pi