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