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


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

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

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

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

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

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

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

Возвращает точную сумму значений с плавающей запятой в 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 recipes for accurate floating point summation.

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, такое, что a2 ≤ n.

Для некоторых приложений может быть удобнее использовать наименьшее целое число a, такое, что n ≤ a2, или, другими словами, максимальное значение точного квадратного корня из 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)

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

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

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

math.remainder(x, y)

Возвращает остаток от x в соответствии с IEEE 754 по отношению к 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, убрав дробную часть и оставив целую. Это округляет значение до 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), и в этом случае любое значение с плавающей точкой x с abs(x) >= 2**52 обязательно не содержит дробных битов.

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

math.cbrt(x)

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

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

math.exp(x)

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

math.exp2(x)

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

Добавлено в версии 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

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

math.log(x[, base])

С помощью одного аргумента верните натуральный логарифм от x (по основанию e).

С помощью двух аргументов верните логарифм от x к заданному основанию, вычисленный как log(x)/log(base).

math.log1p(x)

Возвращает натуральный логарифм 1+x (основание e). Результат вычисляется с точностью до x, близкой к нулю.

math.log2(x)

Возвращает логарифм значения x по основанию 2. Обычно это более точно, чем log(x, 2).

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

См.также

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

math.log10(x)

Возвращает логарифм значения x по основанию 10. Обычно это более точное значение, чем 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)))

Добавлено в версии 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

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

math.erfc(x)

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

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

math.gamma(x)

Верните Gamma function в x.

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

math.lgamma(x)

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

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

Константы

math.pi

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

math.e

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

math.tau

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

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

math.inf

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

Добавлено в версии 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

Добавлено в версии 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, но (опять же, следуя приложению F к C99) из этого правила есть некоторые исключения, например pow(float('nan'), 0.0) или hypot(float('nan'), float('inf')).

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

См.также

Модуль cmath

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

Вернуться на верх