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, определённый функцией fmod(x, y) стандартной библиотеки C. Обратите внимание, что выражение Python x % y может возвращать другой результат. Согласно замыслу стандарта C, fmod(x, y) должно быть в точности (математически, с бесконечной точностью) равно x - n*y для некоторого целого числа n, так чтобы результат имел тот же знак, что и x, и модуль меньше abs(y). В Python x % y вместо этого возвращает результат со знаком 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)

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

На платформах, использующих двоичное представление чисел с плавающей точкой IEEE 754, результат этой операции всегда представим точно: погрешность округления не возникает.

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

math.trunc(x)

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

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

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

math.copysign(x, y)

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

math.frexp(x)

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

Обратите внимание, что у 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)

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

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

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

math.sumprod(p, q)

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

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

Примерно эквивалентно:

sum(map(operator.mul, p, q, strict=True))

Для значений типа float и смешанных значений 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: Теперь доступно всегда.