mirror of https://github.com/python/cpython
467 lines
14 KiB
ReStructuredText
467 lines
14 KiB
ReStructuredText
:mod:`math` --- Mathematical functions
|
|
======================================
|
|
|
|
.. module:: math
|
|
:synopsis: Mathematical functions (sin() etc.).
|
|
|
|
.. testsetup::
|
|
|
|
from math import fsum
|
|
|
|
This module is always available. It provides access to the mathematical
|
|
functions defined by the C standard.
|
|
|
|
These functions cannot be used with complex numbers; use the functions of the
|
|
same name from the :mod:`cmath` module if you require support for complex
|
|
numbers. The distinction between functions which support complex numbers and
|
|
those which don't is made since most users do not want to learn quite as much
|
|
mathematics as required to understand complex numbers. Receiving an exception
|
|
instead of a complex result allows earlier detection of the unexpected complex
|
|
number used as a parameter, so that the programmer can determine how and why it
|
|
was generated in the first place.
|
|
|
|
The following functions are provided by this module. Except when explicitly
|
|
noted otherwise, all return values are floats.
|
|
|
|
|
|
Number-theoretic and representation functions
|
|
---------------------------------------------
|
|
|
|
.. function:: ceil(x)
|
|
|
|
Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
|
|
If *x* is not a float, delegates to ``x.__ceil__()``, which should return an
|
|
:class:`~numbers.Integral` value.
|
|
|
|
|
|
.. function:: copysign(x, y)
|
|
|
|
Return a float with the magnitude (absolute value) of *x* but the sign of
|
|
*y*. On platforms that support signed zeros, ``copysign(1.0, -0.0)``
|
|
returns *-1.0*.
|
|
|
|
.. function:: fabs(x)
|
|
|
|
Return the absolute value of *x*.
|
|
|
|
.. function:: factorial(x)
|
|
|
|
Return *x* factorial. Raises :exc:`ValueError` if *x* is not integral or
|
|
is negative.
|
|
|
|
.. function:: floor(x)
|
|
|
|
Return the floor of *x*, the largest integer less than or equal to *x*.
|
|
If *x* is not a float, delegates to ``x.__floor__()``, which should return an
|
|
:class:`~numbers.Integral` value.
|
|
|
|
|
|
.. function:: fmod(x, y)
|
|
|
|
Return ``fmod(x, y)``, as defined by the platform C library. Note that the
|
|
Python expression ``x % y`` may not return the same result. The intent of the C
|
|
standard is that ``fmod(x, y)`` be exactly (mathematically; to infinite
|
|
precision) equal to ``x - n*y`` for some integer *n* such that the result has
|
|
the same sign as *x* and magnitude less than ``abs(y)``. Python's ``x % y``
|
|
returns a result with the sign of *y* instead, and may not be exactly computable
|
|
for float arguments. For example, ``fmod(-1e-100, 1e100)`` is ``-1e-100``, but
|
|
the result of Python's ``-1e-100 % 1e100`` is ``1e100-1e-100``, which cannot be
|
|
represented exactly as a float, and rounds to the surprising ``1e100``. For
|
|
this reason, function :func:`fmod` is generally preferred when working with
|
|
floats, while Python's ``x % y`` is preferred when working with integers.
|
|
|
|
|
|
.. function:: frexp(x)
|
|
|
|
Return the mantissa and exponent of *x* as the pair ``(m, e)``. *m* is a float
|
|
and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero,
|
|
returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``. This is used to "pick
|
|
apart" the internal representation of a float in a portable way.
|
|
|
|
|
|
.. function:: fsum(iterable)
|
|
|
|
Return an accurate floating point sum of values in the iterable. Avoids
|
|
loss of precision by tracking multiple intermediate partial sums::
|
|
|
|
>>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
|
|
0.9999999999999999
|
|
>>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
|
|
1.0
|
|
|
|
The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
|
|
typical case where the rounding mode is half-even. On some non-Windows
|
|
builds, the underlying C library uses extended precision addition and may
|
|
occasionally double-round an intermediate sum causing it to be off in its
|
|
least significant bit.
|
|
|
|
For further discussion and two alternative approaches, see the `ASPN cookbook
|
|
recipes for accurate floating point summation
|
|
<https://code.activestate.com/recipes/393090/>`_\.
|
|
|
|
|
|
.. function:: gcd(a, b)
|
|
|
|
Return the greatest common divisor of the integers *a* and *b*. If either
|
|
*a* or *b* is nonzero, then the value of ``gcd(a, b)`` is the largest
|
|
positive integer that divides both *a* and *b*. ``gcd(0, 0)`` returns
|
|
``0``.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)
|
|
|
|
Return ``True`` if the values *a* and *b* are close to each other and
|
|
``False`` otherwise.
|
|
|
|
Whether or not two values are considered close is determined according to
|
|
given absolute and relative tolerances.
|
|
|
|
*rel_tol* is the relative tolerance -- it is the maximum allowed difference
|
|
between *a* and *b*, relative to the larger absolute value of *a* or *b*.
|
|
For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default
|
|
tolerance is ``1e-09``, which assures that the two values are the same
|
|
within about 9 decimal digits. *rel_tol* must be greater than zero.
|
|
|
|
*abs_tol* is the minimum absolute tolerance -- useful for comparisons near
|
|
zero. *abs_tol* must be at least zero.
|
|
|
|
If no errors occur, the result will be:
|
|
``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``.
|
|
|
|
The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be
|
|
handled according to IEEE rules. Specifically, ``NaN`` is not considered
|
|
close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only
|
|
considered close to themselves.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
.. seealso::
|
|
|
|
:pep:`485` -- A function for testing approximate equality
|
|
|
|
|
|
.. function:: isfinite(x)
|
|
|
|
Return ``True`` if *x* is neither an infinity nor a NaN, and
|
|
``False`` otherwise. (Note that ``0.0`` *is* considered finite.)
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
|
.. function:: isinf(x)
|
|
|
|
Return ``True`` if *x* is a positive or negative infinity, and
|
|
``False`` otherwise.
|
|
|
|
|
|
.. function:: isnan(x)
|
|
|
|
Return ``True`` if *x* is a NaN (not a number), and ``False`` otherwise.
|
|
|
|
|
|
.. function:: ldexp(x, i)
|
|
|
|
Return ``x * (2**i)``. This is essentially the inverse of function
|
|
:func:`frexp`.
|
|
|
|
|
|
.. function:: modf(x)
|
|
|
|
Return the fractional and integer parts of *x*. Both results carry the sign
|
|
of *x* and are floats.
|
|
|
|
|
|
.. function:: trunc(x)
|
|
|
|
Return the :class:`~numbers.Real` value *x* truncated to an
|
|
:class:`~numbers.Integral` (usually an integer). Delegates to
|
|
``x.__trunc__()``.
|
|
|
|
|
|
Note that :func:`frexp` and :func:`modf` have a different call/return pattern
|
|
than their C equivalents: they take a single argument and return a pair of
|
|
values, rather than returning their second return value through an 'output
|
|
parameter' (there is no such thing in Python).
|
|
|
|
For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
|
|
floating-point numbers of sufficiently large magnitude are exact integers.
|
|
Python floats typically carry no more than 53 bits of precision (the same as the
|
|
platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
|
|
necessarily has no fractional bits.
|
|
|
|
|
|
Power and logarithmic functions
|
|
-------------------------------
|
|
|
|
.. function:: exp(x)
|
|
|
|
Return ``e**x``.
|
|
|
|
|
|
.. function:: expm1(x)
|
|
|
|
Return ``e**x - 1``. For small floats *x*, the subtraction in ``exp(x) - 1``
|
|
can result in a `significant loss of precision
|
|
<https://en.wikipedia.org/wiki/Loss_of_significance>`_\; the :func:`expm1`
|
|
function provides a way to compute this quantity to full precision::
|
|
|
|
>>> from math import exp, expm1
|
|
>>> exp(1e-5) - 1 # gives result accurate to 11 places
|
|
1.0000050000069649e-05
|
|
>>> expm1(1e-5) # result accurate to full precision
|
|
1.0000050000166668e-05
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
|
.. function:: log(x[, base])
|
|
|
|
With one argument, return the natural logarithm of *x* (to base *e*).
|
|
|
|
With two arguments, return the logarithm of *x* to the given *base*,
|
|
calculated as ``log(x)/log(base)``.
|
|
|
|
|
|
.. function:: log1p(x)
|
|
|
|
Return the natural logarithm of *1+x* (base *e*). The
|
|
result is calculated in a way which is accurate for *x* near zero.
|
|
|
|
|
|
.. function:: log2(x)
|
|
|
|
Return the base-2 logarithm of *x*. This is usually more accurate than
|
|
``log(x, 2)``.
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
.. seealso::
|
|
|
|
:meth:`int.bit_length` returns the number of bits necessary to represent
|
|
an integer in binary, excluding the sign and leading zeros.
|
|
|
|
|
|
.. function:: log10(x)
|
|
|
|
Return the base-10 logarithm of *x*. This is usually more accurate
|
|
than ``log(x, 10)``.
|
|
|
|
|
|
.. function:: pow(x, y)
|
|
|
|
Return ``x`` raised to the power ``y``. Exceptional cases follow
|
|
Annex 'F' of the C99 standard as far as possible. In particular,
|
|
``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
|
|
when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite,
|
|
``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
|
|
is undefined, and raises :exc:`ValueError`.
|
|
|
|
Unlike the built-in ``**`` operator, :func:`math.pow` converts both
|
|
its arguments to type :class:`float`. Use ``**`` or the built-in
|
|
:func:`pow` function for computing exact integer powers.
|
|
|
|
|
|
.. function:: sqrt(x)
|
|
|
|
Return the square root of *x*.
|
|
|
|
Trigonometric functions
|
|
-----------------------
|
|
|
|
|
|
.. function:: acos(x)
|
|
|
|
Return the arc cosine of *x*, in radians.
|
|
|
|
|
|
.. function:: asin(x)
|
|
|
|
Return the arc sine of *x*, in radians.
|
|
|
|
|
|
.. function:: atan(x)
|
|
|
|
Return the arc tangent of *x*, in radians.
|
|
|
|
|
|
.. function:: atan2(y, x)
|
|
|
|
Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
|
|
The vector in the plane from the origin to point ``(x, y)`` makes this angle
|
|
with the positive X axis. The point of :func:`atan2` is that the signs of both
|
|
inputs are known to it, so it can compute the correct quadrant for the angle.
|
|
For example, ``atan(1)`` and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1,
|
|
-1)`` is ``-3*pi/4``.
|
|
|
|
|
|
.. function:: cos(x)
|
|
|
|
Return the cosine of *x* radians.
|
|
|
|
|
|
.. function:: hypot(x, y)
|
|
|
|
Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector
|
|
from the origin to point ``(x, y)``.
|
|
|
|
|
|
.. function:: sin(x)
|
|
|
|
Return the sine of *x* radians.
|
|
|
|
|
|
.. function:: tan(x)
|
|
|
|
Return the tangent of *x* radians.
|
|
|
|
Angular conversion
|
|
------------------
|
|
|
|
|
|
.. function:: degrees(x)
|
|
|
|
Convert angle *x* from radians to degrees.
|
|
|
|
|
|
.. function:: radians(x)
|
|
|
|
Convert angle *x* from degrees to radians.
|
|
|
|
Hyperbolic functions
|
|
--------------------
|
|
|
|
`Hyperbolic functions <https://en.wikipedia.org/wiki/Hyperbolic_function>`_
|
|
are analogs of trigonometric functions that are based on hyperbolas
|
|
instead of circles.
|
|
|
|
.. function:: acosh(x)
|
|
|
|
Return the inverse hyperbolic cosine of *x*.
|
|
|
|
|
|
.. function:: asinh(x)
|
|
|
|
Return the inverse hyperbolic sine of *x*.
|
|
|
|
|
|
.. function:: atanh(x)
|
|
|
|
Return the inverse hyperbolic tangent of *x*.
|
|
|
|
|
|
.. function:: cosh(x)
|
|
|
|
Return the hyperbolic cosine of *x*.
|
|
|
|
|
|
.. function:: sinh(x)
|
|
|
|
Return the hyperbolic sine of *x*.
|
|
|
|
|
|
.. function:: tanh(x)
|
|
|
|
Return the hyperbolic tangent of *x*.
|
|
|
|
|
|
Special functions
|
|
-----------------
|
|
|
|
.. function:: erf(x)
|
|
|
|
Return the `error function <https://en.wikipedia.org/wiki/Error_function>`_ at
|
|
*x*.
|
|
|
|
The :func:`erf` function can be used to compute traditional statistical
|
|
functions such as the `cumulative standard normal distribution
|
|
<https://en.wikipedia.org/wiki/Normal_distribution#Cumulative_distribution_function>`_::
|
|
|
|
def phi(x):
|
|
'Cumulative distribution function for the standard normal distribution'
|
|
return (1.0 + erf(x / sqrt(2.0))) / 2.0
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
|
.. function:: erfc(x)
|
|
|
|
Return the complementary error function at *x*. The `complementary error
|
|
function <https://en.wikipedia.org/wiki/Error_function>`_ is defined as
|
|
``1.0 - erf(x)``. It is used for large values of *x* where a subtraction
|
|
from one would cause a `loss of significance
|
|
<https://en.wikipedia.org/wiki/Loss_of_significance>`_\.
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
|
.. function:: gamma(x)
|
|
|
|
Return the `Gamma function <https://en.wikipedia.org/wiki/Gamma_function>`_ at
|
|
*x*.
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
|
.. function:: lgamma(x)
|
|
|
|
Return the natural logarithm of the absolute value of the Gamma
|
|
function at *x*.
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
|
Constants
|
|
---------
|
|
|
|
.. data:: pi
|
|
|
|
The mathematical constant π = 3.141592..., to available precision.
|
|
|
|
|
|
.. data:: e
|
|
|
|
The mathematical constant e = 2.718281..., to available precision.
|
|
|
|
|
|
.. data:: inf
|
|
|
|
A floating-point positive infinity. (For negative infinity, use
|
|
``-math.inf``.) Equivalent to the output of ``float('inf')``.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. data:: nan
|
|
|
|
A floating-point "not a number" (NaN) value. Equivalent to the output of
|
|
``float('nan')``.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
|
|
.. impl-detail::
|
|
|
|
The :mod:`math` module consists mostly of thin wrappers around the platform C
|
|
math library functions. Behavior in exceptional cases follows Annex F of
|
|
the C99 standard where appropriate. The current implementation will raise
|
|
:exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)``
|
|
(where C99 Annex F recommends signaling invalid operation or divide-by-zero),
|
|
and :exc:`OverflowError` for results that overflow (for example,
|
|
``exp(1000.0)``). A NaN will not be returned from any of the functions
|
|
above unless one or more of the input arguments was a NaN; in that case,
|
|
most functions will return a NaN, but (again following C99 Annex F) there
|
|
are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or
|
|
``hypot(float('nan'), float('inf'))``.
|
|
|
|
Note that Python makes no effort to distinguish signaling NaNs from
|
|
quiet NaNs, and behavior for signaling NaNs remains unspecified.
|
|
Typical behavior is to treat all NaNs as though they were quiet.
|
|
|
|
|
|
.. seealso::
|
|
|
|
Module :mod:`cmath`
|
|
Complex number versions of many of these functions.
|