1:mod:`math` --- Mathematical functions 2====================================== 3 4.. module:: math 5 :synopsis: Mathematical functions (sin() etc.). 6 7.. testsetup:: 8 9 from math import fsum 10 11-------------- 12 13This module is always available. It provides access to the mathematical 14functions defined by the C standard. 15 16These functions cannot be used with complex numbers; use the functions of the 17same name from the :mod:`cmath` module if you require support for complex 18numbers. The distinction between functions which support complex numbers and 19those which don't is made since most users do not want to learn quite as much 20mathematics as required to understand complex numbers. Receiving an exception 21instead of a complex result allows earlier detection of the unexpected complex 22number used as a parameter, so that the programmer can determine how and why it 23was generated in the first place. 24 25The following functions are provided by this module. Except when explicitly 26noted otherwise, all return values are floats. 27 28 29Number-theoretic and representation functions 30--------------------------------------------- 31 32.. function:: ceil(x) 33 34 Return the ceiling of *x*, the smallest integer greater than or equal to *x*. 35 If *x* is not a float, delegates to ``x.__ceil__()``, which should return an 36 :class:`~numbers.Integral` value. 37 38 39.. function:: copysign(x, y) 40 41 Return a float with the magnitude (absolute value) of *x* but the sign of 42 *y*. On platforms that support signed zeros, ``copysign(1.0, -0.0)`` 43 returns *-1.0*. 44 45 46.. function:: fabs(x) 47 48 Return the absolute value of *x*. 49 50 51.. function:: factorial(x) 52 53 Return *x* factorial. Raises :exc:`ValueError` if *x* is not integral or 54 is negative. 55 56 57.. function:: floor(x) 58 59 Return the floor of *x*, the largest integer less than or equal to *x*. 60 If *x* is not a float, delegates to ``x.__floor__()``, which should return an 61 :class:`~numbers.Integral` value. 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 108.. function:: gcd(a, b) 109 110 Return the greatest common divisor of the integers *a* and *b*. If either 111 *a* or *b* is nonzero, then the value of ``gcd(a, b)`` is the largest 112 positive integer that divides both *a* and *b*. ``gcd(0, 0)`` returns 113 ``0``. 114 115 .. versionadded:: 3.5 116 117 118.. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0) 119 120 Return ``True`` if the values *a* and *b* are close to each other and 121 ``False`` otherwise. 122 123 Whether or not two values are considered close is determined according to 124 given absolute and relative tolerances. 125 126 *rel_tol* is the relative tolerance -- it is the maximum allowed difference 127 between *a* and *b*, relative to the larger absolute value of *a* or *b*. 128 For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default 129 tolerance is ``1e-09``, which assures that the two values are the same 130 within about 9 decimal digits. *rel_tol* must be greater than zero. 131 132 *abs_tol* is the minimum absolute tolerance -- useful for comparisons near 133 zero. *abs_tol* must be at least zero. 134 135 If no errors occur, the result will be: 136 ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``. 137 138 The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be 139 handled according to IEEE rules. Specifically, ``NaN`` is not considered 140 close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only 141 considered close to themselves. 142 143 .. versionadded:: 3.5 144 145 .. seealso:: 146 147 :pep:`485` -- A function for testing approximate equality 148 149 150.. function:: isfinite(x) 151 152 Return ``True`` if *x* is neither an infinity nor a NaN, and 153 ``False`` otherwise. (Note that ``0.0`` *is* considered finite.) 154 155 .. versionadded:: 3.2 156 157 158.. function:: isinf(x) 159 160 Return ``True`` if *x* is a positive or negative infinity, and 161 ``False`` otherwise. 162 163 164.. function:: isnan(x) 165 166 Return ``True`` if *x* is a NaN (not a number), and ``False`` otherwise. 167 168 169.. function:: ldexp(x, i) 170 171 Return ``x * (2**i)``. This is essentially the inverse of function 172 :func:`frexp`. 173 174 175.. function:: modf(x) 176 177 Return the fractional and integer parts of *x*. Both results carry the sign 178 of *x* and are floats. 179 180 181.. function:: remainder(x, y) 182 183 Return the IEEE 754-style remainder of *x* with respect to *y*. For 184 finite *x* and finite nonzero *y*, this is the difference ``x - n*y``, 185 where ``n`` is the closest integer to the exact value of the quotient ``x / 186 y``. If ``x / y`` is exactly halfway between two consecutive integers, the 187 nearest *even* integer is used for ``n``. The remainder ``r = remainder(x, 188 y)`` thus always satisfies ``abs(r) <= 0.5 * abs(y)``. 189 190 Special cases follow IEEE 754: in particular, ``remainder(x, math.inf)`` is 191 *x* for any finite *x*, and ``remainder(x, 0)`` and 192 ``remainder(math.inf, x)`` raise :exc:`ValueError` for any non-NaN *x*. 193 If the result of the remainder operation is zero, that zero will have 194 the same sign as *x*. 195 196 On platforms using IEEE 754 binary floating-point, the result of this 197 operation is always exactly representable: no rounding error is introduced. 198 199 .. versionadded:: 3.7 200 201 202.. function:: trunc(x) 203 204 Return the :class:`~numbers.Real` value *x* truncated to an 205 :class:`~numbers.Integral` (usually an integer). Delegates to 206 :meth:`x.__trunc__() <object.__trunc__>`. 207 208 209Note that :func:`frexp` and :func:`modf` have a different call/return pattern 210than their C equivalents: they take a single argument and return a pair of 211values, rather than returning their second return value through an 'output 212parameter' (there is no such thing in Python). 213 214For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all* 215floating-point numbers of sufficiently large magnitude are exact integers. 216Python floats typically carry no more than 53 bits of precision (the same as the 217platform C double type), in which case any float *x* with ``abs(x) >= 2**52`` 218necessarily has no fractional bits. 219 220 221Power and logarithmic functions 222------------------------------- 223 224.. function:: exp(x) 225 226 Return *e* raised to the power *x*, where *e* = 2.718281... is the base 227 of natural logarithms. This is usually more accurate than ``math.e ** x`` 228 or ``pow(math.e, x)``. 229 230 231.. function:: expm1(x) 232 233 Return *e* raised to the power *x*, minus 1. Here *e* is the base of natural 234 logarithms. For small floats *x*, the subtraction in ``exp(x) - 1`` 235 can result in a `significant loss of precision 236 <https://en.wikipedia.org/wiki/Loss_of_significance>`_\; the :func:`expm1` 237 function provides a way to compute this quantity to full precision:: 238 239 >>> from math import exp, expm1 240 >>> exp(1e-5) - 1 # gives result accurate to 11 places 241 1.0000050000069649e-05 242 >>> expm1(1e-5) # result accurate to full precision 243 1.0000050000166668e-05 244 245 .. versionadded:: 3.2 246 247 248.. function:: log(x[, base]) 249 250 With one argument, return the natural logarithm of *x* (to base *e*). 251 252 With two arguments, return the logarithm of *x* to the given *base*, 253 calculated as ``log(x)/log(base)``. 254 255 256.. function:: log1p(x) 257 258 Return the natural logarithm of *1+x* (base *e*). The 259 result is calculated in a way which is accurate for *x* near zero. 260 261 262.. function:: log2(x) 263 264 Return the base-2 logarithm of *x*. This is usually more accurate than 265 ``log(x, 2)``. 266 267 .. versionadded:: 3.3 268 269 .. seealso:: 270 271 :meth:`int.bit_length` returns the number of bits necessary to represent 272 an integer in binary, excluding the sign and leading zeros. 273 274 275.. function:: log10(x) 276 277 Return the base-10 logarithm of *x*. This is usually more accurate 278 than ``log(x, 10)``. 279 280 281.. function:: pow(x, y) 282 283 Return ``x`` raised to the power ``y``. Exceptional cases follow 284 Annex 'F' of the C99 standard as far as possible. In particular, 285 ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even 286 when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite, 287 ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)`` 288 is undefined, and raises :exc:`ValueError`. 289 290 Unlike the built-in ``**`` operator, :func:`math.pow` converts both 291 its arguments to type :class:`float`. Use ``**`` or the built-in 292 :func:`pow` function for computing exact integer powers. 293 294 295.. function:: sqrt(x) 296 297 Return the square root of *x*. 298 299 300Trigonometric functions 301----------------------- 302 303.. function:: acos(x) 304 305 Return the arc cosine of *x*, in radians. 306 307 308.. function:: asin(x) 309 310 Return the arc sine of *x*, in radians. 311 312 313.. function:: atan(x) 314 315 Return the arc tangent of *x*, in radians. 316 317 318.. function:: atan2(y, x) 319 320 Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``. 321 The vector in the plane from the origin to point ``(x, y)`` makes this angle 322 with the positive X axis. The point of :func:`atan2` is that the signs of both 323 inputs are known to it, so it can compute the correct quadrant for the angle. 324 For example, ``atan(1)`` and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1, 325 -1)`` is ``-3*pi/4``. 326 327 328.. function:: cos(x) 329 330 Return the cosine of *x* radians. 331 332 333.. function:: hypot(x, y) 334 335 Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector 336 from the origin to point ``(x, y)``. 337 338 339.. function:: sin(x) 340 341 Return the sine of *x* radians. 342 343 344.. function:: tan(x) 345 346 Return the tangent of *x* radians. 347 348 349Angular conversion 350------------------ 351 352.. function:: degrees(x) 353 354 Convert angle *x* from radians to degrees. 355 356 357.. function:: radians(x) 358 359 Convert angle *x* from degrees to radians. 360 361 362Hyperbolic functions 363-------------------- 364 365`Hyperbolic functions <https://en.wikipedia.org/wiki/Hyperbolic_function>`_ 366are analogs of trigonometric functions that are based on hyperbolas 367instead of circles. 368 369.. function:: acosh(x) 370 371 Return the inverse hyperbolic cosine of *x*. 372 373 374.. function:: asinh(x) 375 376 Return the inverse hyperbolic sine of *x*. 377 378 379.. function:: atanh(x) 380 381 Return the inverse hyperbolic tangent of *x*. 382 383 384.. function:: cosh(x) 385 386 Return the hyperbolic cosine of *x*. 387 388 389.. function:: sinh(x) 390 391 Return the hyperbolic sine of *x*. 392 393 394.. function:: tanh(x) 395 396 Return the hyperbolic tangent of *x*. 397 398 399Special functions 400----------------- 401 402.. function:: erf(x) 403 404 Return the `error function <https://en.wikipedia.org/wiki/Error_function>`_ at 405 *x*. 406 407 The :func:`erf` function can be used to compute traditional statistical 408 functions such as the `cumulative standard normal distribution 409 <https://en.wikipedia.org/wiki/Normal_distribution#Cumulative_distribution_function>`_:: 410 411 def phi(x): 412 'Cumulative distribution function for the standard normal distribution' 413 return (1.0 + erf(x / sqrt(2.0))) / 2.0 414 415 .. versionadded:: 3.2 416 417 418.. function:: erfc(x) 419 420 Return the complementary error function at *x*. The `complementary error 421 function <https://en.wikipedia.org/wiki/Error_function>`_ is defined as 422 ``1.0 - erf(x)``. It is used for large values of *x* where a subtraction 423 from one would cause a `loss of significance 424 <https://en.wikipedia.org/wiki/Loss_of_significance>`_\. 425 426 .. versionadded:: 3.2 427 428 429.. function:: gamma(x) 430 431 Return the `Gamma function <https://en.wikipedia.org/wiki/Gamma_function>`_ at 432 *x*. 433 434 .. versionadded:: 3.2 435 436 437.. function:: lgamma(x) 438 439 Return the natural logarithm of the absolute value of the Gamma 440 function at *x*. 441 442 .. versionadded:: 3.2 443 444 445Constants 446--------- 447 448.. data:: pi 449 450 The mathematical constant *π* = 3.141592..., to available precision. 451 452 453.. data:: e 454 455 The mathematical constant *e* = 2.718281..., to available precision. 456 457 458.. data:: tau 459 460 The mathematical constant *τ* = 6.283185..., to available precision. 461 Tau is a circle constant equal to 2\ *π*, the ratio of a circle's circumference to 462 its radius. To learn more about Tau, check out Vi Hart's video `Pi is (still) 463 Wrong <https://www.youtube.com/watch?v=jG7vhMMXagQ>`_, and start celebrating 464 `Tau day <https://tauday.com/>`_ by eating twice as much pie! 465 466 .. versionadded:: 3.6 467 468 469.. data:: inf 470 471 A floating-point positive infinity. (For negative infinity, use 472 ``-math.inf``.) Equivalent to the output of ``float('inf')``. 473 474 .. versionadded:: 3.5 475 476 477.. data:: nan 478 479 A floating-point "not a number" (NaN) value. Equivalent to the output of 480 ``float('nan')``. 481 482 .. versionadded:: 3.5 483 484 485.. impl-detail:: 486 487 The :mod:`math` module consists mostly of thin wrappers around the platform C 488 math library functions. Behavior in exceptional cases follows Annex F of 489 the C99 standard where appropriate. The current implementation will raise 490 :exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)`` 491 (where C99 Annex F recommends signaling invalid operation or divide-by-zero), 492 and :exc:`OverflowError` for results that overflow (for example, 493 ``exp(1000.0)``). A NaN will not be returned from any of the functions 494 above unless one or more of the input arguments was a NaN; in that case, 495 most functions will return a NaN, but (again following C99 Annex F) there 496 are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or 497 ``hypot(float('nan'), float('inf'))``. 498 499 Note that Python makes no effort to distinguish signaling NaNs from 500 quiet NaNs, and behavior for signaling NaNs remains unspecified. 501 Typical behavior is to treat all NaNs as though they were quiet. 502 503 504.. seealso:: 505 506 Module :mod:`cmath` 507 Complex number versions of many of these functions. 508