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