2 :mod:`math` --- Mathematical functions
3 ======================================
6 :synopsis: Mathematical functions (sin() etc.).
9 This module is always available. It provides access to the mathematical
10 functions defined by the C standard.
12 These functions cannot be used with complex numbers; use the functions of the
13 same name from the :mod:`cmath` module if you require support for complex
14 numbers. The distinction between functions which support complex numbers and
15 those which don't is made since most users do not want to learn quite as much
16 mathematics as required to understand complex numbers. Receiving an exception
17 instead of a complex result allows earlier detection of the unexpected complex
18 number used as a parameter, so that the programmer can determine how and why it
19 was generated in the first place.
21 The following functions are provided by this module. Except when explicitly
22 noted otherwise, all return values are floats.
25 Number-theoretic and representation functions
26 ---------------------------------------------
30 Return the ceiling of *x* as a float, the smallest integer value greater than or
34 .. function:: copysign(x, y)
36 Return *x* with the sign of *y*. ``copysign`` copies the sign bit of an IEEE
37 754 float, ``copysign(1, -0.0)`` returns *-1.0*.
44 Return the absolute value of *x*.
47 .. function:: factorial(x)
49 Return *x* factorial. Raises :exc:`ValueError` if *x* is not integral or
55 .. function:: floor(x)
57 Return the floor of *x* as a float, the largest integer value less than or equal
60 .. versionchanged:: 2.6
61 Added :meth:`__floor__` delegation.
64 .. function:: fmod(x, y)
66 Return ``fmod(x, y)``, as defined by the platform C library. Note that the
67 Python expression ``x % y`` may not return the same result. The intent of the C
68 standard is that ``fmod(x, y)`` be exactly (mathematically; to infinite
69 precision) equal to ``x - n*y`` for some integer *n* such that the result has
70 the same sign as *x* and magnitude less than ``abs(y)``. Python's ``x % y``
71 returns a result with the sign of *y* instead, and may not be exactly computable
72 for float arguments. For example, ``fmod(-1e-100, 1e100)`` is ``-1e-100``, but
73 the result of Python's ``-1e-100 % 1e100`` is ``1e100-1e-100``, which cannot be
74 represented exactly as a float, and rounds to the surprising ``1e100``. For
75 this reason, function :func:`fmod` is generally preferred when working with
76 floats, while Python's ``x % y`` is preferred when working with integers.
79 .. function:: frexp(x)
81 Return the mantissa and exponent of *x* as the pair ``(m, e)``. *m* is a float
82 and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero,
83 returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``. This is used to "pick
84 apart" the internal representation of a float in a portable way.
87 .. function:: fsum(iterable)
89 Return an accurate floating point sum of values in the iterable. Avoids
90 loss of precision by tracking multiple intermediate partial sums::
92 >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
94 >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
97 The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
98 typical case where the rounding mode is half-even. On some non-Windows
99 builds, the underlying C library uses extended precision addition and may
100 occasionally double-round an intermediate sum causing it to be off in its
101 least significant bit.
103 For further discussion and two alternative approaches, see the `ASPN cookbook
104 recipes for accurate floating point summation
105 <http://code.activestate.com/recipes/393090/>`_\.
107 .. versionadded:: 2.6
110 .. function:: isinf(x)
112 Checks if the float *x* is positive or negative infinite.
114 .. versionadded:: 2.6
117 .. function:: isnan(x)
119 Checks if the float *x* is a NaN (not a number). NaNs are part of the
120 IEEE 754 standards. Operation like but not limited to ``inf * 0``,
121 ``inf / inf`` or any operation involving a NaN, e.g. ``nan * 1``, return
124 .. versionadded:: 2.6
127 .. function:: ldexp(x, i)
129 Return ``x * (2**i)``. This is essentially the inverse of function
133 .. function:: modf(x)
135 Return the fractional and integer parts of *x*. Both results carry the sign
136 of *x* and are floats.
139 .. function:: trunc(x)
141 Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
142 a long integer). Delegates to ``x.__trunc__()``.
144 .. versionadded:: 2.6
147 Note that :func:`frexp` and :func:`modf` have a different call/return pattern
148 than their C equivalents: they take a single argument and return a pair of
149 values, rather than returning their second return value through an 'output
150 parameter' (there is no such thing in Python).
152 For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
153 floating-point numbers of sufficiently large magnitude are exact integers.
154 Python floats typically carry no more than 53 bits of precision (the same as the
155 platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
156 necessarily has no fractional bits.
159 Power and logarithmic functions
160 -------------------------------
167 .. function:: expm1(x)
169 Return ``e**x - 1``. For small floats *x*, the subtraction in
170 ``exp(x) - 1`` can result in a significant loss of precision; the
171 :func:`expm1` function provides a way to compute this quantity to
174 >>> from math import exp, expm1
175 >>> exp(1e-5) - 1 # gives result accurate to 11 places
176 1.0000050000069649e-05
177 >>> expm1(1e-5) # result accurate to full precision
178 1.0000050000166668e-05
180 .. versionadded:: 2.7
183 .. function:: log(x[, base])
185 With one argument, return the natural logarithm of *x* (to base *e*).
187 With two arguments, return the logarithm of *x* to the given *base*,
188 calculated as ``log(x)/log(base)``.
190 .. versionchanged:: 2.3
191 *base* argument added.
194 .. function:: log1p(x)
196 Return the natural logarithm of *1+x* (base *e*). The
197 result is calculated in a way which is accurate for *x* near zero.
199 .. versionadded:: 2.6
202 .. function:: log10(x)
204 Return the base-10 logarithm of *x*. This is usually more accurate
208 .. function:: pow(x, y)
210 Return ``x`` raised to the power ``y``. Exceptional cases follow
211 Annex 'F' of the C99 standard as far as possible. In particular,
212 ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
213 when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite,
214 ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
215 is undefined, and raises :exc:`ValueError`.
217 .. versionchanged:: 2.6
218 The outcome of ``1**nan`` and ``nan**0`` was undefined.
221 .. function:: sqrt(x)
223 Return the square root of *x*.
226 Trigonometric functions
227 -----------------------
229 .. function:: acos(x)
231 Return the arc cosine of *x*, in radians.
234 .. function:: asin(x)
236 Return the arc sine of *x*, in radians.
239 .. function:: atan(x)
241 Return the arc tangent of *x*, in radians.
244 .. function:: atan2(y, x)
246 Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
247 The vector in the plane from the origin to point ``(x, y)`` makes this angle
248 with the positive X axis. The point of :func:`atan2` is that the signs of both
249 inputs are known to it, so it can compute the correct quadrant for the angle.
250 For example, ``atan(1``) and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1,
251 -1)`` is ``-3*pi/4``.
256 Return the cosine of *x* radians.
259 .. function:: hypot(x, y)
261 Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector
262 from the origin to point ``(x, y)``.
267 Return the sine of *x* radians.
272 Return the tangent of *x* radians.
278 .. function:: degrees(x)
280 Converts angle *x* from radians to degrees.
283 .. function:: radians(x)
285 Converts angle *x* from degrees to radians.
291 .. function:: acosh(x)
293 Return the inverse hyperbolic cosine of *x*.
295 .. versionadded:: 2.6
298 .. function:: asinh(x)
300 Return the inverse hyperbolic sine of *x*.
302 .. versionadded:: 2.6
305 .. function:: atanh(x)
307 Return the inverse hyperbolic tangent of *x*.
309 .. versionadded:: 2.6
312 .. function:: cosh(x)
314 Return the hyperbolic cosine of *x*.
317 .. function:: sinh(x)
319 Return the hyperbolic sine of *x*.
322 .. function:: tanh(x)
324 Return the hyperbolic tangent of *x*.
332 Return the error function at *x*.
334 .. versionadded:: 2.7
337 .. function:: erfc(x)
339 Return the complementary error function at *x*.
341 .. versionadded:: 2.7
344 .. function:: gamma(x)
346 Return the Gamma function at *x*.
348 .. versionadded:: 2.7
351 .. function:: lgamma(x)
353 Return the natural logarithm of the absolute value of the Gamma
356 .. versionadded:: 2.7
364 The mathematical constant *pi*.
369 The mathematical constant *e*.
374 The :mod:`math` module consists mostly of thin wrappers around the platform C
375 math library functions. Behavior in exceptional cases is loosely specified
376 by the C standards, and Python inherits much of its math-function
377 error-reporting behavior from the platform C implementation. As a result,
378 the specific exceptions raised in error cases (and even whether some
379 arguments are considered to be exceptional at all) are not defined in any
380 useful cross-platform or cross-release way. For example, whether
381 ``math.log(0)`` returns ``-Inf`` or raises :exc:`ValueError` or
382 :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises
383 :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead.
385 All functions return a quiet *NaN* if at least one of the args is *NaN*.
386 Signaling *NaN*\s raise an exception. The exception type still depends on the
387 platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*
388 and :exc:`OverflowError` for errno *ERANGE*.
390 .. versionchanged:: 2.6
391 In earlier versions of Python the outcome of an operation with NaN as
392 input depended on platform and libm implementation.
398 Complex number versions of many of these functions.