"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

+------------------------------------------------------+--------------------------------------------------------------------+
| **Conversions to and from polar coordinates**                                                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "phase(z)"                                           | Return the phase of *z*                                            |
+------------------------------------------------------+--------------------------------------------------------------------+
| "polar(z)"                                           | Return the representation of *z* in polar coordinates              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "rect(r, phi)"                                       | Return the complex number *z* with polar coordinates *r* and *phi* |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Power and logarithmic functions**                                                                                       |
+------------------------------------------------------+--------------------------------------------------------------------+
| "exp(z)"                                             | Return *e* raised to the power *z*                                 |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log(z[, base])"                                     | Return the logarithm of *z* to the given *base* (*e* by default)   |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log10(z)"                                           | Return the base-10 logarithm of *z*                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sqrt(z)"                                            | Return the square root of *z*                                      |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Trigonometric functions**                                                                                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acos(z)"                                            | Return the arc cosine of *z*                                       |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asin(z)"                                            | Return the arc sine of *z*                                         |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atan(z)"                                            | Return the arc tangent of *z*                                      |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cos(z)"                                             | Return the cosine of *z*                                           |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sin(z)"                                             | Return the sine of *z*                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tan(z)"                                             | Return the tangent of *z*                                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Hyperbolic functions**                                                                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acosh(z)"                                           | Return the inverse hyperbolic cosine of *z*                        |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asinh(z)"                                           | Return the inverse hyperbolic sine of *z*                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atanh(z)"                                           | Return the inverse hyperbolic tangent of *z*                       |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cosh(z)"                                            | Return the hyperbolic cosine of *z*                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sinh(z)"                                            | Return the hyperbolic sine of *z*                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tanh(z)"                                            | Return the hyperbolic tangent of *z*                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Classification functions**                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isfinite(z)"                                        | Check if all components of *z* are finite                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isinf(z)"                                           | Check if any component of *z* is infinite                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isnan(z)"                                           | Check if any component of *z* is a NaN                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isclose(a, b, *, rel_tol, abs_tol)"                 | Check if the values *a* and *b* are close to each other            |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Constants**                                                                                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "pi"                                                 | *π* = 3.141592...                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "e"                                                  | *e* = 2.718281...                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tau"                                                | *τ* = 2*π* = 6.283185...                                           |
+------------------------------------------------------+--------------------------------------------------------------------+
| "inf"                                                | Positive infinity                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "infj"                                               | Pure imaginary infinity                                            |
+------------------------------------------------------+--------------------------------------------------------------------+
| "nan"                                                | "Not a number" (NaN)                                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| "nanj"                                               | Pure imaginary NaN                                                 |
+------------------------------------------------------+--------------------------------------------------------------------+


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)

   Return the phase of *z* (also known as the *argument* of *z*), as a
   float. "phase(z)" is equivalent to "math.atan2(z.imag, z.real)".
   The result lies in the range [-*π*, *π*], and the branch cut for
   this operation lies along the negative real axis.  The sign of the
   result is the same as the sign of "z.imag", even when "z.imag" is
   zero:

      >>> phase(complex(-1.0, 0.0))
      3.141592653589793
      >>> phase(complex(-1.0, -0.0))
      -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)

   Return the representation of *z* in polar coordinates.  Returns a
   pair "(r, phi)" where *r* is the modulus of *z* and *phi* is the
   phase of *z*.  "polar(z)" is equivalent to "(abs(z), phase(z))".

cmath.rect(r, phi)

   Return the complex number *z* with polar coordinates *r* and *phi*.
   Equivalent to "complex(r * math.cos(phi), r * math.sin(phi))".


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

cmath.exp(z)

   Return *e* raised to the power *z*, where *e* is the base of
   natural logarithms.

cmath.log(z[, base])

   Return the logarithm of *z* to the given *base*. If the *base* is
   not specified, returns the natural logarithm of *z*. There is one
   branch cut, from 0 along the negative real axis to -∞.

cmath.log10(z)

   Return the base-10 logarithm of *z*. This has the same branch cut
   as "log()".

cmath.sqrt(z)

   Return the square root of *z*. This has the same branch cut as
   "log()".


Funções trigonométricas
=======================

cmath.acos(z)

   Return the arc cosine of *z*. There are two branch cuts: One
   extends right from 1 along the real axis to ∞. The other extends
   left from -1 along the real axis to -∞.

cmath.asin(z)

   Return the arc sine of *z*. This has the same branch cuts as
   "acos()".

cmath.atan(z)

   Return the arc tangent of *z*. There are two branch cuts: One
   extends from "1j" along the imaginary axis to "∞j". The other
   extends from "-1j" along the imaginary axis to "-∞j".

cmath.cos(z)

   Return the cosine of *z*.

cmath.sin(z)

   Return the sine of *z*.

cmath.tan(z)

   Return the tangent of *z*.


Funções hiperbólicas
====================

cmath.acosh(z)

   Return the inverse hyperbolic cosine of *z*. There is one branch
   cut, extending left from 1 along the real axis to -∞.

cmath.asinh(z)

   Return the inverse hyperbolic sine of *z*. There are two branch
   cuts: One extends from "1j" along the imaginary axis to "∞j".  The
   other extends from "-1j" along the imaginary axis to "-∞j".

cmath.atanh(z)

   Return the inverse hyperbolic tangent of *z*. There are two branch
   cuts: One extends from "1" along the real axis to "∞". The other
   extends from "-1" along the real axis to "-∞".

cmath.cosh(z)

   Return the hyperbolic cosine of *z*.

cmath.sinh(z)

   Return the hyperbolic sine of *z*.

cmath.tanh(z)

   Return the hyperbolic tangent of *z*.


Funções de classificação
========================

cmath.isfinite(z)

   Return "True" if both the real and imaginary parts of *z* are
   finite, and "False" otherwise.

   Adicionado na versão 3.2.

cmath.isinf(z)

   Return "True" if either the real or the imaginary part of *z* is an
   infinity, and "False" otherwise.

cmath.isnan(z)

   Return "True" if either the real or the imaginary part of *z* is a
   NaN, and "False" otherwise.

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.
