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.