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

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

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 не является целым или отрицательно.

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 вместо этого, и может быть невычислим точно для аргументов float. Например, fmod(-1e-100, 1e100) равно -1e-100, но результат Python-выражения -1e-100 % 1e100 равен 1e100-1e-100, что не может быть представлено точно как float и округляется до удивительного 1e100. По этой причине функция fmod() обычно предпочтительнее при работе с float, в то время как 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 и типичного случая, когда режим округления – «half-even». В некоторых сборках не под 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)¶

Возвращает остаток от деления по стандарту 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)¶

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

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

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

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

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  # даёт результат с точностью до 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. Исключительные случаи следуют Приложению ‘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.

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

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 радиан.

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

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.

Специальные функции¶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').

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