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

Функции теории чисел

math.comb(n, k)

Возвращает количество способов выбрать k элементов из n элементов без повторений и без учёта порядка.

Вычисляет значение n! / (k! * (n - k)!), если k <= n, и возвращает ноль, если k > n.

Эта функция также называется биномиальным коэффициентом, поскольку она эквивалентна коэффициенту члена с номером k в разложении многочлена (1 + x)ⁿ.

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

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

math.factorial(n)

Возвращает факториал неотрицательного целого числа n.

Изменено в версии 3.10: Числа с плавающей точкой, имеющие целочисленные значения (например, 5.0), больше не принимаются.

math.gcd(*integers)

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

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

Изменено в версии 3.9: Добавлена поддержка произвольного количества аргументов. Ранее поддерживались только два аргумента.

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.perm(n, k=None)

Возвращает количество способов выбрать k элементов из n элементов без повторений и с учётом порядка.

Вычисляет значение n! / (n - k)!, если k <= n, и возвращает ноль, если k > n.

Если k не указано или равно None, по умолчанию k принимает значение n, и функция возвращает n!.

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

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

Арифметика с плавающей точкой

math.ceil(x)

Возвращает результат округления x вверх — наименьшее целое число, большее или равное x. Если x не является числом с плавающей точкой, вызывает x.__ceil__, который должен возвращать значение типа Integral.

math.fabs(x)

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

math.floor(x)

Возвращает результат округления x вниз — наибольшее целое число, меньшее или равное x. Если x не является числом с плавающей точкой, вызывает x.__floor__, который должен возвращать значение типа Integral.

math.fma(x, y, z)

Операция умножения с последующим сложением за одно округление. Возвращает (x * y) + z, вычисленное так, как если бы сначала использовались бесконечные точность и диапазон, а затем выполнялось однократное округление до формата float. Эта операция часто обеспечивает более высокую точность, чем непосредственное выражение (x * y) + z.

Эта функция соответствует спецификации операции fusedMultiplyAdd, описанной в стандарте IEEE 754. Стандарт оставляет один случай на усмотрение реализации, а именно результат для fma(0, inf, nan) и fma(inf, 0, nan). В этих случаях math.fma возвращает NaN и не вызывает исключение.

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

math.fmod(x, y)

Возвращает остаток от деления чисел с плавающей точкой x / y, определённый библиотечной функцией платформы C fmod(x, y). Обратите внимание: выражение Python x % y может возвращать другой результат. Согласно замыслу стандарта C, fmod(x, y) должно быть в точности (математически, с бесконечной точностью) равно x - n*y для некоторого целого числа n, причём результат должен иметь тот же знак, что и x, а его модуль должен быть меньше abs(y). Функция x % y в Python вместо этого возвращает результат со знаком y, а для аргументов типа float результат может быть вычислен неточно. Например, fmod(-1e-100, 1e100) равно -1e-100, но результат функции -1e-100 % 1e100 в Python равен 1e100-1e-100, что нельзя точно представить в виде float; при округлении получается неожиданное значение 1e100. Поэтому при работе с числами с плавающей точкой обычно предпочтительнее функция fmod(), а при работе с целыми числами — функция x % y в Python.

math.modf(x)

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

Обратите внимание, что у modf() отличается схема вызова и возврата результата от соответствующих функций C: она принимает один аргумент и возвращает пару значений, а не передаёт второе возвращаемое значение через «выходной параметр» (в Python такого понятия нет).

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 без дробной части, оставляя только целую. Округление выполняется в сторону нуля: trunc() эквивалентно floor() для положительного x и эквивалентно ceil() для отрицательного x. Если x не является числом с плавающей точкой, вызывает x.__trunc__, который должен возвращать значение типа Integral.

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

Функции для работы с числами с плавающей точкой

math.copysign(x, y)

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

math.frexp(x)

Возвращает мантиссу и показатель степени числа x в виде пары (m, e). m — число с плавающей точкой, а e — целое число, такие что x == m * 2**e в точности. Если x равен нулю, возвращает (0.0, 0), иначе — 0.5 <= abs(m) < 1. Эта функция используется для переносимого способа «разбора» внутреннего представления числа с плавающей точкой.

Обратите внимание, что у frexp() отличается порядок вызова и возврата результата от соответствующих функций C: она принимает один аргумент и возвращает пару значений, а не возвращает второе значение через «выходной параметр» (в Python такого понятия нет).

math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

Возвращает True, если значения a и b достаточно близки друг к другу, и False в противном случае.

Близость двух значений определяется заданными абсолютным и относительным допусками. Если ошибок не возникает, результат будет таким: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

rel_tol — относительный допуск: максимально допустимая разница между a и b относительно большего из абсолютных значений a или b. Например, чтобы задать допуск 5 %, передайте rel_tol=0.05. Допуск по умолчанию равен 1e-09, что гарантирует совпадение двух значений с точностью примерно до 9 десятичных знаков. rel_tol должен быть неотрицательным и меньше 1.0.

abs_tol — абсолютный допуск; по умолчанию он равен 0.0 и должен быть неотрицательным. При сравнении x с 0.0 значение isclose(x, 0) вычисляется как abs(x) <= rel_tol  * abs(x), что равно False для любого ненулевого x и rel_tol меньше 1.0. Поэтому добавьте к вызову подходящий положительный аргумент 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.nextafter(x, y, steps=1)

Возвращает значение с плавающей точкой, находящееся на steps шагов после x в направлении y.

Если x равно y, возвращает y, если только steps не равен нулю.

Примеры:

• 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.

Изменено в версии 3.12: Добавлен аргумент steps.

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 расшифровывается как «Unit in the Last Place» (единица последнего разряда).

См. также math.nextafter() и sys.float_info.epsilon.

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

Степенные, экспоненциальные и логарифмические функции

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 по заданному основанию base, вычисленный как 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. Особые случаи обрабатываются в соответствии со стандартом 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.dist(p, q)

Возвращает евклидово расстояние между двумя точками p и q, каждая из которых задана последовательностью (или итерируемым объектом) координат. Обе точки должны иметь одинаковую размерность.

Приблизительно эквивалентно:

sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

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

math.fsum(iterable)

Возвращает точную сумму значений с плавающей точкой в итерируемом объекте. Предотвращает потерю точности, отслеживая несколько промежуточных частичных сумм.

Точность алгоритма зависит от гарантий арифметики IEEE-754 и типичного случая, когда используется округление до ближайшего чётного. В некоторых сборках не для Windows базовая библиотека C использует сложение с расширенной точностью, из-за чего иногда может происходить двойное округление промежуточной суммы и результат может отличаться в младшем значащем бите.

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

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.prod(iterable, *, start=1)

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

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

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

math.sumprod(p, q)

Возвращает сумму произведений значений из двух итерируемых объектов p и q.

Вызывает ValueError, если входные данные имеют разную длину.

Приблизительно эквивалентно:

sum(itertools.starmap(operator.mul, zip(p, q, strict=True)))

Для значений с плавающей точкой и смешанных значений типа int/float промежуточные произведения и суммы вычисляются с расширенной точностью.

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

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

math.degrees(x)

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

math.radians(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.sin(x)

Возвращает синус угла x, заданного в радианах.

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

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

math.inf

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

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

math.nan

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

Изменено в версии 3.11: Теперь всегда доступно.