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)ⁿ.

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

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

math.copysign(x, y)

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

math.fabs(x)

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

math.factorial(n)

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

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

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

math.cbrt(x)

Возвращает кубический корень из x.

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

math.exp(x)

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

math.exp2(x)

Возвращает 2 в степени x.

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

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. Это обычно более точно, чем log(x, 2).

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

См. также

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

math.log10(x)

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

math.pow(x, y)

Возвращает x в степени y . Особые случаи следуют стандарту IEEE 754, насколько это возможно. В частности, pow(1.0, x) и pow(x, 0.0) всегда возвращают 1.0, даже когда x — ноль или NaN. Если x и y — конечные числа, x — отрицательно, и y — не целое число, тогда pow(x, y) не определено и вызывает ValueError.

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

Изменено в версии 3.11: Особые случаи pow(0.0, -inf) и pow(-0.0, -inf) были изменены на возврат inf вместо вызова ValueError, для согласованности со стандартом IEEE 754.

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 единицы в последнем разряде. Чаще всего результат практически всегда округляется до 1/2 единицы в последнем разряде.

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

Новая в версии 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.11: Теперь всегда доступна.

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