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 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 17 .. note:: 18 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 26 Conversions to and from polar coordinates 27 ----------------------------------------- 28 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:: 33 34 z == z.real + z.imag*1j 35 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 40 angle, measured in radians, from the positive x-axis to the line 41 segment that joins the origin to *z*. 42 43 The following functions can be used to convert from the native 44 rectangular coordinates to polar coordinates and back. 45 46 .. function:: phase(x) 47 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, 50 x.real)``. The result lies in the range [-, ], and the branch 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. 68 69 70 .. function:: polar(x) 71 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))``. 76 77 78 .. function:: rect(r, phi) 79 80 Return the complex number *x* with polar coordinates *r* and *phi*. 81 Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``. 82 83 84 Power and logarithmic functions 85 ------------------------------- 86 87 .. function:: exp(x) 88 89 Return the exponential value ``e**x``. 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 110 Trigonometric 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 148 Hyperbolic 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 188 Classification 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 243 Constants 244 --------- 245 246 247 .. data:: pi 248 249 The mathematical constant **, as a float. 250 251 252 .. data:: e 253 254 The mathematical constant *e*, as a float. 255 256 .. data:: tau 257 258 The mathematical constant **, as a float. 259 260 .. versionadded:: 3.6 261 262 .. data:: inf 263 264 Floating-point positive infinity. Equivalent to ``float('inf')``. 265 266 .. versionadded:: 3.6 267 268 .. data:: infj 269 270 Complex number with zero real part and positive infinity imaginary 271 part. Equivalent to ``complex(0.0, float('inf'))``. 272 273 .. versionadded:: 3.6 274 275 .. data:: nan 276 277 A floating-point "not a number" (NaN) value. Equivalent to 278 ``float('nan')``. 279 280 .. versionadded:: 3.6 281 282 .. data:: nanj 283 284 Complex number with zero real part and NaN imaginary part. Equivalent to 285 ``complex(0.0, float('nan'))``. 286 287 .. versionadded:: 3.6 288 289 290 .. index:: module: math 291 292 Note that the selection of functions is similar, but not identical, to that in 293 module :mod:`math`. The reason for having two modules is that some users aren't 294 interested in complex numbers, and perhaps don't even know what they are. They 295 would rather have ``math.sqrt(-1)`` raise an exception than return a complex 296 number. Also note that the functions defined in :mod:`cmath` always return a 297 complex number, even if the answer can be expressed as a real number (in which 298 case the complex number has an imaginary part of zero). 299 300 A note on branch cuts: They are curves along which the given function fails to 301 be continuous. They are a necessary feature of many complex functions. It is 302 assumed that if you need to compute with complex functions, you will understand 303 about branch cuts. Consult almost any (not too elementary) book on complex 304 variables for enlightenment. For information of the proper choice of branch 305 cuts for numerical purposes, a good reference should be the following: 306 307 308 .. seealso:: 309 310 Kahan, W: Branch cuts for complex elementary functions; or, Much ado about 311 nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art 312 in numerical analysis. Clarendon Press (1987) pp165--211. 313
