blob: 14b909bd28cc28fbfef45e53d0ae09b228741a6d [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`cmath` --- Mathematical functions for complex numbers
2===========================================================
3
4.. module:: cmath
5 :synopsis: Mathematical functions for complex numbers.
6
7
8This module is always available. It provides access to mathematical functions
9for complex numbers. The functions in this module accept integers,
10floating-point numbers or complex numbers as arguments. They will also accept
11any Python object that has either a :meth:`__complex__` or a :meth:`__float__`
12method: these methods are used to convert the object to a complex or
13floating-point number, respectively, and the function is then applied to the
14result of the conversion.
15
Christian Heimes53876d92008-04-19 00:31:39 +000016.. note::
Georg Brandl116aa622007-08-15 14:28:22 +000017
Christian Heimes53876d92008-04-19 00:31:39 +000018 On platforms with hardware and system-level support for signed
19 zeros, functions involving branch cuts are continuous on *both*
20 sides of the branch cut: the sign of the zero distinguishes one
21 side of the branch cut from the other. On platforms that do not
22 support signed zeros the continuity is as specified below.
23
24
Mark Dickinson1de22552009-07-28 16:32:56 +000025Conversions to and from polar coordinates
26-----------------------------------------
Christian Heimes53876d92008-04-19 00:31:39 +000027
Mark Dickinson1de22552009-07-28 16:32:56 +000028A Python complex number ``z`` is stored internally using *rectangular*
29or *Cartesian* coordinates. It is completely determined by its *real
30part* ``z.real`` and its *imaginary part* ``z.imag``. In other
31words::
Christian Heimes53876d92008-04-19 00:31:39 +000032
Mark Dickinson1de22552009-07-28 16:32:56 +000033 z == z.real + z.imag*1j
Christian Heimes53876d92008-04-19 00:31:39 +000034
Mark Dickinson1de22552009-07-28 16:32:56 +000035*Polar coordinates* give an alternative way to represent a complex
36number. In polar coordinates, a complex number *z* is defined by the
37modulus *r* and the phase angle *phi*. The modulus *r* is the distance
38from *z* to the origin, while the phase *phi* is the counterclockwise
Mark Dickinsoncc8e1812010-01-02 14:33:47 +000039angle, measured in radians, from the positive x-axis to the line
40segment that joins the origin to *z*.
Christian Heimes53876d92008-04-19 00:31:39 +000041
Mark Dickinson1de22552009-07-28 16:32:56 +000042The following functions can be used to convert from the native
43rectangular coordinates to polar coordinates and back.
Christian Heimes53876d92008-04-19 00:31:39 +000044
45.. function:: phase(x)
46
Mark Dickinson1de22552009-07-28 16:32:56 +000047 Return the phase of *x* (also known as the *argument* of *x*), as a
48 float. ``phase(x)`` is equivalent to ``math.atan2(x.imag,
49 x.real)``. The result lies in the range [-π, π], and the branch
50 cut for this operation lies along the negative real axis,
51 continuous from above. On systems with support for signed zeros
52 (which includes most systems in current use), this means that the
53 sign of the result is the same as the sign of ``x.imag``, even when
54 ``x.imag`` is zero::
55
56 >>> phase(complex(-1.0, 0.0))
57 3.141592653589793
58 >>> phase(complex(-1.0, -0.0))
59 -3.141592653589793
60
61
62.. note::
63
64 The modulus (absolute value) of a complex number *x* can be
65 computed using the built-in :func:`abs` function. There is no
66 separate :mod:`cmath` module function for this operation.
Christian Heimes53876d92008-04-19 00:31:39 +000067
Christian Heimes53876d92008-04-19 00:31:39 +000068
69.. function:: polar(x)
70
Mark Dickinson1de22552009-07-28 16:32:56 +000071 Return the representation of *x* in polar coordinates. Returns a
72 pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the
73 phase of *x*. ``polar(x)`` is equivalent to ``(abs(x),
74 phase(x))``.
Christian Heimes53876d92008-04-19 00:31:39 +000075
Christian Heimes53876d92008-04-19 00:31:39 +000076
77.. function:: rect(r, phi)
78
Mark Dickinson1de22552009-07-28 16:32:56 +000079 Return the complex number *x* with polar coordinates *r* and *phi*.
80 Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``.
Christian Heimes53876d92008-04-19 00:31:39 +000081
Christian Heimes53876d92008-04-19 00:31:39 +000082
Mark Dickinson1de22552009-07-28 16:32:56 +000083Power and logarithmic functions
84-------------------------------
Christian Heimes53876d92008-04-19 00:31:39 +000085
Mark Dickinson1de22552009-07-28 16:32:56 +000086.. function:: exp(x)
87
88 Return the exponential value ``e**x``.
89
90
91.. function:: log(x[, base])
92
93 Returns the logarithm of *x* to the given *base*. If the *base* is not
94 specified, returns the natural logarithm of *x*. There is one branch cut, from 0
95 along the negative real axis to -∞, continuous from above.
96
Mark Dickinson1de22552009-07-28 16:32:56 +000097
98.. function:: log10(x)
99
100 Return the base-10 logarithm of *x*. This has the same branch cut as
101 :func:`log`.
102
103
104.. function:: sqrt(x)
105
106 Return the square root of *x*. This has the same branch cut as :func:`log`.
107
108
109Trigonometric functions
110-----------------------
Georg Brandl116aa622007-08-15 14:28:22 +0000111
112.. function:: acos(x)
113
114 Return the arc cosine of *x*. There are two branch cuts: One extends right from
115 1 along the real axis to ∞, continuous from below. The other extends left from
116 -1 along the real axis to -∞, continuous from above.
117
118
Georg Brandl116aa622007-08-15 14:28:22 +0000119.. function:: asin(x)
120
121 Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
122
123
Georg Brandl116aa622007-08-15 14:28:22 +0000124.. function:: atan(x)
125
126 Return the arc tangent of *x*. There are two branch cuts: One extends from
Christian Heimes53876d92008-04-19 00:31:39 +0000127 ``1j`` along the imaginary axis to ``j``, continuous from the right. The
Georg Brandl116aa622007-08-15 14:28:22 +0000128 other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
Christian Heimes53876d92008-04-19 00:31:39 +0000129 from the left.
130
Georg Brandl116aa622007-08-15 14:28:22 +0000131
Mark Dickinson1de22552009-07-28 16:32:56 +0000132.. function:: cos(x)
133
134 Return the cosine of *x*.
135
136
137.. function:: sin(x)
138
139 Return the sine of *x*.
140
141
142.. function:: tan(x)
143
144 Return the tangent of *x*.
145
146
147Hyperbolic functions
148--------------------
149
150.. function:: acosh(x)
151
152 Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
153 from 1 along the real axis to -∞, continuous from above.
154
155
156.. function:: asinh(x)
157
158 Return the hyperbolic arc sine of *x*. There are two branch cuts:
159 One extends from ``1j`` along the imaginary axis to ``j``,
160 continuous from the right. The other extends from ``-1j`` along
161 the imaginary axis to ``-∞j``, continuous from the left.
162
163
Georg Brandl116aa622007-08-15 14:28:22 +0000164.. function:: atanh(x)
165
166 Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
Christian Heimes53876d92008-04-19 00:31:39 +0000167 extends from ``1`` along the real axis to ````, continuous from below. The
Georg Brandl116aa622007-08-15 14:28:22 +0000168 other extends from ``-1`` along the real axis to ``-∞``, continuous from
Christian Heimes53876d92008-04-19 00:31:39 +0000169 above.
170
Georg Brandl116aa622007-08-15 14:28:22 +0000171
Georg Brandl116aa622007-08-15 14:28:22 +0000172.. function:: cosh(x)
173
174 Return the hyperbolic cosine of *x*.
175
176
Mark Dickinson1de22552009-07-28 16:32:56 +0000177.. function:: sinh(x)
Georg Brandl116aa622007-08-15 14:28:22 +0000178
Mark Dickinson1de22552009-07-28 16:32:56 +0000179 Return the hyperbolic sine of *x*.
Georg Brandl116aa622007-08-15 14:28:22 +0000180
181
Mark Dickinson1de22552009-07-28 16:32:56 +0000182.. function:: tanh(x)
183
184 Return the hyperbolic tangent of *x*.
185
186
187Classification functions
188------------------------
189
Christian Heimes53876d92008-04-19 00:31:39 +0000190.. function:: isinf(x)
191
192 Return *True* if the real or the imaginary part of x is positive
193 or negative infinity.
194
Christian Heimes53876d92008-04-19 00:31:39 +0000195
196.. function:: isnan(x)
197
198 Return *True* if the real or imaginary part of x is not a number (NaN).
199
Christian Heimes53876d92008-04-19 00:31:39 +0000200
Mark Dickinson1de22552009-07-28 16:32:56 +0000201Constants
202---------
Georg Brandl116aa622007-08-15 14:28:22 +0000203
204
205.. data:: pi
206
Mark Dickinson1de22552009-07-28 16:32:56 +0000207 The mathematical constant *π*, as a float.
Georg Brandl116aa622007-08-15 14:28:22 +0000208
209
210.. data:: e
211
212 The mathematical constant *e*, as a float.
213
214.. index:: module: math
215
216Note that the selection of functions is similar, but not identical, to that in
217module :mod:`math`. The reason for having two modules is that some users aren't
218interested in complex numbers, and perhaps don't even know what they are. They
219would rather have ``math.sqrt(-1)`` raise an exception than return a complex
220number. Also note that the functions defined in :mod:`cmath` always return a
221complex number, even if the answer can be expressed as a real number (in which
222case the complex number has an imaginary part of zero).
223
224A note on branch cuts: They are curves along which the given function fails to
225be continuous. They are a necessary feature of many complex functions. It is
226assumed that if you need to compute with complex functions, you will understand
227about branch cuts. Consult almost any (not too elementary) book on complex
228variables for enlightenment. For information of the proper choice of branch
229cuts for numerical purposes, a good reference should be the following:
230
231
232.. seealso::
233
234 Kahan, W: Branch cuts for complex elementary functions; or, Much ado about
235 nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art
236 in numerical analysis. Clarendon Press (1987) pp165-211.
237
Christian Heimes53876d92008-04-19 00:31:39 +0000238