rest25/library/cmath.rst => rest262/library/cmath.rst
2:mod:`cmath` --- Mathematical functions for complex numbers
3===========================================================
4
5.. module:: cmath
6   :synopsis: Mathematical functions for complex numbers.
7
8
9This module is always available.  It provides access to mathematical functions
n10-for complex numbers.  The functions are:
n10+for complex numbers.  The functions in this module accept integers,
11+floating-point numbers or complex numbers as arguments. They will also accept
12+any Python object that has either a :meth:`__complex__` or a :meth:`__float__`
13+method: these methods are used to convert the object to a complex or
14+floating-point number, respectively, and the function is then applied to the
15+result of the conversion.
11
n17+.. note::
18+ 
19+   On platforms with hardware and system-level support for signed
20+   zeros, functions involving branch cuts are continuous on *both*
21+   sides of the branch cut: the sign of the zero distinguishes one
22+   side of the branch cut from the other.  On platforms that do not
23+   support signed zeros the continuity is as specified below.
24+ 
25+ 
26+Complex coordinates
27+-------------------
28+ 
29+Complex numbers can be expressed by two important coordinate systems.
30+Python's :class:`complex` type uses rectangular coordinates where a number
31+on the complex plain is defined by two floats, the real part and the imaginary
32+part.
33+ 
34+Definition::
35+ 
36+   z = x + 1j * y
37+ 
38+   x := real(z)
39+   y := imag(z)
40+ 
41+In engineering the polar coordinate system is popular for complex numbers. In
42+polar coordinates a complex number is defined by the radius *r* and the phase
43+angle *phi*. The radius *r* is the absolute value of the complex, which can be
44+viewed as distance from (0, 0). The radius *r* is always 0 or a positive float.
45+The phase angle *phi* is the counter clockwise angle from the positive x axis,
46+e.g. *1* has the angle *0*, *1j* has the angle *π/2* and *-1* the angle *-π*.
47+ 
48+.. note::
49+   While :func:`phase` and func:`polar` return *+π* for a negative real they
50+   may return *-π* for a complex with a very small negative imaginary
51+   part, e.g. *-1-1E-300j*.
52+ 
53+ 
54+Definition::
55+ 
56+   z = r * exp(1j * phi)
57+   z = r * cis(phi)
58+ 
59+   r := abs(z) := sqrt(real(z)**2 + imag(z)**2)
60+   phi := phase(z) := atan2(imag(z), real(z))
61+   cis(phi) := cos(phi) + 1j * sin(phi)
62+ 
63+ 
64+.. function:: phase(x)
65+ 
66+   Return phase, also known as the argument, of a complex.
67+ 
68+   .. versionadded:: 2.6
69+ 
70+ 
71+.. function:: polar(x)
72+ 
73+   Convert a :class:`complex` from rectangular coordinates to polar
74+   coordinates. The function returns a tuple with the two elements
75+   *r* and *phi*. *r* is the distance from 0 and *phi* the phase
76+   angle.
77+ 
78+   .. versionadded:: 2.6
79+ 
80+ 
81+.. function:: rect(r, phi)
82+ 
83+   Convert from polar coordinates to rectangular coordinates and return
84+   a :class:`complex`.
85+ 
86+   .. versionadded:: 2.6
87+ 
88+ 
89+ 
90+cmath functions
91+---------------
12
13.. function:: acos(x)
14
15   Return the arc cosine of *x*. There are two branch cuts: One extends right from
16   1 along the real axis to ∞, continuous from below. The other extends left from
17   -1 along the real axis to -∞, continuous from above.
18
19
25
26.. function:: asin(x)
27
28   Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
29
30
31.. function:: asinh(x)
32
n33-   Return the hyperbolic arc sine of *x*. There are two branch cuts, extending left
n113+   Return the hyperbolic arc sine of *x*. There are two branch cuts:
34-   from ±``1j`` to ±-∞``j``, both continuous from above. These branch cuts should
114+   One extends from ``1j`` along the imaginary axis to ``∞j``,
35-   be considered a bug to be corrected in a future release. The correct branch cuts
115+   continuous from the right.  The other extends from ``-1j`` along
36-   should extend along the imaginary axis, one from ``1j`` up to ∞``j`` and
116+   the imaginary axis to ``-∞j``, continuous from the left.
37-   continuous from the right, and one from -\ ``1j`` down to -∞``j`` and continuous
117+ 
118+   .. versionchanged:: 2.6
119+      branch cuts moved to match those recommended by the C99 standard
120+ 
121+ 
122+.. function:: atan(x)
123+ 
124+   Return the arc tangent of *x*. There are two branch cuts: One extends from
125+   ``1j`` along the imaginary axis to ``∞j``, continuous from the right. The
126+   other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
38   from the left.
39
n40- 
n129+   .. versionchanged:: 2.6
41-.. function:: atan(x)
130+      direction of continuity of upper cut reversed
42- 
43-   Return the arc tangent of *x*. There are two branch cuts: One extends from
44-   ``1j`` along the imaginary axis to ∞``j``, continuous from the left. The other
45-   extends from -\ ``1j`` along the imaginary axis to -∞``j``, continuous from the
46-   left. (This should probably be changed so the upper cut becomes continuous from
47-   the other side.)
48
49
50.. function:: atanh(x)
51
n52-   Return the hyperbolic arc tangent of *x*. There are two branch cuts: One extends
n135+   Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
53-   from 1 along the real axis to ∞, continuous from above. The other extends from
136+   extends from ``1`` along the real axis to ``∞``, continuous from below. The
54-   -1 along the real axis to -∞, continuous from above. (This should probably be
137+   other extends from ``-1`` along the real axis to ``-∞``, continuous from
55-   changed so the right cut becomes continuous from the other side.)
138+   above.
139+ 
140+   .. versionchanged:: 2.6
141+      direction of continuity of right cut reversed
56
57
58.. function:: cos(x)
59
60   Return the cosine of *x*.
61
62
63.. function:: cosh(x)
64
65   Return the hyperbolic cosine of *x*.
66
67
68.. function:: exp(x)
69
70   Return the exponential value ``e**x``.
n157+ 
158+ 
159+.. function:: isinf(x)
160+ 
161+   Return *True* if the real or the imaginary part of x is positive
162+   or negative infinity.
163+ 
164+   .. versionadded:: 2.6
165+ 
166+ 
167+.. function:: isnan(x)
168+ 
169+   Return *True* if the real or imaginary part of x is not a number (NaN).
170+ 
171+   .. versionadded:: 2.6
71
72
73.. function:: log(x[, base])
74
75   Returns the logarithm of *x* to the given *base*. If the *base* is not
76   specified, returns the natural logarithm of *x*. There is one branch cut, from 0
77   along the negative real axis to -∞, continuous from above.
78
110
111   Return the hyperbolic tangent of *x*.
112
113The module also defines two mathematical constants:
114
115
116.. data:: pi
117
n118-   The mathematical constant *pi*, as a real.
n219+   The mathematical constant *pi*, as a float.
119
120
121.. data:: e
122
n123-   The mathematical constant *e*, as a real.
n224+   The mathematical constant *e*, as a float.
124
125.. index:: module: math
126
127Note that the selection of functions is similar, but not identical, to that in
128module :mod:`math`.  The reason for having two modules is that some users aren't
129interested in complex numbers, and perhaps don't even know what they are.  They
130would rather have ``math.sqrt(-1)`` raise an exception than return a complex
131number. Also note that the functions defined in :mod:`cmath` always return a
141
142
143.. seealso::
144
145   Kahan, W:  Branch cuts for complex elementary functions; or, Much ado about
146   nothing's sign bit.  In Iserles, A., and Powell, M. (eds.), The state of the art
147   in numerical analysis. Clarendon Press (1987) pp165-211.
148
t250+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op