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 Number-theoretic and representation functions:

    25 

    26 

    27 .. function:: ceil(x)

    28 

    29    Return the ceiling of *x* as a float, the smallest integer value greater than or

    30    equal to *x*.

    31 

    32 

    33 .. function:: copysign(x, y)

    34 

    35    Return *x* with the sign of *y*. ``copysign`` copies the sign bit of an IEEE

    36    754 float, ``copysign(1, -0.0)`` returns *-1.0*.

    37 

    38    .. versionadded:: 2.6

    39 

    40 

    41 .. function:: fabs(x)

    42 

    43    Return the absolute value of *x*.

    44 

    45 

    46 .. function:: factorial(x)

    47 

    48    Return *x* factorial.  Raises :exc:`ValueError` if *x* is not integral or

    49    is negative.

    50 

    51    .. versionadded:: 2.6

    52 

    53 

    54 .. function:: floor(x)

    55 

    56    Return the floor of *x* as a float, the largest integer value less than or equal

    57    to *x*.

    58 

    59    .. versionchanged:: 2.6

    60       Added :meth:`__floor__` delegation.

    61 

    62 

    63 .. function:: fmod(x, y)

    64 

    65    Return ``fmod(x, y)``, as defined by the platform C library. Note that the

    66    Python expression ``x % y`` may not return the same result.  The intent of the C

    67    standard is that ``fmod(x, y)`` be exactly (mathematically; to infinite

    68    precision) equal to ``x - n*y`` for some integer *n* such that the result has

    69    the same sign as *x* and magnitude less than ``abs(y)``.  Python's ``x % y``

    70    returns a result with the sign of *y* instead, and may not be exactly computable

    71    for float arguments. For example, ``fmod(-1e-100, 1e100)`` is ``-1e-100``, but

    72    the result of Python's ``-1e-100 % 1e100`` is ``1e100-1e-100``, which cannot be

    73    represented exactly as a float, and rounds to the surprising ``1e100``.  For

    74    this reason, function :func:`fmod` is generally preferred when working with

    75    floats, while Python's ``x % y`` is preferred when working with integers.

    76 

    77 

    78 .. function:: frexp(x)

    79 

    80    Return the mantissa and exponent of *x* as the pair ``(m, e)``.  *m* is a float

    81    and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero,

    82    returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``.  This is used to "pick

    83    apart" the internal representation of a float in a portable way.

    84 

    85 

    86 .. function:: fsum(iterable)

    87 

    88    Return an accurate floating point sum of values in the iterable.  Avoids

    89    loss of precision by tracking multiple intermediate partial sums.  The

    90    algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the

    91    typical case where the rounding mode is half-even.

    92 

    93    .. note::

    94 

    95       The accuracy of fsum() may be impaired on builds that use

    96       extended precision addition and then double-round the results.

    97 

    98    .. versionadded:: 2.6

    99 

   100 

   101 .. function:: isinf(x)

   102 

   103    Checks if the float *x* is positive or negative infinite.

   104 

   105    .. versionadded:: 2.6

   106 

   107 

   108 .. function:: isnan(x)

   109 

   110    Checks if the float *x* is a NaN (not a number). NaNs are part of the

   111    IEEE 754 standards. Operation like but not limited to ``inf * 0``, 

   112    ``inf / inf`` or any operation involving a NaN, e.g. ``nan * 1``, return

   113    a NaN.

   114 

   115    .. versionadded:: 2.6

   116 

   117 

   118 .. function:: ldexp(x, i)

   119 

   120    Return ``x * (2**i)``.  This is essentially the inverse of function

   121    :func:`frexp`.

   122 

   123 

   124 .. function:: modf(x)

   125 

   126    Return the fractional and integer parts of *x*.  Both results carry the sign of

   127    *x*, and both are floats.

   128 

   129 

   130 .. function:: trunc(x)

   131 

   132    Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually

   133    a long integer). Delegates to ``x.__trunc__()``.

   134 

   135    .. versionadded:: 2.6

   136 

   137 

   138 Note that :func:`frexp` and :func:`modf` have a different call/return pattern

   139 than their C equivalents: they take a single argument and return a pair of

   140 values, rather than returning their second return value through an 'output

   141 parameter' (there is no such thing in Python).

   142 

   143 For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*

   144 floating-point numbers of sufficiently large magnitude are exact integers.

   145 Python floats typically carry no more than 53 bits of precision (the same as the

   146 platform C double type), in which case any float *x* with ``abs(x) >= 2**52``

   147 necessarily has no fractional bits.

   148 

   149 Power and logarithmic functions:

   150 

   151 .. function:: exp(x)

   152 

   153    Return ``e**x``.

   154 

   155 

   156 .. function:: log(x[, base])

   157 

   158    Return the logarithm of *x* to the given *base*. If the *base* is not specified,

   159    return the natural logarithm of *x* (that is, the logarithm to base *e*).

   160 

   161    .. versionchanged:: 2.3

   162       *base* argument added.

   163 

   164 

   165 .. function:: log1p(x)

   166 

   167    Return the natural logarithm of *1+x* (base *e*). The

   168    result is calculated in a way which is accurate for *x* near zero.

   169 

   170    .. versionadded:: 2.6

   171 

   172 

   173 .. function:: log10(x)

   174 

   175    Return the base-10 logarithm of *x*.

   176 

   177 

   178 .. function:: pow(x, y)

   179 

   180    Return ``x`` raised to the power ``y``.  Exceptional cases follow

   181    Annex 'F' of the C99 standard as far as possible.  In particular,

   182    ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even

   183    when ``x`` is a zero or a NaN.  If both ``x`` and ``y`` are finite,

   184    ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``

   185    is undefined, and raises :exc:`ValueError`.

   186 

   187    .. versionchanged:: 2.6

   188       The outcome of ``1**nan`` and ``nan**0`` was undefined.

   189 

   190 

   191 .. function:: sqrt(x)

   192 

   193    Return the square root of *x*.

   194 

   195 

   196 Trigonometric functions:

   197 

   198 .. function:: acos(x)

   199 

   200    Return the arc cosine of *x*, in radians.

   201 

   202 

   203 .. function:: asin(x)

   204 

   205    Return the arc sine of *x*, in radians.

   206 

   207 

   208 .. function:: atan(x)

   209 

   210    Return the arc tangent of *x*, in radians.

   211 

   212 

   213 .. function:: atan2(y, x)

   214 

   215    Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.

   216    The vector in the plane from the origin to point ``(x, y)`` makes this angle

   217    with the positive X axis. The point of :func:`atan2` is that the signs of both

   218    inputs are known to it, so it can compute the correct quadrant for the angle.

   219    For example, ``atan(1``) and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1,

   220    -1)`` is ``-3*pi/4``.

   221 

   222 

   223 .. function:: cos(x)

   224 

   225    Return the cosine of *x* radians.

   226 

   227 

   228 .. function:: hypot(x, y)

   229 

   230    Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector

   231    from the origin to point ``(x, y)``.

   232 

   233 

   234 .. function:: sin(x)

   235 

   236    Return the sine of *x* radians.

   237 

   238 

   239 .. function:: tan(x)

   240 

   241    Return the tangent of *x* radians.

   242 

   243 

   244 Angular conversion:

   245 

   246 .. function:: degrees(x)

   247 

   248    Converts angle *x* from radians to degrees.

   249 

   250 

   251 .. function:: radians(x)

   252 

   253    Converts angle *x* from degrees to radians.

   254 

   255 

   256 Hyperbolic functions:

   257 

   258 .. function:: acosh(x)

   259 

   260    Return the inverse hyperbolic cosine of *x*.

   261 

   262    .. versionadded:: 2.6

   263 

   264 

   265 .. function:: asinh(x)

   266 

   267    Return the inverse hyperbolic sine of *x*.

   268 

   269    .. versionadded:: 2.6

   270 

   271 

   272 .. function:: atanh(x)

   273 

   274    Return the inverse hyperbolic tangent of *x*.

   275 

   276    .. versionadded:: 2.6

   277 

   278 

   279 .. function:: cosh(x)

   280 

   281    Return the hyperbolic cosine of *x*.

   282 

   283 

   284 .. function:: sinh(x)

   285 

   286    Return the hyperbolic sine of *x*.

   287 

   288 

   289 .. function:: tanh(x)

   290 

   291    Return the hyperbolic tangent of *x*.

   292 

   293 

   294 The module also defines two mathematical constants:

   295 

   296 .. data:: pi

   297 

   298    The mathematical constant *pi*.

   299 

   300 

   301 .. data:: e

   302 

   303    The mathematical constant *e*.

   304 

   305 

   306 .. note::

   307 

   308    The :mod:`math` module consists mostly of thin wrappers around the platform C

   309    math library functions.  Behavior in exceptional cases is loosely specified

   310    by the C standards, and Python inherits much of its math-function

   311    error-reporting behavior from the platform C implementation.  As a result,

   312    the specific exceptions raised in error cases (and even whether some

   313    arguments are considered to be exceptional at all) are not defined in any

   314    useful cross-platform or cross-release way.  For example, whether

   315    ``math.log(0)`` returns ``-Inf`` or raises :exc:`ValueError` or

   316    :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises

   317    :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead.

   318 

   319    All functions return a quiet *NaN* if at least one of the args is *NaN*.

   320    Signaling *NaN*\s raise an exception. The exception type still depends on the

   321    platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*

   322    and :exc:`OverflowError` for errno *ERANGE*.

   323 

   324    .. versionchanged:: 2.6

   325       In earlier versions of Python the outcome of an operation with NaN as

   326       input depended on platform and libm implementation.

   327 

   328 

   329 .. seealso::

   330 

   331    Module :mod:`cmath`

   332       Complex number versions of many of these functions.