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

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.