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

---

Этот модуль предоставляет доступ к математическим функциям, определенным стандартом C.

Эти функции нельзя использовать с комплексными числами; если вам нужна поддержка комплексных чисел, используйте одноименные функции из модуля cmath. Различие между функциями, поддерживающими комплексные числа, и функциями, не поддерживающими их, сделано потому, что большинство пользователей не хотят изучать столько математики, сколько требуется для понимания комплексных чисел. Получение исключения вместо комплексного результата позволяет раньше обнаружить неожиданное комплексное число, используемое в качестве параметра, чтобы программист мог определить, как и почему оно было сгенерировано в первую очередь.

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

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

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

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

Added in version 3.8.

math.copysign(x, y)

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

math.fabs(x)

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

math.factorial(n)

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

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

math.floor(x)

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

Added in version 3.13.

math.fmod(x, y)

Возвращает fmod(x, y), как определено библиотекой платформы C. Обратите внимание, что выражение x % y в Python может не возвращать тот же результат. Согласно стандарту C, fmod(x, y) должно быть точно (математически; с бесконечной точностью) равно x - n*y для некоторого целого числа n, такого, что результат имеет тот же знак, что и x, и величину меньше, чем abs(y). Питоновская x % y возвращает результат со знаком y, и может быть не совсем вычислима для аргументов с плавающей точкой. Например, fmod(-1e-100, 1e100) равно -1e-100, но результат функции Python -1e-100 % 1e100 равен 1e100-1e-100, что не может быть точно представлено как float, и округляется до удивительного 1e100. По этой причине функция fmod() обычно предпочтительнее при работе с плавающими числами, а x % y от Python - при работе с целыми числами.

math.frexp(x)

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

math.fsum(iterable)

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

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

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

math.gcd(*integers)

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

Added in version 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 считаются близкими только к самим себе.

Added in version 3.5.

См.также

PEP 485 – Функция для проверки приблизительного равенства

math.isfinite(x)

Верните True, если x не является ни бесконечностью, ни NaN, и False в противном случае. (Обратите внимание, что 0.0 *считается конечным).

Added in version 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).

Added in version 3.8.

math.lcm(*integers)

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

Added in version 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, если только шаги не равны нулю.

Примеры:

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

Added in version 3.9.

Изменено в версии 3.12: Добавлен аргумент шаги.

math.perm(n, k=None)

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

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

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

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

Added in version 3.8.

math.prod(iterable, *, start=1)

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

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

Added in version 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, результат этой операции всегда точно представим: ошибки округления не возникает.

Added in version 3.7.

math.sumprod(p, q)

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

Вызывает ValueError, если входные данные не имеют одинаковой длины.

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

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

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

Added in version 3.12.

math.trunc(x)

Возвращает x с удаленной дробной частью, оставляя целую часть. Округление происходит в сторону 0: trunc() эквивалентно floor() для положительных x, и эквивалентно ceil() для отрицательных x. Если x не является float, то передается значение x.__trunc__, которое должно вернуть значение Integral.

math.ulp(x)

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

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

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

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

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

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

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

ULP расшифровывается как «Unit in the Last Place».

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

Added in version 3.9.

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

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

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

math.cbrt(x)

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

Added in version 3.11.

math.exp(x)

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

math.exp2(x)

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

Added in version 3.11.

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

Added in version 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).

Added in version 3.3.

См.также

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

math.log10(x)

Возвращает логарифм по основанию 10 от 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.

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

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

Added in version 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

Added in version 3.2.

math.erfc(x)

Возвращает дополняющую функцию ошибки в точке x. Значение complementary error function определяется как 1.0 - erf(x). Она используется при больших значениях x, когда вычитание из единицы приводит к loss of significance.

Added in version 3.2.

math.gamma(x)

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

Added in version 3.2.

math.lgamma(x)

Возвращает натуральный логарифм абсолютного значения функции Гамма в точке x.

Added in version 3.2.

Константы

math.pi

Математическая константа π = 3,141592…, с доступной точностью.

math.e

Математическая константа e = 2,718281…, с доступной точностью.

math.tau

Математическая константа τ = 6,283185…, с доступной точностью. Тау - это константа окружности, равная 2π, отношение окружности круга к его радиусу. Чтобы узнать больше о тау, посмотрите видеоролик Ви Харта Pi is (still) Wrong и начните праздновать Tau day, съев в два раза больше пирога!

Added in version 3.6.

math.inf

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

Added in version 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

Added in version 3.5.

Изменено в версии 3.11: Теперь она всегда доступна.

Детали реализации CPython: Модуль math состоит в основном из тонких оберток вокруг функций математической библиотеки платформы C. Поведение в исключительных случаях соответствует приложению F стандарта C99, где это уместно. Текущая реализация будет поднимать ValueError для недопустимых операций, таких как sqrt(-1.0) или log(0.0) (где приложение F стандарта C99 рекомендует сигнализировать о недопустимой операции или делении на ноль), и OverflowError для результатов, которые переполняются (например, exp(1000.0)). NaN не будет возвращен ни одной из вышеперечисленных функций, если только один или несколько входных аргументов не были NaN; в этом случае большинство функций вернут NaN, но (опять же в соответствии с C99 Annex F) из этого правила есть некоторые исключения, например pow(float('nan'), 0.0) или hypot(float('nan'), float('inf')).

Обратите внимание, что Python не пытается отличить сигнальные NaN от тихих NaN, и поведение для сигнальных NaN остается неопределенным. Типичным поведением является обращение со всеми NaN как с тихими.

См.также

Модуль cmath

Версии комплексных чисел многих из этих функций.