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

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

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 не является целым числом или отрицательным.

Устаревшее с версии 3.9: Принятие чисел с плавающей точкой с целыми значениями (например, 5.0) устарело.

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

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 такое, что a² ≤ n.

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

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

math.lcm(*integers)

Возвращает наименьшее общее кратное указанных целочисленных аргументов. Если все аргументы отличны от нуля, возвращаемое значение — наименьшее положительное целое число, кратное всем аргументам. Если какой-либо из аргументов равен нулю, возвращаемое значение — 0. lcm() без аргументов возвращает 1.

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

math.ldexp(x, i)

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

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)

Вычисляет произведение всех элементов в входном итерируемом объекте. Значение по умолчанию для start в произведении равно 1.

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

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

math.remainder(x, y)

Возвращает остаток от деления x на y в стиле IEEE 754. Для конечных 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 для любого x, которое не является NaN. Если результат операции получения остатка равен нулю, этот ноль имеет тот же знак, что и 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 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 по заданному основанию, вычисляемый как 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.

Исключительные случаи соответствуют Приложению «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 в радианах. Результат находится в диапазоне от 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 из градусов в радианы.

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

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

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π, отношению окружности к радиусу. Чтобы узнать больше о Тау, посмотрите видео Vi Hart Pi is (still) Wrong и начните отмечать День Тау, съев вдвое больше пирога!

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

math.inf

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

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

math.nan

Значение с плавающей запятой «не число» (NaN). Эквивалентно результату float('nan'). В соответствии с требованиями стандарта IEEE-754, 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.