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

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

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

Возвращает float с модулем (абсолютным значением) 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 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(*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)¶

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

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.

Обратите внимание, что 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 в радианах. Результат находится в диапазоне от 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 радиан.

Преобразование углов¶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'). В соответствии с требованиями стандарта 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.