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 | |
| 7 | |
| 8 | This module is always available. It provides access to the mathematical |
| 9 | functions defined by the C standard. |
| 10 | |
| 11 | These functions cannot be used with complex numbers; use the functions of the |
| 12 | same name from the :mod:`cmath` module if you require support for complex |
| 13 | numbers. The distinction between functions which support complex numbers and |
| 14 | those which don't is made since most users do not want to learn quite as much |
| 15 | mathematics as required to understand complex numbers. Receiving an exception |
| 16 | instead of a complex result allows earlier detection of the unexpected complex |
| 17 | number used as a parameter, so that the programmer can determine how and why it |
| 18 | was generated in the first place. |
| 19 | |
| 20 | The following functions are provided by this module. Except when explicitly |
| 21 | noted otherwise, all return values are floats. |
| 22 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 24 | Number-theoretic and representation functions |
| 25 | --------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
| 27 | .. function:: ceil(x) |
| 28 | |
Georg Brandl | 2a03373 | 2008-04-05 17:37:09 +0000 | [diff] [blame] | 29 | Return the ceiling of *x*, the smallest integer greater than or equal to *x*. |
| 30 | If *x* is not a float, delegates to ``x.__ceil__()``, which should return an |
| 31 | :class:`Integral` value. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 32 | |
| 33 | |
| 34 | .. function:: copysign(x, y) |
| 35 | |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 36 | Return *x* with the sign of *y*. On a platform that supports |
| 37 | signed zeros, ``copysign(1.0, -0.0)`` returns *-1.0*. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 38 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
| 40 | .. function:: fabs(x) |
| 41 | |
| 42 | Return the absolute value of *x*. |
| 43 | |
Georg Brandl | c28e1fa | 2008-06-10 19:20:26 +0000 | [diff] [blame] | 44 | .. function:: factorial(x) |
| 45 | |
Benjamin Peterson | fea6a94 | 2008-07-02 16:11:42 +0000 | [diff] [blame] | 46 | Return *x* factorial. Raises :exc:`ValueError` if *x* is not integral or |
Georg Brandl | c28e1fa | 2008-06-10 19:20:26 +0000 | [diff] [blame] | 47 | is negative. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
| 49 | .. function:: floor(x) |
| 50 | |
Georg Brandl | 2a03373 | 2008-04-05 17:37:09 +0000 | [diff] [blame] | 51 | Return the floor of *x*, the largest integer less than or equal to *x*. |
| 52 | If *x* is not a float, delegates to ``x.__floor__()``, which should return an |
| 53 | :class:`Integral` value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
| 55 | |
| 56 | .. function:: fmod(x, y) |
| 57 | |
| 58 | Return ``fmod(x, y)``, as defined by the platform C library. Note that the |
| 59 | Python expression ``x % y`` may not return the same result. The intent of the C |
| 60 | standard is that ``fmod(x, y)`` be exactly (mathematically; to infinite |
| 61 | precision) equal to ``x - n*y`` for some integer *n* such that the result has |
| 62 | the same sign as *x* and magnitude less than ``abs(y)``. Python's ``x % y`` |
| 63 | returns a result with the sign of *y* instead, and may not be exactly computable |
| 64 | for float arguments. For example, ``fmod(-1e-100, 1e100)`` is ``-1e-100``, but |
| 65 | the result of Python's ``-1e-100 % 1e100`` is ``1e100-1e-100``, which cannot be |
| 66 | represented exactly as a float, and rounds to the surprising ``1e100``. For |
| 67 | this reason, function :func:`fmod` is generally preferred when working with |
| 68 | floats, while Python's ``x % y`` is preferred when working with integers. |
| 69 | |
| 70 | |
| 71 | .. function:: frexp(x) |
| 72 | |
| 73 | Return the mantissa and exponent of *x* as the pair ``(m, e)``. *m* is a float |
| 74 | and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero, |
| 75 | returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``. This is used to "pick |
| 76 | apart" the internal representation of a float in a portable way. |
| 77 | |
| 78 | |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 79 | .. function:: fsum(iterable) |
| 80 | |
| 81 | Return an accurate floating point sum of values in the iterable. Avoids |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 82 | loss of precision by tracking multiple intermediate partial sums:: |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 83 | |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 84 | >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) |
Mark Dickinson | d1cc39d | 2009-06-28 21:00:42 +0000 | [diff] [blame] | 85 | 0.9999999999999999 |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 86 | >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]) |
| 87 | 1.0 |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 88 | |
Raymond Hettinger | f3936f8 | 2009-02-19 05:48:05 +0000 | [diff] [blame] | 89 | The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the |
| 90 | typical case where the rounding mode is half-even. On some non-Windows |
| 91 | builds, the underlying C library uses extended precision addition and may |
| 92 | occasionally double-round an intermediate sum causing it to be off in its |
| 93 | least significant bit. |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 94 | |
Raymond Hettinger | 477be82 | 2009-02-19 06:44:30 +0000 | [diff] [blame] | 95 | For further discussion and two alternative approaches, see the `ASPN cookbook |
| 96 | recipes for accurate floating point summation |
| 97 | <http://code.activestate.com/recipes/393090/>`_\. |
| 98 | |
Mark Dickinson | aa7633a | 2008-08-01 08:16:13 +0000 | [diff] [blame] | 99 | |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 100 | .. function:: isinf(x) |
| 101 | |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 102 | Check if the float *x* is positive or negative infinity. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 103 | |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 104 | |
| 105 | .. function:: isnan(x) |
| 106 | |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 107 | Check if the float *x* is a NaN (not a number). For more information |
| 108 | on NaNs, see the IEEE 754 standards. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 109 | |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 110 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | .. function:: ldexp(x, i) |
| 112 | |
| 113 | Return ``x * (2**i)``. This is essentially the inverse of function |
| 114 | :func:`frexp`. |
| 115 | |
| 116 | |
| 117 | .. function:: modf(x) |
| 118 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 119 | Return the fractional and integer parts of *x*. Both results carry the sign |
| 120 | of *x* and are floats. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
Christian Heimes | 400adb0 | 2008-02-01 08:12:03 +0000 | [diff] [blame] | 122 | |
| 123 | .. function:: trunc(x) |
| 124 | |
| 125 | Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually |
Mark Dickinson | bf5c6a9 | 2009-01-17 10:21:23 +0000 | [diff] [blame] | 126 | an integer). Delegates to ``x.__trunc__()``. |
Christian Heimes | 400adb0 | 2008-02-01 08:12:03 +0000 | [diff] [blame] | 127 | |
Christian Heimes | 400adb0 | 2008-02-01 08:12:03 +0000 | [diff] [blame] | 128 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | Note that :func:`frexp` and :func:`modf` have a different call/return pattern |
| 130 | than their C equivalents: they take a single argument and return a pair of |
| 131 | values, rather than returning their second return value through an 'output |
| 132 | parameter' (there is no such thing in Python). |
| 133 | |
| 134 | For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all* |
| 135 | floating-point numbers of sufficiently large magnitude are exact integers. |
| 136 | Python floats typically carry no more than 53 bits of precision (the same as the |
| 137 | platform C double type), in which case any float *x* with ``abs(x) >= 2**52`` |
| 138 | necessarily has no fractional bits. |
| 139 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 140 | |
| 141 | Power and logarithmic functions |
| 142 | ------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | .. function:: exp(x) |
| 145 | |
| 146 | Return ``e**x``. |
| 147 | |
| 148 | |
| 149 | .. function:: log(x[, base]) |
| 150 | |
Georg Brandl | 7baf625 | 2009-09-01 08:13:16 +0000 | [diff] [blame] | 151 | With one argument, return the natural logarithm of *x* (to base *e*). |
| 152 | |
| 153 | With two arguments, return the logarithm of *x* to the given *base*, |
| 154 | calculated as ``log(x)/log(base)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 155 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 157 | .. function:: log1p(x) |
| 158 | |
| 159 | Return the natural logarithm of *1+x* (base *e*). The |
| 160 | result is calculated in a way which is accurate for *x* near zero. |
| 161 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 162 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 163 | .. function:: log10(x) |
| 164 | |
Georg Brandl | 7baf625 | 2009-09-01 08:13:16 +0000 | [diff] [blame] | 165 | Return the base-10 logarithm of *x*. This is usually more accurate |
| 166 | than ``log(x, 10)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 167 | |
| 168 | |
| 169 | .. function:: pow(x, y) |
| 170 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 171 | Return ``x`` raised to the power ``y``. Exceptional cases follow |
| 172 | Annex 'F' of the C99 standard as far as possible. In particular, |
| 173 | ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even |
| 174 | when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite, |
| 175 | ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)`` |
| 176 | is undefined, and raises :exc:`ValueError`. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 177 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 178 | |
| 179 | .. function:: sqrt(x) |
| 180 | |
| 181 | Return the square root of *x*. |
| 182 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 183 | Trigonometric functions |
| 184 | ----------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 185 | |
| 186 | |
| 187 | .. function:: acos(x) |
| 188 | |
| 189 | Return the arc cosine of *x*, in radians. |
| 190 | |
| 191 | |
| 192 | .. function:: asin(x) |
| 193 | |
| 194 | Return the arc sine of *x*, in radians. |
| 195 | |
| 196 | |
| 197 | .. function:: atan(x) |
| 198 | |
| 199 | Return the arc tangent of *x*, in radians. |
| 200 | |
| 201 | |
| 202 | .. function:: atan2(y, x) |
| 203 | |
| 204 | Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``. |
| 205 | The vector in the plane from the origin to point ``(x, y)`` makes this angle |
| 206 | with the positive X axis. The point of :func:`atan2` is that the signs of both |
| 207 | inputs are known to it, so it can compute the correct quadrant for the angle. |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 208 | 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] | 209 | -1)`` is ``-3*pi/4``. |
| 210 | |
| 211 | |
| 212 | .. function:: cos(x) |
| 213 | |
| 214 | Return the cosine of *x* radians. |
| 215 | |
| 216 | |
| 217 | .. function:: hypot(x, y) |
| 218 | |
| 219 | Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector |
| 220 | from the origin to point ``(x, y)``. |
| 221 | |
| 222 | |
| 223 | .. function:: sin(x) |
| 224 | |
| 225 | Return the sine of *x* radians. |
| 226 | |
| 227 | |
| 228 | .. function:: tan(x) |
| 229 | |
| 230 | Return the tangent of *x* radians. |
| 231 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 232 | Angular conversion |
| 233 | ------------------ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | |
| 235 | |
| 236 | .. function:: degrees(x) |
| 237 | |
| 238 | Converts angle *x* from radians to degrees. |
| 239 | |
| 240 | |
| 241 | .. function:: radians(x) |
| 242 | |
| 243 | Converts angle *x* from degrees to radians. |
| 244 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 245 | Hyperbolic functions |
| 246 | -------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
| 248 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 249 | .. function:: acosh(x) |
| 250 | |
| 251 | Return the inverse hyperbolic cosine of *x*. |
| 252 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 253 | |
| 254 | .. function:: asinh(x) |
| 255 | |
| 256 | Return the inverse hyperbolic sine of *x*. |
| 257 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 258 | |
| 259 | .. function:: atanh(x) |
| 260 | |
| 261 | Return the inverse hyperbolic tangent of *x*. |
| 262 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 263 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 264 | .. function:: cosh(x) |
| 265 | |
| 266 | Return the hyperbolic cosine of *x*. |
| 267 | |
| 268 | |
| 269 | .. function:: sinh(x) |
| 270 | |
| 271 | Return the hyperbolic sine of *x*. |
| 272 | |
| 273 | |
| 274 | .. function:: tanh(x) |
| 275 | |
| 276 | Return the hyperbolic tangent of *x*. |
| 277 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 278 | |
Benjamin Peterson | 6ebe78f | 2008-12-21 00:06:59 +0000 | [diff] [blame] | 279 | Constants |
Mark Dickinson | 60fe6b0 | 2009-06-02 12:53:15 +0000 | [diff] [blame] | 280 | --------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 281 | |
| 282 | .. data:: pi |
| 283 | |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 284 | The mathematical constant π = 3.141592..., to available precision. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
| 286 | |
| 287 | .. data:: e |
| 288 | |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 289 | The mathematical constant e = 2.718281..., to available precision. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 290 | |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 291 | |
Georg Brandl | 628e6f9 | 2009-10-27 20:24:45 +0000 | [diff] [blame] | 292 | .. impl-detail:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
| 294 | The :mod:`math` module consists mostly of thin wrappers around the platform C |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 295 | math library functions. Behavior in exceptional cases follows Annex F of |
| 296 | the C99 standard where appropriate. The current implementation will raise |
| 297 | :exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)`` |
| 298 | (where C99 Annex F recommends signaling invalid operation or divide-by-zero), |
| 299 | and :exc:`OverflowError` for results that overflow (for example, |
Mark Dickinson | 1862840 | 2010-04-12 18:52:08 +0000 | [diff] [blame] | 300 | ``exp(1000.0)``). A NaN will not be returned from any of the functions |
| 301 | above unless one or more of the input arguments was a NaN; in that case, |
| 302 | most functions will return a NaN, but (again following C99 Annex F) there |
Mark Dickinson | c7d44a4 | 2010-04-06 19:55:38 +0000 | [diff] [blame] | 303 | are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or |
| 304 | ``hypot(float('nan'), float('inf'))``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 305 | |
Mark Dickinson | a3607c8 | 2010-04-06 22:14:23 +0000 | [diff] [blame] | 306 | Note that Python makes no effort to distinguish signaling NaNs from |
| 307 | quiet NaNs, and behavior for signaling NaNs remains unspecified. |
| 308 | Typical behavior is to treat all NaNs as though they were quiet. |
Christian Heimes | 53876d9 | 2008-04-19 00:31:39 +0000 | [diff] [blame] | 309 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 310 | |
| 311 | .. seealso:: |
| 312 | |
| 313 | Module :mod:`cmath` |
| 314 | Complex number versions of many of these functions. |