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

Este módulo fornece acesso a funções matemáticas para números complexos. As funções neste módulo aceitam inteiros, números de ponto flutuante ou números complexos como argumentos. Eles também aceitarão qualquer objeto Python que tenha um método __complex__() ou __float__(): esses métodos são usados ​​para converter o objeto em um número complexo ou de ponto flutuante, respectivamente, e a função é então aplicada ao resultado da conversão.

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

Um número complexo Python z é armazenado internamente usando coordenadas retangulares ou cartesianas. É completamente determinado por sua parte real z.real e sua parte imaginária z.imag.

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)

Retorna o número complexo x com coordenadas polares r e phi. Equivalente a complex(r * math.cos(phi), r * math.sin(phi)).

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.

Adicionado 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 considerados próximos ou não é determinado de acordo com tolerâncias absolutas e relativas fornecidas. Se nenhum erro ocorrer, o resultado será: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

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 não negativo e menor que 1.0.

abs_tol é a tolerância absoluta; o padrão é 0.0 e deve ser não negativo. Ao comparar x com 0.0, isclose(x, 0) é computado como abs(x) <= rel_tol * abs(x), que é False para qualquer x e rel_tol menor que 1.0. Então adicione um argumento abs_tol positivo apropriado à chamada.

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.

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

Adicionado na versão 3.6.

cmath.inf

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

Adicionado na versão 3.6.

cmath.infj

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

Adicionado na versão 3.6.

cmath.nan

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

Adicionado na versão 3.6.

cmath.nanj

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

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