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 как целое число. Возбуждает исключение ValueError, если 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.__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)

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

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

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

math.trunc(x)

Возвращает x с удалённой дробной частью, оставляя целую часть. Это округление к 0: 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). 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 означает «Единица в последнем разряде».

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

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

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

Добавлена в версии 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π, отношению окружности к радиусу. Чтобы узнать больше о τ, посмотрите видео Ви Харт 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.

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