math – Математические функции¶math – Mathematical functions

Теоретико-числовые функции¶Number-theoretic functions

math.comb(n, k)¶

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

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

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

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

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

math.factorial(n)¶

Возвращает факториал неотрицательного целого числа n.

Изменено в версии 3.10: Числа с плавающей запятой, имеющие целые значения (например, 5.0), больше не принимаются.

math.gcd(*integers)¶

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

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

Изменено в версии 3.9: Добавлена поддержка произвольного количества аргументов. Ранее поддерживалось только два аргумента.

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.perm(n, k=None)¶

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

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

Если k не указан или равен None, то k по умолчанию принимается равным n, и функция возвращает n!.

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

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

Арифметика с плавающей запятой¶Floating point arithmetic

math.ceil(x)¶

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

math.fabs(x)¶

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

math.floor(x)¶

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

math.fma(x, y, z)¶

Совмещённая операция умножения-сложения. Возвращает (x * y) + z, вычисленное как будто с бесконечной точностью и диапазоном, после чего следует однократное округление до формата float. Эта операция часто обеспечивает лучшую точность, чем прямое выражение (x * y) + z.

Эта функция следует спецификации операции fusedMultiplyAdd, описанной в стандарте IEEE 754. Стандарт оставляет один случай определённым реализацией, а именно результат fma(0, inf, nan) и fma(inf, 0, nan). В этих случаях math.fma возвращает NaN и не возбуждает никаких исключений.

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

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

math.modf(x)¶

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

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

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 с отброшенной дробной частью, оставляя только целую часть. Это округление в сторону нуля: trunc() эквивалентно floor() для положительных x и эквивалентно ceil() для отрицательных x. Если x не является float, делегирует x.__trunc__, которая должна возвращать значение Integral.

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

Функции для работы с числами с плавающей запятой¶Floating point manipulation functions

math.copysign(x, y)¶

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

math.frexp(x)¶

Возвращает мантиссу и экспоненту x в виде пары (m, e). Если x – конечное ненулевое число, то m является float с 0.5 <= abs(m) < 1.0, а целое e таково, что x == m * 2**e точно. В противном случае возвращает (x, 0). Это используется для «разбора» внутреннего представления float переносимым способом.

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

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

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

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.ulp(x)¶

Возвращает значение наименее значащего бита числа с плавающей запятой x:

• Если x – NaN (не число), возвращает x.

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

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

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

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

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

ULP означает «единица в последнем разряде».

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

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

Степенные, показательные и логарифмические функции¶Power, exponential and logarithmic functions

math.cbrt(x)¶

Возвращает кубический корень из x.

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

math.exp(x)¶

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

math.exp2(x)¶

Возвращает 2, возведённое в степень x.

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

math.expm1(x)¶

Возвращает e, возведённое в степень x, минус 1. Здесь e – основание натуральных логарифмов. Для малых чисел с плавающей запятой x вычитание в exp(x) - 1 может привести к значительной потере точности; функция expm1() позволяет вычислить это значение с полной точностью:

>>> from math import exp, expm1
>>> exp(1e-5) - 1  # даёт результат с точностью до 11 знаков
1.0000050000069649e-05
>>> expm1(1e-5)    # результат с полной точностью
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.

Функции суммирования и произведения¶Summation and product functions

math.dist(p, q)¶

Возвращает евклидово расстояние между двумя точками p и q, каждая из которых задаётся как последовательность (или итерируемый объект) координат. Обе точки должны иметь одинаковую размерность.

Примерно эквивалентно:

sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

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

math.fsum(iterable)¶

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

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

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

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.prod(iterable, *, start=1)¶

Вычисляет произведение всех элементов входного итерируемого объекта. Значение start по умолчанию для произведения равно 1.

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

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

math.sumprod(p, q)¶

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

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

Примерно эквивалентно:

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

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

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

Преобразование углов¶Angular conversion

math.degrees(x)¶

Преобразует угол x из радианов в градусы.

math.radians(x)¶

Преобразует угол x из градусов в радианы.

Тригонометрические функции¶Trigonometric functions

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.sin(x)¶

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

math.tan(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.

Специальные функции¶Special functions

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.

Константы¶Constants

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