1 2:mod:`math` --- Mathematical functions 3====================================== 4 5.. module:: math 6 :synopsis: Mathematical functions (sin() etc.). 7 8.. testsetup:: 9 10 from math import fsum 11 12This module is always available. It provides access to the mathematical 13functions defined by the C standard. 14 15These functions cannot be used with complex numbers; use the functions of the 16same name from the :mod:`cmath` module if you require support for complex 17numbers. The distinction between functions which support complex numbers and 18those which don't is made since most users do not want to learn quite as much 19mathematics as required to understand complex numbers. Receiving an exception 20instead of a complex result allows earlier detection of the unexpected complex 21number used as a parameter, so that the programmer can determine how and why it 22was generated in the first place. 23 24The following functions are provided by this module. Except when explicitly 25noted otherwise, all return values are floats. 26 27 28Number-theoretic and representation functions 29--------------------------------------------- 30 31.. function:: ceil(x) 32 33 Return the ceiling of *x* as a float, the smallest integer value greater than or 34 equal to *x*. 35 36 37.. function:: copysign(x, y) 38 39 Return *x* with the sign of *y*. On a platform that supports 40 signed zeros, ``copysign(1.0, -0.0)`` returns *-1.0*. 41 42 .. versionadded:: 2.6 43 44 45.. function:: fabs(x) 46 47 Return the absolute value of *x*. 48 49 50.. function:: factorial(x) 51 52 Return *x* factorial. Raises :exc:`ValueError` if *x* is not integral or 53 is negative. 54 55 .. versionadded:: 2.6 56 57 58.. function:: floor(x) 59 60 Return the floor of *x* as a float, the largest integer value less than or equal 61 to *x*. 62 63 64.. function:: fmod(x, y) 65 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. 77 78 79.. function:: frexp(x) 80 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. 85 86 87.. function:: fsum(iterable) 88 89 Return an accurate floating point sum of values in the iterable. Avoids 90 loss of precision by tracking multiple intermediate partial sums:: 91 92 >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) 93 0.9999999999999999 94 >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) 95 1.0 96 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. 102 103 For further discussion and two alternative approaches, see the `ASPN cookbook 104 recipes for accurate floating point summation 105 <https://code.activestate.com/recipes/393090/>`_\. 106 107 .. versionadded:: 2.6 108 109 110.. function:: isinf(x) 111 112 Check if the float *x* is positive or negative infinity. 113 114 .. versionadded:: 2.6 115 116 117.. function:: isnan(x) 118 119 Check if the float *x* is a NaN (not a number). For more information 120 on NaNs, see the IEEE 754 standards. 121 122 .. versionadded:: 2.6 123 124 125.. function:: ldexp(x, i) 126 127 Return ``x * (2**i)``. This is essentially the inverse of function 128 :func:`frexp`. 129 130 131.. function:: modf(x) 132 133 Return the fractional and integer parts of *x*. Both results carry the sign 134 of *x* and are floats. 135 136 137.. function:: trunc(x) 138 139 Return the :class:`~numbers.Real` value *x* truncated to an 140 :class:`~numbers.Integral` (usually a long integer). Uses the 141 ``__trunc__`` method. 142 143 .. versionadded:: 2.6 144 145 146Note that :func:`frexp` and :func:`modf` have a different call/return pattern 147than their C equivalents: they take a single argument and return a pair of 148values, rather than returning their second return value through an 'output 149parameter' (there is no such thing in Python). 150 151For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all* 152floating-point numbers of sufficiently large magnitude are exact integers. 153Python floats typically carry no more than 53 bits of precision (the same as the 154platform C double type), in which case any float *x* with ``abs(x) >= 2**52`` 155necessarily has no fractional bits. 156 157 158Power and logarithmic functions 159------------------------------- 160 161.. function:: exp(x) 162 163 Return ``e**x``. 164 165 166.. function:: expm1(x) 167 168 Return ``e**x - 1``. For small floats *x*, the subtraction in 169 ``exp(x) - 1`` can result in a significant loss of precision; the 170 :func:`expm1` function provides a way to compute this quantity to 171 full precision:: 172 173 >>> from math import exp, expm1 174 >>> exp(1e-5) - 1 # gives result accurate to 11 places 175 1.0000050000069649e-05 176 >>> expm1(1e-5) # result accurate to full precision 177 1.0000050000166668e-05 178 179 .. versionadded:: 2.7 180 181 182.. function:: log(x[, base]) 183 184 With one argument, return the natural logarithm of *x* (to base *e*). 185 186 With two arguments, return the logarithm of *x* to the given *base*, 187 calculated as ``log(x)/log(base)``. 188 189 .. versionchanged:: 2.3 190 *base* argument added. 191 192 193.. function:: log1p(x) 194 195 Return the natural logarithm of *1+x* (base *e*). The 196 result is calculated in a way which is accurate for *x* near zero. 197 198 .. versionadded:: 2.6 199 200 201.. function:: log10(x) 202 203 Return the base-10 logarithm of *x*. This is usually more accurate 204 than ``log(x, 10)``. 205 206 207.. function:: pow(x, y) 208 209 Return ``x`` raised to the power ``y``. Exceptional cases follow 210 Annex 'F' of the C99 standard as far as possible. In particular, 211 ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even 212 when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite, 213 ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)`` 214 is undefined, and raises :exc:`ValueError`. 215 216 Unlike the built-in ``**`` operator, :func:`math.pow` converts both 217 its arguments to type :class:`float`. Use ``**`` or the built-in 218 :func:`pow` function for computing exact integer powers. 219 220 .. versionchanged:: 2.6 221 The outcome of ``1**nan`` and ``nan**0`` was undefined. 222 223 224.. function:: sqrt(x) 225 226 Return the square root of *x*. 227 228 229Trigonometric functions 230----------------------- 231 232.. function:: acos(x) 233 234 Return the arc cosine of *x*, in radians. 235 236 237.. function:: asin(x) 238 239 Return the arc sine of *x*, in radians. 240 241 242.. function:: atan(x) 243 244 Return the arc tangent of *x*, in radians. 245 246 247.. function:: atan2(y, x) 248 249 Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``. 250 The vector in the plane from the origin to point ``(x, y)`` makes this angle 251 with the positive X axis. The point of :func:`atan2` is that the signs of both 252 inputs are known to it, so it can compute the correct quadrant for the angle. 253 For example, ``atan(1)`` and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1, 254 -1)`` is ``-3*pi/4``. 255 256 257.. function:: cos(x) 258 259 Return the cosine of *x* radians. 260 261 262.. function:: hypot(x, y) 263 264 Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector 265 from the origin to point ``(x, y)``. 266 267 268.. function:: sin(x) 269 270 Return the sine of *x* radians. 271 272 273.. function:: tan(x) 274 275 Return the tangent of *x* radians. 276 277 278Angular conversion 279------------------ 280 281.. function:: degrees(x) 282 283 Convert angle *x* from radians to degrees. 284 285 286.. function:: radians(x) 287 288 Convert angle *x* from degrees to radians. 289 290 291Hyperbolic functions 292-------------------- 293 294.. function:: acosh(x) 295 296 Return the inverse hyperbolic cosine of *x*. 297 298 .. versionadded:: 2.6 299 300 301.. function:: asinh(x) 302 303 Return the inverse hyperbolic sine of *x*. 304 305 .. versionadded:: 2.6 306 307 308.. function:: atanh(x) 309 310 Return the inverse hyperbolic tangent of *x*. 311 312 .. versionadded:: 2.6 313 314 315.. function:: cosh(x) 316 317 Return the hyperbolic cosine of *x*. 318 319 320.. function:: sinh(x) 321 322 Return the hyperbolic sine of *x*. 323 324 325.. function:: tanh(x) 326 327 Return the hyperbolic tangent of *x*. 328 329 330Special functions 331----------------- 332 333.. function:: erf(x) 334 335 Return the error function at *x*. 336 337 .. versionadded:: 2.7 338 339 340.. function:: erfc(x) 341 342 Return the complementary error function at *x*. 343 344 .. versionadded:: 2.7 345 346 347.. function:: gamma(x) 348 349 Return the Gamma function at *x*. 350 351 .. versionadded:: 2.7 352 353 354.. function:: lgamma(x) 355 356 Return the natural logarithm of the absolute value of the Gamma 357 function at *x*. 358 359 .. versionadded:: 2.7 360 361 362Constants 363--------- 364 365.. data:: pi 366 367 The mathematical constant π = 3.141592..., to available precision. 368 369 370.. data:: e 371 372 The mathematical constant e = 2.718281..., to available precision. 373 374 375.. impl-detail:: 376 377 The :mod:`math` module consists mostly of thin wrappers around the platform C 378 math library functions. Behavior in exceptional cases follows Annex F of 379 the C99 standard where appropriate. The current implementation will raise 380 :exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)`` 381 (where C99 Annex F recommends signaling invalid operation or divide-by-zero), 382 and :exc:`OverflowError` for results that overflow (for example, 383 ``exp(1000.0)``). A NaN will not be returned from any of the functions 384 above unless one or more of the input arguments was a NaN; in that case, 385 most functions will return a NaN, but (again following C99 Annex F) there 386 are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or 387 ``hypot(float('nan'), float('inf'))``. 388 389 Note that Python makes no effort to distinguish signaling NaNs from 390 quiet NaNs, and behavior for signaling NaNs remains unspecified. 391 Typical behavior is to treat all NaNs as though they were quiet. 392 393 .. versionchanged:: 2.6 394 Behavior in special cases now aims to follow C99 Annex F. In earlier 395 versions of Python the behavior in special cases was loosely specified. 396 397 398.. seealso:: 399 400 Module :mod:`cmath` 401 Complex number versions of many of these functions. 402