/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
  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