1 :mod:`cmath` --- Mathematical functions for complex numbers 2 =========================================================== 3 4 .. module:: cmath 5 :synopsis: Mathematical functions for complex numbers. 6 7 8 This module is always available. It provides access to mathematical functions 9 for complex numbers. The functions in this module accept integers, 10 floating-point numbers or complex numbers as arguments. They will also accept 11 any Python object that has either a :meth:`__complex__` or a :meth:`__float__` 12 method: these methods are used to convert the object to a complex or 13 floating-point number, respectively, and the function is then applied to the 14 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 25 Conversions to and from polar coordinates 26 ----------------------------------------- 27 28 A Python complex number ``z`` is stored internally using *rectangular* 29 or *Cartesian* coordinates. It is completely determined by its *real 30 part* ``z.real`` and its *imaginary part* ``z.imag``. In other 31 words:: 32 33 z == z.real + z.imag*1j 34 35 *Polar coordinates* give an alternative way to represent a complex 36 number. In polar coordinates, a complex number *z* is defined by the 37 modulus *r* and the phase angle *phi*. The modulus *r* is the distance 38 from *z* to the origin, while the phase *phi* is the counterclockwise 39 angle, measured in radians, from the positive x-axis to the line 40 segment that joins the origin to *z*. 41 42 The following functions can be used to convert from the native 43 rectangular 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.1415926535897931 58 >>> phase(complex(-1.0, -0.0)) 59 -3.1415926535897931 60 61 .. versionadded:: 2.6 62 63 64 .. note:: 65 66 The modulus (absolute value) of a complex number *x* can be 67 computed using the built-in :func:`abs` function. There is no 68 separate :mod:`cmath` module function for this operation. 69 70 71 .. function:: polar(x) 72 73 Return the representation of *x* in polar coordinates. Returns a 74 pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the 75 phase of *x*. ``polar(x)`` is equivalent to ``(abs(x), 76 phase(x))``. 77 78 .. versionadded:: 2.6 79 80 81 .. function:: rect(r, phi) 82 83 Return the complex number *x* with polar coordinates *r* and *phi*. 84 Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``. 85 86 .. versionadded:: 2.6 87 88 89 Power and logarithmic functions 90 ------------------------------- 91 92 .. function:: exp(x) 93 94 Return the exponential value ``e**x``. 95 96 97 .. function:: log(x[, base]) 98 99 Returns the logarithm of *x* to the given *base*. If the *base* is not 100 specified, returns the natural logarithm of *x*. There is one branch cut, from 0 101 along the negative real axis to -, continuous from above. 102 103 .. versionchanged:: 2.4 104 *base* argument added. 105 106 107 .. function:: log10(x) 108 109 Return the base-10 logarithm of *x*. This has the same branch cut as 110 :func:`log`. 111 112 113 .. function:: sqrt(x) 114 115 Return the square root of *x*. This has the same branch cut as :func:`log`. 116 117 118 Trigonometric functions 119 ----------------------- 120 121 .. function:: acos(x) 122 123 Return the arc cosine of *x*. There are two branch cuts: One extends right from 124 1 along the real axis to , continuous from below. The other extends left from 125 -1 along the real axis to -, continuous from above. 126 127 128 .. function:: asin(x) 129 130 Return the arc sine of *x*. This has the same branch cuts as :func:`acos`. 131 132 133 .. function:: atan(x) 134 135 Return the arc tangent of *x*. There are two branch cuts: One extends from 136 ``1j`` along the imaginary axis to ``j``, continuous from the right. The 137 other extends from ``-1j`` along the imaginary axis to ``-j``, continuous 138 from the left. 139 140 .. versionchanged:: 2.6 141 direction of continuity of upper cut reversed 142 143 144 .. function:: cos(x) 145 146 Return the cosine of *x*. 147 148 149 .. function:: sin(x) 150 151 Return the sine of *x*. 152 153 154 .. function:: tan(x) 155 156 Return the tangent of *x*. 157 158 159 Hyperbolic functions 160 -------------------- 161 162 .. function:: acosh(x) 163 164 Return the inverse hyperbolic cosine of *x*. There is one branch cut, 165 extending left from 1 along the real axis to -, continuous from above. 166 167 168 .. function:: asinh(x) 169 170 Return the inverse hyperbolic sine of *x*. There are two branch cuts: 171 One extends from ``1j`` along the imaginary axis to ``j``, 172 continuous from the right. The other extends from ``-1j`` along 173 the imaginary axis to ``-j``, continuous from the left. 174 175 .. versionchanged:: 2.6 176 branch cuts moved to match those recommended by the C99 standard 177 178 179 .. function:: atanh(x) 180 181 Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One 182 extends from ``1`` along the real axis to ````, continuous from below. The 183 other extends from ``-1`` along the real axis to ``-``, continuous from 184 above. 185 186 .. versionchanged:: 2.6 187 direction of continuity of right cut reversed 188 189 190 .. function:: cosh(x) 191 192 Return the hyperbolic cosine of *x*. 193 194 195 .. function:: sinh(x) 196 197 Return the hyperbolic sine of *x*. 198 199 200 .. function:: tanh(x) 201 202 Return the hyperbolic tangent of *x*. 203 204 205 Classification functions 206 ------------------------ 207 208 .. function:: isinf(x) 209 210 Return ``True`` if the real or the imaginary part of x is positive 211 or negative infinity. 212 213 .. versionadded:: 2.6 214 215 216 .. function:: isnan(x) 217 218 Return ``True`` if the real or imaginary part of x is not a number (NaN). 219 220 .. versionadded:: 2.6 221 222 223 Constants 224 --------- 225 226 227 .. data:: pi 228 229 The mathematical constant **, as a float. 230 231 232 .. data:: e 233 234 The mathematical constant *e*, as a float. 235 236 .. index:: module: math 237 238 Note that the selection of functions is similar, but not identical, to that in 239 module :mod:`math`. The reason for having two modules is that some users aren't 240 interested in complex numbers, and perhaps don't even know what they are. They 241 would rather have ``math.sqrt(-1)`` raise an exception than return a complex 242 number. Also note that the functions defined in :mod:`cmath` always return a 243 complex number, even if the answer can be expressed as a real number (in which 244 case the complex number has an imaginary part of zero). 245 246 A note on branch cuts: They are curves along which the given function fails to 247 be continuous. They are a necessary feature of many complex functions. It is 248 assumed that if you need to compute with complex functions, you will understand 249 about branch cuts. Consult almost any (not too elementary) book on complex 250 variables for enlightenment. For information of the proper choice of branch 251 cuts for numerical purposes, a good reference should be the following: 252 253 254 .. seealso:: 255 256 Kahan, W: Branch cuts for complex elementary functions; or, Much ado about 257 nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art 258 in numerical analysis. Clarendon Press (1987) pp165--211. 259 260 261
