Doc/library/math.rst

   1
   2 :mod:`math` --- Mathematical functions
   3 ======================================
   4
   5 .. module:: math
   6    :synopsis: Mathematical functions (sin() etc.).
   7
   8
   9 This module is always available.  It provides access to the mathematical
  10 functions defined by the C standard.
  11
  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.
  20
  21 The following functions are provided by this module.  Except when explicitly
  22 noted otherwise, all return values are floats.
  23
  24
  25 Number-theoretic and representation functions
  26 ---------------------------------------------
  27
  28 .. function:: ceil(x)
  29
  30    Return the ceiling of *x* as a float, the smallest integer value greater than or
  31    equal to *x*.
  32
  33
  34 .. function:: copysign(x, y)
  35
  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*.
  38
  39    .. versionadded:: 2.6
  40
  41
  42 .. function:: fabs(x)
  43
  44    Return the absolute value of *x*.
  45
  46
  47 .. function:: factorial(x)
  48
  49    Return *x* factorial.  Raises :exc:`ValueError` if *x* is not integral or
  50    is negative.
  51
  52    .. versionadded:: 2.6
  53
  54
  55 .. function:: floor(x)
  56
  57    Return the floor of *x* as a float, the largest integer value less than or equal
  58    to *x*.
  59
  60    .. versionchanged:: 2.6
  61       Added :meth:`__floor__` delegation.
  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.99999999999999989
  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    <http://code.activestate.com/recipes/393090/>`_\.
 106
 107    .. versionadded:: 2.6
 108
 109
 110 .. function:: isinf(x)
 111
 112    Checks if the float *x* is positive or negative infinite.
 113
 114    .. versionadded:: 2.6
 115
 116
 117 .. function:: isnan(x)
 118
 119    Checks if the float *x* is a NaN (not a number). NaNs are part of the
 120    IEEE 754 standards. Operation like but not limited to ``inf * 0``,
 121    ``inf / inf`` or any operation involving a NaN, e.g. ``nan * 1``, return
 122    a NaN.
 123
 124    .. versionadded:: 2.6
 125
 126
 127 .. function:: ldexp(x, i)
 128
 129    Return ``x * (2**i)``.  This is essentially the inverse of function
 130    :func:`frexp`.
 131
 132
 133 .. function:: modf(x)
 134
 135    Return the fractional and integer parts of *x*.  Both results carry the sign
 136    of *x* and are floats.
 137
 138
 139 .. function:: trunc(x)
 140
 141    Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
 142    a long integer). Delegates to ``x.__trunc__()``.
 143
 144    .. versionadded:: 2.6
 145
 146
 147 Note that :func:`frexp` and :func:`modf` have a different call/return pattern
 148 than their C equivalents: they take a single argument and return a pair of
 149 values, rather than returning their second return value through an 'output
 150 parameter' (there is no such thing in Python).
 151
 152 For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
 153 floating-point numbers of sufficiently large magnitude are exact integers.
 154 Python floats typically carry no more than 53 bits of precision (the same as the
 155 platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
 156 necessarily has no fractional bits.
 157
 158
 159 Power and logarithmic functions
 160 -------------------------------
 161
 162 .. function:: exp(x)
 163
 164    Return ``e**x``.
 165
 166
 167 .. function:: log(x[, base])
 168
 169    Return the logarithm of *x* to the given *base*. If the *base* is not specified,
 170    return the natural logarithm of *x* (that is, the logarithm to base *e*).
 171
 172    .. versionchanged:: 2.3
 173       *base* argument added.
 174
 175
 176 .. function:: log1p(x)
 177
 178    Return the natural logarithm of *1+x* (base *e*). The
 179    result is calculated in a way which is accurate for *x* near zero.
 180
 181    .. versionadded:: 2.6
 182
 183
 184 .. function:: log10(x)
 185
 186    Return the base-10 logarithm of *x*.
 187
 188
 189 .. function:: pow(x, y)
 190
 191    Return ``x`` raised to the power ``y``.  Exceptional cases follow
 192    Annex 'F' of the C99 standard as far as possible.  In particular,
 193    ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
 194    when ``x`` is a zero or a NaN.  If both ``x`` and ``y`` are finite,
 195    ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
 196    is undefined, and raises :exc:`ValueError`.
 197
 198    .. versionchanged:: 2.6
 199       The outcome of ``1**nan`` and ``nan**0`` was undefined.
 200
 201
 202 .. function:: sqrt(x)
 203
 204    Return the square root of *x*.
 205
 206
 207 Trigonometric functions
 208 -----------------------
 209
 210 .. function:: acos(x)
 211
 212    Return the arc cosine of *x*, in radians.
 213
 214
 215 .. function:: asin(x)
 216
 217    Return the arc sine of *x*, in radians.
 218
 219
 220 .. function:: atan(x)
 221
 222    Return the arc tangent of *x*, in radians.
 223
 224
 225 .. function:: atan2(y, x)
 226
 227    Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
 228    The vector in the plane from the origin to point ``(x, y)`` makes this angle
 229    with the positive X axis. The point of :func:`atan2` is that the signs of both
 230    inputs are known to it, so it can compute the correct quadrant for the angle.
 231    For example, ``atan(1``) and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1,
 232    -1)`` is ``-3*pi/4``.
 233
 234
 235 .. function:: cos(x)
 236
 237    Return the cosine of *x* radians.
 238
 239
 240 .. function:: hypot(x, y)
 241
 242    Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector
 243    from the origin to point ``(x, y)``.
 244
 245
 246 .. function:: sin(x)
 247
 248    Return the sine of *x* radians.
 249
 250
 251 .. function:: tan(x)
 252
 253    Return the tangent of *x* radians.
 254
 255
 256 Angular conversion
 257 ------------------
 258
 259 .. function:: degrees(x)
 260
 261    Converts angle *x* from radians to degrees.
 262
 263
 264 .. function:: radians(x)
 265
 266    Converts angle *x* from degrees to radians.
 267
 268
 269 Hyperbolic functions
 270 --------------------
 271
 272 .. function:: acosh(x)
 273
 274    Return the inverse hyperbolic cosine of *x*.
 275
 276    .. versionadded:: 2.6
 277
 278
 279 .. function:: asinh(x)
 280
 281    Return the inverse hyperbolic sine of *x*.
 282
 283    .. versionadded:: 2.6
 284
 285
 286 .. function:: atanh(x)
 287
 288    Return the inverse hyperbolic tangent of *x*.
 289
 290    .. versionadded:: 2.6
 291
 292
 293 .. function:: cosh(x)
 294
 295    Return the hyperbolic cosine of *x*.
 296
 297
 298 .. function:: sinh(x)
 299
 300    Return the hyperbolic sine of *x*.
 301
 302
 303 .. function:: tanh(x)
 304
 305    Return the hyperbolic tangent of *x*.
 306
 307
 308 Constants
 309 ---------
 310
 311 .. data:: pi
 312
 313    The mathematical constant *pi*.
 314
 315
 316 .. data:: e
 317
 318    The mathematical constant *e*.
 319
 320
 321 .. note::
 322
 323    The :mod:`math` module consists mostly of thin wrappers around the platform C
 324    math library functions.  Behavior in exceptional cases is loosely specified
 325    by the C standards, and Python inherits much of its math-function
 326    error-reporting behavior from the platform C implementation.  As a result,
 327    the specific exceptions raised in error cases (and even whether some
 328    arguments are considered to be exceptional at all) are not defined in any
 329    useful cross-platform or cross-release way.  For example, whether
 330    ``math.log(0)`` returns ``-Inf`` or raises :exc:`ValueError` or
 331    :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises
 332    :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead.
 333
 334    All functions return a quiet *NaN* if at least one of the args is *NaN*.
 335    Signaling *NaN*\s raise an exception. The exception type still depends on the
 336    platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*
 337    and :exc:`OverflowError` for errno *ERANGE*.
 338
 339    .. versionchanged:: 2.6
 340       In earlier versions of Python the outcome of an operation with NaN as
 341       input depended on platform and libm implementation.
 342
 343
 344 .. seealso::
 345
 346    Module :mod:`cmath`
 347       Complex number versions of many of these functions.