math
— Математические функции¶
Этот модуль обеспечивает доступ к математическим функциям, определенным стандартом языка Си.
Эти функции нельзя использовать с комплексными числами; используйте одноименные функции из модуля cmath
, если вам требуется поддержка комплексных чисел. Различие между функциями, которые поддерживают комплексные числа, и функциями, которые этого не делают, проводится потому, что большинство пользователей не хотят изучать математику в объеме, необходимом для понимания комплексных чисел. Получение исключения вместо комплексного результата позволяет заблаговременно обнаружить неожиданное комплексное число, используемое в качестве параметра, чтобы программист мог определить, как и почему оно было сгенерировано в первую очередь.
Этот модуль предоставляет следующие функции. За исключением случаев, когда явно указано иное, все возвращаемые значения являются плавающими.
Теоретико-числовые функции и функции представления¶
- math.ceil(x)¶
Возвращает максимальное значение x, наименьшее целое число, большее или равное x. Если x не является числом с плавающей точкой, то используется
x.__ceil__
, которое должно возвращать значениеIntegral
.
- math.comb(n, k)¶
Возвращает количество способов выбора k элементов из n элементов без повторения и без упорядочивания.
Вычисляется как
n! / (k! * (n - k)!)
приk <= n
и обнуляется приk > n
.Также называется биномиальным коэффициентом, поскольку он эквивалентен коэффициенту k-го члена в полиномиальном разложении
(1 + x)ⁿ
.Увеличивает значение
TypeError
, если какой-либо из аргументов не является целым числом. Увеличивает значениеValueError
, если какой-либо из аргументов отрицательный.Добавлено в версии 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.9: Использование чисел с плавающей запятой с целыми значениями (например,
5.0
) не рекомендуется.
- math.floor(x)¶
Возвращает значение x, наибольшее целое число, меньшее или равное x. Если x не является числом с плавающей точкой, то используется
x.__floor__
, которое должно возвращать значениеIntegral
.
- math.fmod(x, y)¶
Возвращает
fmod(x, y)
, как определено библиотекой платформы C. Обратите внимание, что выражение Pythonx % y
может возвращать другой результат. Цель стандарта C состоит в том, чтобыfmod(x, y)
было точно (математически; с бесконечной точностью) равноx - n*y
для некоторого целого числа n, так что результат имеет тот же знак, что и x, и величину, меньшуюabs(y)
. Вместо этогоx % y
возвращает результат со знаком y и может быть не совсем вычислимым для аргументов с плавающей точкой. Например,fmod(-1e-100, 1e100)
равно-1e-100
, но результатом-1e-100 % 1e100
в Python является1e100-1e-100
, который не может быть представлен точно как число с плавающей точкой и округляется до неожиданного1e100
. По этой причине функцияfmod()
обычно предпочтительнее при работе с числами с плавающей запятой, в то время как функция Pythonx % y
предпочтительнее при работе с целыми числами.
- math.frexp(x)¶
Возвращает мантиссу и показатель степени x в виде пары
(m, e)
. m - число с плавающей точкой, а e - целое число, такое, чтоx == m * 2**e
точно. Если x равно нулю, возвращает(0.0, 0)
, в противном случае0.5 <= abs(m) < 1
. Это используется для «выделения» внутреннего представления числа с плавающей точкой переносимым способом.
- math.fsum(iterable)¶
Возвращает точную сумму значений с плавающей запятой в iterable. Позволяет избежать потери точности путем отслеживания нескольких промежуточных частичных сумм:
>>> 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
Точность алгоритма зависит от арифметических гарантий стандарта IEEE-754 и типичного случая, когда режим округления является половинчатым. В некоторых сборках, отличных от Windows, базовая библиотека C использует расширенное прецизионное сложение и иногда может дважды округлять промежуточную сумму, в результате чего она не соответствует младшему разряду.
Для дальнейшего обсуждения и двух альтернативных подходов смотрите ASPN cookbook recipes for accurate floating point summation.
- math.gcd(*integers)¶
Возвращает наибольший общий делитель указанных целочисленных аргументов. Если какой-либо из аргументов отличен от нуля, то возвращаемое значение является наибольшим положительным целым числом, которое является делителем всех аргументов. Если все аргументы равны нулю, то возвращаемое значение равно
0
.gcd()
без аргументов возвращает0
.Добавлено в версии 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
считаются близкими только к самим себе.Добавлено в версии 3.5.
См.также
PEP 485 – Функция для проверки приблизительного равенства
- math.isfinite(x)¶
Верните
True
, если x не является ни бесконечностью, ни NaN, иFalse
в противном случае. (Обратите внимание, что0.0
* считается конечным.)Добавлено в версии 3.2.
- math.isinf(x)¶
Верните
True
, если x - положительная или отрицательная бесконечность, иFalse
в противном случае.
- math.isnan(x)¶
Возвращает
True
, если x является NaN (не числом), иFalse
в противном случае.
- math.isqrt(n)¶
Возвращает целочисленный квадратный корень из неотрицательного целого числа n. Это нижний уровень точного квадратного корня из n или, что эквивалентно, наибольшее целое число a, такое, что a2 ≤ n.
Для некоторых приложений может быть удобнее использовать наименьшее целое число a, такое, что n ≤ a2, или, другими словами, максимальное значение точного квадратного корня из n. Для положительного n это можно вычислить с помощью
a = 1 + isqrt(n - 1)
.Добавлено в версии 3.8.
- math.lcm(*integers)¶
Возвращает наименьшее общее число, кратное указанным целочисленным аргументам. Если все аргументы отличны от нуля, то возвращаемое значение является наименьшим положительным целым числом, кратным всем аргументам. Если какой-либо из аргументов равен нулю, то возвращаемое значение равно
0
.lcm()
без аргументов возвращает1
.Добавлено в версии 3.9.
- math.modf(x)¶
Возвращает дробную и целую части x. Оба результата имеют знак x и являются числами с плавающей запятой.
- math.nextafter(x, y)¶
Возвращает следующее значение с плавающей запятой после 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()
.Добавлено в версии 3.9.
- math.perm(n, k=None)¶
Возвращает количество способов выбора k элементов из n элементов без повторения и в определенном порядке.
Вычисляется как
n! / (n - k)!
приk <= n
и обнуляется приk > n
.Если значение k не указано или равно None, то значение k по умолчанию равно n и функция возвращает
n!
.Увеличивает значение
TypeError
, если какой-либо из аргументов не является целым числом. Увеличивает значениеValueError
, если какой-либо из аргументов отрицательный.Добавлено в версии 3.8.
- math.prod(iterable, *, start=1)¶
Вычислите произведение всех элементов во входных данных iterable. Начальное значение по умолчанию для продукта равно
1
.Если итерируемая строка пуста, верните начальное значение. Эта функция предназначена специально для использования с числовыми значениями и может отклонять нечисловые типы.
Добавлено в версии 3.8.
- math.remainder(x, y)¶
Возвращает остаток от x в соответствии с IEEE 754 по отношению к 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, результат этой операции всегда представляется в точности: ошибка округления не возникает.
Добавлено в версии 3.7.
- math.trunc(x)¶
Верните x, убрав дробную часть и оставив целую. Это округляет значение до 0:
trunc()
эквивалентноfloor()
для положительного x и эквивалентноceil()
для отрицательного x. Если x не является числом с плавающей запятой, делегируется значениеx.__trunc__
, которое должно возвращать значениеIntegral
.
- math.ulp(x)¶
Возвращает значение младшего значащего бита числа с плавающей запятой x:
Если x - это NaN (не число), верните x.
Если x отрицательно, верните
ulp(-x)
.Если x - положительная бесконечность, верните x.
Если x равно нулю, верните наименьшее положительное денормализованное значение с плавающей точкой (меньше минимального положительного нормализованного значения с плавающей точкой,
sys.float_info.min
).Если x равно наибольшему положительно представимому значению с плавающей точкой, верните значение младшего значащего бита x, так что первое значение с плавающей точкой, меньшее, чем x, равно
x - ulp(x)
.В противном случае (x - положительное конечное число) верните значение младшего значащего бита x таким образом, чтобы первое число с плавающей точкой, большее, чем x, было
x + ulp(x)
.
ULP расшифровывается как «Подразделение, занимающее последнее место».
Смотрите также
math.nextafter()
иsys.float_info.epsilon
.Добавлено в версии 3.9.
Обратите внимание, что frexp()
и modf()
имеют другой шаблон вызова/возврата, чем их эквиваленты на C: они принимают один аргумент и возвращают пару значений, вместо того, чтобы возвращать свое второе возвращаемое значение через «выходной параметр» (такого понятия не существует на Python).
Для функций ceil()
, floor()
, и modf()
обратите внимание, что все числа с плавающей запятой достаточно большой величины являются точными целыми числами. Значения с плавающей точкой в Python обычно имеют точность не более 53 бит (то же, что и в двойном типе платформы C), и в этом случае любое значение с плавающей точкой x с abs(x) >= 2**52
обязательно не содержит дробных битов.
Степенные и логарифмические функции¶
- math.cbrt(x)¶
Возвращает кубический корень из x.
Добавлено в версии 3.11.
- math.exp(x)¶
Возвращает значение e, возведенное в степень x, где e = 2,718281… это основание натуральных логарифмов. Обычно это более точное значение, чем
math.e ** x
илиpow(math.e, x)
.
- math.exp2(x)¶
Верните 2, возведенное в степень x.
Добавлено в версии 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
Добавлено в версии 3.2.
- math.log(x[, base])¶
С помощью одного аргумента верните натуральный логарифм от x (по основанию e).
С помощью двух аргументов верните логарифм от x к заданному основанию, вычисленный как
log(x)/log(base)
.
- math.log1p(x)¶
Возвращает натуральный логарифм 1+x (основание e). Результат вычисляется с точностью до x, близкой к нулю.
- math.log2(x)¶
Возвращает логарифм значения x по основанию 2. Обычно это более точно, чем
log(x, 2)
.Добавлено в версии 3.3.
См.также
int.bit_length()
возвращает количество битов, необходимое для представления целого числа в двоичном формате, исключая знак и начальные нули.
- math.log10(x)¶
Возвращает логарифм значения x по основанию 10. Обычно это более точное значение, чем
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)))
Добавлено в версии 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
Добавлено в версии 3.2.
- math.erfc(x)¶
Возвращает дополнительную функцию ошибки в x. complementary error function определяется как
1.0 - erf(x)
. Используется для больших значений x, когда вычитание из единицы привело бы к loss of significance.Добавлено в версии 3.2.
- math.gamma(x)¶
Верните Gamma function в x.
Добавлено в версии 3.2.
- math.lgamma(x)¶
Возвращает натуральный логарифм абсолютного значения гамма-функции при x.
Добавлено в версии 3.2.
Константы¶
- math.pi¶
Математическая константа π = 3,141592…, с доступной точностью.
- math.e¶
Математическая константа e = 2,718281…, с доступной точностью.
- math.tau¶
Математическая константа τ = 6,283185… с доступной точностью. Tau - это постоянная окружности, равная 2*π*, отношению длины окружности к ее радиусу. Чтобы узнать больше о Тау, посмотрите видео Ви Харт Pi is (still) Wrong и начните праздновать Tau day, съев в два раза больше пирога!
Добавлено в версии 3.6.
- math.inf¶
Положительная бесконечность с плавающей запятой. (Для отрицательной бесконечности используйте
-math.inf
.) Эквивалентно результатуfloat('inf')
.Добавлено в версии 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
Добавлено в версии 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, но (опять же, следуя приложению F к C99) из этого правила есть некоторые исключения, например pow(float('nan'), 0.0)
или hypot(float('nan'), float('inf'))
.
Обратите внимание, что Python не предпринимает никаких усилий, чтобы отличить сигнальные NAN от тихих NAN, и поведение для сигнализации NAN остается неопределенным. Типичным поведением является обращение со всеми NAN как с тихими.
См.также
- Модуль
cmath
Версии многих из этих функций с комплексными числами.