# `cmath` --- 複數的數學函式

本模組提供一些適用於複數的數學函式。本模組中的函式接受整數、浮點數或複數作為引數。它們也接受任何具有 `__complex__()` 或 `__float__()` 方法的 Python 物件：這些方法分別用於將物件轉換為複數或浮點數，然後再將函式應用於轉換後的結果。

備註

對於涉及分枝切割 (branch cut) 的函式，我們面臨的問題是決定如何定義在切割本身上的這些函式。遵循 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)` | 透過極座標 r 和 phi 回傳複數 z。
冪函數和對數函數
`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)` | 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)` | 檢查 a 和 b 的值是否接近
常數
`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

## 轉換到極座標和從極座標做轉換

Python 複數 `z` 是用 直角坐標 或 笛卡爾坐標 儲存在內部的。它完全是由其 實部 `z.real` 和 虛部 `z.imag` 所決定。

極座標 提供了另一種表示複數的方法。在極座標中，複數 z 由絕對值 (modulus) r 和相位角 (phase) 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

備註

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)

  回傳 z 在極座標中的表達方式。回傳一組數對 `(r, phi)`， r 是 z 的絕對值， phi 是 z 的相位角。 `polar(z)` 相當於 `(abs(z), phase(z))`。

cmath.rect(r, phi)

  透過極座標 r 和 phi 回傳複數 z。相當於 `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`。

  在 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`。

  兩數是否足夠接近取決於給定的絕對及相對容許偏差 (tolerance)。如果沒有錯誤發生，結果將為：`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 is the absolute tolerance; it defaults to `0.0` and it must be nonnegative. When comparing `x` to `0.0`, `isclose(x, 0)` is computed as `abs(x) <= rel_tol * abs(x)`, which is `False` for any `x` and rel_tol less than `1.0`. So add an appropriate positive abs_tol argument to the call.

  定義於 IEEE 754 浮點標準中的特殊值 `NaN`、`inf` 和 `-inf` 會根據該標準處理。更明確地說，`NaN` 不會與包含自身在內的任何數字足夠接近，而 `inf` 及 `-inf` 皆只與自身接近。

  在 3.5 版被加入.

  也參考

  PEP 485 ── 用於測試近似相等的函式

## 常數

cmath.pi

  數學常數 π，作為一個浮點數。

cmath.e

  數學常數 e，作為一個浮點數。

cmath.tau

  數學常數 τ，作為一個浮點數。

  在 3.6 版被加入.

cmath.inf

  正無窮大的浮點數。相當於 `float('inf')`。

  在 3.6 版被加入.

cmath.infj

  實部為零和虛部為正無窮的複數。相當於 `complex(0.0, float('inf'))`。

  在 3.6 版被加入.

cmath.nan

  浮點「非數字」 (NaN) 值。相當於 `float('nan')`。另請參閱 `math.nan`。

  在 3.6 版被加入.

cmath.nanj

  實部為零和虛部為 NaN 的複數。相當於 `complex(0.0, float('nan'))`。

  在 3.6 版被加入.

Note that the selection of functions is similar, but not identical, to that in module `math`. The reason for having two modules is that some users aren't interested in complex numbers, and perhaps don't even know what they are. They would rather have `math.sqrt(-1)` raise an exception than return a complex number. Also note that the functions defined in `cmath` always return a complex number, even if the answer can be expressed as a real number (in which case the complex number has an imaginary part of zero).

關於分枝切割的註釋：它們是沿著給定的不連續函式的曲線。它們是許多複變函數的必要特徵。假設你需要使用複變函數進行計算，你將會了解分枝切割的概念。請參閱幾乎所有關於複變函數的（不是太初級的）書籍以獲得啟發。對於如何正確地基於數值目的選擇分枝切割的相關訊息，以下內容應該是一個很好的參考：

也參考

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.