Index: Doc/library/cmath.rst =================================================================== --- Doc/library/cmath.rst (revision 74184) +++ Doc/library/cmath.rst (working copy) @@ -23,102 +23,114 @@ 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 -Definition:: + .. versionadded:: 2.6 - z = r * exp(1j * phi) - z = r * cis(phi) - 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) +.. note:: + 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) - Return phase, also known as the argument, of a complex. +.. function:: polar(x) + 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) Return the arc tangent of *x*. There are two branch cuts: One extends from @@ -130,90 +142,89 @@ 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). - Return the hyperbolic tangent of *x*. + .. versionadded:: 2.6 -The module also defines two mathematical constants: +Constants +--------- + .. data:: pi The mathematical constant *π*, as a float.