Doc/library/cmath.rst

   1
   2 :mod:`cmath` --- Mathematical functions for complex numbers
   3 ===========================================================
   4
   5 .. module:: cmath
   6    :synopsis: Mathematical functions for complex numbers.
   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 Complex coordinates
  27 -------------------
  28
  29 Complex numbers can be expressed by two important coordinate systems.
  30 Python's :class:`complex` type uses rectangular coordinates where a number
  31 on the complex plain is defined by two floats, the real part and the imaginary
  32 part.
  33
  34 Definition::
  35
  36    z = x + 1j * y
  37
  38    x := real(z)
  39    y := imag(z)
  40
  41 In engineering the polar coordinate system is popular for complex numbers. In
  42 polar coordinates a complex number is defined by the radius *r* and the phase
  43 angle *phi*. The radius *r* is the absolute value of the complex, which can be
  44 viewed as distance from (0, 0). The radius *r* is always 0 or a positive float.
  45 The phase angle *phi* is the counter clockwise angle from the positive x axis,
  46 e.g. *1* has the angle *0*, *1j* has the angle *π/2* and *-1* the angle *-π*.
  47
  48 .. note::
  49    While :func:`phase` and func:`polar` return *+π* for a negative real they
  50    may return *-π* for a complex with a very small negative imaginary
  51    part, e.g. *-1-1E-300j*.
  52
  53
  54 Definition::
  55
  56    z = r * exp(1j * phi)
  57    z = r * cis(phi)
  58
  59    r := abs(z) := sqrt(real(z)**2 + imag(z)**2)
  60    phi := phase(z) := atan2(imag(z), real(z))
  61    cis(phi) := cos(phi) + 1j * sin(phi)
  62
  63
  64 .. function:: phase(x)
  65
  66    Return phase, also known as the argument, of a complex.
  67
  68    .. versionadded:: 2.6
  69
  70
  71 .. function:: polar(x)
  72
  73    Convert a :class:`complex` from rectangular coordinates to polar
  74    coordinates. The function returns a tuple with the two elements
  75    *r* and *phi*. *r* is the distance from 0 and *phi* the phase
  76    angle.
  77
  78    .. versionadded:: 2.6
  79
  80
  81 .. function:: rect(r, phi)
  82
  83    Convert from polar coordinates to rectangular coordinates and return
  84    a :class:`complex`.
  85
  86    .. versionadded:: 2.6
  87
  88
  89
  90 cmath functions
  91 ---------------
  92
  93 .. function:: acos(x)
  94
  95    Return the arc cosine of *x*. There are two branch cuts: One extends right from
  96    1 along the real axis to ∞, continuous from below. The other extends left from
  97    -1 along the real axis to -∞, continuous from above.
  98
  99
 100 .. function:: acosh(x)
 101
 102    Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
 103    from 1 along the real axis to -∞, continuous from above.
 104
 105
 106 .. function:: asin(x)
 107
 108    Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
 109
 110
 111 .. function:: asinh(x)
 112
 113    Return the hyperbolic arc sine of *x*. There are two branch cuts:
 114    One extends from ``1j`` along the imaginary axis to ``∞j``,
 115    continuous from the right.  The other extends from ``-1j`` along
 116    the imaginary axis to ``-∞j``, continuous from the left.
 117
 118    .. versionchanged:: 2.6
 119       branch cuts moved to match those recommended by the C99 standard
 120
 121
 122 .. function:: atan(x)
 123
 124    Return the arc tangent of *x*. There are two branch cuts: One extends from
 125    ``1j`` along the imaginary axis to ``∞j``, continuous from the right. The
 126    other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
 127    from the left.
 128
 129    .. versionchanged:: 2.6
 130       direction of continuity of upper cut reversed
 131
 132
 133 .. function:: atanh(x)
 134
 135    Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
 136    extends from ``1`` along the real axis to ``∞``, continuous from below. The
 137    other extends from ``-1`` along the real axis to ``-∞``, continuous from
 138    above.
 139
 140    .. versionchanged:: 2.6
 141       direction of continuity of right cut reversed
 142
 143
 144 .. function:: cos(x)
 145
 146    Return the cosine of *x*.
 147
 148
 149 .. function:: cosh(x)
 150
 151    Return the hyperbolic cosine of *x*.
 152
 153
 154 .. function:: exp(x)
 155
 156    Return the exponential value ``e**x``.
 157
 158
 159 .. function:: isinf(x)
 160
 161    Return *True* if the real or the imaginary part of x is positive
 162    or negative infinity.
 163
 164    .. versionadded:: 2.6
 165
 166
 167 .. function:: isnan(x)
 168
 169    Return *True* if the real or imaginary part of x is not a number (NaN).
 170
 171    .. versionadded:: 2.6
 172
 173
 174 .. function:: log(x[, base])
 175
 176    Returns the logarithm of *x* to the given *base*. If the *base* is not
 177    specified, returns the natural logarithm of *x*. There is one branch cut, from 0
 178    along the negative real axis to -∞, continuous from above.
 179
 180    .. versionchanged:: 2.4
 181       *base* argument added.
 182
 183
 184 .. function:: log10(x)
 185
 186    Return the base-10 logarithm of *x*. This has the same branch cut as
 187    :func:`log`.
 188
 189
 190 .. function:: sin(x)
 191
 192    Return the sine of *x*.
 193
 194
 195 .. function:: sinh(x)
 196
 197    Return the hyperbolic sine of *x*.
 198
 199
 200 .. function:: sqrt(x)
 201
 202    Return the square root of *x*. This has the same branch cut as :func:`log`.
 203
 204
 205 .. function:: tan(x)
 206
 207    Return the tangent of *x*.
 208
 209
 210 .. function:: tanh(x)
 211
 212    Return the hyperbolic tangent of *x*.
 213
 214 The module also defines two mathematical constants:
 215
 216
 217 .. data:: pi
 218
 219    The mathematical constant *pi*, as a float.
 220
 221
 222 .. data:: e
 223
 224    The mathematical constant *e*, as a float.
 225
 226 .. index:: module: math
 227
 228 Note that the selection of functions is similar, but not identical, to that in
 229 module :mod:`math`.  The reason for having two modules is that some users aren't
 230 interested in complex numbers, and perhaps don't even know what they are.  They
 231 would rather have ``math.sqrt(-1)`` raise an exception than return a complex
 232 number. Also note that the functions defined in :mod:`cmath` always return a
 233 complex number, even if the answer can be expressed as a real number (in which
 234 case the complex number has an imaginary part of zero).
 235
 236 A note on branch cuts: They are curves along which the given function fails to
 237 be continuous.  They are a necessary feature of many complex functions.  It is
 238 assumed that if you need to compute with complex functions, you will understand
 239 about branch cuts.  Consult almost any (not too elementary) book on complex
 240 variables for enlightenment.  For information of the proper choice of branch
 241 cuts for numerical purposes, a good reference should be the following:
 242
 243
 244 .. seealso::
 245
 246    Kahan, W:  Branch cuts for complex elementary functions; or, Much ado about
 247    nothing's sign bit.  In Iserles, A., and Powell, M. (eds.), The state of the art
 248    in numerical analysis. Clarendon Press (1987) pp165-211.
 249
 250