Документация Python неофициальный перевод
Содержание страницы

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

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

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

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

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

math.ceil(x)

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

math.copysign(x, y)

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

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

math.fabs(x)

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

math.factorial(x)

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

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

math.floor(x)

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

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 для точного суммирования чисел с плавающей запятой.

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

math.isinf(x)

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

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

math.isnan(x)

Проверяет, является ли число с плавающей запятой x значением NaN (не число). Для получения дополнительной информации о NaN см. стандарт IEEE 754.

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

math.ldexp(x, i)

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

math.modf(x)

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

math.trunc(x)

Return the Real value x truncated to an Integral (usually a long integer). Uses the __trunc__ method.

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

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

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

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

math.exp(x)

Вернуть e**x.

math.expm1(x)

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

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

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

math.log(x[, base])

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

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

Изменено в версии 2.3: добавлен аргумент base.

math.log1p(x)

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

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

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() для точного вычисления целочисленных степеней.

Изменено в версии 2.6: Результат 1**nan и nan**0 был неопределён.

math.sqrt(x)

Возвращает квадратный корень из x.

9.2.3. Тригонометрические функции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.hypot(x, y)

Возвращает евклидову норму sqrt(x*x + y*y). Это длина вектора от начала координат до точки (x, y).

math.sin(x)

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

math.tan(x)

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

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

math.degrees(x)

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

math.radians(x)

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

9.2.5. Гиперболические функцииHyperbolic functions

math.acosh(x)

Возвращает обратный гиперболический косинус x.

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

math.asinh(x)

Возвращает обратный гиперболический синус x.

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

math.atanh(x)

Возвращает обратный гиперболический тангенс x.

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

math.cosh(x)

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

math.sinh(x)

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

math.tanh(x)

Возвращает гиперболический тангенс x.

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

math.erf(x)

Возвращает функцию ошибок в точке x.

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

math.erfc(x)

Возвращает дополнительную функцию ошибок в точке x.

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

math.gamma(x)

Возвращает гамма-функцию в точке x.

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

math.lgamma(x)

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

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

9.2.7. КонстантыConstants

math.pi

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

math.e

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

Особенность реализации 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 так, как будто они тихие.

Изменено в версии 2.6: Поведение в особых случаях теперь стремится соответствовать приложению F стандарта C99. В более ранних версиях Python поведение в особых случаях было описано нестрого.

См. также

Модуль cmath

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