"cmath" --- 针对复数的数学函数
******************************

======================================================================

本模块提供了一些适用于复数的数学函数。 本模块中的函数接受整数、浮点数
或复数作为参数。 它们也接受任意具有 "__complex__()" 或 "__float__()"
方法的 Python 对象：这些方法分别用于将对象转换为复数或浮点数，然后再将
函数应用于转换后的结果。

备注:

  对于涉及分支切割的函数，我们会有确定如何在切割本身上定义这些函数的问
  题。 根据 Kahan 的论文 "Branch cuts for complex elementary
  functions"，以及 C99 的附录 G 和之后的 C 标准，我们使用零符号来区别
  分支切割的一侧和另一侧：对于沿实轴（一部分）的分支切割我们要看虚部的
  符号，而对于沿虚轴的分支切割我们则要看实部的符号。例如，
  "cmath.sqrt()" 函数有一个沿着负实轴的支割线。 参数 "-2-0j" 会被当作
  位于支割线的 *下方* 来处理，因而将给出一个负虚轴上的结果:

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

  但是参数 "-2+0j" 则会被当作位于支割线的上方来处理:

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

+------------------------------------------------------+--------------------------------------------------------------------+
| **针对极坐标的转换**                                                                                                      |
+------------------------------------------------------+--------------------------------------------------------------------+
| "phase(z)"                                           | 返回 *z* 的相位                                                    |
+------------------------------------------------------+--------------------------------------------------------------------+
| "polar(z)"                                           | 返回 *z* 的极坐标表示形式                                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "rect(r, phi)"                                       | 返回复数 *z* 的极坐标值 *r* 和 *phi*                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| **幂函数与对数函数**                                                                                                      |
+------------------------------------------------------+--------------------------------------------------------------------+
| "exp(z)"                                             | 返回 *e* 的 *z* 次幂                                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log(z[, base])"                                     | 返回 *z* 的指定底数 *base* (默认为 *e*) 的对数                     |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log10(z)"                                           | 返回 *z* 的以 10 为底的对数                                        |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sqrt(z)"                                            | 返回 *z* 的平方根                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| **三角函数**                                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acos(z)"                                            | 返回 *z* 的反余弦                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asin(z)"                                            | 返回 *z* 的反正弦                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atan(z)"                                            | 返回 *z* 的反正切                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cos(z)"                                             | 返回 *z* 的余弦                                                    |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sin(z)"                                             | 返回 *z* 的正弦                                                    |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tan(z)"                                             | 返回 *z* 的正切                                                    |
+------------------------------------------------------+--------------------------------------------------------------------+
| **双曲函数**                                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acosh(z)"                                           | 返回 *z* 的反双曲余弦                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asinh(z)"                                           | 返回 *z* 的反双曲正弦                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atanh(z)"                                           | 返回 *z* 反双曲正切                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cosh(z)"                                            | 返回 *z* 的双曲余弦                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sinh(z)"                                            | 返回 *z* 的双曲正弦                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tanh(z)"                                            | 返回 *z* 的双曲正切                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| **分类函数**                                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isfinite(z)"                                        | 检测是否 *z* 的所有部分均为有限值                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isinf(z)"                                           | 检测是否 *z* 的每个部分均为无穷大                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isnan(z)"                                           | 检测是否 *z* 的每个部分均为 NaN                                    |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isclose(a, b, *, rel_tol, abs_tol)"                 | 检查 *a* 和 *b* 的值是否彼此接近                                   |
+------------------------------------------------------+--------------------------------------------------------------------+
| **常量**                                                                                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "pi"                                                 | *π* = 3.141592...                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "e"                                                  | *e* = 2.718281...                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tau"                                                | *τ* = 2*π* = 6.283185...                                           |
+------------------------------------------------------+--------------------------------------------------------------------+
| "inf"                                                | 正无穷                                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "infj"                                               | 纯虚部无穷                                                         |
+------------------------------------------------------+--------------------------------------------------------------------+
| "nan"                                                | "非数字" (NaN)                                                     |
+------------------------------------------------------+--------------------------------------------------------------------+
| "nanj"                                               | 纯实部 NaN                                                         |
+------------------------------------------------------+--------------------------------------------------------------------+


到极坐标和从极坐标的转换
========================

Python 复数 "z" 是使用 *直角* 或 *笛卡尔* 坐标在内部存储的。 这完全取
决于其 *实部* "z.real" 及其 *虚部* "z.imag" 的值。

*极坐标* 提供了另一种复数的表示方法。在极坐标中，一个复数 *z* 由模量
*r* 和相位角 *phi* 来定义。模量 *r* 是从 *z* 到坐标原点的距离，而相位
角 *phi* 是以弧度为单位的，逆时针的，从正X轴到连接原点和 *z* 的线段间
夹角的角度。

下面的函数可用于原生直角坐标与极坐标的相互转换。

cmath.phase(z)

   将 *z* 的相位 (或称 *z* 的 *参数*) 作为一个浮点数返回。 "phase(z)"
   等价于 "math.atan2(z.imag, z.real)"。 结果将位于 [-*π*, *π*] 范围内
   ，且此操作的支割线将位于负实轴上。 结果的正负号将与 "z.imag" 的正负
   号相同，即使 "z.imag" 值为零:

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

备注:

  一个复数 *z* 的模数（绝对值）可以使用内置的 "abs()" 函数来计算。 没
  有用于此操作的单独的 "cmath" 模块函数。

cmath.polar(z)

   返回在极坐标中 *z* 的表示形式。 返回一个数值对 "(r, phi)" 其中 *r*
   是 *z* 的模数而 *phi* 是 *z* 的相位。 "polar(z)" 等价于 "(abs(z),
   phase(z))"。

cmath.rect(r, phi)

   将复数 *z* 返回为极坐标 *r* 和 *phi* 形式。 等价于 "complex(r *
   math.cos(phi), r * math.sin(phi))"。


幂函数与对数函数
================

cmath.exp(z)

   返回 *e* 的 *z* 次方，其中 *e* 是自然对数的底数。

cmath.log(z[, base])

   返回 *z* 的以给定的 *base* 为底的对数。 如果没有指定 *base*，则返回
   *z* 的自然对数。 存在一条支割线，即沿着负实轴从 0 到 -∞。

cmath.log10(z)

   返回 *z* 的以 10 为底的对数。 它具有与 "log()" 相同的支割线。

cmath.sqrt(z)

   返回 *z* 的平方根。 它具有与 "log()" 相同的支割线。


三角函数
========

cmath.acos(z)

   返回 *z* 的反余弦。 存在两条支割线：一条沿着实轴从 1 到 ∞。 另一条
   沿着实轴从 -1 向左延伸到 -∞。

cmath.asin(z)

   返回 *z* 的反正弦。 它具有与 "acos()" 相同的支割线。

cmath.atan(z)

   返回 *z* 的反正切。 存在两条支割线：一条沿着虚轴从 "1j" 到 "∞j"。
   另一条沿着虚轴从 "-1j" 延伸到 "-∞j"。

cmath.cos(z)

   返回 *z* 的余弦。

cmath.sin(z)

   返回 *z* 的正弦。

cmath.tan(z)

   返回 *z* 的正切。


双曲函数
========

cmath.acosh(z)

   返回 *z* 的反双曲余弦。 存在一条支割线，沿着实轴从 1 向左延伸到 -∞
   。

cmath.asinh(z)

   返回 *z* 的反双曲正弦。 存在两条支割线：一条沿着虚轴从 "1j" 注册会
   计师到 "∞j"。 另一条沿着虚轴从 "-1j" 延伸到 "-∞j"。

cmath.atanh(z)

   返回 *z* 的反双曲正切。 存在两条支割线：一条沿着实轴从 "1" 延伸到
   "∞"。 另一条沿着实轴从 "-1" 延伸到 "-∞"。

cmath.cosh(z)

   返回 *z* 的双曲余弦。

cmath.sinh(z)

   返回 *z* 的双曲正弦。

cmath.tanh(z)

   返回 *z* 的双曲正切。


分类函数
========

cmath.isfinite(z)

   如果 *z* 的实部和虚部均为有限值则返回 "True"，否则返回 "False"。

   Added in version 3.2.

cmath.isinf(z)

   如果 *z* 的实部或虚部为无穷大则返回 "True"，否则返回 "False"。

cmath.isnan(z)

   如果 *z* 的实部或虚部为 NaN 则返回 "True"，否则返回 "False"。

cmath.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

   若 *a* 和 *b* 的值比较接近则返回 "True"，否则返回 "False"。

   两个值是否会被视为相近是根据给定的绝对和相对容差来确定的。 如果未发
   生错误，结果将为: "abs(a-b) <= max(rel_tol * max(abs(a), abs(b)),
   abs_tol)"。

   *rel_tol* 是相对容差 -- 它是 *a* 和 *b* 之间的最大允许差值，相对于
   *a* 或 *b* 中绝对值较大的一个而言。 例如，要设置 5% 的容差，则传入
   "rel_tol=0.05"。 默认的容差为 "1e-09"，这将确保两个值在大约 9 个十
   进制数位内是相同的。 *rel_tol* 必须为非负值并且小于 "1.0"。

   *abs_tol* 是绝对容差；其默认值为 "0.0" 并且必须为非负值。 当将 "x"
   与 "0.0" 比较时，"isclose(x, 0)" 将按 "abs(x) <= rel_tol  * abs(x)"
   来计算，对于 "x" 和小于 "1.0" 的 rel_tol 来说均为 "False"。 因此请
   为该调用添一个为适当正值的 abs_tol。

   IEEE 754特殊值 "NaN" ， "inf" 和 "-inf" 将根据IEEE规则处理。具体来
   说， "NaN" 不被认为接近任何其他值，包括 "NaN" 。 "inf" 和 "-inf" 只
   被认为接近自己。

   Added in version 3.5.

   参见: **PEP 485** —— 用于测试近似相等的函数


常量
====

cmath.pi

   数学常数 *π* ，作为一个浮点数。

cmath.e

   数学常数 *e* ，作为一个浮点数。

cmath.tau

   数学常数 *τ* ，作为一个浮点数。

   Added in version 3.6.

cmath.inf

   浮点正无穷大。相当于 "float('inf')"。

   Added in version 3.6.

cmath.infj

   具有零实部和正无穷虚部的复数。相当于 "complex(0.0, float('inf'))"。

   Added in version 3.6.

cmath.nan

   A floating-point "not a number" (NaN) value.  Equivalent to
   "float('nan')". See also "math.nan".

   Added in version 3.6.

cmath.nanj

   具有零实部和 NaN 虚部的复数。相当于 "complex(0.0, float('nan'))"。

   Added in version 3.6.

请注意，函数的选择与模块 "math" 中的函数选择相似，但不完全相同。 拥有
两个模块的原因是因为有些用户对复数不感兴趣，甚至根本不知道它们是什么。
它们宁愿 "math.sqrt(-1)" 引发异常，也不想返回一个复数。 另请注意，被
"cmath" 定义的函数始终会返回一个复数，尽管答案可以表示为一个实数（在这
种情况下，复数的虚数部分为零）。

关于支割线的注释：它们是沿着给定函数无法连续的曲线。它们是许多复变函数
的必要特征。 假设您需要使用复变函数进行计算，您将会了解支割线的概念。
请参阅几乎所有关于复变函数的（不太基本）的书来获得启发。 对于如何正确
地基于数值目的来选择支割线的相关信息，一个良好的参考如下：

参见:

  Kahan, W: Branch cuts for complex elementary functions; or, Much ado
  about nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The
  state of the art in numerical analysis. Clarendon Press (1987) pp165
  --211.
