Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Doc: Reorganize math module documentation (#126337) 

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
This commit is contained in:
Joseph Martinot-Lagarde 2024-11-18 08:57:32 +01:00 committed by GitHub
parent 500a4712bb
commit ce453e6c2f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 263 additions and 239 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

500
Doc/library/math.rst
View File

@ -27,36 +27,39 @@ noted otherwise, all return values are floats.
==================================================== ============================================
**Number-theoretic and representation functions**
**Number-theoretic functions**
--------------------------------------------------------------------------------------------------
:func:`comb(n, k) <comb>` Number of ways to choose *k* items from *n* items without repetition and without order
:func:`factorial(n) <factorial>` *n* factorial
:func:`gcd(*integers) <gcd>` Greatest common divisor of the integer arguments
:func:`isqrt(n) <isqrt>` Integer square root of a nonnegative integer *n*
:func:`lcm(*integers) <lcm>` Least common multiple of the integer arguments
:func:`perm(n, k) <perm>` Number of ways to choose *k* items from *n* items without repetition and with order
**Floating point arithmetic**
--------------------------------------------------------------------------------------------------
:func:`ceil(x) <ceil>` Ceiling of *x*, the smallest integer greater than or equal to *x*
:func:`comb(n, k) <comb>` Number of ways to choose *k* items from *n* items without repetition and without order
:func:`copysign(x, y) <copysign>` Magnitude (absolute value) of *x* with the sign of *y*
:func:`fabs(x) <fabs>` Absolute value of *x*
:func:`factorial(n) <factorial>` *n* factorial
:func:`floor(x) <floor>` Floor of *x*, the largest integer less than or equal to *x*
:func:`fma(x, y, z) <fma>` Fused multiply-add operation: ``(x * y) + z``
:func:`fmod(x, y) <fmod>` Remainder of division ``x / y``
:func:`modf(x) <modf>` Fractional and integer parts of *x*
:func:`remainder(x, y) <remainder>` Remainder of *x* with respect to *y*
:func:`trunc(x) <trunc>` Integer part of *x*
**Floating point manipulation functions**
--------------------------------------------------------------------------------------------------
:func:`copysign(x, y) <copysign>` Magnitude (absolute value) of *x* with the sign of *y*
:func:`frexp(x) <frexp>` Mantissa and exponent of *x*
:func:`fsum(iterable) <fsum>` Sum of values in the input *iterable*
:func:`gcd(*integers) <gcd>` Greatest common divisor of the integer arguments
:func:`isclose(a, b, rel_tol, abs_tol) <isclose>` Check if the values *a* and *b* are close to each other
:func:`isfinite(x) <isfinite>` Check if *x* is neither an infinity nor a NaN
:func:`isinf(x) <isinf>` Check if *x* is a positive or negative infinity
:func:`isnan(x) <isnan>` Check if *x* is a NaN (not a number)
:func:`isqrt(n) <isqrt>` Integer square root of a nonnegative integer *n*
:func:`lcm(*integers) <lcm>` Least common multiple of the integer arguments
:func:`ldexp(x, i) <ldexp>` ``x * (2**i)``, inverse of function :func:`frexp`
:func:`modf(x) <modf>` Fractional and integer parts of *x*
:func:`nextafter(x, y, steps) <nextafter>` Floating-point value *steps* steps after *x* towards *y*
:func:`perm(n, k) <perm>` Number of ways to choose *k* items from *n* items without repetition and with order
:func:`prod(iterable, start) <prod>` Product of elements in the input *iterable* with a *start* value
:func:`remainder(x, y) <remainder>` Remainder of *x* with respect to *y*
:func:`sumprod(p, q) <sumprod>` Sum of products from two iterables *p* and *q*
:func:`trunc(x) <trunc>` Integer part of *x*
:func:`ulp(x) <ulp>` Value of the least significant bit of *x*
**Power and logarithmic functions**
**Power, exponential and logarithmic functions**
--------------------------------------------------------------------------------------------------
:func:`cbrt(x) <cbrt>` Cube root of *x*
:func:`exp(x) <exp>` *e* raised to the power *x*
@ -69,6 +72,19 @@ noted otherwise, all return values are floats.
:func:`pow(x, y) <math.pow>` *x* raised to the power *y*
:func:`sqrt(x) <sqrt>` Square root of *x*
**Summation and product functions**
--------------------------------------------------------------------------------------------------
:func:`dist(p, q) <dist>` Euclidean distance between two points *p* and *q* given as an iterable of coordinates
:func:`fsum(iterable) <fsum>` Sum of values in the input *iterable*
:func:`hypot(*coordinates) <hypot>` Euclidean norm of an iterable of coordinates
:func:`prod(iterable, start) <prod>` Product of elements in the input *iterable* with a *start* value
:func:`sumprod(p, q) <sumprod>` Sum of products from two iterables *p* and *q*
**Angular conversion**
--------------------------------------------------------------------------------------------------
:func:`degrees(x) <degrees>` Convert angle *x* from radians to degrees
:func:`radians(x) <radians>` Convert angle *x* from degrees to radians
**Trigonometric functions**
--------------------------------------------------------------------------------------------------
:func:`acos(x) <acos>` Arc cosine of *x*
@ -76,16 +92,9 @@ noted otherwise, all return values are floats.
:func:`atan(x) <atan>` Arc tangent of *x*
:func:`atan2(y, x) <atan2>` ``atan(y / x)``
:func:`cos(x) <cos>` Cosine of *x*
:func:`dist(p, q) <dist>` Euclidean distance between two points *p* and *q* given as an iterable of coordinates
:func:`hypot(*coordinates) <hypot>` Euclidean norm of an iterable of coordinates
:func:`sin(x) <sin>` Sine of *x*
:func:`tan(x) <tan>` Tangent of *x*
**Angular conversion**
--------------------------------------------------------------------------------------------------
:func:`degrees(x) <degrees>` Convert angle *x* from radians to degrees
:func:`radians(x) <radians>` Convert angle *x* from degrees to radians
**Hyperbolic functions**
--------------------------------------------------------------------------------------------------
:func:`acosh(x) <acosh>` Inverse hyperbolic cosine of *x*
@ -112,15 +121,8 @@ 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 :meth:`x.__ceil__ <object.__ceil__>`,
which should return an :class:`~numbers.Integral` value.
Number-theoretic functions
--------------------------
.. function:: comb(n, k)
@ -140,18 +142,6 @@ Number-theoretic and representation functions
.. versionadded:: 3.8
.. 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(n)
Return *n* factorial as an integer. Raises :exc:`ValueError` if *n* is not integral or
@ -161,6 +151,78 @@ Number-theoretic and representation functions
Floats with integral values (like ``5.0``) are no longer accepted.
.. function:: gcd(*integers)
Return the greatest common divisor of the specified integer arguments.
If any of the arguments is nonzero, then the returned value is the largest
positive integer that is a divisor of all arguments. If all arguments
are zero, then the returned value is ``0``. ``gcd()`` without arguments
returns ``0``.
.. versionadded:: 3.5
.. versionchanged:: 3.9
Added support for an arbitrary number of arguments. Formerly, only two
arguments were supported.
.. function:: isqrt(n)
Return the integer square root of the nonnegative integer *n*. This is the
floor of the exact square root of *n*, or equivalently the greatest integer
*a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
For some applications, it may be more convenient to have the least integer
*a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
the exact square root of *n*. For positive *n*, this can be computed using
``a = 1 + isqrt(n - 1)``.
.. versionadded:: 3.8
.. function:: lcm(*integers)
Return the least common multiple of the specified integer arguments.
If all arguments are nonzero, then the returned value is the smallest
positive integer that is a multiple of all arguments. If any of the arguments
is zero, then the returned value is ``0``. ``lcm()`` without arguments
returns ``1``.
.. versionadded:: 3.9
.. function:: perm(n, k=None)
Return the number of ways to choose *k* items from *n* items
without repetition and with order.
Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
to zero when ``k > n``.
If *k* is not specified or is ``None``, then *k* defaults to *n*
and the function returns ``n!``.
Raises :exc:`TypeError` if either of the arguments are not integers.
Raises :exc:`ValueError` if either of the arguments are negative.
.. versionadded:: 3.8
Floating point arithmetic
-------------------------
.. 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 :meth:`x.__ceil__ <object.__ceil__>`,
which should return an :class:`~numbers.Integral` value.
.. function:: fabs(x)
Return the absolute value of *x*.
.. function:: floor(x)
Return the floor of *x*, the largest integer less than or equal to *x*. If
@ -199,6 +261,64 @@ Number-theoretic and representation functions
floats, while Python's ``x % y`` is preferred when working with integers.
.. function:: modf(x)
Return the fractional and integer parts of *x*. Both results carry the sign
of *x* and are floats.
Note that :func:`modf` has a different call/return pattern
than its C equivalents: it takes a single argument and return a pair of
values, rather than returning its second return value through an 'output
parameter' (there is no such thing in Python).
.. function:: remainder(x, y)
Return the IEEE 754-style remainder of *x* with respect to *y*. For
finite *x* and finite nonzero *y*, this is the difference ``x - n*y``,
where ``n`` is the closest integer to the exact value of the quotient ``x /
y``. If ``x / y`` is exactly halfway between two consecutive integers, the
nearest *even* integer is used for ``n``. The remainder ``r = remainder(x,
y)`` thus always satisfies ``abs(r) <= 0.5 * abs(y)``.
Special cases follow IEEE 754: in particular, ``remainder(x, math.inf)`` is
*x* for any finite *x*, and ``remainder(x, 0)`` and
``remainder(math.inf, x)`` raise :exc:`ValueError` for any non-NaN *x*.
If the result of the remainder operation is zero, that zero will have
the same sign as *x*.
On platforms using IEEE 754 binary floating point, the result of this
operation is always exactly representable: no rounding error is introduced.
.. versionadded:: 3.7
.. function:: trunc(x)
Return *x* with the fractional part
removed, leaving the integer part. This rounds toward 0: ``trunc()`` is
equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil`
for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__
<object.__trunc__>`, which should return an :class:`~numbers.Integral` value.
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.
Floating point manipulation functions
-------------------------------------
.. 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:: frexp(x)
Return the mantissa and exponent of *x* as the pair ``(m, e)``. *m* is a float
@ -206,37 +326,10 @@ Number-theoretic and representation functions
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.
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-binary-floating-point-summation-accurate-to-full-p/>`_\.
.. function:: gcd(*integers)
Return the greatest common divisor of the specified integer arguments.
If any of the arguments is nonzero, then the returned value is the largest
positive integer that is a divisor of all arguments. If all arguments
are zero, then the returned value is ``0``. ``gcd()`` without arguments
returns ``0``.
.. versionadded:: 3.5
.. versionchanged:: 3.9
Added support for an arbitrary number of arguments. Formerly, only two
arguments were supported.
Note that :func:`frexp` has a different call/return pattern
than its C equivalents: it takes a single argument and return a pair of
values, rather than returning its second return value through an 'output
parameter' (there is no such thing in Python).
.. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)
@ -291,43 +384,12 @@ Number-theoretic and representation functions
Return ``True`` if *x* is a NaN (not a number), and ``False`` otherwise.
.. function:: isqrt(n)
Return the integer square root of the nonnegative integer *n*. This is the
floor of the exact square root of *n*, or equivalently the greatest integer
*a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
For some applications, it may be more convenient to have the least integer
*a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
the exact square root of *n*. For positive *n*, this can be computed using
``a = 1 + isqrt(n - 1)``.
.. versionadded:: 3.8
.. function:: lcm(*integers)
Return the least common multiple of the specified integer arguments.
If all arguments are nonzero, then the returned value is the smallest
positive integer that is a multiple of all arguments. If any of the arguments
is zero, then the returned value is ``0``. ``lcm()`` without arguments
returns ``1``.
.. versionadded:: 3.9
.. 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:: nextafter(x, y, steps=1)
Return the floating-point value *steps* steps after *x* towards *y*.
@ -348,79 +410,6 @@ Number-theoretic and representation functions
.. versionchanged:: 3.12
Added the *steps* argument.
.. function:: perm(n, k=None)
Return the number of ways to choose *k* items from *n* items
without repetition and with order.
Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
to zero when ``k > n``.
If *k* is not specified or is ``None``, then *k* defaults to *n*
and the function returns ``n!``.
Raises :exc:`TypeError` if either of the arguments are not integers.
Raises :exc:`ValueError` if either of the arguments are negative.
.. versionadded:: 3.8
.. function:: prod(iterable, *, start=1)
Calculate the product of all the elements in the input *iterable*.
The default *start* value for the product is ``1``.
When the iterable is empty, return the start value. This function is
intended specifically for use with numeric values and may reject
non-numeric types.
.. versionadded:: 3.8
.. function:: remainder(x, y)
Return the IEEE 754-style remainder of *x* with respect to *y*. For
finite *x* and finite nonzero *y*, this is the difference ``x - n*y``,
where ``n`` is the closest integer to the exact value of the quotient ``x /
y``. If ``x / y`` is exactly halfway between two consecutive integers, the
nearest *even* integer is used for ``n``. The remainder ``r = remainder(x,
y)`` thus always satisfies ``abs(r) <= 0.5 * abs(y)``.
Special cases follow IEEE 754: in particular, ``remainder(x, math.inf)`` is
*x* for any finite *x*, and ``remainder(x, 0)`` and
``remainder(math.inf, x)`` raise :exc:`ValueError` for any non-NaN *x*.
If the result of the remainder operation is zero, that zero will have
the same sign as *x*.
On platforms using IEEE 754 binary floating point, the result of this
operation is always exactly representable: no rounding error is introduced.
.. versionadded:: 3.7
.. function:: sumprod(p, q)
Return the sum of products of values from two iterables *p* and *q*.
Raises :exc:`ValueError` if the inputs do not have the same length.
Roughly equivalent to::
sum(map(operator.mul, p, q, strict=True))
For float and mixed int/float inputs, the intermediate products
and sums are computed with extended precision.
.. versionadded:: 3.12
.. function:: trunc(x)
Return *x* with the fractional part
removed, leaving the integer part. This rounds toward 0: ``trunc()`` is
equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil`
for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__
<object.__trunc__>`, which should return an :class:`~numbers.Integral` value.
.. function:: ulp(x)
@ -447,20 +436,8 @@ Number-theoretic and representation functions
.. versionadded:: 3.9
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
-------------------------------
Power, exponential and logarithmic functions
--------------------------------------------
.. function:: cbrt(x)
@ -557,6 +534,99 @@ Power and logarithmic functions
Return the square root of *x*.
Summation and product functions
-------------------------------
.. function:: dist(p, q)
Return the Euclidean distance between two points *p* and *q*, each
given as a sequence (or iterable) of coordinates. The two points
must have the same dimension.
Roughly equivalent to::
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
.. versionadded:: 3.8
.. function:: fsum(iterable)
Return an accurate floating-point sum of values in the iterable. Avoids
loss of precision by tracking multiple intermediate partial sums.
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-binary-floating-point-summation-accurate-to-full-p/>`_\.
.. function:: hypot(*coordinates)
Return the Euclidean norm, ``sqrt(sum(x**2 for x in coordinates))``.
This is the length of the vector from the origin to the point
given by the coordinates.
For a two dimensional point ``(x, y)``, this is equivalent to computing
the hypotenuse of a right triangle using the Pythagorean theorem,
``sqrt(x*x + y*y)``.
.. versionchanged:: 3.8
Added support for n-dimensional points. Formerly, only the two
dimensional case was supported.
.. versionchanged:: 3.10
Improved the algorithm's accuracy so that the maximum error is
under 1 ulp (unit in the last place). More typically, the result
is almost always correctly rounded to within 1/2 ulp.
.. function:: prod(iterable, *, start=1)
Calculate the product of all the elements in the input *iterable*.
The default *start* value for the product is ``1``.
When the iterable is empty, return the start value. This function is
intended specifically for use with numeric values and may reject
non-numeric types.
.. versionadded:: 3.8
.. function:: sumprod(p, q)
Return the sum of products of values from two iterables *p* and *q*.
Raises :exc:`ValueError` if the inputs do not have the same length.
Roughly equivalent to::
sum(map(operator.mul, p, q, strict=True))
For float and mixed int/float inputs, the intermediate products
and sums are computed with extended precision.
.. versionadded:: 3.12
Angular conversion
------------------
.. function:: degrees(x)
Convert angle *x* from radians to degrees.
.. function:: radians(x)
Convert angle *x* from degrees to radians.
Trigonometric functions
-----------------------
@ -593,39 +663,6 @@ Trigonometric functions
Return the cosine of *x* radians.
.. function:: dist(p, q)
Return the Euclidean distance between two points *p* and *q*, each
given as a sequence (or iterable) of coordinates. The two points
must have the same dimension.
Roughly equivalent to::
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
.. versionadded:: 3.8
.. function:: hypot(*coordinates)
Return the Euclidean norm, ``sqrt(sum(x**2 for x in coordinates))``.
This is the length of the vector from the origin to the point
given by the coordinates.
For a two dimensional point ``(x, y)``, this is equivalent to computing
the hypotenuse of a right triangle using the Pythagorean theorem,
``sqrt(x*x + y*y)``.
.. versionchanged:: 3.8
Added support for n-dimensional points. Formerly, only the two
dimensional case was supported.
.. versionchanged:: 3.10
Improved the algorithm's accuracy so that the maximum error is
under 1 ulp (unit in the last place). More typically, the result
is almost always correctly rounded to within 1/2 ulp.
.. function:: sin(x)
Return the sine of *x* radians.
@ -636,19 +673,6 @@ Trigonometric functions
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
--------------------