`math.md`

381 строк · 28.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.8/library/math.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`math`](https://python-all.ru/3.8/library/math.html#module-math) – Математические функции89---1011Этот модуль предоставляет доступ к математическим функциям, определённым стандартом C.1213Эти функции нельзя использовать с комплексными числами; если нужна поддержка комплексных чисел, используйте одноимённые функции из модуля [`cmath`](https://python-all.ru/3.8/library/cmath.html#module-cmath). Различие между функциями, поддерживающими комплексные числа, и теми, которые их не поддерживают, проведено потому, что большинству пользователей не нужно углубляться в математику, необходимую для понимания комплексных чисел. Получение исключения вместо комплексного результата позволяет раньше обнаружить непредвиденное комплексное число, переданное в качестве параметра, так что программист может выяснить, как и почему оно возникло.1415Модуль предоставляет следующие функции. Если не указано иное, все возвращаемые значения являются числами с плавающей запятой.1617## Теоретико-числовые функции и функции представления1819#### `math.ceil(x)`2021Возвращает потолок *x* – наименьшее целое число, большее или равное *x*. Если *x* не является float, делегирует `x.__ceil__()`, которая должна вернуть значение [`Integral`](https://python-all.ru/3.8/library/numbers.html#numbers.Integral).2223#### `math.comb(n, k)`2425Возвращает количество способов выбрать *k* элементов из *n* элементов без повторений и без учёта порядка.2627Вычисляется в `n! / (k! * (n - k)!)`, когда `k <= n`, и в ноль, когда `k > n`.2829Также называется биномиальным коэффициентом, поскольку он эквивалентен коэффициенту k-го члена в разложении выражения `(1 + x) ** n` по полиному.3031Возбуждает [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError), если хотя бы один из аргументов не является целым числом. Возбуждает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError), если хотя бы один из аргументов отрицателен.3233Новое в версии 3.8.3435#### `math.copysign(x, y)`3637Возвращает float с модулем (абсолютным значением) *x*, но со знаком *y*. На платформах, поддерживающих знаковый нуль, `copysign(1.0, -0.0)` возвращает *-1.0*.3839#### `math.fabs(x)`4041Возвращает абсолютное значение *x*.4243#### `math.factorial(x)`4445Возвращает факториал *x* в виде целого числа. Вызывает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError), если *x* не является целым или отрицательно.4647#### `math.floor(x)`4849Возвращает пол *x* – наибольшее целое число, меньшее или равное *x*. Если *x* не является float, делегирует `x.__floor__()`, которая должна вернуть значение [`Integral`](https://python-all.ru/3.8/library/numbers.html#numbers.Integral).5051#### `math.fmod(x, y)`5253Возвращает `fmod(x, y)`, как определено библиотекой C платформы. Обратите внимание, что Python-выражение `x % y` может вернуть другой результат. Стандарт C подразумевает, что `fmod(x, y)` точно (математически, с бесконечной точностью) равно `x - n*y` для некоторого целого *n* такого, что результат имеет тот же знак, что и *x*, а его модуль меньше `abs(y)`. В Python `x % y` возвращает результат со знаком *y* вместо этого, и может быть невычислим точно для аргументов float. Например, `fmod(-1e-100, 1e100)` равно `-1e-100`, но результат Python-выражения `-1e-100 % 1e100` равен `1e100-1e-100`, что не может быть представлено точно как float и округляется до удивительного `1e100`. По этой причине функция [`fmod()`](https://python-all.ru/3.8/library/math.html#math.fmod) обычно предпочтительнее при работе с float, в то время как `x % y` предпочтительнее при работе с целыми числами.5455#### `math.frexp(x)`5657Возвращает мантиссу и экспоненту числа *x* в виде пары `(m, e)`. *m* – число с плавающей запятой, а *e* – целое число, такие что `x == m * 2**e` точно. Если *x* равно нулю, возвращает `(0.0, 0)`, иначе `0.5 <= abs(m) < 1`. Это используется для «разбора» внутреннего представления числа с плавающей запятой переносимым способом.5859#### `math.fsum(iterable)`6061Возвращает точную сумму чисел с плавающей запятой из итерируемого объекта. Избегает потери точности за счёт отслеживания нескольких промежуточных частичных сумм:6263```python64>>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])650.999999999999999966>>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])671.068```6970Точность алгоритма зависит от гарантий арифметики IEEE-754 и типичного случая, когда режим округления – «half-even». В некоторых сборках не под Windows базовая библиотека C использует сложение с расширенной точностью и может иногда дважды округлять промежуточную сумму, что приводит к ошибке в самом младшем значащем бите.7172Для более подробного обсуждения и двух альтернативных подходов см. [рецепты ASPN cookbook для точного суммирования чисел с плавающей запятой](https://python-all.ru/3.8/library/math.html).7374#### `math.gcd(a, b)`7576Возвращает наибольший общий делитель целых чисел *a* и *b*. Если *a* или *b* не равно нулю, то значение `gcd(a, b)` – это наибольшее положительное целое число, которое делит как *a*, так и *b*. `gcd(0, 0)` возвращает `0`.7778Новое в версии 3.5.7980#### `math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)`8182Возвращает `True`, если значения *a* и *b* близки друг к другу, и `False` иначе.8384Близость двух значений определяется заданными абсолютной и относительной допустимыми погрешностями.8586*rel\_tol* – это относительная допустимая погрешность: максимально допустимая разница между *a* и *b*, взятая относительно большего абсолютного значения *a* или *b*. Например, чтобы установить погрешность 5%, передайте `rel_tol=0.05`. По умолчанию погрешность равна `1e-09`, что гарантирует совпадение двух значений с точностью примерно до 9 десятичных знаков. *rel\_tol* должен быть больше нуля.8788*abs\_tol* – это минимальная абсолютная допустимая погрешность, полезная для сравнений вблизи нуля. *abs\_tol* должен быть не меньше нуля.8990Если ошибок не возникло, результатом будет: `abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)`.9192Особые значения IEEE 754: `NaN`, `inf` и `-inf` обрабатываются согласно правилам IEEE. В частности, `NaN` не считается близким ни к какому другому значению, включая `NaN`. `inf` и `-inf` считаются близкими только сами к себе.9394Новое в версии 3.5.9596> **См. также**97>98> [**PEP 485**](https://python-all.ru/3.8/library/math.html) – Функция для проверки приблизительного равенства99100#### `math.isfinite(x)`101102Возвращает `True`, если *x* не является ни бесконечностью, ни NaN, и `False` в противном случае. (Заметьте, что `0.0` *считается* конечным.)103104Новое в версии 3.2.105106#### `math.isinf(x)`107108Возвращает `True`, если *x* является положительной или отрицательной бесконечностью, и `False` в противном случае.109110#### `math.isnan(x)`111112Возвращает `True`, если *x* является NaN (не числом), и `False` в противном случае.113114#### `math.isqrt(n)`115116Возвращает целую часть квадратного корня неотрицательного целого числа *n*. Это округление вниз точного квадратного корня из *n*, или, что то же самое, наибольшее целое число *a* такое, что *a*² ≤ *n*.117118Для некоторых приложений может быть удобнее наименьшее целое число *a* такое, что *n* ≤ *a*², иными словами, округление вверх точного квадратного корня из *n*. Для положительного *n* это можно вычислить с помощью `a = 1 + isqrt(n - 1)`.119120Новое в версии 3.8.121122#### `math.ldexp(x, i)`123124Возвращает `x * (2**i)`. По сути, это обратная функция по отношению к [`frexp()`](https://python-all.ru/3.8/library/math.html#math.frexp).125126#### `math.modf(x)`127128Возвращает дробную и целую части *x*. Оба результата имеют тот же знак, что и *x*, и являются числами с плавающей запятой.129130#### `math.perm(n, k=None)`131132Возвращает количество способов выбрать *k* элементов из *n* без повторений и с учётом порядка.133134Вычисляется в `n! / (n - k)!`, когда `k <= n`, и в ноль, когда `k > n`.135136Если *k* не указан или равен None, то *k* по умолчанию равен *n*, и функция возвращает `n!`.137138Возбуждает [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError), если хотя бы один из аргументов не является целым числом. Возбуждает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError), если хотя бы один из аргументов отрицателен.139140Новое в версии 3.8.141142#### `math.prod(iterable, *, start=1)`143144Вычисляет произведение всех элементов входного *итерируемого объекта*. Значение *start* по умолчанию для произведения равно `1`.145146Если итерируемый объект пуст, возвращает начальное значение. Эта функция предназначена специально для работы с числовыми значениями и может отвергать нечисловые типы.147148Новое в версии 3.8.149150#### `math.remainder(x, y)`151152Возвращает остаток от деления по стандарту IEEE 754 для *x* на *y*. Для конечных *x* и конечного ненулевого *y* это разность `x - n*y`, где `n` – ближайшее целое к точному значению частного `x / y`. Если `x / y` находится ровно посередине между двумя последовательными целыми, то для `n` используется ближайшее *чётное* целое. Таким образом, остаток `r = remainder(x, y)` всегда удовлетворяет условию `abs(r) <= 0.5 * abs(y)`.153154Особые случаи следуют IEEE 754: в частности, `remainder(x, math.inf)` равно *x* для любого конечного *x*, а `remainder(x, 0)` и `remainder(math.inf, x)` возбуждают [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) для любого не-NaN *x*. Если результат операции остатка равен нулю, этот нуль будет иметь тот же знак, что и *x*.155156На платформах, использующих двоичные числа с плавающей запятой IEEE 754, результат этой операции всегда точно представим: ошибка округления не возникает.157158Добавлено в версии 3.7.159160#### `math.trunc(x)`161162Возвращает значение [`Real`](https://python-all.ru/3.8/library/numbers.html#numbers.Real) *x*, усечённое до [`Integral`](https://python-all.ru/3.8/library/numbers.html#numbers.Integral) (обычно целого числа). Делегирует [`x.__trunc__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__trunc__).163164Обратите внимание, что [`frexp()`](https://python-all.ru/3.8/library/math.html#math.frexp) и [`modf()`](https://python-all.ru/3.8/library/math.html#math.modf) имеют иной шаблон вызова и возврата, чем их эквиваленты на C: они принимают один аргумент и возвращают пару значений, а не возвращают второе возвращаемое значение через «выходной параметр» (в Python такого нет).165166Для функций [`ceil()`](https://python-all.ru/3.8/library/math.html#math.ceil), [`floor()`](https://python-all.ru/3.8/library/math.html#math.floor) и [`modf()`](https://python-all.ru/3.8/library/math.html#math.modf) обратите внимание, что *все* числа с плавающей запятой достаточно большой величины являются точными целыми числами. Float в Python обычно имеют точность не более 53 бит (как и тип C double на данной платформе), и в этом случае любой float *x* с `abs(x) >= 2**52` не имеет дробных битов.167168## Степенные и логарифмические функции169170#### `math.exp(x)`171172Возвращает *e*, возведённое в степень *x*, где *e* = 2.718281… – основание натуральных логарифмов. Обычно это точнее, чем `math.e ** x` или `pow(math.e, x)`.173174#### `math.expm1(x)`175176Возвращает *e*, возведённое в степень *x*, минус 1. Здесь *e* – основание натуральных логарифмов. Для малых чисел с плавающей запятой *x* вычитание в `exp(x) - 1` может привести к [значительной потере точности](https://python-all.ru/3.8/library/math.html); функция [`expm1()`](https://python-all.ru/3.8/library/math.html#math.expm1) позволяет вычислить это значение с полной точностью:177178```python179>>> from math import exp, expm1180>>> exp(1e-5) - 1  # даёт результат с точностью до 11 знаков1811.0000050000069649e-05182>>> expm1(1e-5)    # результат с полной точностью1831.0000050000166668e-05184```185186Новое в версии 3.2.187188#### `math.log(x[, base])`189190С одним аргументом возвращает натуральный логарифм *x* (по основанию *e*).191192С двумя аргументами возвращает логарифм *x* по заданному основанию *base*, вычисленный как `log(x)/log(base)`.193194#### `math.log1p(x)`195196Возвращает натуральный логарифм *1+x* (основание *e*). Результат вычисляется способом, точным для *x* вблизи нуля.197198#### `math.log2(x)`199200Возвращает двоичный логарифм *x*. Обычно это точнее, чем `log(x, 2)`.201202Новое в версии 3.3.203204> **См. также**205>206> [`int.bit_length()`](https://python-all.ru/3.8/library/stdtypes.html#int.bit_length) возвращает количество битов, необходимое для представления целого числа в двоичном виде, без учёта знака и ведущих нулей.207208#### `math.log10(x)`209210Возвращает десятичный логарифм *x*. Обычно это точнее, чем `log(x, 10)`.211212#### `math.pow(x, y)`213214Возвращает `x`, возведённое в степень `y`. Исключительные случаи следуют Приложению ‘F’ стандарта C99 насколько это возможно. В частности, `pow(1.0, x)` и `pow(x, 0.0)` всегда возвращают `1.0`, даже когда `x` равен нулю или NaN. Если и `x`, и `y` конечны, `x` отрицательно, а `y` не является целым числом, то `pow(x, y)` не определён и вызывает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError).215216В отличие от встроенного оператора `**`, [`math.pow()`](https://python-all.ru/3.8/library/math.html#math.pow) преобразует оба аргумента к типу [`float`](https://python-all.ru/3.8/library/functions.html#float). Используйте `**` или встроенную функцию [`pow()`](https://python-all.ru/3.8/library/functions.html#pow) для точного вычисления целочисленных степеней.217218#### `math.sqrt(x)`219220Возвращает квадратный корень из *x*.221222## Тригонометрические функции223224#### `math.acos(x)`225226Возвращает арккосинус *x* в радианах.227228#### `math.asin(x)`229230Возвращает арксинус *x* в радианах.231232#### `math.atan(x)`233234Возвращает арктангенс *x* в радианах.235236#### `math.atan2(y, x)`237238Возвращает `atan(y / x)` в радианах. Результат находится в диапазоне от `-pi` до `pi`. Вектор на плоскости от начала координат до точки `(x, y)` образует этот угол с положительной осью X. Особенность [`atan2()`](https://python-all.ru/3.8/library/math.html#math.atan2) в том, что ему известны знаки обоих аргументов, поэтому он может вычислить правильный квадрант для угла. Например, `atan(1)` и `atan2(1, 1)` равны `pi/4`, но `atan2(-1, -1)` равен `-3*pi/4`.239240#### `math.cos(x)`241242Возвращает косинус *x* радиан.243244#### `math.dist(p, q)`245246Возвращает евклидово расстояние между двумя точками *p* и *q*, каждая из которых задаётся как последовательность (или итерируемый объект) координат. Обе точки должны иметь одинаковую размерность.247248Примерно эквивалентно:249250```python251sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))252```253254Новое в версии 3.8.255256#### `math.hypot(*coordinates)`257258Возвращает евклидову норму, `sqrt(sum(x**2 for x in coordinates))`. Это длина вектора от начала координат до точки, заданной координатами.259260Для двумерной точки `(x, y)` это эквивалентно вычислению гипотенузы прямоугольного треугольника по теореме Пифагора, `sqrt(x*x + y*y)`.261262Изменено в версии 3.8: Добавлена поддержка n-мерных точек. Ранее поддерживался только двумерный случай.263264#### `math.sin(x)`265266Возвращает синус *x* радиан.267268#### `math.tan(x)`269270Возвращает тангенс *x* радиан.271272## Преобразование углов273274#### `math.degrees(x)`275276Преобразует угол *x* из радианов в градусы.277278#### `math.radians(x)`279280Преобразует угол *x* из градусов в радианы.281282## Гиперболические функции283284[Гиперболические функции](https://python-all.ru/3.8/library/math.html) – это аналоги тригонометрических функций, основанные на гиперболах, а не на окружностях.285286#### `math.acosh(x)`287288Возвращает обратный гиперболический косинус *x*.289290#### `math.asinh(x)`291292Возвращает обратный гиперболический синус *x*.293294#### `math.atanh(x)`295296Возвращает обратный гиперболический тангенс *x*.297298#### `math.cosh(x)`299300Возвращает гиперболический косинус *x*.301302#### `math.sinh(x)`303304Возвращает гиперболический синус *x*.305306#### `math.tanh(x)`307308Возвращает гиперболический тангенс *x*.309310## Специальные функции311312#### `math.erf(x)`313314Возвращает значение [функции ошибок](https://python-all.ru/3.8/library/math.html) в точке *x*.315316Функция [`erf()`](https://python-all.ru/3.8/library/math.html#math.erf) может использоваться для вычисления традиционных статистических функций, таких как [кумулятивное стандартное нормальное распределение](https://python-all.ru/3.8/library/math.html):317318```python319def phi(x):320    'Cumulative distribution function for the standard normal distribution'321    return (1.0 + erf(x / sqrt(2.0))) / 2.0322```323324Новое в версии 3.2.325326#### `math.erfc(x)`327328Возвращает дополнительную функцию ошибок в точке *x*. [Дополнительная функция ошибок](https://python-all.ru/3.8/library/math.html) определяется как `1.0 - erf(x)`. Она используется для больших значений *x*, где вычитание из единицы может привести к [потере значимости](https://python-all.ru/3.8/library/math.html).329330Новое в версии 3.2.331332#### `math.gamma(x)`333334Возвращает значение [гамма-функции](https://python-all.ru/3.8/library/math.html) в точке *x*.335336Новое в версии 3.2.337338#### `math.lgamma(x)`339340Возвращает натуральный логарифм абсолютного значения гамма-функции в точке *x*.341342Новое в версии 3.2.343344## Константы345346#### `math.pi`347348Математическая константа *π* = 3,141592… с доступной точностью.349350#### `math.e`351352Математическая константа *e* = 2,718281… с доступной точностью.353354#### `math.tau`355356Математическая константа *τ* = 6,283185… с доступной точностью. Тау – это константа окружности, равная 2*π*, отношению длины окружности к её радиусу. Чтобы узнать больше о Тау, посмотрите видео Ви Харт [Pi is (still) Wrong](https://python-all.ru/3.8/library/math.html) и начните праздновать [День Тау](https://python-all.ru/3.8/library/math.html), съев вдвое больше пирога!357358Новое в версии 3.6.359360#### `math.inf`361362Положительная бесконечность с плавающей запятой. (Для отрицательной бесконечности используйте `-math.inf`.) Эквивалентно результату `float('inf')`.363364Новое в версии 3.5.365366#### `math.nan`367368Значение с плавающей запятой «не число» (NaN). Эквивалентно результату `float('nan')`.369370Новое в версии 3.5.371372**Особенность реализации CPython:** Модуль [`math`](https://python-all.ru/3.8/library/math.html#module-math) в основном состоит из тонких обёрток вокруг функций математической библиотеки C платформы. Поведение в исключительных случаях следует приложению F стандарта C99, где это применимо. Текущая реализация вызывает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) для недопустимых операций, таких как `sqrt(-1.0)` или `log(0.0)` (где приложение F C99 рекомендует сигнализировать о недопустимой операции или делении на ноль), и [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError) для результатов, вызывающих переполнение (например, `exp(1000.0)`). NaN не будет возвращён ни одной из указанных выше функций, если только один или несколько входных аргументов не были NaN; в этом случае большинство функций вернут NaN, но (опять же следуя приложению F C99) есть некоторые исключения из этого правила, например `pow(float('nan'), 0.0)` или `hypot(float('nan'), float('inf'))`.373374Обратите внимание, что Python не различает сигнальные NaN и тихие NaN, и поведение для сигнальных NaN остаётся неуточнённым. Обычное поведение – обрабатывать все NaN так, как будто они тихие.375376> **См. также**377>378> **Модуль [`cmath`](https://python-all.ru/3.8/library/cmath.html#module-cmath)**379>380> Версии многих из этих функций для комплексных чисел.381