#### /Doc/library/cmath.rst

ReStructuredText | 260 lines | 154 code | 106 blank | 0 comment | 0 complexity | 15ae969dd08e3b5a4bb3b8c2e8d3ddd4 MD5 | raw file

1:mod:`cmath` --- Mathematical functions for complex numbers 2=========================================================== 3 4.. module:: cmath 5 :synopsis: Mathematical functions for complex numbers. 6 7 8This module is always available. It provides access to mathematical functions 9for complex numbers. The functions in this module accept integers, 10floating-point numbers or complex numbers as arguments. They will also accept 11any Python object that has either a :meth:`__complex__` or a :meth:`__float__` 12method: these methods are used to convert the object to a complex or 13floating-point number, respectively, and the function is then applied to the 14result 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 from the positive x-axis to the line segment that joins the 40origin 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.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 89Power 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 118Trigonometric 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 159Hyperbolic functions 160-------------------- 161 162.. function:: acosh(x) 163 164 Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left 165 from 1 along the real axis to -∞, continuous from above. 166 167 168.. function:: asinh(x) 169 170 Return the hyperbolic arc 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 hyperbolic arc 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 205Classification 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 223Constants 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 238Note that the selection of functions is similar, but not identical, to that in 239module :mod:`math`. The reason for having two modules is that some users aren't 240interested in complex numbers, and perhaps don't even know what they are. They 241would rather have ``math.sqrt(-1)`` raise an exception than return a complex 242number. Also note that the functions defined in :mod:`cmath` always return a 243complex number, even if the answer can be expressed as a real number (in which 244case the complex number has an imaginary part of zero). 245 246A note on branch cuts: They are curves along which the given function fails to 247be continuous. They are a necessary feature of many complex functions. It is 248assumed that if you need to compute with complex functions, you will understand 249about branch cuts. Consult almost any (not too elementary) book on complex 250variables for enlightenment. For information of the proper choice of branch 251cuts 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