diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst index 8761c886b80..b50ca5ebfc4 100644 --- a/Doc/library/cmath.rst +++ b/Doc/library/cmath.rst @@ -22,66 +22,95 @@ 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 plain 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 - - x := real(z) - y := imag(z) - -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 *-π*. - -.. 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*. - - -Definition:: - - 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) +*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*. +The following functions can be used to convert from the native +rectangular coordinates to polar coordinates and back. .. function:: phase(x) - Return phase, also known as the argument, of a complex. + 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.141592653589793 + >>> phase(complex(-1.0, -0.0)) + -3.141592653589793 + + +.. 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:: polar(x) - 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 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))``. .. function:: rect(r, phi) - Convert from polar coordinates to rectangular coordinates and return - a :class:`complex`. + Return the complex number *x* with polar coordinates *r* and *phi*. + Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``. +Power and logarithmic functions +------------------------------- -cmath functions ---------------- +.. function:: exp(x) + + Return the exponential value ``e**x``. + + +.. 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. + + .. versionchanged:: 2.4 + *base* argument added. + + +.. function:: log10(x) + + Return the base-10 logarithm of *x*. This has the same branch cut as + :func:`log`. + + +.. function:: sqrt(x) + + Return the square root of *x*. This has the same branch cut as :func:`log`. + + +Trigonometric functions +----------------------- .. function:: acos(x) @@ -90,25 +119,11 @@ cmath functions -1 along the real axis to -∞, continuous from above. -.. function:: acosh(x) - - 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:: asin(x) Return the arc sine of *x*. This has the same branch cuts as :func:`acos`. -.. function:: asinh(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. - - .. function:: atan(x) Return the arc tangent of *x*. There are two branch cuts: One extends from @@ -117,6 +132,38 @@ cmath functions from the left. +.. function:: cos(x) + + Return the cosine of *x*. + + +.. function:: sin(x) + + Return the sine of *x*. + + +.. function:: tan(x) + + Return the tangent of *x*. + + +Hyperbolic functions +-------------------- + +.. function:: acosh(x) + + 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:: asinh(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. + + .. function:: atanh(x) Return the hyperbolic arc tangent of *x*. There are two branch cuts: One @@ -125,21 +172,24 @@ cmath functions above. -.. function:: cos(x) - - Return the cosine of *x*. - - .. function:: cosh(x) Return the hyperbolic cosine of *x*. -.. function:: exp(x) +.. function:: sinh(x) - Return the exponential value ``e**x``. + Return the hyperbolic sine of *x*. +.. function:: tanh(x) + + Return the hyperbolic tangent of *x*. + + +Classification functions +------------------------ + .. function:: isinf(x) Return *True* if the real or the imaginary part of x is positive @@ -151,49 +201,13 @@ cmath functions Return *True* if the real or imaginary part of x is not a number (NaN). -.. 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. - - -.. function:: log10(x) - - Return the base-10 logarithm of *x*. This has the same branch cut as - :func:`log`. - - -.. function:: sin(x) - - Return the sine of *x*. - - -.. function:: sinh(x) - - Return the hyperbolic sine of *x*. - - -.. function:: sqrt(x) - - Return the square root of *x*. This has the same branch cut as :func:`log`. - - -.. function:: tan(x) - - Return the tangent of *x*. - - -.. function:: tanh(x) - - Return the hyperbolic tangent of *x*. - -The module also defines two mathematical constants: +Constants +--------- .. data:: pi - The mathematical constant *pi*, as a float. + The mathematical constant *π*, as a float. .. data:: e