| 1 |
:mod:`!cmath` --- Mathematical functions for complex numbers |
| 2 |
============================================================ |
| 3 |
|
| 4 |
.. module:: cmath |
| 5 |
:synopsis: Mathematical functions for complex numbers. |
| 6 |
|
| 7 |
-------------- |
| 8 |
|
| 9 |
This module provides access to mathematical functions for complex numbers. The |
| 10 |
functions in this module accept integers, floating-point numbers or complex |
| 11 |
numbers as arguments. They will also accept any Python object that has either a |
| 12 |
:meth:`~object.__complex__` or a :meth:`~object.__float__` method: these methods are used to |
| 13 |
convert the object to a complex or floating-point number, respectively, and |
| 14 |
the function is then applied to the result of the conversion. |
| 15 |
|
| 16 |
.. note:: |
| 17 |
|
| 18 |
For functions involving branch cuts, we have the problem of deciding how to |
| 19 |
define those functions on the cut itself. Following Kahan's "Branch cuts for |
| 20 |
complex elementary functions" paper, as well as Annex G of C99 and later C |
| 21 |
standards, we use the sign of zero to distinguish one side of the branch cut |
| 22 |
from the other: for a branch cut along (a portion of) the real axis we look |
| 23 |
at the sign of the imaginary part, while for a branch cut along the |
| 24 |
imaginary axis we look at the sign of the real part. |
| 25 |
|
| 26 |
For example, the :func:`cmath.sqrt` function has a branch cut along the |
| 27 |
negative real axis. An argument of ``-2-0j`` is treated as |
| 28 |
though it lies *below* the branch cut, and so gives a result on the negative |
| 29 |
imaginary axis:: |
| 30 |
|
| 31 |
>>> cmath.sqrt(-2-0j) |
| 32 |
-1.4142135623730951j |
| 33 |
|
| 34 |
But an argument of ``-2+0j`` is treated as though it lies above |
| 35 |
the branch cut:: |
| 36 |
|
| 37 |
>>> cmath.sqrt(-2+0j) |
| 38 |
1.4142135623730951j |
| 39 |
|
| 40 |
|
| 41 |
==================================================== ============================================ |
| 42 |
**Conversions to and from polar coordinates** |
| 43 |
-------------------------------------------------------------------------------------------------- |
| 44 |
:func:`phase(z) <phase>` Return the phase of *z* |
| 45 |
:func:`polar(z) <polar>` Return the representation of *z* in polar coordinates |
| 46 |
:func:`rect(r, phi) <rect>` Return the complex number *z* with polar coordinates *r* and *phi* |
| 47 |
|
| 48 |
**Power and logarithmic functions** |
| 49 |
-------------------------------------------------------------------------------------------------- |
| 50 |
:func:`exp(z) <exp>` Return *e* raised to the power *z* |
| 51 |
:func:`log(z[, base]) <log>` Return the logarithm of *z* to the given *base* (*e* by default) |
| 52 |
:func:`log10(z) <log10>` Return the base-10 logarithm of *z* |
| 53 |
:func:`sqrt(z) <sqrt>` Return the square root of *z* |
| 54 |
|
| 55 |
**Trigonometric functions** |
| 56 |
-------------------------------------------------------------------------------------------------- |
| 57 |
:func:`acos(z) <acos>` Return the arc cosine of *z* |
| 58 |
:func:`asin(z) <asin>` Return the arc sine of *z* |
| 59 |
:func:`atan(z) <atan>` Return the arc tangent of *z* |
| 60 |
:func:`cos(z) <cos>` Return the cosine of *z* |
| 61 |
:func:`sin(z) <sin>` Return the sine of *z* |
| 62 |
:func:`tan(z) <tan>` Return the tangent of *z* |
| 63 |
|
| 64 |
**Hyperbolic functions** |
| 65 |
-------------------------------------------------------------------------------------------------- |
| 66 |
:func:`acosh(z) <acosh>` Return the inverse hyperbolic cosine of *z* |
| 67 |
:func:`asinh(z) <asinh>` Return the inverse hyperbolic sine of *z* |
| 68 |
:func:`atanh(z) <atanh>` Return the inverse hyperbolic tangent of *z* |
| 69 |
:func:`cosh(z) <cosh>` Return the hyperbolic cosine of *z* |
| 70 |
:func:`sinh(z) <sinh>` Return the hyperbolic sine of *z* |
| 71 |
:func:`tanh(z) <tanh>` Return the hyperbolic tangent of *z* |
| 72 |
|
| 73 |
**Classification functions** |
| 74 |
-------------------------------------------------------------------------------------------------- |
| 75 |
:func:`isfinite(z) <isfinite>` Check if all components of *z* are finite |
| 76 |
:func:`isinf(z) <isinf>` Check if any component of *z* is infinite |
| 77 |
:func:`isnan(z) <isnan>` Check if any component of *z* is a NaN |
| 78 |
:func:`isclose(a, b, *, rel_tol, abs_tol) <isclose>` Check if the values *a* and *b* are close to each other |
| 79 |
|
| 80 |
**Constants** |
| 81 |
-------------------------------------------------------------------------------------------------- |
| 82 |
:data:`pi` *π* = 3.141592... |
| 83 |
:data:`e` *e* = 2.718281... |
| 84 |
:data:`tau` *τ* = 2\ *π* = 6.283185... |
| 85 |
:data:`inf` Positive infinity |
| 86 |
:data:`infj` Pure imaginary infinity |
| 87 |
:data:`nan` "Not a number" (NaN) |
| 88 |
:data:`nanj` Pure imaginary NaN |
| 89 |
==================================================== ============================================ |
| 90 |
|
| 91 |
|
| 92 |
Conversions to and from polar coordinates |
| 93 |
----------------------------------------- |
| 94 |
|
| 95 |
A Python complex number ``z`` is stored internally using *rectangular* |
| 96 |
or *Cartesian* coordinates. It is completely determined by its *real |
| 97 |
part* ``z.real`` and its *imaginary part* ``z.imag``. |
| 98 |
|
| 99 |
*Polar coordinates* give an alternative way to represent a complex |
| 100 |
number. In polar coordinates, a complex number *z* is defined by the |
| 101 |
modulus *r* and the phase angle *phi*. The modulus *r* is the distance |
| 102 |
from *z* to the origin, while the phase *phi* is the counterclockwise |
| 103 |
angle, measured in radians, from the positive x-axis to the line |
| 104 |
segment that joins the origin to *z*. |
| 105 |
|
| 106 |
The following functions can be used to convert from the native |
| 107 |
rectangular coordinates to polar coordinates and back. |
| 108 |
|
| 109 |
.. function:: phase(z) |
| 110 |
|
| 111 |
Return the phase of *z* (also known as the *argument* of *z*), as a float. |
| 112 |
``phase(z)`` is equivalent to ``math.atan2(z.imag, z.real)``. The result |
| 113 |
lies in the range [-\ *π*, *π*], and the branch cut for this operation lies |
| 114 |
along the negative real axis. The sign of the result is the same as the |
| 115 |
sign of ``z.imag``, even when ``z.imag`` is zero:: |
| 116 |
|
| 117 |
>>> phase(-1+0j) |
| 118 |
3.141592653589793 |
| 119 |
>>> phase(-1-0j) |
| 120 |
-3.141592653589793 |
| 121 |
|
| 122 |
|
| 123 |
.. note:: |
| 124 |
|
| 125 |
The modulus (absolute value) of a complex number *z* can be |
| 126 |
computed using the built-in :func:`abs` function. There is no |
| 127 |
separate :mod:`!cmath` module function for this operation. |
| 128 |
|
| 129 |
|
| 130 |
.. function:: polar(z) |
| 131 |
|
| 132 |
Return the representation of *z* in polar coordinates. Returns a |
| 133 |
pair ``(r, phi)`` where *r* is the modulus of *z* and *phi* is the |
| 134 |
phase of *z*. ``polar(z)`` is equivalent to ``(abs(z), |
| 135 |
phase(z))``. |
| 136 |
|
| 137 |
|
| 138 |
.. function:: rect(r, phi) |
| 139 |
|
| 140 |
Return the complex number *z* with polar coordinates *r* and *phi*. |
| 141 |
Equivalent to ``complex(r * math.cos(phi), r * math.sin(phi))``. |
| 142 |
|
| 143 |
|
| 144 |
Power and logarithmic functions |
| 145 |
------------------------------- |
| 146 |
|
| 147 |
.. function:: exp(z) |
| 148 |
|
| 149 |
Return *e* raised to the power *z*, where *e* is the base of natural |
| 150 |
logarithms. |
| 151 |
|
| 152 |
|
| 153 |
.. function:: log(z[, base]) |
| 154 |
|
| 155 |
Return the logarithm of *z* to the given *base*. If the *base* is not |
| 156 |
specified, returns the natural logarithm of *z*. There is one branch cut, |
| 157 |
from 0 along the negative real axis to -∞. |
| 158 |
|
| 159 |
|
| 160 |
.. function:: log10(z) |
| 161 |
|
| 162 |
Return the base-10 logarithm of *z*. This has the same branch cut as |
| 163 |
:func:`log`. |
| 164 |
|
| 165 |
|
| 166 |
.. function:: sqrt(z) |
| 167 |
|
| 168 |
Return the square root of *z*. This has the same branch cut as :func:`log`. |
| 169 |
|
| 170 |
|
| 171 |
Trigonometric functions |
| 172 |
----------------------- |
| 173 |
|
| 174 |
.. function:: acos(z) |
| 175 |
|
| 176 |
Return the arc cosine of *z*. There are two branch cuts: One extends right |
| 177 |
from 1 along the real axis to ∞. The other extends left from -1 along the |
| 178 |
real axis to -∞. |
| 179 |
|
| 180 |
|
| 181 |
.. function:: asin(z) |
| 182 |
|
| 183 |
Return the arc sine of *z*. This has the same branch cuts as :func:`acos`. |
| 184 |
|
| 185 |
|
| 186 |
.. function:: atan(z) |
| 187 |
|
| 188 |
Return the arc tangent of *z*. There are two branch cuts: One extends from |
| 189 |
``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j`` |
| 190 |
along the imaginary axis to ``-∞j``. |
| 191 |
|
| 192 |
|
| 193 |
.. function:: cos(z) |
| 194 |
|
| 195 |
Return the cosine of *z*. |
| 196 |
|
| 197 |
|
| 198 |
.. function:: sin(z) |
| 199 |
|
| 200 |
Return the sine of *z*. |
| 201 |
|
| 202 |
|
| 203 |
.. function:: tan(z) |
| 204 |
|
| 205 |
Return the tangent of *z*. |
| 206 |
|
| 207 |
|
| 208 |
Hyperbolic functions |
| 209 |
-------------------- |
| 210 |
|
| 211 |
.. function:: acosh(z) |
| 212 |
|
| 213 |
Return the inverse hyperbolic cosine of *z*. There is one branch cut, |
| 214 |
extending left from 1 along the real axis to -∞. |
| 215 |
|
| 216 |
|
| 217 |
.. function:: asinh(z) |
| 218 |
|
| 219 |
Return the inverse hyperbolic sine of *z*. There are two branch cuts: |
| 220 |
One extends from ``1j`` along the imaginary axis to ``∞j``. The other |
| 221 |
extends from ``-1j`` along the imaginary axis to ``-∞j``. |
| 222 |
|
| 223 |
|
| 224 |
.. function:: atanh(z) |
| 225 |
|
| 226 |
Return the inverse hyperbolic tangent of *z*. There are two branch cuts: One |
| 227 |
extends from ``1`` along the real axis to ``∞``. The other extends from |
| 228 |
``-1`` along the real axis to ``-∞``. |
| 229 |
|
| 230 |
|
| 231 |
.. function:: cosh(z) |
| 232 |
|
| 233 |
Return the hyperbolic cosine of *z*. |
| 234 |
|
| 235 |
|
| 236 |
.. function:: sinh(z) |
| 237 |
|
| 238 |
Return the hyperbolic sine of *z*. |
| 239 |
|
| 240 |
|
| 241 |
.. function:: tanh(z) |
| 242 |
|
| 243 |
Return the hyperbolic tangent of *z*. |
| 244 |
|
| 245 |
|
| 246 |
Classification functions |
| 247 |
------------------------ |
| 248 |
|
| 249 |
.. function:: isfinite(z) |
| 250 |
|
| 251 |
Return ``True`` if both the real and imaginary parts of *z* are finite, and |
| 252 |
``False`` otherwise. |
| 253 |
|
| 254 |
.. versionadded:: 3.2 |
| 255 |
|
| 256 |
|
| 257 |
.. function:: isinf(z) |
| 258 |
|
| 259 |
Return ``True`` if either the real or the imaginary part of *z* is an |
| 260 |
infinity, and ``False`` otherwise. |
| 261 |
|
| 262 |
|
| 263 |
.. function:: isnan(z) |
| 264 |
|
| 265 |
Return ``True`` if either the real or the imaginary part of *z* is a NaN, |
| 266 |
and ``False`` otherwise. |
| 267 |
|
| 268 |
|
| 269 |
.. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0) |
| 270 |
|
| 271 |
Return ``True`` if the values *a* and *b* are close to each other and |
| 272 |
``False`` otherwise. |
| 273 |
|
| 274 |
Whether or not two values are considered close is determined according to |
| 275 |
given absolute and relative tolerances. If no errors occur, the result will |
| 276 |
be: ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``. |
| 277 |
|
| 278 |
*rel_tol* is the relative tolerance -- it is the maximum allowed difference |
| 279 |
between *a* and *b*, relative to the larger absolute value of *a* or *b*. |
| 280 |
For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default |
| 281 |
tolerance is ``1e-09``, which assures that the two values are the same |
| 282 |
within about 9 decimal digits. *rel_tol* must be nonnegative and less |
| 283 |
than ``1.0``. |
| 284 |
|
| 285 |
*abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be |
| 286 |
nonnegative. When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed |
| 287 |
as ``abs(x) <= rel_tol * abs(x)``, which is ``False`` for any ``x`` and |
| 288 |
rel_tol less than ``1.0``. So add an appropriate positive abs_tol argument |
| 289 |
to the call. |
| 290 |
|
| 291 |
The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be |
| 292 |
handled according to IEEE rules. Specifically, ``NaN`` is not considered |
| 293 |
close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only |
| 294 |
considered close to themselves. |
| 295 |
|
| 296 |
.. versionadded:: 3.5 |
| 297 |
|
| 298 |
.. seealso:: |
| 299 |
|
| 300 |
:pep:`485` -- A function for testing approximate equality |
| 301 |
|
| 302 |
|
| 303 |
Constants |
| 304 |
--------- |
| 305 |
|
| 306 |
.. data:: pi |
| 307 |
|
| 308 |
The mathematical constant *π*, as a float. |
| 309 |
|
| 310 |
|
| 311 |
.. data:: e |
| 312 |
|
| 313 |
The mathematical constant *e*, as a float. |
| 314 |
|
| 315 |
|
| 316 |
.. data:: tau |
| 317 |
|
| 318 |
The mathematical constant *τ*, as a float. |
| 319 |
|
| 320 |
.. versionadded:: 3.6 |
| 321 |
|
| 322 |
|
| 323 |
.. data:: inf |
| 324 |
|
| 325 |
Floating-point positive infinity. Equivalent to ``float('inf')``. |
| 326 |
|
| 327 |
.. versionadded:: 3.6 |
| 328 |
|
| 329 |
|
| 330 |
.. data:: infj |
| 331 |
|
| 332 |
Complex number with zero real part and positive infinity imaginary |
| 333 |
part. Equivalent to ``complex(0.0, float('inf'))``. |
| 334 |
|
| 335 |
.. versionadded:: 3.6 |
| 336 |
|
| 337 |
|
| 338 |
.. data:: nan |
| 339 |
|
| 340 |
A floating-point "not a number" (NaN) value. Equivalent to |
| 341 |
``float('nan')``. See also :data:`math.nan`. |
| 342 |
|
| 343 |
.. versionadded:: 3.6 |
| 344 |
|
| 345 |
|
| 346 |
.. data:: nanj |
| 347 |
|
| 348 |
Complex number with zero real part and NaN imaginary part. Equivalent to |
| 349 |
``complex(0.0, float('nan'))``. |
| 350 |
|
| 351 |
.. versionadded:: 3.6 |
| 352 |
|
| 353 |
|
| 354 |
.. index:: pair: module; math |
| 355 |
|
| 356 |
Note that the selection of functions is similar, but not identical, to that in |
| 357 |
module :mod:`math`. The reason for having two modules is that some users aren't |
| 358 |
interested in complex numbers, and perhaps don't even know what they are. They |
| 359 |
would rather have ``math.sqrt(-1)`` raise an exception than return a complex |
| 360 |
number. Also note that the functions defined in :mod:`!cmath` always return a |
| 361 |
complex number, even if the answer can be expressed as a real number (in which |
| 362 |
case the complex number has an imaginary part of zero). |
| 363 |
|
| 364 |
A note on branch cuts: They are curves along which the given function fails to |
| 365 |
be continuous. They are a necessary feature of many complex functions. It is |
| 366 |
assumed that if you need to compute with complex functions, you will understand |
| 367 |
about branch cuts. Consult almost any (not too elementary) book on complex |
| 368 |
variables for enlightenment. For information of the proper choice of branch |
| 369 |
cuts for numerical purposes, a good reference should be the following: |
| 370 |
|
| 371 |
|
| 372 |
.. seealso:: |
| 373 |
|
| 374 |
Kahan, W: Branch cuts for complex elementary functions; or, Much ado about |
| 375 |
nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art |
| 376 |
in numerical analysis. Clarendon Press (1987) pp165--211. |