math
— Математические функции¶
Этот модуль предоставляет доступ к математическим функциям, определенным стандартом C.
Эти функции нельзя использовать с комплексными числами; если вам нужна поддержка комплексных чисел, используйте одноименные функции из модуля cmath
. Различие между функциями, поддерживающими комплексные числа, и функциями, не поддерживающими их, сделано потому, что большинство пользователей не хотят изучать столько математики, сколько требуется для понимания комплексных чисел. Получение исключения вместо комплексного результата позволяет раньше обнаружить неожиданное комплексное число, используемое в качестве параметра, чтобы программист мог определить, как и почему оно было сгенерировано в первую очередь.
Данный модуль предоставляет следующие функции. Если явно не указано иное, все возвращаемые значения являются плавающей величиной.
Теоретико-числовые функции и функции представления¶
- math.ceil(x)¶
Возвращает потолок x, наименьшее целое число, большее или равное x. Если x не является float, делегируется значение
x.__ceil__
, которое должно вернуть значениеIntegral
.
- math.comb(n, k)¶
Возвращает количество способов выбрать k элементов из n элементов без повторений и без порядка.
Оценивается в
n! / (k! * (n - k)!)
, еслиk <= n
, и оценивается в ноль, еслиk > n
.Также называется биномиальным коэффициентом, поскольку эквивалентен коэффициенту k-го члена в полиномиальном разложении
(1 + x)ⁿ
.Вызывает
TypeError
, если любой из аргументов не является целым числом. ВызываетValueError
, если один из аргументов отрицательный.Added in version 3.8.
- math.copysign(x, y)¶
Возвращает float с величиной (абсолютным значением) x и знаком y. На платформах, поддерживающих знаковые нули,
copysign(1.0, -0.0)
возвращает -1.0.
- math.fabs(x)¶
Возвращает абсолютное значение x.
- math.factorial(n)¶
Возвращает факториал n в виде целого числа. Возвращает
ValueError
, если n не является целым или отрицательным.Изменено в версии 3.10: Плавающие символы с интегральными значениями (например,
5.0
) больше не принимаются.
- math.floor(x)¶
Возвращает значение x, наибольшее целое число, меньшее или равное x. Если x не является float, делегируется значение
x.__floor__
, которое должно вернуть значениеIntegral
.
- math.fma(x, y, z)¶
Операция умножения и сложения. Возвращает
(x * y) + z
, вычисленное как будто с бесконечной точностью и диапазоном, за которым следует одно округление до форматаfloat
. Эта операция часто обеспечивает более высокую точность, чем прямое выражение(x * y) + z
.Эта функция соответствует спецификации операции fusedMultiplyAdd, описанной в стандарте IEEE 754. Стандарт оставляет один случай, определяемый реализацией, а именно результат
fma(0, inf, nan)
иfma(inf, 0, nan)
. В этих случаяхmath.fma
возвращает NaN и не вызывает никаких исключений.Added in version 3.13.
- math.fmod(x, y)¶
Возвращает
fmod(x, y)
, как определено библиотекой платформы C. Обратите внимание, что выражениеx % y
в Python может не возвращать тот же результат. Согласно стандарту C,fmod(x, y)
должно быть точно (математически; с бесконечной точностью) равноx - n*y
для некоторого целого числа n, такого, что результат имеет тот же знак, что и x, и величину меньше, чемabs(y)
. Питоновскаяx % y
возвращает результат со знаком y, и может быть не совсем вычислима для аргументов с плавающей точкой. Например,fmod(-1e-100, 1e100)
равно-1e-100
, но результат функции Python-1e-100 % 1e100
равен1e100-1e-100
, что не может быть точно представлено как float, и округляется до удивительного1e100
. По этой причине функцияfmod()
обычно предпочтительнее при работе с плавающими числами, аx % y
от Python - при работе с целыми числами.
- math.frexp(x)¶
Возвращает мантиссу и экспоненту числа x в виде пары
(m, e)
. m - плавающая цифра, а e - целое число, такое, чтоx == m * 2**e
точно. Если x равно нулю, возвращается(0.0, 0)
, иначе0.5 <= abs(m) < 1
. Это используется для «разбора» внутреннего представления float в переносимом виде.
- math.fsum(iterable)¶
Возвращает точную сумму значений в итерируемой таблице с плавающей точкой. Позволяет избежать потери точности при отслеживании нескольких промежуточных частичных сумм.
Точность алгоритма зависит от арифметических гарантий IEEE-754 и типичного случая, когда режим округления получетный. В некоторых сборках, отличных от Windows, базовая библиотека C использует сложение с расширенной точностью и может иногда дважды округлять промежуточную сумму, что приводит к ошибке в наименьшем значащем бите.
Дальнейшее обсуждение и два альтернативных подхода см. в ASPN cookbook recipes for accurate floating point summation.
- math.gcd(*integers)¶
Возвращает наибольший общий делитель указанных целочисленных аргументов. Если любой из аргументов ненулевой, то возвращаемое значение - наибольшее положительное целое число, являющееся делителем всех аргументов. Если все аргументы равны нулю, то возвращаемым значением будет
0
.gcd()
без аргументов возвращает0
.Added in version 3.5.
Изменено в версии 3.9: Добавлена поддержка произвольного количества аргументов. Ранее поддерживалось только два аргумента.
- math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)¶
Возвращает
True
, если значения a и b близки друг к другу, иFalse
в противном случае.Считаются ли два значения близкими или нет, определяется в соответствии с заданными абсолютными и относительными допусками.
rel_tol - это относительный допуск - максимально допустимая разница между a и b по отношению к большему абсолютному значению a или b. Например, чтобы установить допуск в 5%, передайте
rel_tol=0.05
. Допуск по умолчанию равен1e-09
, что гарантирует, что два значения будут одинаковыми примерно в пределах 9 десятичных цифр. Значение rel_tol должно быть больше нуля.abs_tol - минимальный абсолютный допуск - полезно для сравнений вблизи нуля. abs_tol должно быть не меньше нуля.
Если ошибок не возникло, результатом будет:
abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)
.Специальные значения IEEE 754
NaN
,inf
и-inf
будут обрабатываться в соответствии с правилами IEEE. В частности,NaN
не считается близким к любому другому значению, включаяNaN
.inf
и-inf
считаются близкими только к самим себе.Added in version 3.5.
См.также
PEP 485 – Функция для проверки приблизительного равенства
- math.isfinite(x)¶
Верните
True
, если x не является ни бесконечностью, ни NaN, иFalse
в противном случае. (Обратите внимание, что0.0
*считается конечным).Added in version 3.2.
- math.isinf(x)¶
Возвращает
True
, если x - положительная или отрицательная бесконечность, иFalse
в противном случае.
- math.isnan(x)¶
Возвращает
True
, если x - NaN (не число), иFalse
в противном случае.
- math.isqrt(n)¶
Возвращает целый квадратный корень из неотрицательного целого числа n. Это пол точного квадратного корня из n, или, эквивалентно, наибольшее целое число a такое, что a² ≤ n.
Для некоторых приложений может быть удобнее иметь наименьшее целое число a, такое, что n ≤ a², или, другими словами, потолок точного квадратного корня из n. Для положительных n это можно вычислить с помощью
a = 1 + isqrt(n - 1)
.Added in version 3.8.
- math.lcm(*integers)¶
Возвращает наименьшее общее кратное указанных целочисленных аргументов. Если все аргументы ненулевые, то возвращаемое значение - наименьшее положительное целое число, кратное всем аргументам. Если любой из аргументов равен нулю, то возвращаемое значение будет
0
.lcm()
без аргументов возвращает1
.Added in version 3.9.
- math.modf(x)¶
Возвращает дробную и целую части x. Оба результата имеют знак x и являются плавающими числами.
- math.nextafter(x, y, steps=1)¶
Возвращает значение с плавающей точкой steps шагов после x в направлении y.
Если x равно y, верните y, если только шаги не равны нулю.
Примеры:
math.nextafter(x, math.inf)
поднимается вверх: к положительной бесконечности.math.nextafter(x, -math.inf)
уменьшается: в сторону минус бесконечности.math.nextafter(x, 0.0)
стремится к нулю.math.nextafter(x, math.copysign(math.inf, x))
удаляется от нуля.
См. также
math.ulp()
.Added in version 3.9.
Изменено в версии 3.12: Добавлен аргумент шаги.
- math.perm(n, k=None)¶
Возвращает количество способов выбрать k элементов из n элементов без повторений и по порядку.
Оценивается в
n! / (n - k)!
, еслиk <= n
, и оценивается в ноль, еслиk > n
.Если k не задано или равно
None
, то k по умолчанию равно n и функция возвращаетn!
.Вызывает
TypeError
, если любой из аргументов не является целым числом. ВызываетValueError
, если один из аргументов отрицательный.Added in version 3.8.
- math.prod(iterable, *, start=1)¶
Вычисляет произведение всех элементов входного итерабля. По умолчанию начальным значением для произведения является
1
.Если итерируемая таблица пуста, верните начальное значение. Эта функция предназначена для работы с числовыми значениями и может отвергать нечисловые типы.
Added in version 3.8.
- math.remainder(x, y)¶
Возвращает остаток в стиле 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)
.Специальные случаи соответствуют стандарту IEEE 754: в частности,
remainder(x, math.inf)
является x для любого конечного x, аremainder(x, 0)
иremainder(math.inf, x)
увеличиваютValueError
для любого не-NaN x. Если результат операции остатка равен нулю, то этот ноль будет иметь тот же знак, что и x.На платформах, использующих двоичную систему с плавающей точкой IEEE 754, результат этой операции всегда точно представим: ошибки округления не возникает.
Added in version 3.7.
- math.sumprod(p, q)¶
Возвращает сумму произведений значений из двух итерабельных таблиц p и q.
Вызывает
ValueError
, если входные данные не имеют одинаковой длины.Примерно эквивалентно:
sum(itertools.starmap(operator.mul, zip(p, q, strict=True)))
Для плавающих и смешанных входов int/float промежуточные произведения и суммы вычисляются с расширенной точностью.
Added in version 3.12.
- math.trunc(x)¶
Возвращает x с удаленной дробной частью, оставляя целую часть. Округление происходит в сторону 0:
trunc()
эквивалентноfloor()
для положительных x, и эквивалентноceil()
для отрицательных x. Если x не является float, то передается значениеx.__trunc__
, которое должно вернуть значениеIntegral
.
- math.ulp(x)¶
Возвращает значение наименьшего значащего бита числа float x:
Если x - NaN (не число), верните x.
Если x отрицательно, верните
ulp(-x)
.Если x - положительная бесконечность, верните x.
Если x равно нулю, верните наименьшее положительное денормированное представимое число (меньше, чем минимальное положительное нормированное число,
sys.float_info.min
).Если x равно наибольшему положительному представимому float, верните значение наименьшего значащего бита x, такое, чтобы первый float, меньший x, был
x - ulp(x)
.В противном случае (x - положительное конечное число) верните значение наименьшего значащего бита x, такое, чтобы первый float больше x был
x + ulp(x)
.
ULP расшифровывается как «Unit in the Last Place».
См. также
math.nextafter()
иsys.float_info.epsilon
.Added in version 3.9.
Обратите внимание, что frexp()
и modf()
имеют другую схему вызова/возврата, чем их аналоги на C: они принимают один аргумент и возвращают пару значений, а не возвращают второе возвращаемое значение через «выходной параметр» (в Python такого понятия нет).
Для функций ceil()
, floor()
и modf()
обратите внимание, что все числа с плавающей точкой достаточно большой величины являются точными целыми числами. Плавающие числа в Python обычно имеют не более 53 бит точности (столько же, сколько и тип double платформы C), и в этом случае любое плавающее число x с abs(x) >= 2**52
обязательно не имеет дробных битов.
Силовые и логарифмические функции¶
- math.cbrt(x)¶
Возвращает кубический корень из x.
Added in version 3.11.
- math.exp(x)¶
Возвращает e, возведенное в степень x, где e = 2,718281… - основание натуральных логарифмов. Обычно это более точное значение, чем
math.e ** x
илиpow(math.e, x)
.
- math.exp2(x)¶
Возвращает 2, возведенное в степень x.
Added in version 3.11.
- math.expm1(x)¶
Возвращает e, возведенное в степень x, минус 1. Здесь e - основание натуральных логарифмов. Для малых плавающих чисел x вычитание в
exp(x) - 1
может привести к significant loss of precision; функцияexpm1()
предоставляет возможность вычислить это значение с полной точностью:>>> 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
Added in version 3.2.
- math.log(x[, base])¶
С одним аргументом возвращает натуральный логарифм от x (по основанию e).
При двух аргументах возвращает логарифм x к заданному базису, вычисленный как
log(x)/log(base)
.
- math.log1p(x)¶
Возвращает натуральный логарифм от 1+x (основание e). Результат вычисляется с точностью до x вблизи нуля.
- math.log2(x)¶
Возвращает логарифм по основанию 2 от x. Обычно это более точное значение, чем
log(x, 2)
.Added in version 3.3.
См.также
int.bit_length()
возвращает количество битов, необходимых для представления целого числа в двоичном виде, без учета знака и ведущих нулей.
- math.log10(x)¶
Возвращает логарифм по основанию 10 от x. Обычно это более точное значение, чем
log(x, 10)
.
- math.pow(x, y)¶
Верните
x
, возведенное в степеньy
. Исключительные случаи следуют стандарту IEEE 754, насколько это возможно. В частности,pow(1.0, x)
иpow(x, 0.0)
всегда возвращают1.0
, даже еслиx
- ноль или NaN. Если иx
, иy
конечны,x
отрицательно, аy
не является целым числом, тоpow(x, y)
не определено и возвращаетValueError
.В отличие от встроенного оператора
**
,math.pow()
приводит оба своих аргумента к типуfloat
. Для вычисления точных значений целых чисел используйте оператор**
или встроенную функциюpow()
.Изменено в версии 3.11: Специальные случаи
pow(0.0, -inf)
иpow(-0.0, -inf)
были изменены на возвратinf
вместо повышенияValueError
, чтобы соответствовать стандарту IEEE 754.
- math.sqrt(x)¶
Возвращает квадратный корень из x.
Тригонометрические функции¶
- math.acos(x)¶
Возвращает косинус дуги от x в радианах. Результат находится между
0
иpi
.
- math.asin(x)¶
Возвращает синус дуги от x в радианах. Результат находится между
-pi/2
иpi/2
.
- math.atan(x)¶
Возвращает тангенс дуги к x в радианах. Результат находится между
-pi/2
иpi/2
.
- math.atan2(y, x)¶
Возвращает значение
atan(y / x)
в радианах. Результат находится между-pi
иpi
. Вектор в плоскости от начала координат до точки(x, y)
составляет этот угол с положительной осью X. Смыслatan2()
в том, что ему известны знаки обоих входов, поэтому он может вычислить правильный квадрант для угла. Например,atan(1)
иatan2(1, 1)
- этоpi/4
, аatan2(-1, -1)
--3*pi/4
.
- math.cos(x)¶
Возвращает косинус x радиан.
- math.dist(p, q)¶
Возвращает евклидово расстояние между двумя точками p и q, каждая из которых задана как последовательность (или итерабельность) координат. Эти две точки должны иметь одинаковую размерность.
Примерно эквивалентно:
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
Added in version 3.8.
- math.hypot(*coordinates)¶
Возвращает евклидову норму,
sqrt(sum(x**2 for x in coordinates))
. Это длина вектора от начала координат до точки, заданной координатами.Для двумерной точки
(x, y)
это эквивалентно вычислению гипотенузы правильного треугольника по теореме Пифагора,sqrt(x*x + y*y)
.Изменено в версии 3.8: Добавлена поддержка n-мерных точек. Ранее поддерживался только двумерный случай.
Изменено в версии 3.10: Улучшена точность алгоритма, так что максимальная ошибка составляет менее 1 ulp (единица на последнем месте). Как правило, результат почти всегда правильно округляется с точностью до 1/2 ulp.
- math.sin(x)¶
Возвращает синус x радиан.
- math.tan(x)¶
Возвращает тангенс x радиан.
Ангулярное преобразование¶
- math.degrees(x)¶
Преобразование угла x из радианов в градусы.
- math.radians(x)¶
Преобразование угла x из градусов в радианы.
Гиперболические функции¶
Hyperbolic functions - это аналоги тригонометрических функций, которые основаны на гиперболах, а не на окружностях.
- math.acosh(x)¶
Возвращает обратный гиперболический косинус от x.
- math.asinh(x)¶
Возвращает обратный гиперболический синус от x.
- math.atanh(x)¶
Возвращает обратный гиперболический тангенс к x.
- math.cosh(x)¶
Возвращает гиперболический косинус x.
- math.sinh(x)¶
Возвращает гиперболический синус от x.
- math.tanh(x)¶
Возвращает гиперболический тангенс к x.
Специальные функции¶
- math.erf(x)¶
Возвращает error function в точке x.
Функция
erf()
может использоваться для вычисления традиционных статистических функций, таких как cumulative standard normal distribution:def phi(x): 'Cumulative distribution function for the standard normal distribution' return (1.0 + erf(x / sqrt(2.0))) / 2.0
Added in version 3.2.
- math.erfc(x)¶
Возвращает дополняющую функцию ошибки в точке x. Значение complementary error function определяется как
1.0 - erf(x)
. Она используется при больших значениях x, когда вычитание из единицы приводит к loss of significance.Added in version 3.2.
- math.gamma(x)¶
Возвращает Gamma function в точке x.
Added in version 3.2.
- math.lgamma(x)¶
Возвращает натуральный логарифм абсолютного значения функции Гамма в точке x.
Added in version 3.2.
Константы¶
- math.pi¶
Математическая константа π = 3,141592…, с доступной точностью.
- math.e¶
Математическая константа e = 2,718281…, с доступной точностью.
- math.tau¶
Математическая константа τ = 6,283185…, с доступной точностью. Тау - это константа окружности, равная 2π, отношение окружности круга к его радиусу. Чтобы узнать больше о тау, посмотрите видеоролик Ви Харта Pi is (still) Wrong и начните праздновать Tau day, съев в два раза больше пирога!
Added in version 3.6.
- math.inf¶
Положительная бесконечность с плавающей точкой. (Для отрицательной бесконечности используйте
-math.inf
.) Эквивалентно выводуfloat('inf')
.Added in version 3.5.
- math.nan¶
Значение с плавающей точкой «не число» (NaN). Эквивалентно выводу
float('nan')
. В силу требований IEEE-754 standard,math.nan
иfloat('nan')
не считаются равными никаким другим числовым значениям, включая самих себя. Чтобы проверить, является ли число NaN, используйте функциюisnan()
для проверки на NaN вместоis
или==
. Пример:>>> import math >>> math.nan == math.nan False >>> float('nan') == float('nan') False >>> math.isnan(math.nan) True >>> math.isnan(float('nan')) True
Added in version 3.5.
Изменено в версии 3.11: Теперь она всегда доступна.
Детали реализации CPython: Модуль math
состоит в основном из тонких оберток вокруг функций математической библиотеки платформы C. Поведение в исключительных случаях соответствует приложению F стандарта C99, где это уместно. Текущая реализация будет поднимать ValueError
для недопустимых операций, таких как sqrt(-1.0)
или log(0.0)
(где приложение F стандарта C99 рекомендует сигнализировать о недопустимой операции или делении на ноль), и OverflowError
для результатов, которые переполняются (например, exp(1000.0)
). NaN не будет возвращен ни одной из вышеперечисленных функций, если только один или несколько входных аргументов не были NaN; в этом случае большинство функций вернут NaN, но (опять же в соответствии с C99 Annex F) из этого правила есть некоторые исключения, например pow(float('nan'), 0.0)
или hypot(float('nan'), float('inf'))
.
Обратите внимание, что Python не пытается отличить сигнальные NaN от тихих NaN, и поведение для сигнальных NaN остается неопределенным. Типичным поведением является обращение со всеми NaN как с тихими.
См.также
- Модуль
cmath
Версии комплексных чисел многих из этих функций.