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)

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

Близость двух значений определяется с учётом заданных абсолютного и относительного допусков. Если ошибок не возникает, результат будет следующим: 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.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, 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)

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

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

Добавлено в версии 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)))

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

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

math.trunc(x)

Возвращает x без дробной части, оставляя только целую часть. Округление выполняется в направлении нуля: 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 расшифровывается как «Unit in the Last Place» (единица в последнем разряде).

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

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

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

Для функций ceil(), floor() и modf() следует учитывать, что все числа с плавающей точкой, модуль которых достаточно велик, являются точными целыми числами. Точность чисел float в Python обычно не превышает 53 бит (как и у платформенного типа double в C); в этом случае любое число float 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 по основанию 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.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π, отношению длины окружности к её радиусу. Чтобы узнать больше о тау, посмотрите видео Вай Харт Пи по-прежнему неверно и начните отмечать День тау, съев вдвое больше пирога!

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