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 *e* raised to the power *x*, where *e* is the base of natural 90 logarithms. 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 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 ----------------------- 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 121 .. function:: asin(x) 122 123 Return the arc sine of *x*. This has the same branch cuts as :func:`acos`. 124 125 126 .. function:: atan(x) 127 128 Return the arc tangent of *x*. There are two branch cuts: One extends from 129 ``1j`` along the imaginary axis to ``j``, continuous from the right. The 130 other extends from ``-1j`` along the imaginary axis to ``-j``, continuous 131 from the left. 132 133 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 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. 156 157 158 .. function:: asinh(x) 159 160 Return the inverse hyperbolic sine of *x*. There are two branch cuts: 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 166 .. function:: atanh(x) 167 168 Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One 169 extends from ``1`` along the real axis to ````, continuous from below. The 170 other extends from ``-1`` along the real axis to ``-``, continuous from 171 above. 172 173 174 .. function:: cosh(x) 175 176 Return the hyperbolic cosine of *x*. 177 178 179 .. function:: sinh(x) 180 181 Return the hyperbolic sine of *x*. 182 183 184 .. function:: tanh(x) 185 186 Return the hyperbolic tangent of *x*. 187 188 189 Classification functions 190 ------------------------ 191 192 .. function:: isfinite(x) 193 194 Return ``True`` if both the real and imaginary parts of *x* are finite, and 195 ``False`` otherwise. 196 197 .. versionadded:: 3.2 198 199 200 .. function:: isinf(x) 201 202 Return ``True`` if either the real or the imaginary part of *x* is an 203 infinity, and ``False`` otherwise. 204 205 206 .. function:: isnan(x) 207 208 Return ``True`` if either the real or the imaginary part of *x* is a NaN, 209 and ``False`` otherwise. 210 211 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 244 Constants 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 257 .. data:: tau 258 259 The mathematical constant **, as a float. 260 261 .. versionadded:: 3.6 262 263 264 .. data:: inf 265 266 Floating-point positive infinity. Equivalent to ``float('inf')``. 267 268 .. versionadded:: 3.6 269 270 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 278 279 .. data:: nan 280 281 A floating-point "not a number" (NaN) value. Equivalent to 282 ``float('nan')``. 283 284 .. versionadded:: 3.6 285 286 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 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 317 in numerical analysis. Clarendon Press (1987) pp165--211. 318
