Перейти к содержимому

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


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

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

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

Арифметика с плавающей запятой

ceil(x)

Потолок x, наименьшее целое число, большее или равное x

fabs(x)

Абсолютное значение x

floor(x)

Пол x, наибольшее целое число, меньшее или равное x

fma(x, y, z)

Операция слитного умножения-сложения: (x * y) + z

fmax(x, y)

Максимум двух значений с плавающей запятой

fmin(x, y)

Минимум двух значений с плавающей запятой

fmod(x, y)

Остаток от деления x / y

modf(x)

Дробная и целая части x

remainder(x, y)

Остаток от деления x на y

trunc(x)

Целая часть x

Функции манипуляции числами с плавающей запятой

copysign(x, y)

Модуль (абсолютное значение) x со знаком y

frexp(x)

Мантисса и порядок x

isclose(a, b, rel_tol, abs_tol)

Проверяет, близки ли значения a и b друг к другу

isfinite(x)

Проверяет, не является ли x ни бесконечностью, ни NaN

isnormal(x)

Проверяет, является ли x нормальным числом

issubnormal(x)

Проверить, является ли x субнормальным числом

isinf(x)

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

isnan(x)

Проверить, является ли x значением NaN (не число)

ldexp(x, i)

x * (2**i), обратная функция к frexp()

nextafter(x, y, steps)

Значение с плавающей точкой на steps шагов после x в направлении y

signbit(x)

Проверить, является ли x отрицательным числом

ulp(x)

Значение наименьшего значащего бита числа x

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

cbrt(x)

Кубический корень из x

exp(x)

e в степени x

exp2(x)

2 в степени x

expm1(x)

e в степени x минус 1

log(x, base)

Логарифм x по заданному основанию (по умолчанию e)

log1p(x)

Натуральный логарифм 1+x (по основанию e)

log2(x)

Двоичный логарифм x

log10(x)

Десятичный логарифм x

pow(x, y)

x в степени y

sqrt(x)

Квадратный корень из x

Функции суммирования и произведения

dist(p, q)

Евклидово расстояние между двумя точками p и q, заданными в виде итерируемого набора координат

fsum(iterable)

Сумма значений во входном iterable

hypot(*coordinates)

Евклидова норма итерируемого набора координат

prod(iterable, start)

Произведение элементов во входном iterable с начальным значением start

sumprod(p, q)

Сумма произведений из двух итерабельных объектов p и q

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

degrees(x)

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

radians(x)

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

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

acos(x)

Арккосинус x

asin(x)

Арксинус x

atan(x)

Арктангенс x

atan2(y, x)

atan(y / x)

cos(x)

Косинус x

sin(x)

Синус x

tan(x)

Тангенс x

Гиперболические функции

acosh(x)

Обратный гиперболический косинус x

asinh(x)

Обратный гиперболический синус x

atanh(x)

Обратный гиперболический тангенс x

cosh(x)

Гиперболический косинус x

sinh(x)

Гиперболический синус x

tanh(x)

Гиперболический тангенс x

Специальные функции

erf(x)

Функция ошибок от x

erfc(x)

Дополнительная функция ошибок от x

gamma(x)

Гамма-функция от x

lgamma(x)

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

Константы

pi

π = 3.141592…

e

e = 2.718281…

tau

τ = 2π = 6.283185…

inf

Положительная бесконечность

nan

«Не число» (NaN)

Floating point arithmeticАрифметика с плавающей запятой

math.ceil(x)

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

math.fabs(x)

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

math.floor(x)

Возвращает пол x, наибольшее целое число, меньшее или равное x. Если x не является float, делегирует x.__floor__, которая должна возвращать значение Integral.

math.fma(x, y, z)

Операция слитного умножения-сложения. Возвращает (x * y) + z, вычисленный так, как если бы использовалась бесконечная точность и диапазон с последующим однократным округлением до формата float. Эта операция часто обеспечивает лучшую точность, чем прямое выражение (x * y) + z.

Эта функция следует спецификации операции fusedMultiplyAdd, описанной в стандарте IEEE 754. Стандарт оставляет один случай определённым реализацией, а именно результат fma(0, inf, nan) и fma(inf, 0, nan). В этих случаях math.fma возвращает NaN и не возбуждает никаких исключений.

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

math.fmax(x, y)

Возвращает большее из двух чисел с плавающей запятой, рассматривая NaN как отсутствующие данные.

Когда оба операнда являются (знаковыми) NaN или нулями, возвращает nan и 0 соответственно, а знак результата определён реализацией, то есть fmax() не обязан быть чувствительным к знаку таких операндов (см. Приложение F стандарта C11, §F.10.0.3 и §F.10.9.2).

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

math.fmin(x, y)

Возвращает меньшее из двух чисел с плавающей запятой, рассматривая NaN как отсутствующие данные.

Когда оба операнда являются (знаковыми) NaN или нулями, функция возвращает nan и 0 соответственно, а знак результата определяется реализацией; то есть fmin() не обязан учитывать знак таких операндов (см. приложение F к стандарту C11, §F.10.0.3 и §F.10.9.3).

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

math.fmod(x, y)

Возвращает остаток от деления с плавающей точкой от x / y, как определено библиотечной функцией C fmod(x, y). Обратите внимание, что выражение 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() обычно предпочтительнее при работе с числами с плавающей точкой, а Python x % y предпочтительнее при работе с целыми числами.

math.modf(x)

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

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

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.

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

Floating point manipulation functionsФункции для работы с числами с плавающей точкой

math.copysign(x, y)

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

math.frexp(x)

Возвращает мантиссу и экспоненту x в виде пары (m, e). m – это float, а e – целое число, такие что x == m * 2**e точно. Если x равно нулю, возвращает (0.0, 0), иначе 0.5 <= abs(m) < 1. Это используется для «разбора» внутреннего представления числа с плавающей точкой переносимым способом.

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

math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

Возвращает True, если значения a и b близки друг к другу, и False в противном случае.

Близость двух значений определяется в соответствии с заданными абсолютным и относительным допусками. Если ошибок не возникает, результат будет: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

rel_tol – это относительный допуск; это максимально допустимая разница между a и b относительно большего абсолютного значения a или b. Например, чтобы установить допуск 5%, передайте rel_tol=0.05. Допуск по умолчанию равен 1e-09, что гарантирует совпадение двух значений примерно до 9 десятичных знаков. rel_tol должен быть неотрицательным и меньше 1.0.

abs_tol – это абсолютный допуск; по умолчанию равен 0.0 и должен быть неотрицательным. При сравнении x с 0.0, isclose(x, 0) вычисляется как abs(x) <= rel_tol  * abs(x), что равно False для любого ненулевого x и rel_tol, меньшего 1.0. Поэтому добавьте соответствующий положительный аргумент 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.isnormal(x)

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

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

math.issubnormal(x)

Возвращает True, если x является субнормальным числом, то есть конечным ненулевым числом с модулем меньшим sys.float_info.min. Возвращает False в противном случае.

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

math.isinf(x)

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

math.isnan(x)

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

math.ldexp(x, i)

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

math.nextafter(x, y, steps=1)

Возвращает значение с плавающей запятой, отстоящее на steps шагов от x в направлении y.

Если x равно y, возвращает y, если только steps не равно нулю.

Примеры:

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

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

math.signbit(x)

Возвращает True, если знак x отрицательный, иначе False.

Это полезно для определения знакового бита нулей, бесконечностей и NaN.

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

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 расшифровывается как «Unit in the Last Place».

Смотрите также math.nextafter() и sys.float_info.epsilon.

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

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

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 может привести к значительной потере точности; функция expm1() позволяет вычислить это значение с полной точностью:

text
>>> 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. Исключительные случаи обрабатываются в соответствии со стандартом 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.

Summation and product functionsФункции суммирования и произведения

math.dist(p, q)

Возвращает евклидово расстояние между двумя точками p и q, каждая из которых задана как последовательность (или итерируемый объект) координат. Обе точки должны иметь одинаковую размерность.

Приблизительно эквивалентно:

python
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q, strict=True)))

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

math.fsum(iterable)

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

Точность алгоритма зависит от гарантий арифметики IEEE-754 и типичного случая, когда режим округления – «половина к чётному». В некоторых сборках не под Windows базовая библиотека C использует сложение с расширенной точностью и может иногда выполнять двойное округление промежуточной суммы, что приводит к погрешности в младшем значащем бите.

Дополнительное обсуждение и два альтернативных подхода см. в рецептах ASPN cookbook по точному суммированию чисел с плавающей запятой.

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 (unit in the last place – единица в последнем разряде). В более типичных случаях результат почти всегда корректно округляется до 1/2 ulp.

math.prod(iterable, *, start=1)

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

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

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

math.sumprod(p, q)

Возвращает сумму произведений значений из двух итерируемых объектов p и q.

Возбуждает ValueError, если входные данные имеют разную длину.

Приблизительно эквивалентно:

python
sum(map(operator.mul, p, q, strict=True))

Для входных данных типа float и смешанных int/float промежуточные произведения и суммы вычисляются с расширенной точностью.

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

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

math.degrees(x)

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

math.radians(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.sin(x)

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

math.tan(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() может использоваться для вычисления традиционных статистических функций, таких как кумулятивное стандартное нормальное распределение:

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

Number-theoretic functionsТеоретико-числовые функции

Для обратной совместимости модуль math также предоставляет псевдонимы следующих функций из модуля math.integer:

comb(n, k)

Количество способов выбрать k элементов из n без повторений и без учёта порядка

factorial(n)

n факториал

gcd(*integers)

Наибольший общий делитель целочисленных аргументов

isqrt(n)

Целочисленный квадратный корень неотрицательного целого числа n

lcm(*integers)

Наименьшее общее кратное целочисленных аргументов

perm(n, k)

Количество способов выбрать k элементов из n без повторений с учётом порядка

Добавлено в версии 3.5: Функция gcd().

Добавлено в версии 3.8: Функции comb(), perm() и isqrt().

Добавлено в версии 3.9: Функция lcm().

Изменено в версии 3.9: Добавлена поддержка произвольного количества аргументов в функции gcd(). Ранее поддерживалось только два аргумента.

Изменено в версии 3.10: Числа с плавающей запятой с целыми значениями (например, 5.0) больше не принимаются в функции factorial().

Мягко устарело с версии 3.15: Вместо этих псевдонимов используйте функции math.integer.

ConstantsКонстанты

math.pi

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

math.e

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

math.tau

Математическая константа τ = 6.283185…, с доступной точностью. Тау – это константа окружности, равная 2π, отношению длины окружности к её радиусу. Чтобы узнать больше о Тау, посмотрите видео Vi Hart 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 или ==. Пример:

text
>>> 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

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

Модуль math.integer

Целочисленные математические функции.