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) ** n.

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

Новая в версии 3.8.

math.copysign(x, y)

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

math.fabs(x)

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

math.factorial(x)

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

math.floor(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)

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

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

math.gcd(a, b)

Возвращает наибольший общий делитель целых чисел a и b. Если a или b не равно нулю, то значение gcd(a, b) — это наибольшее положительное целое число, которое делит как a, так и b. gcd(0, 0) возвращает 0.

Новая в версии 3.5.

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.ldexp(x, i)

Возвращает x * (2**i). Это по существу обратная функция frexp().

math.modf(x)

Возвращает дробную и целую части x. Оба результата имеют знак x и являются числами с плавающей точкой.

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.

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

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

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

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

math.trunc(x)

Возвращает значение Real x, усечённое до Integral (обычно целое число). Делегирует вызов x.__trunc__().

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

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

math.asin(x)

Возвращает арксинус x в радианах.

math.atan(x)

Возвращает арктангенс x в радианах.

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-мерных точек. Ранее поддерживался только двухмерный случай.

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

Новая в версии 3.5.