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