9.2. math — Funções matemáticas

This module is always available. It provides access to the mathematical functions defined by the C standard.

Essas funções não podem ser usadas com números complexos; use as funções de mesmo nome do módulo cmath se você precisar de suporte para números complexos. A distinção entre funções que suportam números complexos e aquelas que não suportam é feita uma vez que a maioria dos usuários não quer aprender a matemática necessária para entender números complexos. Receber uma exceção em vez de um resultado complexo permite a detecção antecipada do número complexo inesperado usado como parâmetro, para que o programador possa determinar como e por que ele foi gerado em primeiro lugar.

As funções a seguir são fornecidas por este módulo. Exceto quando explicitamente indicado de outra forma, todos os valores de retorno são pontos flutuantes.

9.2.1. Funções teóricas dos números e de representação

math.ceil(x)

Retorna o teto de x, o menor inteiro maior ou igual a x. Se x não for um ponto flutuante, delega para x.__ceil__(), que deve retornar um valor de Integral.

math.copysign(x, y)

Retorna um ponto flutuante com a magnitude (valor absoluto) de x, mas o sinal de y. Em plataformas que suportam zeros sem sinal, copysign(1.0, -0.0) retorna -1.0.

math.fabs(x)

Retorna o valor absoluto de x.

math.factorial(x)

Return x factorial. Raises ValueError if x is not integral or is negative.

math.floor(x)

Retorna o piso de x, o maior inteiro menor ou igual a x. Se x não for um ponto flutuante, delega para x.__floor__(), que deve retornar um valor de Integral.

math.fmod(x, y)

Retorna fmod(x, y), conforme definido pela biblioteca C da plataforma. Observe que a expressão Python x % y pode não retornar o mesmo resultado. A intenção do padrão C é que fmod(x, y) seja exatamente (matematicamente; com precisão infinita) igual a x - n*y para algum inteiro n de modo que o resultado tenha o mesmo sinal que x e magnitude menor que abs(y). O x % y do Python retorna um resultado com o sinal de y, e pode não ser exatamente computável para argumentos de ponto flutuante. Por exemplo, fmod(-1e-100, 1e100) é -1e-100, mas o resultado de -1e-100 % 1e100 do Python é 1e100-1e-100, que não pode ser representado exatamente como um ponto flutuante, e é arredondado para o surpreendente 1e100. Por esta razão, a função fmod() é geralmente preferida ao trabalhar com pontos flutuantes, enquanto o x % y do Python é preferido ao trabalhar com inteiros.

math.frexp(x)

Retorna a mantissa e o expoente de x como o par (m, e). m é um ponto flutuante e e é um inteiro tal que x == m * 2**e exatamente. Se x for zero, retorna (0.0, 0), caso contrário, 0.5 <= abs(m) < 1. Isso é usado para “separar” a representação interna de um ponto flutuante de forma portátil.

math.fsum(iterable)

Retorna uma soma de valores de ponto flutuante precisa no iterável. Evita perda de precisão rastreando várias somas parciais intermediárias:

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

A precisão do algoritmo depende das garantias aritméticas IEEE-754 e do caso típico em que o modo de arredondamento é meio par. Em algumas compilações que não são do Windows, a biblioteca C subjacente usa adição de precisão estendida e pode ocasionalmente arredondar uma soma intermediária fazendo com que ela fique fora do bit menos significativo.

Para uma discussão mais aprofundada e duas abordagens alternativas, consulte as receitas do livro de receitas ASPN para soma de ponto flutuante preciso.

math.gcd(a, b)

Return the greatest common divisor of the integers a and b. If either a or b is nonzero, then the value of gcd(a, b) is the largest positive integer that divides both a and b. gcd(0, 0) returns 0.

Novo na versão 3.5.

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

Retorna True se os valores a e b estiverem próximos e False caso contrário.

Se dois valores são ou não considerados próximos, é determinado de acordo com as tolerâncias absolutas e relativas fornecidas.

rel_tol é a tolerância relativa – é a diferença máxima permitida entre a e b, em relação ao maior valor absoluto de a e b. Por exemplo, para definir uma tolerância de 5%, passe rel_tol=0.05. A tolerância padrão é 1e-09, o que garante que os dois valores sejam iguais em cerca de 9 dígitos decimais. rel_tol deve ser maior que zero.

abs_tol é a tolerância absoluta mínima – útil para comparações próximas a zero. abs_tol deve ser pelo menos zero.

Se nenhum erro ocorrer, o resultado será: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

Os valores especiais do IEEE 754 de NaN, inf e -inf serão tratados de acordo com as regras do IEEE. Especificamente, NaN não é considerado próximo a qualquer outro valor, incluindo NaN. inf e -inf são considerados apenas próximos a si mesmos.

Novo na versão 3.5.

Ver também

PEP 485 – Uma função para testar igualdade aproximada

math.isfinite(x)

Retorna True se x não for um infinito nem um NaN, e False caso contrário. (Observe que 0.0 é considerado finito.)

Novo na versão 3.2.

math.isinf(x)

Retorna True se x for um infinito positivo ou negativo, e False caso contrário.

math.isnan(x)

Retorna True se x for um NaN (não um número), e False caso contrário.

math.ldexp(x, i)

Retorna x * (2**i). Este é essencialmente o inverso da função frexp().

math.modf(x)

Retorna as partes fracionárias e inteiras de x. Ambos os resultados carregam o sinal de x e são pontos flutuantes.

math.trunc(x)

Retorna o valor x Real truncado com um Integral (geralmente um inteiro). Delega para x.__trunc__().

Observe que frexp() e modf() têm um padrão de chamada/retorno diferente de seus equivalentes C: elas pegam um único argumento e retornam um par de valores, ao invés de retornar seu segundo valor de retorno por meio de um “parâmetro de saída” (não existe tal coisa em Python).

Para as funções ceil(), floor() e modf(), observe que todos os números de ponto flutuante de magnitude suficientemente grande são inteiros exatos. Os pontos flutuantes do Python normalmente não carregam mais do que 53 bits de precisão (o mesmo que o tipo duplo da plataforma C), caso em que qualquer flutuante x com abs(x) >= 2**52 necessariamente não tem bits fracionários.

9.2.2. Funções de potência e logarítmicas

math.exp(x)

Return e**x.

math.expm1(x)

Return e**x - 1. For small floats x, the subtraction in exp(x) - 1 can result in a significant loss of precision; the expm1() function provides a way to compute this quantity to full precision:

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

Novo na versão 3.2.

math.log(x[, base])

Com um argumento, retorna o logaritmo natural de x (para base e).

Com dois argumentos, retorna o logaritmo de x para a base fornecida, calculada como log(x)/log(base).

math.log1p(x)

Retorna o logaritmo natural de 1+x (base e). O resultado é calculado de forma precisa para x próximo a zero.

math.log2(x)

Retorna o logaritmo de base 2 de x. Isso geralmente é mais preciso do que log(x, 2).

Novo na versão 3.3.

Ver também

int.bit_length() retorna o número de bits necessários para representar um inteiro em binário, excluindo o sinal e os zeros à esquerda.

math.log10(x)

Retorna o logaritmo de base 10 de x. Isso geralmente é mais preciso do que log(x, 10).

math.pow(x, y)

Retorna x elevado à potência y. Os casos excepcionais seguem o Anexo ‘F’ da norma C99, tanto quanto possível. Em particular, pow(1.0, x) e pow(x, 0.0) sempre retornam 1.0, mesmo quando x é um zero ou um NaN. Se ambos x e y são finitos, x é negativo, e y não é um inteiro, então pow(x, y) é indefinido e levanta ValueError.

Ao contrário do operador embutido **, math.pow() converte ambos os seus argumentos para o tipo float. Use ** ou a função embutida pow() para calcular potências inteiras exatas.

math.sqrt(x)

Retorna a raiz quadrada de x.

9.2.3. Funções trigonométricas

math.acos(x)

Return the arc cosine of x, in radians.

math.asin(x)

Return the arc sine of x, in radians.

math.atan(x)

Return the arc tangent of x, in radians.

math.atan2(y, x)

Retorna atan(y / x), em radianos. O resultado está entre -pi e pi. O vetor no plano da origem ao ponto (x, y) faz este ângulo com o eixo X positivo. O ponto de atan2() é que os sinais de ambas as entradas são conhecidos por ele, então ele pode calcular o quadrante correto para o ângulo. Por exemplo, atan(1) e atan2(1, 1) são ambos``pi/4``, mas atan2(-1, -1) é -3*pi/4.

math.cos(x)

Retorna o cosseno de x radianos.

math.hypot(x, y)

Return the Euclidean norm, sqrt(x*x + y*y). This is the length of the vector from the origin to point (x, y).

math.sin(x)

Retorna o seno de x radianos.

math.tan(x)

Retorna o tangente de x radianos.

9.2.4. Conversão angular

math.degrees(x)

Converte o ângulo x de radianos para graus.

math.radians(x)

Converte o ângulo x de graus para radianos.

9.2.5. Funções hiperbólicas

Funções hiperbólicas são análogos de funções trigonométricas baseadas em hipérboles em vez de círculos.

math.acosh(x)

Retorna o cosseno hiperbólico inverso de x.

math.asinh(x)

Retorna o seno hiperbólico inverso de x.

math.atanh(x)

Retorna a tangente hiperbólica inversa de x.

math.cosh(x)

Retorna o cosseno hiperbólico de x.

math.sinh(x)

Retorna o seno hiperbólico de x.

math.tanh(x)

Retorna a tangente hiperbólica de x.

9.2.6. Funções especiais

math.erf(x)

Retorna a função erro em x.

A função erf() pode ser usada para calcular funções estatísticas tradicionais, como a distribuição normal padrão cumulativa:

def phi(x):
    'Cumulative distribution function for the standard normal distribution'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0

Novo na versão 3.2.

math.erfc(x)

Retorna a função erro complementar em x. A função erro complementar é definida como 1.0 - erf(x). É usado para grandes valores de x onde uma subtração de um causaria uma perda de significância.

Novo na versão 3.2.

math.gamma(x)

Retorna a função gama em x.

Novo na versão 3.2.

math.lgamma(x)

Retorna o logaritmo natural do valor absoluto da função gama em x.

Novo na versão 3.2.

9.2.7. Constantes

math.pi

The mathematical constant π = 3.141592…, to available precision.

math.e

The mathematical constant e = 2.718281…, to available precision.

math.tau

The mathematical constant τ = 6.283185…, to available precision. Tau is a circle constant equal to 2π, the ratio of a circle’s circumference to its radius. To learn more about Tau, check out Vi Hart’s video Pi is (still) Wrong, and start celebrating Tau day by eating twice as much pie!

Novo na versão 3.6.

math.inf

Um infinito positivo de ponto flutuante. (Para infinito negativo, use -math.inf.) Equivalente à saída de float('inf').

Novo na versão 3.5.

math.nan

Um valor de ponto flutuante “não um número” (NaN). Equivalente à saída de float('nan').

Novo na versão 3.5.

CPython implementation detail: O módulo math consiste principalmente em O módulo: mod: math consiste principalmente em invólucros finos em torno das funções da biblioteca matemática C da plataforma. O comportamento em casos excepcionais segue o Anexo F da norma C99 quando apropriado. A implementação atual levantará ValueError para operações inválidas como sqrt(-1.0) ou log(0.0) (onde C99 Anexo F recomenda sinalizar operação inválida ou divisão por zero), e OverflowError para resultados que estouram (por exemplo,``exp(1000.0)``). Um NaN não será retornado de nenhuma das funções acima, a menos que um ou mais dos argumentos de entrada sejam um NaN; nesse caso, a maioria das funções retornará um NaN, mas (novamente seguindo C99 Anexo F) há algumas exceções a esta regra, por exemplo, pow(float('nan'), 0.0) ou hypot(float('nan'), float('inf')).

Observe que o Python não faz nenhum esforço para distinguir NaNs de sinalização de NaNs silenciosos, e o comportamento para NaNs de sinalização permanece não especificado. O comportamento típico é tratar todos os NaNs como se estivessem quietos.

Ver também

Modulo cmath

Versões de números complexos de muitas dessas funções.