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 -2-0j é tratado como se estivesse abaixo do corte de ramificação, e assim dá um resultado no eixo imaginário negativo:

>>> cmath.sqrt(-2-0j)
-1.4142135623730951j

Mas um argumento de -2+0j é tratado como se estivesse acima do corte de ramificação:

>>> cmath.sqrt(-2+0j)
1.4142135623730951j

Conversões de e para coordenadas polares
phase(z)	Retorna a fase de z
polar(z)	Retorna a representação de z em coordenadas polares
rect(r, phi)	Retorna o número complexo z com coordenadas polares r e phi
Funções de potência e logarítmicas
exp(z)	Retorna e elevado à potência z
log(z[, base])	Retorna o logaritmo de z para a base fornecida (e por padrão)
log10(z)	Retorna o logaritmo de base 10 de z
sqrt(z)	Retorna a raiz quadrada de z
Funções trigonométricas
acos(z)	Retorna o arco cosseno de z
asin(z)	Retorna o arco seno de z
atan(z)	Retorna o arco tangente de z
cos(z)	Retorna o cosseno de z
sin(z)	Retorna o seno de z
tan(z)	Retorna a tangente de z
Funções hiperbólicas
acosh(z)	Retorna o cosseno hiperbólico inverso de z
asinh(z)	Retorna o seno hiperbólico inverso de z
atanh(z)	Retorna a tangente hiperbólica inversa de z
cosh(z)	Retorna o cosseno hiperbólico de z
sinh(z)	Retorna o seno hiperbólico de z
tanh(z)	Retorna a tangente hiperbólica de z
Funções de classificação
isfinite(z)	Verifica se todos os componentes de z são finitos
isinf(z)	Verifica se algum componente de z é infinito
isnan(z)	Verifica se algum componente de z é NaN
isclose(a, b, *, rel_tol, abs_tol)	Verifica se os valores a e b estão próximos um do outro
Constantes
pi	π = 3.141592…
e	e = 2.718281…
tau	τ = 2π = 6.283185…
inf	Infinito positivo
infj	Infinito imaginário puro
nan	“Not a number” (NaN)
nanj	NaN imaginário puro

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(z)

Retorna a fase de z (também conhecido como argumento de z), como um ponto flutuante. phase(z) equivale a math.atan2(z.imag, z.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 z.imag, mesmo quando z.imag é zero:

>>> phase(-1+0j)
3.141592653589793
>>> phase(-1-0j)
-3.141592653589793

Nota

The modulus (absolute value) of a complex number z can be computed using the built-in abs() function. There is no separate cmath module function for this operation.

cmath.polar(z)

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

cmath.rect(r, phi)

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

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

cmath.exp(z)

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

cmath.log(z[, base])

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

cmath.log10(z)

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

cmath.sqrt(z)

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

Funções trigonométricas

cmath.acos(z)

Retorna o arco cosseno de z. 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(z)

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

cmath.atan(z)

Retorna o arco tangente de z. 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(z)

Retorna o cosseno de z.

cmath.sin(z)

Retorna o seno de z.

cmath.tan(z)

Retorna a tangente de z.

Funções hiperbólicas

cmath.acosh(z)

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

cmath.asinh(z)

Retorna o seno hiperbólico inverso de z. 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(z)

Retorna a tangente hiperbólica inversa de z. 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(z)

Retorna o cosseno hiperbólico de z.

cmath.sinh(z)

Retorna o seno hiperbólico de z.

cmath.tanh(z)

Retorna a tangente hiperbólica de z.

Funções de classificação

cmath.isfinite(z)

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

Adicionado na versão 3.2.

cmath.isinf(z)

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

cmath.isnan(z)

Retorna True se ou a parte real ou a imaginária de z 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. Equivale a float('inf').

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

Adicionado na versão 3.6.

cmath.nan

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

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

Adicionado na versão 3.6.

Note that the selection of functions is similar, but not identical, to that in module math. The reason for having two modules is that some users aren’t interested in complex numbers, and perhaps don’t even know what they are. They would rather have math.sqrt(-1) raise an exception than return a complex number. Also note that the functions defined in cmath always return a complex number, even if the answer can be expressed as a real number (in which case the complex number has an imaginary part of 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.