cmath — Funções matemáticas para números complexos

This module provides access to mathematical functions for complex numbers. The functions in this module accept integers, floating-point numbers or complex numbers as arguments. They will also accept any Python object that has either a __complex__() or a __float__() method: these methods are used to convert the object to a complex or floating-point number, respectively, and the function is then applied to the result of the conversion.

Nota

Para funções que envolvem cortes de ramificação, temos o problema de decidir como definir essas funções no próprio corte. Seguindo o artigo de Kahan intitulado “Branch cuts for complex elementary functions” (em tradução livre, “Cortes de ramificação para funções complexas elementares”), bem como o Anexo G do C99 e padrões C posteriores, usamos o sinal de zero para distinguir um lado do outro no corte de ramificação: para um corte de ramificação ao longo (de uma porção) do eixo real olhamos para o sinal da parte imaginária, enquanto para um corte de ramificação ao longo do eixo imaginário olhamos para o sinal da parte real.

Por exemplo, a função cmath.sqrt() tem um corte de ramificação ao longo do eixo real negativo. Um argumento de complex(-2.0, -0.0) é tratado como se estivesse abaixo do corte de ramificação, e assim dá um resultado no eixo imaginário negativo:

>>> cmath.sqrt(complex(-2.0, -0.0))
-1.4142135623730951j

Mas um argumento de complex(-2.0, 0.0) é tratado como se estivesse acima do corte de ramificação:

>>> cmath.sqrt(complex(-2.0, 0.0))
1.4142135623730951j

Conversões de e para coordenadas polares

A Python complex number z is stored internally using rectangular or Cartesian coordinates. It is completely determined by its real part z.real and its imaginary part z.imag. In other words:

z == z.real + z.imag*1j

Coordenadas polares fornecem uma forma alternativa de representar um número complexo. Em coordenadas polares, um número complexo z é definido pelo módulo r e pelo ângulo de fase phi. O módulo r é a distância de z à origem, enquanto a fase phi é o ângulo anti-horário, medido em radianos, do eixo x positivo ao segmento de reta que une a origem a z.

As funções a seguir podem ser usadas para converter coordenadas retangulares nativas em coordenadas polares e vice-versa.

cmath.phase(x)

Retorna a fase de x (também conhecido como argumento de x), como um ponto flutuante. phase(x) é equivalente a math.atan2(x.imag, x.real). O resultado está no intervalo [-π, π], e o corte de ramificação para esta operação está ao longo do eixo real negativo. O sinal do resultado é igual ao sinal de x.imag, mesmo quando x.imag é zero:

>>> phase(complex(-1.0, 0.0))
3.141592653589793
>>> phase(complex(-1.0, -0.0))
-3.141592653589793

Nota

O módulo (valor absoluto) de um número complexo x pode ser calculado usando a função embutida abs(). Não há função do módulo cmath separada para esta operação.

cmath.polar(x)

Retorna a representação de x em coordenadas polares. Retorna um par (r, phi) onde r é o módulo de x e phi é a fase de x. polar(x) é equivalente a (abs(x), phase(x)).

cmath.rect(r, phi)

Return the complex number x with polar coordinates r and phi. Equivalent to r * (math.cos(phi) + math.sin(phi)*1j).

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

cmath.exp(x)

Retorna e elevado à potência x, onde e é a base de logaritmos naturais.

cmath.log(x[, base])

Retorna o logaritmo de x para a base fornecida. Se a base não for especificada, retorna o logaritmo natural de x. Há um corte de ramificação, de 0 ao longo do eixo real negativo até -∞.

cmath.log10(x)

Retorna o logaritmo de x na base 10. Este tem o mesmo corte de ramificação que log().

cmath.sqrt(x)

Retorna a raiz quadrada de x. Este tem o mesmo corte de ramificação que log().

Funções trigonométricas

cmath.acos(x)

Retorna o arco cosseno de x. Existem dois cortes de ramificação: um se estende desde 1 ao longo do eixo real até ∞. O outro se estende para a esquerda de -1 ao longo do eixo real até -∞.

cmath.asin(x)

Retorna o arco seno de x. Tem os mesmos cortes de ramificação que acos().

cmath.atan(x)

Retorna o arco tangente de x. Existem dois cortes de ramificação: Um se estende de 1j ao longo do eixo imaginário até ∞j. O outro se estende de -1j ao longo do eixo imaginário até -∞j.

cmath.cos(x)

Retorna o cosseno de x.

cmath.sin(x)

Retorna o seno de x.

cmath.tan(x)

Retorna a tangente de x.

Funções hiperbólicas

cmath.acosh(x)

Retorna o cosseno hiperbólico inverso de x. Há um corte de ramificação, estendendo-se para a esquerda de 1 ao longo do eixo real até -∞.

cmath.asinh(x)

Retorna o seno hiperbólico inverso de x. Existem dois cortes de ramificação: Um se estende de 1j ao longo do eixo imaginário até ∞j. O outro se estende de -1j ao longo do eixo imaginário até -∞j.

cmath.atanh(x)

Retorna a tangente hiperbólica inversa de x. Existem dois cortes de ramificação: Um se estende de 1 ao longo do eixo real até ∞. O outro se estende de -1 ao longo do eixo real até -∞.

cmath.cosh(x)

Retorna o cosseno hiperbólico de x.

cmath.sinh(x)

Retorna o seno hiperbólico de x.

cmath.tanh(x)

Retorna a tangente hiperbólica de x.

Funções de classificação

cmath.isfinite(x)

Retorna True se ambas as partes real e imaginária de x forem finitas, e False caso contrário.

Novo na versão 3.2.

cmath.isinf(x)

Retorna True se ou a parte real ou a imaginária de x for infinita, e False caso contrário.

cmath.isnan(x)

Retorna True se ou a parte real ou a imaginária de x for NaN, e False caso contrário.

cmath.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 ou 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

Constantes

cmath.pi

A constante matemática π, como um ponto flutuante.

cmath.e

A constante matemática e, como um ponto flutuante.

cmath.tau

A constante matemática τ, como um ponto flutuante.

Novo na versão 3.6.

cmath.inf

Infinito positivo de ponto flutuante. Equivale a float('inf').

Novo na versão 3.6.

cmath.infj

Número complexo com parte real zero e parte imaginária infinita positiva. Equivale a complex(0.0, float('inf')).

Novo na versão 3.6.

cmath.nan

Um valor de ponto flutuante “não um número” (NaN). Equivale a float('nan').

Novo na versão 3.6.

cmath.nanj

Número complexo com parte real zero e parte imaginária NaN. Equivale a complex(0.0, float('nan')).

Novo na versão 3.6.

Observe que a seleção de funções é semelhante, mas não idêntica, àquela no módulo math. A razão para ter dois módulos é que alguns usuários não estão interessados em números complexos e talvez nem saibam o que são. Eles preferem que math.sqrt(-1) gere uma exceção do que retorne um número complexo. Observe também que as funções definidas em cmath sempre retornam um número complexo, mesmo que a resposta possa ser expressa como um número real (nesse caso o número complexo tem uma parte imaginária de zero).

Uma nota sobre cortes de ramificação: são curvas ao longo das quais a função dada não é contínua. Eles são um recurso necessário de muitas funções complexas. Presume-se que se você precisar calcular com funções complexas, você entenderá sobre cortes de ramificação. Consulte quase qualquer livro (não muito elementar) sobre variáveis complexas para obter esclarecimento. Para informações sobre a escolha adequada dos cortes de ramificação para fins numéricos, uma boa referência deve ser a seguinte:

Ver também

Kahan, W: Branch cuts for complex elementary functions; or, Much ado about nothing’s sign bit. Em Iserles, A. e Powell, M. (eds.), The state of the art in numerical analysis. Clarendon Press (1987) pp165–211.