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

Теоретико-числовые функции и функции представления¶

math.ceil(x)¶

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

math.comb(n, k)¶

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

Оценивается в n! / (k! * (n - k)!) при k <= n и оценивается в ноль при k > n.

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

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

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

math.copysign(x, y)¶

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

math.fabs(x)¶

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

math.factorial(x)¶

Возвращает факториал x в виде целого числа. Вызывает ValueError, если x не является интегралом или отрицателен.

Не рекомендуется, начиная с версии 3.9: Принятие плавающих чисел с интегральными значениями (например, 5.0) устарело.

math.floor(x)¶

Возвращает значение x, наибольшее целое число, меньшее или равное x. Если x не является float, делегируется функция 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 x % y возвращает результат со знаком y, и может быть не совсем вычислимым для аргументов с плавающей точкой. Например, fmod(-1e-100, 1e100) - это -1e-100, но результат Python’s -1e-100 % 1e100 - это 1e100-1e-100, который не может быть точно представлен как float, и округляется до удивительного 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)¶

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

>>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
0.9999999999999999
>>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
1.0

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

Дальнейшее обсуждение и два альтернативных подхода см. в ASPN cookbook recipes for accurate floating point summation.

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. Это пол точного квадратного корня из 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)¶

Возвращает следующее значение с плавающей точкой после x в направлении y.

Если x равно y, возвращается y.

Примеры:

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

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

Вычисляет произведение всех элементов во входной итерабельной таблице. По умолчанию начальное значение для произведения равно 1.

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

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

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.

math.ulp(x)¶

Возвращает значение наименьшего значащего бита числа float x:

• Если x - NaN (не число), верните x.

• Если x отрицательно, верните ulp(-x).

• Если x - положительная бесконечность, верните x.

• Если x равно нулю, возвращается наименьшее положительное денормализованное представимое число (меньше минимального положительного нормализованного числа, sys.float_info.min).

• Если x равно наибольшей положительной представимой плавающей величине, верните значение наименьшего значащего бита x, такое, что первая плавающая величина меньше x будет x - ulp(x).

• В противном случае (x - положительное конечное число), возвращается значение наименьшего значащего бита x, такое, что первый float больше x равен x + ulp(x).

ULP расшифровывается как «Единица в последнем месте».

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

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

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

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

Силовые и логарифмические функции¶

math.exp(x)¶

Возвращает e, возведенное в степень x, где e = 2.718281… - основание натуральных логарифмов. Обычно это более точное значение, чем math.e ** x или pow(math.e, x).

math.expm1(x)¶

Возвращает e, возведенное в степень x, минус 1. Здесь e - основание натуральных логарифмов. Для малых плавающих чисел x вычитание в exp(x) - 1 может привести к significant loss of precision; функция 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)¶

Возвращает логарифм по основанию 2 от x. Обычно это более точное значение, чем log(x, 2).

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

См.также

int.bit_length() возвращает количество битов, необходимых для представления целого числа в двоичном формате, исключая знак и ведущие нули.

math.log10(x)¶

Возвращает логарифм по основанию 10 от x. Обычно это более точное значение, чем log(x, 10).

math.pow(x, y)¶

Верните x, возведенное в степень y. Исключительные случаи следуют приложению „F“ стандарта C99, насколько это возможно. В частности, pow(1.0, x) и pow(x, 0.0) всегда возвращают 1.0, даже если x - ноль или NaN. Если x и y конечны, x отрицательно, а y не целое число, то pow(x, y) не определено и возвращает ValueError.

В отличие от встроенного оператора **, math.pow() приводит оба аргумента к типу float. Для вычисления точных целых чисел используйте ** или встроенную функцию pow().

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 из градусов в радианы.

Гиперболические функции¶

Hyperbolic functions являются аналогами тригонометрических функций, которые основаны на гиперболах вместо окружностей.

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

Возвращает error function в точке x.

Функция erf() может использоваться для вычисления традиционных статистических функций, таких как cumulative standard normal distribution:

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. Функция complementary error function определяется как 1.0 - erf(x). Она используется для больших значений x, где вычитание из единицы привело бы к loss of significance.

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

math.gamma(x)¶

Возвращает Gamma function в точке 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, и начните праздновать Tau day, съев вдвое больше пирога!

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

math.inf¶

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

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

math.nan¶

Значение с плавающей точкой «не число» (NaN). Эквивалентно выводу float('nan'). Из-за требований IEEE-754 standard, 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.