# `cmath` --- 针对复数的数学函数

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

备注

对于涉及分支切割的函数，我们会有确定如何在切割本身上定义这些函数的问题。 根据 Kahan 的论文 "Branch cuts for complex elementary functions"，以及 C99 的附录 G 和之后的 C 标准，我们使用零符号来区别分支切割的一侧和另一侧：对于沿实轴（一部分）的分支切割我们要看虚部的符号，而对于沿虚轴的分支切割我们则要看实部的符号。

例如，`cmath.sqrt()` 函数有一个沿着负实轴的分支切割。 参数 `complex(-2.0, -0.0)` 会被当作位于切支切割的 下方 来处理，因而将给出一个负虚轴上的结果。

    >>> cmath.sqrt(complex(-2.0, -0.0))
    -1.4142135623730951j

但是参数 `complex(-2.0, 0.0)` 则会被当作是位于支割线的上方来处理:

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

  浮点 "非数字" (NaN) 值。 相当于 `float('nan')`。 另请参阅 `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.