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)

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

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

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

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. Это наибольшее целое число 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, 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.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.sumprod(p, q)

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

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

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

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

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

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

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