Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`math` --- Mathematical functions |
| 2 | ====================================== |
| 3 | |
| 4 | .. module:: math |
| 5 | :synopsis: Mathematical functions (sin() etc.). |
| 6 | |
Łukasz Langa | 288234f | 2013-01-18 13:40:43 +0100 | [diff] [blame] | 7 | .. testsetup:: |
| 8 | |
| 9 | from math import fsum |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 11 | -------------- |
| 12 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | This module is always available. It provides access to the mathematical |
| 14 | functions defined by the C standard. |
| 15 | |
| 16 | These functions cannot be used with complex numbers; use the functions of the |
| 17 | same name from the :mod:`cmath` module if you require support for complex |
| 18 | numbers. The distinction between functions which support complex numbers and |
| 19 | those which don't is made since most users do not want to learn quite as much |
| 20 | mathematics as required to understand complex numbers. Receiving an exception |
| 21 | instead of a complex result allows earlier detection of the unexpected complex |
| 22 | number used as a parameter, so that the programmer can determine how and why it |
| 23 | was generated in the first place. |
| 24 | |
| 25 | The following functions are provided by this module. Except when explicitly |
| 26 | noted otherwise, all return values are floats. |
| 27 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 29 | Number-theoretic and representation functions |
| 30 | --------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | |
| 32 | .. function:: ceil(x) |
| 33 | |
Georg Brandl | 2a03373 | 2008-04-05 17:37:09 +0000 | [diff] [blame] | 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 |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 36 | :class:`~numbers.Integral` value. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 37 | |
| 38 | |
| 39 | .. function:: copysign(x, y) |
| 40 | |
Andrew Kuchling | 8cb1ec3 | 2014-02-16 11:11:25 -0500 | [diff] [blame] | 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*. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 44 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 45 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | .. function:: fabs(x) |
| 47 | |
| 48 | Return the absolute value of *x*. |
| 49 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 50 | |
Georg Brandl | c28e1fa | 2008-06-10 19:20:26 +0000 | [diff] [blame] | 51 | .. function:: factorial(x) |
| 52 | |
Benjamin Peterson | fea6a94 | 2008-07-02 16:11:42 +0000 | [diff] [blame] | 53 | Return *x* factorial. Raises :exc:`ValueError` if *x* is not integral or |
Georg Brandl | c28e1fa | 2008-06-10 19:20:26 +0000 | [diff] [blame] | 54 | is negative. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 56 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | .. function:: floor(x) |
| 58 | |
Georg Brandl | 2a03373 | 2008-04-05 17:37:09 +0000 | [diff] [blame] | 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 |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 61 | :class:`~numbers.Integral` value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 87 | .. function:: fsum(iterable) |
| 88 | |
| 89 | Return an accurate floating point sum of values in the iterable. Avoids |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 90 | loss of precision by tracking multiple intermediate partial sums:: |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 91 | |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 92 | >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) |
Mark Dickinson | 5a55b61 | 2009-06-28 20:59:42 +0000 | [diff] [blame] | 93 | 0.9999999999999999 |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 94 | >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) |
| 95 | 1.0 |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 96 | |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 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. |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 102 | |
Raymond Hettinger | 477be82 | 2009-02-19 06:44:30 +0000 | [diff] [blame] | 103 | For further discussion and two alternative approaches, see the `ASPN cookbook |
| 104 | recipes for accurate floating point summation |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 105 | <https://code.activestate.com/recipes/393090/>`_\. |
Raymond Hettinger | 477be82 | 2009-02-19 06:44:30 +0000 | [diff] [blame] | 106 | |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 107 | |
Serhiy Storchaka | 48e47aa | 2015-05-13 00:19:51 +0300 | [diff] [blame] | 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 | |
Benjamin Peterson | e960d18 | 2015-05-12 17:24:17 -0400 | [diff] [blame] | 115 | .. versionadded:: 3.5 |
| 116 | |
Serhiy Storchaka | 48e47aa | 2015-05-13 00:19:51 +0300 | [diff] [blame] | 117 | |
Tal Einat | d5519ed | 2015-05-31 22:05:00 +0300 | [diff] [blame] | 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 | |
Mark Dickinson | 8e0c996 | 2010-07-11 17:38:24 +0000 | [diff] [blame] | 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 | |
Mark Dickinson | c762242 | 2010-07-11 19:47:37 +0000 | [diff] [blame] | 155 | .. versionadded:: 3.2 |
| 156 | |
Mark Dickinson | 8e0c996 | 2010-07-11 17:38:24 +0000 | [diff] [blame] | 157 | |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 158 | .. function:: isinf(x) |
| 159 | |
Mark Dickinson | c762242 | 2010-07-11 19:47:37 +0000 | [diff] [blame] | 160 | Return ``True`` if *x* is a positive or negative infinity, and |
| 161 | ``False`` otherwise. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 162 | |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 163 | |
| 164 | .. function:: isnan(x) |
| 165 | |
Mark Dickinson | c762242 | 2010-07-11 19:47:37 +0000 | [diff] [blame] | 166 | Return ``True`` if *x* is a NaN (not a number), and ``False`` otherwise. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 167 | |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 168 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 177 | Return the fractional and integer parts of *x*. Both results carry the sign |
| 178 | of *x* and are floats. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 179 | |
Christian Heimes | 400adb0 | 2008-02-01 08:12:03 +0000 | [diff] [blame] | 180 | |
Mark Dickinson | a0ce375 | 2017-04-05 18:34:27 +0100 | [diff] [blame] | 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 | |
Christian Heimes | 400adb0 | 2008-02-01 08:12:03 +0000 | [diff] [blame] | 202 | .. function:: trunc(x) |
| 203 | |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 204 | Return the :class:`~numbers.Real` value *x* truncated to an |
| 205 | :class:`~numbers.Integral` (usually an integer). Delegates to |
| 206 | ``x.__trunc__()``. |
Christian Heimes | 400adb0 | 2008-02-01 08:12:03 +0000 | [diff] [blame] | 207 | |
Christian Heimes | 400adb0 | 2008-02-01 08:12:03 +0000 | [diff] [blame] | 208 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 209 | Note that :func:`frexp` and :func:`modf` have a different call/return pattern |
| 210 | than their C equivalents: they take a single argument and return a pair of |
| 211 | values, rather than returning their second return value through an 'output |
| 212 | parameter' (there is no such thing in Python). |
| 213 | |
| 214 | For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all* |
| 215 | floating-point numbers of sufficiently large magnitude are exact integers. |
| 216 | Python floats typically carry no more than 53 bits of precision (the same as the |
| 217 | platform C double type), in which case any float *x* with ``abs(x) >= 2**52`` |
| 218 | necessarily has no fractional bits. |
| 219 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 220 | |
| 221 | Power and logarithmic functions |
| 222 | ------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 223 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 224 | .. function:: exp(x) |
| 225 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | |
Mark Dickinson | 664b511 | 2009-12-16 20:23:42 +0000 | [diff] [blame] | 231 | .. function:: expm1(x) |
| 232 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 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`` |
Raymond Hettinger | 1081d48 | 2011-03-31 12:04:53 -0700 | [diff] [blame] | 235 | can result in a `significant loss of precision |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 236 | <https://en.wikipedia.org/wiki/Loss_of_significance>`_\; the :func:`expm1` |
Raymond Hettinger | 1081d48 | 2011-03-31 12:04:53 -0700 | [diff] [blame] | 237 | function provides a way to compute this quantity to full precision:: |
Mark Dickinson | 664b511 | 2009-12-16 20:23:42 +0000 | [diff] [blame] | 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 | |
Mark Dickinson | 45f992a | 2009-12-19 11:20:49 +0000 | [diff] [blame] | 245 | .. versionadded:: 3.2 |
| 246 | |
Mark Dickinson | 664b511 | 2009-12-16 20:23:42 +0000 | [diff] [blame] | 247 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 248 | .. function:: log(x[, base]) |
| 249 | |
Georg Brandl | a6053b4 | 2009-09-01 08:11:14 +0000 | [diff] [blame] | 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)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 254 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 255 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 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 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 261 | |
Victor Stinner | fa0e3d5 | 2011-05-09 01:01:09 +0200 | [diff] [blame] | 262 | .. function:: log2(x) |
| 263 | |
Benjamin Peterson | eaee138 | 2011-05-08 19:48:08 -0500 | [diff] [blame] | 264 | Return the base-2 logarithm of *x*. This is usually more accurate than |
| 265 | ``log(x, 2)``. |
Victor Stinner | fa0e3d5 | 2011-05-09 01:01:09 +0200 | [diff] [blame] | 266 | |
| 267 | .. versionadded:: 3.3 |
| 268 | |
Victor Stinner | 9415afc | 2011-09-21 03:35:18 +0200 | [diff] [blame] | 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 | |
Victor Stinner | fa0e3d5 | 2011-05-09 01:01:09 +0200 | [diff] [blame] | 274 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 275 | .. function:: log10(x) |
| 276 | |
Georg Brandl | a6053b4 | 2009-09-01 08:11:14 +0000 | [diff] [blame] | 277 | Return the base-10 logarithm of *x*. This is usually more accurate |
| 278 | than ``log(x, 10)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 279 | |
| 280 | |
| 281 | .. function:: pow(x, y) |
| 282 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 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`. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 289 | |
Ezio Melotti | 739d549 | 2013-02-23 04:53:44 +0200 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 294 | |
| 295 | .. function:: sqrt(x) |
| 296 | |
| 297 | Return the square root of *x*. |
| 298 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 299 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 300 | Trigonometric functions |
| 301 | ----------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 302 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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. |
Mark Dickinson | 603b753 | 2010-04-06 19:55:03 +0000 | [diff] [blame] | 324 | For example, ``atan(1)`` and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 348 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 349 | Angular conversion |
| 350 | ------------------ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 351 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 352 | .. function:: degrees(x) |
| 353 | |
Benjamin Peterson | 19a3f17 | 2015-05-12 19:15:53 -0400 | [diff] [blame] | 354 | Convert angle *x* from radians to degrees. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 355 | |
| 356 | |
| 357 | .. function:: radians(x) |
| 358 | |
Benjamin Peterson | 19a3f17 | 2015-05-12 19:15:53 -0400 | [diff] [blame] | 359 | Convert angle *x* from degrees to radians. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 360 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 361 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 362 | Hyperbolic functions |
| 363 | -------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 365 | `Hyperbolic functions <https://en.wikipedia.org/wiki/Hyperbolic_function>`_ |
Raymond Hettinger | 1081d48 | 2011-03-31 12:04:53 -0700 | [diff] [blame] | 366 | are analogs of trigonometric functions that are based on hyperbolas |
| 367 | instead of circles. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 368 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 369 | .. function:: acosh(x) |
| 370 | |
| 371 | Return the inverse hyperbolic cosine of *x*. |
| 372 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 373 | |
| 374 | .. function:: asinh(x) |
| 375 | |
| 376 | Return the inverse hyperbolic sine of *x*. |
| 377 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 378 | |
| 379 | .. function:: atanh(x) |
| 380 | |
| 381 | Return the inverse hyperbolic tangent of *x*. |
| 382 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 383 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 398 | |
Mark Dickinson | 12c4bdb | 2009-09-28 19:21:11 +0000 | [diff] [blame] | 399 | Special functions |
| 400 | ----------------- |
| 401 | |
Mark Dickinson | 45f992a | 2009-12-19 11:20:49 +0000 | [diff] [blame] | 402 | .. function:: erf(x) |
| 403 | |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 404 | Return the `error function <https://en.wikipedia.org/wiki/Error_function>`_ at |
Raymond Hettinger | 1081d48 | 2011-03-31 12:04:53 -0700 | [diff] [blame] | 405 | *x*. |
| 406 | |
| 407 | The :func:`erf` function can be used to compute traditional statistical |
| 408 | functions such as the `cumulative standard normal distribution |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 409 | <https://en.wikipedia.org/wiki/Normal_distribution#Cumulative_distribution_function>`_:: |
Raymond Hettinger | 1081d48 | 2011-03-31 12:04:53 -0700 | [diff] [blame] | 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 |
Mark Dickinson | 45f992a | 2009-12-19 11:20:49 +0000 | [diff] [blame] | 414 | |
| 415 | .. versionadded:: 3.2 |
| 416 | |
| 417 | |
| 418 | .. function:: erfc(x) |
| 419 | |
Raymond Hettinger | 1081d48 | 2011-03-31 12:04:53 -0700 | [diff] [blame] | 420 | Return the complementary error function at *x*. The `complementary error |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 421 | function <https://en.wikipedia.org/wiki/Error_function>`_ is defined as |
Raymond Hettinger | 12e6c25 | 2011-03-31 13:59:24 -0700 | [diff] [blame] | 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 |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 424 | <https://en.wikipedia.org/wiki/Loss_of_significance>`_\. |
Mark Dickinson | 45f992a | 2009-12-19 11:20:49 +0000 | [diff] [blame] | 425 | |
| 426 | .. versionadded:: 3.2 |
| 427 | |
| 428 | |
Mark Dickinson | 12c4bdb | 2009-09-28 19:21:11 +0000 | [diff] [blame] | 429 | .. function:: gamma(x) |
| 430 | |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 431 | Return the `Gamma function <https://en.wikipedia.org/wiki/Gamma_function>`_ at |
Raymond Hettinger | 12e6c25 | 2011-03-31 13:59:24 -0700 | [diff] [blame] | 432 | *x*. |
Mark Dickinson | 12c4bdb | 2009-09-28 19:21:11 +0000 | [diff] [blame] | 433 | |
Mark Dickinson | 56e0966 | 2009-10-01 16:13:29 +0000 | [diff] [blame] | 434 | .. versionadded:: 3.2 |
Mark Dickinson | 12c4bdb | 2009-09-28 19:21:11 +0000 | [diff] [blame] | 435 | |
| 436 | |
Mark Dickinson | 05d2e08 | 2009-12-11 20:17:17 +0000 | [diff] [blame] | 437 | .. function:: lgamma(x) |
| 438 | |
| 439 | Return the natural logarithm of the absolute value of the Gamma |
| 440 | function at *x*. |
| 441 | |
Mark Dickinson | 45f992a | 2009-12-19 11:20:49 +0000 | [diff] [blame] | 442 | .. versionadded:: 3.2 |
Mark Dickinson | 05d2e08 | 2009-12-11 20:17:17 +0000 | [diff] [blame] | 443 | |
| 444 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 445 | Constants |
Mark Dickinson | 60fe6b0 | 2009-06-02 12:53:15 +0000 | [diff] [blame] | 446 | --------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 447 | |
| 448 | .. data:: pi |
| 449 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 450 | The mathematical constant *π* = 3.141592..., to available precision. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 451 | |
| 452 | |
| 453 | .. data:: e |
| 454 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 455 | The mathematical constant *e* = 2.718281..., to available precision. |
| 456 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 457 | |
Guido van Rossum | 0a891d7 | 2016-08-15 09:12:52 -0700 | [diff] [blame] | 458 | .. data:: tau |
| 459 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 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 |
Guido van Rossum | 0a891d7 | 2016-08-15 09:12:52 -0700 | [diff] [blame] | 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 |
Sanyam Khurana | 338cd83 | 2018-01-20 05:55:37 +0530 | [diff] [blame^] | 464 | `Tau day <https://tauday.com/>`_ by eating twice as much pie! |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 465 | |
Georg Brandl | 4770d6e | 2016-08-16 07:08:46 +0200 | [diff] [blame] | 466 | .. versionadded:: 3.6 |
| 467 | |
Serhiy Storchaka | dbaf746 | 2017-05-04 12:25:09 +0300 | [diff] [blame] | 468 | |
Mark Dickinson | a5d0c7c | 2015-01-11 11:55:29 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 485 | .. impl-detail:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 486 | |
| 487 | The :mod:`math` module consists mostly of thin wrappers around the platform C |
Mark Dickinson | 603b753 | 2010-04-06 19:55:03 +0000 | [diff] [blame] | 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, |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 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 |
Mark Dickinson | 603b753 | 2010-04-06 19:55:03 +0000 | [diff] [blame] | 496 | are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or |
| 497 | ``hypot(float('nan'), float('inf'))``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 498 | |
Mark Dickinson | 42dfeec | 2010-04-06 22:13:37 +0000 | [diff] [blame] | 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. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 502 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 503 | |
| 504 | .. seealso:: |
| 505 | |
| 506 | Module :mod:`cmath` |
| 507 | Complex number versions of many of these functions. |