Doc/library/cmath.rst

   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 from the positive x-axis to the line segment that joins the
  40 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 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
 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