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

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

math.ceil(x)

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

math.comb(n, k)

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

Вычисляется как n! / (k! * (n - k)!) при k <= n, и равняется нулю, когда k > n.

Также называется биномиальным коэффициентом, поскольку он эквивалентен коэффициенту к-го члена в многочленном разложении выражения (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 не целое или отрицательное.

Устарело начиная с версии 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)

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

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

Вычислить произведение всех элементов в входном итерируемом объекте. Значение по умолчанию для 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)

Возвращает 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 бит точности (такие же, как платформенный тип C double), в этом случае любое число с плавающей точкой 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 по заданному основанию, вычисленному как 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)

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

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» https://www.youtube.com/watch?v=jG7vhMMXagQ, и начните праздновать День τ, съев вдвое больше пирога!

Новая в версии 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.