"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**                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "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(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 *z* 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(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')".

   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.

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.
