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


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

Данные функции нельзя использовать с комплексными числами; используйте одноименные функции из модуля 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) ** n.

Поднимает TypeError, если любой из аргументов не является целыми числами. Поднимает ValueError, если любой из аргументов отрицательный.

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

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

Возвращает точную сумму значения с плавающей запятой в 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.isqrt(n)

Возвращает целочисленный квадратный корень из неотрицательного целого числа n. Это нижний предел точного квадратного корня из n или, что эквивалентно, наибольшего целого числа a, такого что a² ≤ n.

Для некоторых приложений может быть более удобным иметь наименьшее целое число a, такое, что n ≤ a², или, другими словами, потолок точного квадратного корня из n. Для положительного n это можно вычислить с помощью a = 1 + isqrt(n - 1).

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

math.ldexp(x, i)

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

math.modf(x)

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

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. start значение по умолчанию для умножения — 1.

Когда iterable объект пуст, возвращает начальное значение. Эта функция предназначена специально для использования с числовыми значениями и может отклонять нечисловые типы.

Добавлено в версии 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)

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

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

Обратите внимание, что для функций ceil(), floor() и modf() все числа с плавающей запятой достаточно большой величины являются точными целыми числами. Дробные Python обычно несут не более 53 бит точности (такая же, как двойной тип платформы C), и в этом случае любое число с плавающей запятой 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  # дает результат с точностью до 11 мест
1.0000050000069649e-05
>>> expm1(1e-5)    # результат с точностью до полной точности
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)

Возвращает логарифм с основанием 2 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.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-мерных точек. Ранее поддерживался только двумерный.

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):
    'Накопительная функция распределения для стандартного нормального распределения'
    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π, отношению длины окружности к её радиусу. Чтобы узнать больше о Тау, посмотрите видео Ви Харт Пи (всё ещё) ошибается и начните праздновать День тау, съев в два раза больше пирога!

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

math.inf

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

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

math.nan

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

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

Детали реализации 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
Комплексные числовые версии многих из этих функций.