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. The
91 algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
92 typical case where the rounding mode is half-even.
96 The accuracy of fsum() may be impaired on builds that use
97 extended precision addition and then double-round the results.
102 .. function:: isinf(x)
104 Checks if the float *x* is positive or negative infinite.
106 .. versionadded:: 2.6
109 .. function:: isnan(x)
111 Checks if the float *x* is a NaN (not a number). NaNs are part of the
112 IEEE 754 standards. Operation like but not limited to ``inf * 0``,
113 ``inf / inf`` or any operation involving a NaN, e.g. ``nan * 1``, return
116 .. versionadded:: 2.6
119 .. function:: ldexp(x, i)
121 Return ``x * (2**i)``. This is essentially the inverse of function
125 .. function:: modf(x)
127 Return the fractional and integer parts of *x*. Both results carry the sign
128 of *x* and are floats.
131 .. function:: trunc(x)
133 Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
134 a long integer). Delegates to ``x.__trunc__()``.
136 .. versionadded:: 2.6
139 Note that :func:`frexp` and :func:`modf` have a different call/return pattern
140 than their C equivalents: they take a single argument and return a pair of
141 values, rather than returning their second return value through an 'output
142 parameter' (there is no such thing in Python).
144 For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
145 floating-point numbers of sufficiently large magnitude are exact integers.
146 Python floats typically carry no more than 53 bits of precision (the same as the
147 platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
148 necessarily has no fractional bits.
151 Power and logarithmic functions
152 -------------------------------
159 .. function:: log(x[, base])
161 Return the logarithm of *x* to the given *base*. If the *base* is not specified,
162 return the natural logarithm of *x* (that is, the logarithm to base *e*).
164 .. versionchanged:: 2.3
165 *base* argument added.
168 .. function:: log1p(x)
170 Return the natural logarithm of *1+x* (base *e*). The
171 result is calculated in a way which is accurate for *x* near zero.
173 .. versionadded:: 2.6
176 .. function:: log10(x)
178 Return the base-10 logarithm of *x*.
181 .. function:: pow(x, y)
183 Return ``x`` raised to the power ``y``. Exceptional cases follow
184 Annex 'F' of the C99 standard as far as possible. In particular,
185 ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
186 when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite,
187 ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
188 is undefined, and raises :exc:`ValueError`.
190 .. versionchanged:: 2.6
191 The outcome of ``1**nan`` and ``nan**0`` was undefined.
194 .. function:: sqrt(x)
196 Return the square root of *x*.
199 Trigonometric functions
200 -----------------------
202 .. function:: acos(x)
204 Return the arc cosine of *x*, in radians.
207 .. function:: asin(x)
209 Return the arc sine of *x*, in radians.
212 .. function:: atan(x)
214 Return the arc tangent of *x*, in radians.
217 .. function:: atan2(y, x)
219 Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
220 The vector in the plane from the origin to point ``(x, y)`` makes this angle
221 with the positive X axis. The point of :func:`atan2` is that the signs of both
222 inputs are known to it, so it can compute the correct quadrant for the angle.
223 For example, ``atan(1``) and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1,
224 -1)`` is ``-3*pi/4``.
229 Return the cosine of *x* radians.
232 .. function:: hypot(x, y)
234 Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector
235 from the origin to point ``(x, y)``.
240 Return the sine of *x* radians.
245 Return the tangent of *x* radians.
251 .. function:: degrees(x)
253 Converts angle *x* from radians to degrees.
256 .. function:: radians(x)
258 Converts angle *x* from degrees to radians.
264 .. function:: acosh(x)
266 Return the inverse hyperbolic cosine of *x*.
268 .. versionadded:: 2.6
271 .. function:: asinh(x)
273 Return the inverse hyperbolic sine of *x*.
275 .. versionadded:: 2.6
278 .. function:: atanh(x)
280 Return the inverse hyperbolic tangent of *x*.
282 .. versionadded:: 2.6
285 .. function:: cosh(x)
287 Return the hyperbolic cosine of *x*.
290 .. function:: sinh(x)
292 Return the hyperbolic sine of *x*.
295 .. function:: tanh(x)
297 Return the hyperbolic tangent of *x*.
305 The mathematical constant *pi*.
310 The mathematical constant *e*.
315 The :mod:`math` module consists mostly of thin wrappers around the platform C
316 math library functions. Behavior in exceptional cases is loosely specified
317 by the C standards, and Python inherits much of its math-function
318 error-reporting behavior from the platform C implementation. As a result,
319 the specific exceptions raised in error cases (and even whether some
320 arguments are considered to be exceptional at all) are not defined in any
321 useful cross-platform or cross-release way. For example, whether
322 ``math.log(0)`` returns ``-Inf`` or raises :exc:`ValueError` or
323 :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises
324 :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead.
326 All functions return a quiet *NaN* if at least one of the args is *NaN*.
327 Signaling *NaN*\s raise an exception. The exception type still depends on the
328 platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*
329 and :exc:`OverflowError` for errno *ERANGE*.
331 .. versionchanged:: 2.6
332 In earlier versions of Python the outcome of an operation with NaN as
333 input depended on platform and libm implementation.
339 Complex number versions of many of these functions.