math — Математические функции

Этот модуль всегда доступен. Он предоставляет доступ к математическим функциям, определённым стандартом C.

Эти функции нельзя использовать с комплексными числами; используйте функции с тем же именем из модуля cmath, если вам требуется поддержка комплексных чисел. Различие между функциями, поддерживающими комплексные числа, и теми, которые этого не делают, сделано, так как большинство пользователей не хотят изучать столько математики, сколько нужно для понимания комплексных чисел. Получение исключения вместо комплексного результата позволяет раньше обнаружить неожиданное комплексное число, используемое в качестве параметра, чтобы программист мог определить, как и почему оно было сгенерировано.

В этом модуле предоставляются следующие функции. За исключением случаев, когда явно указано обратное, все возвращаемые значения являются числами с плавающей точкой.

9.2.1. Теоретико-числовые и представительные функции

math.ceil(x)

Возвращает целую часть x, наименьшее целое число, большее или равное x. Если x не является числом с плавающей точкой, делегирует x.__ceil__(), которое должно вернуть значение Integral.

math.copysign(x, y)

Возвращает число с плавающей точкой с модулем (абсолютным значением) x, но со знаком y. На платформах, которые поддерживают знакомые нули, copysign(1.0, -0.0) возвращает -1.0.

math.fabs(x)

Возвращает абсолютное значение x.

math.factorial(x)

Возвращает факториал x. Вызывает исключение ValueError, если x не является целым или отрицательным.

math.floor(x)

Возвращает целую часть от x, наибольшее целое число, меньшее или равное x. Если x не является числом с плавающей точкой, делегирует x.__floor__(), которое должно вернуть значение Integral.

math.fmod(x, y)

Возвращает fmod(x, y), как определено библиотекой C платформы. Обратите внимание, что выражение Python x % y может не вернуть тот же результат. Целью стандарта C является то, что fmod(x, y) должно быть точно (математически; с бесконечной точностью) равно x - n*y для некоторого целого n, такого что результат имеет тот же знак, что и x, и величина меньше abs(y). Python’s x % y возвращает результат со знаком y вместо этого и может быть неточно вычислен для аргументов с плавающей точкой. Например, fmod(-1e-100, 1e100) равно -1e-100, но результат Python’s -1e-100 % 1e100 равен 1e100-1e-100, который не может быть точно представлен как число с плавающей точкой и округляется до неожиданного 1e100. По этой причине функция fmod() обычно предпочтительнее при работе с числами с плавающей точкой, тогда как Python’s x % 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)

Возвращает точную сумму чисел с плавающей точкой в итерируемом объекте. Избегает потери точности, отслеживая несколько промежуточных частичных сумм:

>>> 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 по точной суммированию чисел с плавающей точкой.

math.gcd(a, b)

Возвращает наибольший общий делитель целых чисел a и b. Если a или b не равно нулю, то значение gcd(a, b) — это наибольшее положительное целое число, которое делит как a, так и b. gcd(0, 0) возвращает 0.

Введено в версии 3.5.

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.ldexp(x, i)

Возвращает x * (2**i). Это по существу обратное функции frexp().

math.modf(x)

Возвращает дробную и целую части x. Оба результата несут знак x и являются числами с плавающей точкой.

math.trunc(x)

Возвращает значение Real x, усечённое до Integral (обычно целое число). Делегирует x.__trunc__().

Обратите внимание, что frexp() и modf() имеют другой шаблон вызова/возврата, чем их C-эквиваленты: они принимают один аргумент и возвращают пару значений, а не возвращают второе возвращаемое значение через «параметр вывода» (в Python такого нет).

Для функций ceil(), floor() и modf() обратите внимание, что все числа с плавающей точкой достаточной большой величины являются точными целыми числами. Числа с плавающей точкой в Python обычно несут не более 53 бит точности (такие же, как тип platform C double), в таком случае любое число с плавающей точкой x с abs(x) >= 2**52 обязательно не имеет дробных битов.

9.2.2. Функции возведения в степень и логарифмические функции

math.exp(x)

Возвращает e**x.

math.expm1(x)

Возвращает e**x - 1. Для малых чисел с плавающей точкой x, вычитание в exp(x) - 1 может привести к значительной потере точности; функция 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 по заданному основанию base, вычисленный как log(x)/log(base).

math.log1p(x)

Возвращает натуральный логарифм 1+x (по основанию e). Результат вычисляется таким образом, чтобы он был точным для x, близкого к нулю.

math.log2(x)

Возвращает двоичный логарифм x. Обычно это более точный результат, чем log(x, 2).

Введено в версии 3.3.

См. также

int.bit_length() возвращает количество бит, необходимых для представления целого числа в двоичном формате, исключая знак и ведущие нули.

math.log10(x)

Возвращает десятичный логарифм x. Обычно это более точный результат, чем log(x, 10).

math.pow(x, y)

Возвращает x в степени y. Исключительные случаи следуют Приложению «F» стандарта C99 по возможности. В частности, pow(1.0, x) и pow(x, 0.0) всегда возвращают 1.0, даже когда x является нулём или NaN. Если оба x и y являются конечными, x отрицательно, а y не является целым числом, то значение pow(x, y) не определено и вызывает ValueError.

В отличие от встроенного оператора **, math.pow() преобразует оба своих аргумента в тип float. Используйте ** или встроенную функцию pow() для вычисления точных степеней целых чисел.

math.sqrt(x)

Возвращает квадратный корень из x.

9.2.3. Тригонометрические функции

math.acos(x)

Возвращает арккосинус x в радианах.

math.asin(x)

Возвращает арксинус x в радианах.

math.atan(x)

Возвращает арктангенс x в радианах.

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.hypot(x, y)

Возвращает евклидову норму, sqrt(x*x + y*y). Это длина вектора от начала координат до точки (x, y).

math.sin(x)

Возвращает синус x в радианах.

math.tan(x)

Возвращает тангенс x в радианах.

9.2.4. Преобразование углов

math.degrees(x)

Преобразует угол x из радиан в градусы.

math.radians(x)

Преобразует угол x из градусов в радианы.

9.2.5. Гиперболические функции

Гиперболические функции — аналоги тригонометрических функций, основанные на гиперболах, а не на окружностях.

math.acosh(x)

Возвращает обратную гиперболическую косинус x.

math.asinh(x)

Возвращает обратную гиперболическую синус x.

math.atanh(x)

Возвращает обратную гиперболическую тангенс x.

math.cosh(x)

Возвращает гиперболическую косинус x.

math.sinh(x)

Возвращает гиперболическую синус x.

math.tanh(x)

Возвращает гиперболическую тангенс x.

9.2.6. Специальные функции

math.erf(x)

Возвращает функцию ошибки в точке x.

Функцию erf() можно использовать для вычисления традиционных статистических функций, таких как кумулятивная стандартная нормальная функция распределения:

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. Дополнительная функция ошибки определяется как 1.0 - erf(x). Она используется для больших значений x, где вычитание из единицы привело бы к потере значимости.

Введено в версии 3.2.

math.gamma(x)

Возвращает гамма-функцию в точке x.

Введено в версии 3.2.

math.lgamma(x)

Возвращает натуральный логарифм модуля гамма-функции в точке x.

Введено в версии 3.2.

9.2.7. Константы

math.pi

Математическая константа π = 3,141592…, с доступной точностью.

math.e

Математическая константа e = 2,718281…, с доступной точностью.

math.tau

Математическая константа τ = 6,283185…, с доступной точностью. Константа τ является круговой константой, равной 2π, отношению окружности круга к его радиусу. Чтобы узнать больше о τ, посмотрите видео Ви Харт Pi is (still) Wrong, и начните отмечать День Tau, съев в два раза больше пирога!

Введено в версии 3.6.

math.inf

Положительная бесконечность с плавающей точкой. (Для отрицательной бесконечности используйте -math.inf.) Эквивалентно результату float('inf').

Введено в версии 3.5.

math.nan

Значение «не число» (NaN) с плавающей точкой. Эквивалентно результату float('nan').

Введено в версии 3.5.