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

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

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

Данный модуль предоставляет следующие функции. Если не указано иное, все возвращаемые значения являются числами с плавающей точкой.

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.__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 и типичного случая, когда режим округления — half-even. На некоторых сборках не 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 бит точности (такой же, как платформенный тип C double), в таком случае любое число с плавающей точкой x с abs(x) >= 2**52 обязательно не имеет дробных битов.

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.

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 радиан.

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

math.degrees(x)

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

math.radians(x)

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

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.

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.

7. Константы

math.pi

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

math.e

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

math.inf

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

Добавлена в версии 3.5.

math.nan

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

Добавлена в версии 3.5.