Merged revisions 74184,74230 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk ........ r74184 | georg.brandl | 2009-07-23 08:08:58 +0100 (Thu, 23 Jul 2009) | 1 line #6548: dont suggest existence of real and imag functions in cmath. ........ r74230 | mark.dickinson | 2009-07-28 17:12:40 +0100 (Tue, 28 Jul 2009) | 4 lines 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. ........
This commit is contained in:
parent
30006c76f4
commit
f8edb67f09
|
@ -23,154 +23,78 @@ result of the conversion.
|
||||||
support signed zeros the continuity is as specified below.
|
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.
|
A Python complex number ``z`` is stored internally using *rectangular*
|
||||||
Python's :class:`complex` type uses rectangular coordinates where a number
|
or *Cartesian* coordinates. It is completely determined by its *real
|
||||||
on the complex plain is defined by two floats, the real part and the imaginary
|
part* ``z.real`` and its *imaginary part* ``z.imag``. In other
|
||||||
part.
|
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
|
||||||
x := real(z)
|
modulus *r* and the phase angle *phi*. The modulus *r* is the distance
|
||||||
y := imag(z)
|
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
|
||||||
In engineering the polar coordinate system is popular for complex numbers. In
|
origin to *z*.
|
||||||
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)
|
|
||||||
|
|
||||||
|
The following functions can be used to convert from the native
|
||||||
|
rectangular coordinates to polar coordinates and back.
|
||||||
|
|
||||||
.. function:: phase(x)
|
.. 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.1415926535897931
|
||||||
|
>>> phase(complex(-1.0, -0.0))
|
||||||
|
-3.1415926535897931
|
||||||
|
|
||||||
.. versionadded:: 2.6
|
.. versionadded:: 2.6
|
||||||
|
|
||||||
|
|
||||||
|
.. 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)
|
.. function:: polar(x)
|
||||||
|
|
||||||
Convert a :class:`complex` from rectangular coordinates to polar
|
Return the representation of *x* in polar coordinates. Returns a
|
||||||
coordinates. The function returns a tuple with the two elements
|
pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the
|
||||||
*r* and *phi*. *r* is the distance from 0 and *phi* the phase
|
phase of *x*. ``polar(x)`` is equivalent to ``(abs(x),
|
||||||
angle.
|
phase(x))``.
|
||||||
|
|
||||||
.. versionadded:: 2.6
|
.. versionadded:: 2.6
|
||||||
|
|
||||||
|
|
||||||
.. function:: rect(r, phi)
|
.. function:: rect(r, phi)
|
||||||
|
|
||||||
Convert from polar coordinates to rectangular coordinates and return
|
Return the complex number *x* with polar coordinates *r* and *phi*.
|
||||||
a :class:`complex`.
|
Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``.
|
||||||
|
|
||||||
.. versionadded:: 2.6
|
.. versionadded:: 2.6
|
||||||
|
|
||||||
|
|
||||||
|
Power and logarithmic functions
|
||||||
cmath 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.
|
|
||||||
|
|
||||||
|
|
||||||
.. 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.
|
|
||||||
|
|
||||||
.. versionchanged:: 2.6
|
|
||||||
branch cuts moved to match those recommended by the C99 standard
|
|
||||||
|
|
||||||
|
|
||||||
.. 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.
|
|
||||||
|
|
||||||
.. versionchanged:: 2.6
|
|
||||||
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)
|
|
||||||
|
|
||||||
Return the hyperbolic cosine of *x*.
|
|
||||||
|
|
||||||
|
|
||||||
.. function:: exp(x)
|
.. function:: exp(x)
|
||||||
|
|
||||||
Return the exponential value ``e**x``.
|
Return the exponential value ``e**x``.
|
||||||
|
|
||||||
|
|
||||||
.. function:: isinf(x)
|
|
||||||
|
|
||||||
Return *True* if the real or the imaginary part of x is positive
|
|
||||||
or negative infinity.
|
|
||||||
|
|
||||||
.. versionadded:: 2.6
|
|
||||||
|
|
||||||
|
|
||||||
.. function:: isnan(x)
|
|
||||||
|
|
||||||
Return *True* if the real or imaginary part of x is not a number (NaN).
|
|
||||||
|
|
||||||
.. versionadded:: 2.6
|
|
||||||
|
|
||||||
|
|
||||||
.. function:: log(x[, base])
|
.. function:: log(x[, base])
|
||||||
|
|
||||||
Returns the logarithm of *x* to the given *base*. If the *base* is not
|
Returns the logarithm of *x* to the given *base*. If the *base* is not
|
||||||
|
@ -187,36 +111,123 @@ cmath functions
|
||||||
:func:`log`.
|
:func:`log`.
|
||||||
|
|
||||||
|
|
||||||
.. function:: sin(x)
|
|
||||||
|
|
||||||
Return the sine of *x*.
|
|
||||||
|
|
||||||
|
|
||||||
.. function:: sinh(x)
|
|
||||||
|
|
||||||
Return the hyperbolic sine of *x*.
|
|
||||||
|
|
||||||
|
|
||||||
.. function:: sqrt(x)
|
.. function:: sqrt(x)
|
||||||
|
|
||||||
Return the square root of *x*. This has the same branch cut as :func:`log`.
|
Return the square root of *x*. This has the same branch cut as :func:`log`.
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
``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.
|
||||||
|
|
||||||
|
.. versionchanged:: 2.6
|
||||||
|
direction of continuity of upper cut reversed
|
||||||
|
|
||||||
|
|
||||||
|
.. function:: cos(x)
|
||||||
|
|
||||||
|
Return the cosine of *x*.
|
||||||
|
|
||||||
|
|
||||||
|
.. function:: sin(x)
|
||||||
|
|
||||||
|
Return the sine of *x*.
|
||||||
|
|
||||||
|
|
||||||
.. function:: tan(x)
|
.. function:: tan(x)
|
||||||
|
|
||||||
Return the tangent of *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.
|
||||||
|
|
||||||
|
.. versionchanged:: 2.6
|
||||||
|
branch cuts moved to match those recommended by the C99 standard
|
||||||
|
|
||||||
|
|
||||||
|
.. 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:: cosh(x)
|
||||||
|
|
||||||
|
Return the hyperbolic cosine of *x*.
|
||||||
|
|
||||||
|
|
||||||
|
.. function:: sinh(x)
|
||||||
|
|
||||||
|
Return the hyperbolic sine of *x*.
|
||||||
|
|
||||||
|
|
||||||
.. function:: tanh(x)
|
.. function:: tanh(x)
|
||||||
|
|
||||||
Return the hyperbolic tangent of *x*.
|
Return the hyperbolic tangent of *x*.
|
||||||
|
|
||||||
The module also defines two mathematical constants:
|
|
||||||
|
Classification functions
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
.. function:: isinf(x)
|
||||||
|
|
||||||
|
Return *True* if the real or the imaginary part of x is positive
|
||||||
|
or negative infinity.
|
||||||
|
|
||||||
|
.. versionadded:: 2.6
|
||||||
|
|
||||||
|
|
||||||
|
.. function:: isnan(x)
|
||||||
|
|
||||||
|
Return *True* if the real or imaginary part of x is not a number (NaN).
|
||||||
|
|
||||||
|
.. versionadded:: 2.6
|
||||||
|
|
||||||
|
|
||||||
|
Constants
|
||||||
|
---------
|
||||||
|
|
||||||
|
|
||||||
.. data:: pi
|
.. data:: pi
|
||||||
|
|
||||||
The mathematical constant *pi*, as a float.
|
The mathematical constant *π*, as a float.
|
||||||
|
|
||||||
|
|
||||||
.. data:: e
|
.. data:: e
|
||||||
|
|
Loading…
Reference in New Issue