Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`cmath` --- Mathematical functions for complex numbers |
| 2 | =========================================================== |
| 3 | |
| 4 | .. module:: cmath |
| 5 | :synopsis: Mathematical functions for complex numbers. |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | This module is always available. It provides access to mathematical functions |
| 10 | 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. |
| 16 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 17 | .. note:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 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 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 26 | Conversions to and from polar coordinates |
| 27 | ----------------------------------------- |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 28 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 29 | A Python complex number ``z`` is stored internally using *rectangular* |
| 30 | or *Cartesian* coordinates. It is completely determined by its *real |
| 31 | part* ``z.real`` and its *imaginary part* ``z.imag``. In other |
| 32 | words:: |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 33 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 34 | z == z.real + z.imag*1j |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 35 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 36 | *Polar coordinates* give an alternative way to represent a complex |
| 37 | number. In polar coordinates, a complex number *z* is defined by the |
| 38 | modulus *r* and the phase angle *phi*. The modulus *r* is the distance |
| 39 | from *z* to the origin, while the phase *phi* is the counterclockwise |
Mark Dickinson | 5251cce | 2010-01-02 14:33:10 +0000 | [diff] [blame] | 40 | angle, measured in radians, from the positive x-axis to the line |
| 41 | segment that joins the origin to *z*. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 42 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 43 | The following functions can be used to convert from the native |
| 44 | rectangular coordinates to polar coordinates and back. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 45 | |
| 46 | .. function:: phase(x) |
| 47 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 48 | Return the phase of *x* (also known as the *argument* of *x*), as a |
| 49 | float. ``phase(x)`` is equivalent to ``math.atan2(x.imag, |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 50 | x.real)``. The result lies in the range [-\ *π*, *π*], and the branch |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 51 | cut for this operation lies along the negative real axis, |
| 52 | continuous from above. On systems with support for signed zeros |
| 53 | (which includes most systems in current use), this means that the |
| 54 | sign of the result is the same as the sign of ``x.imag``, even when |
| 55 | ``x.imag`` is zero:: |
| 56 | |
| 57 | >>> phase(complex(-1.0, 0.0)) |
| 58 | 3.141592653589793 |
| 59 | >>> phase(complex(-1.0, -0.0)) |
| 60 | -3.141592653589793 |
| 61 | |
| 62 | |
| 63 | .. note:: |
| 64 | |
| 65 | The modulus (absolute value) of a complex number *x* can be |
| 66 | computed using the built-in :func:`abs` function. There is no |
| 67 | separate :mod:`cmath` module function for this operation. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 68 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 69 | |
| 70 | .. function:: polar(x) |
| 71 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 72 | Return the representation of *x* in polar coordinates. Returns a |
| 73 | pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the |
| 74 | phase of *x*. ``polar(x)`` is equivalent to ``(abs(x), |
| 75 | phase(x))``. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 76 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 77 | |
| 78 | .. function:: rect(r, phi) |
| 79 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 80 | Return the complex number *x* with polar coordinates *r* and *phi*. |
| 81 | Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 82 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 83 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 84 | Power and logarithmic functions |
| 85 | ------------------------------- |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 86 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 87 | .. function:: exp(x) |
| 88 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 89 | Return *e* raised to the power *x*, where *e* is the base of natural |
| 90 | logarithms. |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 91 | |
| 92 | |
| 93 | .. function:: log(x[, base]) |
| 94 | |
| 95 | Returns the logarithm of *x* to the given *base*. If the *base* is not |
| 96 | specified, returns the natural logarithm of *x*. There is one branch cut, from 0 |
| 97 | along the negative real axis to -∞, continuous from above. |
| 98 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 99 | |
| 100 | .. function:: log10(x) |
| 101 | |
| 102 | Return the base-10 logarithm of *x*. This has the same branch cut as |
| 103 | :func:`log`. |
| 104 | |
| 105 | |
| 106 | .. function:: sqrt(x) |
| 107 | |
| 108 | Return the square root of *x*. This has the same branch cut as :func:`log`. |
| 109 | |
| 110 | |
| 111 | Trigonometric functions |
| 112 | ----------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
| 114 | .. function:: acos(x) |
| 115 | |
| 116 | Return the arc cosine of *x*. There are two branch cuts: One extends right from |
| 117 | 1 along the real axis to ∞, continuous from below. The other extends left from |
| 118 | -1 along the real axis to -∞, continuous from above. |
| 119 | |
| 120 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | .. function:: asin(x) |
| 122 | |
| 123 | Return the arc sine of *x*. This has the same branch cuts as :func:`acos`. |
| 124 | |
| 125 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | .. function:: atan(x) |
| 127 | |
| 128 | Return the arc tangent of *x*. There are two branch cuts: One extends from |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 129 | ``1j`` along the imaginary axis to ``∞j``, continuous from the right. The |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 131 | from the left. |
| 132 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 134 | .. function:: cos(x) |
| 135 | |
| 136 | Return the cosine of *x*. |
| 137 | |
| 138 | |
| 139 | .. function:: sin(x) |
| 140 | |
| 141 | Return the sine of *x*. |
| 142 | |
| 143 | |
| 144 | .. function:: tan(x) |
| 145 | |
| 146 | Return the tangent of *x*. |
| 147 | |
| 148 | |
| 149 | Hyperbolic functions |
| 150 | -------------------- |
| 151 | |
| 152 | .. function:: acosh(x) |
| 153 | |
Mark Dickinson | dfe0b23 | 2015-01-11 13:08:05 +0000 | [diff] [blame] | 154 | Return the inverse hyperbolic cosine of *x*. There is one branch cut, |
| 155 | extending left from 1 along the real axis to -∞, continuous from above. |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 156 | |
| 157 | |
| 158 | .. function:: asinh(x) |
| 159 | |
Mark Dickinson | dfe0b23 | 2015-01-11 13:08:05 +0000 | [diff] [blame] | 160 | Return the inverse hyperbolic sine of *x*. There are two branch cuts: |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 161 | One extends from ``1j`` along the imaginary axis to ``∞j``, |
| 162 | continuous from the right. The other extends from ``-1j`` along |
| 163 | the imaginary axis to ``-∞j``, continuous from the left. |
| 164 | |
| 165 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | .. function:: atanh(x) |
| 167 | |
Mark Dickinson | dfe0b23 | 2015-01-11 13:08:05 +0000 | [diff] [blame] | 168 | Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 169 | extends from ``1`` along the real axis to ``∞``, continuous from below. The |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 170 | other extends from ``-1`` along the real axis to ``-∞``, continuous from |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 171 | above. |
| 172 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 174 | .. function:: cosh(x) |
| 175 | |
| 176 | Return the hyperbolic cosine of *x*. |
| 177 | |
| 178 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 179 | .. function:: sinh(x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 181 | Return the hyperbolic sine of *x*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 182 | |
| 183 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 184 | .. function:: tanh(x) |
| 185 | |
| 186 | Return the hyperbolic tangent of *x*. |
| 187 | |
| 188 | |
| 189 | Classification functions |
| 190 | ------------------------ |
| 191 | |
Mark Dickinson | 8e0c996 | 2010-07-11 17:38:24 +0000 | [diff] [blame] | 192 | .. function:: isfinite(x) |
| 193 | |
Mark Dickinson | c762242 | 2010-07-11 19:47:37 +0000 | [diff] [blame] | 194 | Return ``True`` if both the real and imaginary parts of *x* are finite, and |
| 195 | ``False`` otherwise. |
| 196 | |
| 197 | .. versionadded:: 3.2 |
Mark Dickinson | 8e0c996 | 2010-07-11 17:38:24 +0000 | [diff] [blame] | 198 | |
| 199 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 200 | .. function:: isinf(x) |
| 201 | |
Mark Dickinson | c762242 | 2010-07-11 19:47:37 +0000 | [diff] [blame] | 202 | Return ``True`` if either the real or the imaginary part of *x* is an |
| 203 | infinity, and ``False`` otherwise. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 204 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 205 | |
| 206 | .. function:: isnan(x) |
| 207 | |
Mark Dickinson | c762242 | 2010-07-11 19:47:37 +0000 | [diff] [blame] | 208 | Return ``True`` if either the real or the imaginary part of *x* is a NaN, |
| 209 | and ``False`` otherwise. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 210 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 211 | |
Tal Einat | d5519ed | 2015-05-31 22:05:00 +0300 | [diff] [blame] | 212 | .. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0) |
| 213 | |
| 214 | Return ``True`` if the values *a* and *b* are close to each other and |
| 215 | ``False`` otherwise. |
| 216 | |
| 217 | Whether or not two values are considered close is determined according to |
| 218 | given absolute and relative tolerances. |
| 219 | |
| 220 | *rel_tol* is the relative tolerance -- it is the maximum allowed difference |
| 221 | between *a* and *b*, relative to the larger absolute value of *a* or *b*. |
| 222 | For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default |
| 223 | tolerance is ``1e-09``, which assures that the two values are the same |
| 224 | within about 9 decimal digits. *rel_tol* must be greater than zero. |
| 225 | |
| 226 | *abs_tol* is the minimum absolute tolerance -- useful for comparisons near |
| 227 | zero. *abs_tol* must be at least zero. |
| 228 | |
| 229 | If no errors occur, the result will be: |
| 230 | ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``. |
| 231 | |
| 232 | The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be |
| 233 | handled according to IEEE rules. Specifically, ``NaN`` is not considered |
| 234 | close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only |
| 235 | considered close to themselves. |
| 236 | |
| 237 | .. versionadded:: 3.5 |
| 238 | |
| 239 | .. seealso:: |
| 240 | |
| 241 | :pep:`485` -- A function for testing approximate equality |
| 242 | |
| 243 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 244 | Constants |
| 245 | --------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 246 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | .. data:: pi |
| 248 | |
Mark Dickinson | c2eab89 | 2009-07-28 16:31:03 +0000 | [diff] [blame] | 249 | The mathematical constant *π*, as a float. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 250 | |
| 251 | |
| 252 | .. data:: e |
| 253 | |
| 254 | The mathematical constant *e*, as a float. |
| 255 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 256 | |
Guido van Rossum | 0a891d7 | 2016-08-15 09:12:52 -0700 | [diff] [blame] | 257 | .. data:: tau |
| 258 | |
| 259 | The mathematical constant *τ*, as a float. |
| 260 | |
Georg Brandl | 4770d6e | 2016-08-16 07:08:46 +0200 | [diff] [blame] | 261 | .. versionadded:: 3.6 |
| 262 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 263 | |
Mark Dickinson | 84e6311 | 2016-08-29 13:56:58 +0100 | [diff] [blame] | 264 | .. data:: inf |
| 265 | |
| 266 | Floating-point positive infinity. Equivalent to ``float('inf')``. |
| 267 | |
| 268 | .. versionadded:: 3.6 |
| 269 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 270 | |
Mark Dickinson | 84e6311 | 2016-08-29 13:56:58 +0100 | [diff] [blame] | 271 | .. data:: infj |
| 272 | |
| 273 | Complex number with zero real part and positive infinity imaginary |
| 274 | part. Equivalent to ``complex(0.0, float('inf'))``. |
| 275 | |
| 276 | .. versionadded:: 3.6 |
| 277 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 278 | |
Mark Dickinson | 84e6311 | 2016-08-29 13:56:58 +0100 | [diff] [blame] | 279 | .. data:: nan |
| 280 | |
| 281 | A floating-point "not a number" (NaN) value. Equivalent to |
| 282 | ``float('nan')``. |
| 283 | |
| 284 | .. versionadded:: 3.6 |
| 285 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 286 | |
Mark Dickinson | 84e6311 | 2016-08-29 13:56:58 +0100 | [diff] [blame] | 287 | .. data:: nanj |
| 288 | |
| 289 | Complex number with zero real part and NaN imaginary part. Equivalent to |
| 290 | ``complex(0.0, float('nan'))``. |
| 291 | |
| 292 | .. versionadded:: 3.6 |
| 293 | |
| 294 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 295 | .. index:: module: math |
| 296 | |
| 297 | Note that the selection of functions is similar, but not identical, to that in |
| 298 | module :mod:`math`. The reason for having two modules is that some users aren't |
| 299 | interested in complex numbers, and perhaps don't even know what they are. They |
| 300 | would rather have ``math.sqrt(-1)`` raise an exception than return a complex |
| 301 | number. Also note that the functions defined in :mod:`cmath` always return a |
| 302 | complex number, even if the answer can be expressed as a real number (in which |
| 303 | case the complex number has an imaginary part of zero). |
| 304 | |
| 305 | A note on branch cuts: They are curves along which the given function fails to |
| 306 | be continuous. They are a necessary feature of many complex functions. It is |
| 307 | assumed that if you need to compute with complex functions, you will understand |
| 308 | about branch cuts. Consult almost any (not too elementary) book on complex |
| 309 | variables for enlightenment. For information of the proper choice of branch |
| 310 | cuts for numerical purposes, a good reference should be the following: |
| 311 | |
| 312 | |
| 313 | .. seealso:: |
| 314 | |
| 315 | Kahan, W: Branch cuts for complex elementary functions; or, Much ado about |
| 316 | nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art |
Serhiy Storchaka | c7b1a0b | 2016-11-26 13:43:28 +0200 | [diff] [blame] | 317 | in numerical analysis. Clarendon Press (1987) pp165--211. |