Debian Codegraph @

Doc/library/cmath.rst

raw
1 :mod:`!cmath` --- Mathematical functions for complex numbers
2 ============================================================
3
4 .. module:: cmath
5 :synopsis: Mathematical functions for complex numbers.
6
7 --------------
8
9 This module provides access to mathematical functions for complex numbers. The
10 functions in this module accept integers, floating-point numbers or complex
11 numbers as arguments. They will also accept any Python object that has either a
12 :meth:`~object.__complex__` or a :meth:`~object.__float__` method: these methods are used to
13 convert the object to a complex or floating-point number, respectively, and
14 the function is then applied to the result of the conversion.
15
16 .. note::
17
18 For functions involving branch cuts, we have the problem of deciding how to
19 define those functions on the cut itself. Following Kahan's "Branch cuts for
20 complex elementary functions" paper, as well as Annex G of C99 and later C
21 standards, we use the sign of zero to distinguish one side of the branch cut
22 from the other: for a branch cut along (a portion of) the real axis we look
23 at the sign of the imaginary part, while for a branch cut along the
24 imaginary axis we look at the sign of the real part.
25
26 For example, the :func:`cmath.sqrt` function has a branch cut along the
27 negative real axis. An argument of ``-2-0j`` is treated as
28 though it lies *below* the branch cut, and so gives a result on the negative
29 imaginary axis::
30
31 >>> cmath.sqrt(-2-0j)
32 -1.4142135623730951j
33
34 But an argument of ``-2+0j`` is treated as though it lies above
35 the branch cut::
36
37 >>> cmath.sqrt(-2+0j)
38 1.4142135623730951j
39
40
41 ==================================================== ============================================
42 **Conversions to and from polar coordinates**
43 --------------------------------------------------------------------------------------------------
44 :func:`phase(z) <phase>` Return the phase of *z*
45 :func:`polar(z) <polar>` Return the representation of *z* in polar coordinates
46 :func:`rect(r, phi) <rect>` Return the complex number *z* with polar coordinates *r* and *phi*
47
48 **Power and logarithmic functions**
49 --------------------------------------------------------------------------------------------------
50 :func:`exp(z) <exp>` Return *e* raised to the power *z*
51 :func:`log(z[, base]) <log>` Return the logarithm of *z* to the given *base* (*e* by default)
52 :func:`log10(z) <log10>` Return the base-10 logarithm of *z*
53 :func:`sqrt(z) <sqrt>` Return the square root of *z*
54
55 **Trigonometric functions**
56 --------------------------------------------------------------------------------------------------
57 :func:`acos(z) <acos>` Return the arc cosine of *z*
58 :func:`asin(z) <asin>` Return the arc sine of *z*
59 :func:`atan(z) <atan>` Return the arc tangent of *z*
60 :func:`cos(z) <cos>` Return the cosine of *z*
61 :func:`sin(z) <sin>` Return the sine of *z*
62 :func:`tan(z) <tan>` Return the tangent of *z*
63
64 **Hyperbolic functions**
65 --------------------------------------------------------------------------------------------------
66 :func:`acosh(z) <acosh>` Return the inverse hyperbolic cosine of *z*
67 :func:`asinh(z) <asinh>` Return the inverse hyperbolic sine of *z*
68 :func:`atanh(z) <atanh>` Return the inverse hyperbolic tangent of *z*
69 :func:`cosh(z) <cosh>` Return the hyperbolic cosine of *z*
70 :func:`sinh(z) <sinh>` Return the hyperbolic sine of *z*
71 :func:`tanh(z) <tanh>` Return the hyperbolic tangent of *z*
72
73 **Classification functions**
74 --------------------------------------------------------------------------------------------------
75 :func:`isfinite(z) <isfinite>` Check if all components of *z* are finite
76 :func:`isinf(z) <isinf>` Check if any component of *z* is infinite
77 :func:`isnan(z) <isnan>` Check if any component of *z* is a NaN
78 :func:`isclose(a, b, *, rel_tol, abs_tol) <isclose>` Check if the values *a* and *b* are close to each other
79
80 **Constants**
81 --------------------------------------------------------------------------------------------------
82 :data:`pi` *π* = 3.141592...
83 :data:`e` *e* = 2.718281...
84 :data:`tau` *τ* = 2\ *π* = 6.283185...
85 :data:`inf` Positive infinity
86 :data:`infj` Pure imaginary infinity
87 :data:`nan` "Not a number" (NaN)
88 :data:`nanj` Pure imaginary NaN
89 ==================================================== ============================================
90
91
92 Conversions to and from polar coordinates
93 -----------------------------------------
94
95 A Python complex number ``z`` is stored internally using *rectangular*
96 or *Cartesian* coordinates. It is completely determined by its *real
97 part* ``z.real`` and its *imaginary part* ``z.imag``.
98
99 *Polar coordinates* give an alternative way to represent a complex
100 number. In polar coordinates, a complex number *z* is defined by the
101 modulus *r* and the phase angle *phi*. The modulus *r* is the distance
102 from *z* to the origin, while the phase *phi* is the counterclockwise
103 angle, measured in radians, from the positive x-axis to the line
104 segment that joins the origin to *z*.
105
106 The following functions can be used to convert from the native
107 rectangular coordinates to polar coordinates and back.
108
109 .. function:: phase(z)
110
111 Return the phase of *z* (also known as the *argument* of *z*), as a float.
112 ``phase(z)`` is equivalent to ``math.atan2(z.imag, z.real)``. The result
113 lies in the range [-\ *π*, *π*], and the branch cut for this operation lies
114 along the negative real axis. The sign of the result is the same as the
115 sign of ``z.imag``, even when ``z.imag`` is zero::
116
117 >>> phase(-1+0j)
118 3.141592653589793
119 >>> phase(-1-0j)
120 -3.141592653589793
121
122
123 .. note::
124
125 The modulus (absolute value) of a complex number *z* can be
126 computed using the built-in :func:`abs` function. There is no
127 separate :mod:`!cmath` module function for this operation.
128
129
130 .. function:: polar(z)
131
132 Return the representation of *z* in polar coordinates. Returns a
133 pair ``(r, phi)`` where *r* is the modulus of *z* and *phi* is the
134 phase of *z*. ``polar(z)`` is equivalent to ``(abs(z),
135 phase(z))``.
136
137
138 .. function:: rect(r, phi)
139
140 Return the complex number *z* with polar coordinates *r* and *phi*.
141 Equivalent to ``complex(r * math.cos(phi), r * math.sin(phi))``.
142
143
144 Power and logarithmic functions
145 -------------------------------
146
147 .. function:: exp(z)
148
149 Return *e* raised to the power *z*, where *e* is the base of natural
150 logarithms.
151
152
153 .. function:: log(z[, base])
154
155 Return the logarithm of *z* to the given *base*. If the *base* is not
156 specified, returns the natural logarithm of *z*. There is one branch cut,
157 from 0 along the negative real axis to -∞.
158
159
160 .. function:: log10(z)
161
162 Return the base-10 logarithm of *z*. This has the same branch cut as
163 :func:`log`.
164
165
166 .. function:: sqrt(z)
167
168 Return the square root of *z*. This has the same branch cut as :func:`log`.
169
170
171 Trigonometric functions
172 -----------------------
173
174 .. function:: acos(z)
175
176 Return the arc cosine of *z*. There are two branch cuts: One extends right
177 from 1 along the real axis to ∞. The other extends left from -1 along the
178 real axis to -∞.
179
180
181 .. function:: asin(z)
182
183 Return the arc sine of *z*. This has the same branch cuts as :func:`acos`.
184
185
186 .. function:: atan(z)
187
188 Return the arc tangent of *z*. There are two branch cuts: One extends from
189 ``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j``
190 along the imaginary axis to ``-∞j``.
191
192
193 .. function:: cos(z)
194
195 Return the cosine of *z*.
196
197
198 .. function:: sin(z)
199
200 Return the sine of *z*.
201
202
203 .. function:: tan(z)
204
205 Return the tangent of *z*.
206
207
208 Hyperbolic functions
209 --------------------
210
211 .. function:: acosh(z)
212
213 Return the inverse hyperbolic cosine of *z*. There is one branch cut,
214 extending left from 1 along the real axis to -∞.
215
216
217 .. function:: asinh(z)
218
219 Return the inverse hyperbolic sine of *z*. There are two branch cuts:
220 One extends from ``1j`` along the imaginary axis to ``∞j``. The other
221 extends from ``-1j`` along the imaginary axis to ``-∞j``.
222
223
224 .. function:: atanh(z)
225
226 Return the inverse hyperbolic tangent of *z*. There are two branch cuts: One
227 extends from ``1`` along the real axis to ``∞``. The other extends from
228 ``-1`` along the real axis to ``-∞``.
229
230
231 .. function:: cosh(z)
232
233 Return the hyperbolic cosine of *z*.
234
235
236 .. function:: sinh(z)
237
238 Return the hyperbolic sine of *z*.
239
240
241 .. function:: tanh(z)
242
243 Return the hyperbolic tangent of *z*.
244
245
246 Classification functions
247 ------------------------
248
249 .. function:: isfinite(z)
250
251 Return ``True`` if both the real and imaginary parts of *z* are finite, and
252 ``False`` otherwise.
253
254 .. versionadded:: 3.2
255
256
257 .. function:: isinf(z)
258
259 Return ``True`` if either the real or the imaginary part of *z* is an
260 infinity, and ``False`` otherwise.
261
262
263 .. function:: isnan(z)
264
265 Return ``True`` if either the real or the imaginary part of *z* is a NaN,
266 and ``False`` otherwise.
267
268
269 .. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)
270
271 Return ``True`` if the values *a* and *b* are close to each other and
272 ``False`` otherwise.
273
274 Whether or not two values are considered close is determined according to
275 given absolute and relative tolerances. If no errors occur, the result will
276 be: ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``.
277
278 *rel_tol* is the relative tolerance -- it is the maximum allowed difference
279 between *a* and *b*, relative to the larger absolute value of *a* or *b*.
280 For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default
281 tolerance is ``1e-09``, which assures that the two values are the same
282 within about 9 decimal digits. *rel_tol* must be nonnegative and less
283 than ``1.0``.
284
285 *abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be
286 nonnegative. When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed
287 as ``abs(x) <= rel_tol * abs(x)``, which is ``False`` for any ``x`` and
288 rel_tol less than ``1.0``. So add an appropriate positive abs_tol argument
289 to the call.
290
291 The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be
292 handled according to IEEE rules. Specifically, ``NaN`` is not considered
293 close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only
294 considered close to themselves.
295
296 .. versionadded:: 3.5
297
298 .. seealso::
299
300 :pep:`485` -- A function for testing approximate equality
301
302
303 Constants
304 ---------
305
306 .. data:: pi
307
308 The mathematical constant *π*, as a float.
309
310
311 .. data:: e
312
313 The mathematical constant *e*, as a float.
314
315
316 .. data:: tau
317
318 The mathematical constant *τ*, as a float.
319
320 .. versionadded:: 3.6
321
322
323 .. data:: inf
324
325 Floating-point positive infinity. Equivalent to ``float('inf')``.
326
327 .. versionadded:: 3.6
328
329
330 .. data:: infj
331
332 Complex number with zero real part and positive infinity imaginary
333 part. Equivalent to ``complex(0.0, float('inf'))``.
334
335 .. versionadded:: 3.6
336
337
338 .. data:: nan
339
340 A floating-point "not a number" (NaN) value. Equivalent to
341 ``float('nan')``. See also :data:`math.nan`.
342
343 .. versionadded:: 3.6
344
345
346 .. data:: nanj
347
348 Complex number with zero real part and NaN imaginary part. Equivalent to
349 ``complex(0.0, float('nan'))``.
350
351 .. versionadded:: 3.6
352
353
354 .. index:: pair: module; math
355
356 Note that the selection of functions is similar, but not identical, to that in
357 module :mod:`math`. The reason for having two modules is that some users aren't
358 interested in complex numbers, and perhaps don't even know what they are. They
359 would rather have ``math.sqrt(-1)`` raise an exception than return a complex
360 number. Also note that the functions defined in :mod:`!cmath` always return a
361 complex number, even if the answer can be expressed as a real number (in which
362 case the complex number has an imaginary part of zero).
363
364 A note on branch cuts: They are curves along which the given function fails to
365 be continuous. They are a necessary feature of many complex functions. It is
366 assumed that if you need to compute with complex functions, you will understand
367 about branch cuts. Consult almost any (not too elementary) book on complex
368 variables for enlightenment. For information of the proper choice of branch
369 cuts for numerical purposes, a good reference should be the following:
370
371
372 .. seealso::
373
374 Kahan, W: Branch cuts for complex elementary functions; or, Much ado about
375 nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art
376 in numerical analysis. Clarendon Press (1987) pp165--211.