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

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

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

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

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

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 и типичного случая, когда режим округления — половина-чётное. На некоторых не-Windows сборках, используемая подлежащая библиотека C использует сложение с расширенной точностью и может периодически удваивать округление промежуточной суммы, что заставляет её быть неверной в её наименее значимом бите.

Для дальнейшего обсуждения и двух альтернативных подходов см. рецепты в кулинарной книге ASPN для точного суммирования чисел с плавающей точкой.

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.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 двоичные числа с плавающей точкой, результат этой операции всегда точно представим: погрешности округления не вводятся.

Новое в версии 3.7.

math.trunc(x)

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

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

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

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

math.exp(x)

Возвращает e в степени x, где e = 2.718281… — основание натуральных логарифмов. Обычно это более точно, чем math.e ** x или pow(math.e, x).

math.expm1(x)

Возвращает e в степени x минус 1. Здесь e — основание натуральных логарифмов. Для малых значений 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.

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

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

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

math.degrees(x)

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

math.radians(x)

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

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

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

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)

Возвращает функцию ошибки в точке 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.

Константы

math.pi

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

math.e

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

math.tau

Математическая константа τ = 6.283185…, с доступной точностью. Константа τ равна 2π, отношению окружности к радиусу. Чтобы узнать больше о τ, посмотрите видео Ви Харт «Пи (по-прежнему) неправильно» https://www.youtube.com/watch?v=jG7vhMMXagQ, и начните праздновать День τ, съев в два раза больше пирога!

Новая в версии 3.6.

math.inf

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

Новая в версии 3.5.

math.nan

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

Новая в версии 3.5.