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

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

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

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

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

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

math.ceil(x)

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

math.copysign(x, y)

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

Возвращает точную сумму чисел с плавающей запятой из итерируемого объекта. Избегает потери точности за счёт отслеживания нескольких промежуточных частичных сумм:

>>> 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.isfinite(x)

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

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

math.isinf(x)

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

math.isnan(x)

Возвращает True, если x является NaN (не числом), и False в противном случае.

math.ldexp(x, i)

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

math.modf(x)

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

math.trunc(x)

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

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

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

8.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

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

math.log(x[, base])

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

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

math.log1p(x)

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

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.

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

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

math.degrees(x)

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

math.radians(x)

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

8.2.5. Гиперболические функции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.

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

8.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 так, как будто они тихие.

См. также

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