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