cmath --- 複數的數學函式


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

備註

對於涉及分枝切割 (branch cut) 的函式,我們面臨的問題是決定如何定義在切割本身上的這些函式。遵循 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

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

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

極座標 提供了另一種表示複數的方法。在極座標中,複數 z 由絕對值 (modulus) r 和相位角 (phase) phi 定義。絕對值 r 是從 z 到原點的距離,而相位角 phi 是從正 x 軸到連接原點到 z 的線段的逆時針角度(以弧度為單位)。

以下的函式可用於原始直角座標與極座標之間的相互轉換。

cmath.phase(x)

以浮點數的形式回傳 x 的相位角(也稱為 x引數 )。 phase(x) 等價於 math.atan2(x.imag, x.real)。結果將位於 [-π, π] 的範圍內,且此操作的分枝切割將位於負實軸上。結果的符號會與 x.imag 的符號相同,即使 x.imag 為零:

>>> phase(complex(-1.0, 0.0))
3.141592653589793
>>> phase(complex(-1.0, -0.0))
-3.141592653589793

備註

複數 x 的絕對值可以使用內建的 abs() 函式計算。沒有單獨的 cmath 模組函式適用於此操作。

cmath.polar(x)

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

cmath.rect(r, phi)

透過極座標 rphi 回傳複數 x。相當於 complex(r * math.cos(phi), r * math.sin(phi))

冪函數和對數函數

cmath.exp(x)

回傳 ex 次方,其中 e 是自然對數的底數。

cmath.log(x[, base])

回傳 x 給定 base 的對數。如果未指定 base,則傳回 x 的自然對數。存在一條分枝切割,從 0 沿負實數軸到 -∞。

cmath.log10(x)

回傳 x 以 10 為底的對數。它與 log() 具有相同的分枝切割。

cmath.sqrt(x)

回傳 x 的平方根。它與 log() 具有相同的分枝切割。

三角函數

cmath.acos(x)

回傳 x 的反餘弦值。存在兩條分枝切割:一條是從 1 沿著實數軸向右延伸到 ∞。另一條從 -1 沿實數軸向左延伸到 -∞。

cmath.asin(x)

回傳 x 的反正弦值。它與 acos() 具有相同的分枝切割。

cmath.atan(x)

回傳 x 的反正切值。有兩條分枝切割:一條是從 1j 沿著虛軸延伸到 ∞j。另一條從 -1j 沿著虛軸延伸到 -∞j

cmath.cos(x)

回傳 x 的餘弦值。

cmath.sin(x)

回傳 x 的正弦值。

cmath.tan(x)

回傳 x 的正切值。

雙曲函數

cmath.acosh(x)

回傳 x 的反雙曲餘弦值。存在一條分枝切割,從 1 沿實數軸向左延伸到 -∞。

cmath.asinh(x)

回傳 x 的反雙曲正弦值。存在兩條分枝切割:一條是從 1j 沿著虛軸延伸到 ∞j。另一條從 -1j 沿著虛軸延伸到 -∞j

cmath.atanh(x)

回傳 x 的反雙曲正切值。存在兩條分枝切割:一條是從 1 沿著實數軸延伸到 。另一條從 -1 沿著實數軸延伸到 -∞

cmath.cosh(x)

回傳 x 的反雙曲餘弦值。

cmath.sinh(x)

回傳 x 的反雙曲正弦值。

cmath.tanh(x)

回傳 x 的反雙曲正切值。

分類函式

cmath.isfinite(x)

如果 x 的實部和虛部都是有限的,則回傳 True,否則回傳 False

在 3.2 版被加入.

cmath.isinf(x)

如果 x 的實部或虛部是無窮大,則回傳 True,否則回傳 False

cmath.isnan(x)

如果 x 的實部或虛部為 NaN,則回傳 True,否則回傳 False

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

如果 ab 的值相互接近,則回傳 True,否則回傳 False

兩個值是否被認為相互接近是由給定的絕對和相對容許偏差 (tolerance) 所決定的。

rel_tol 是相對容許偏差 -- 它是 ab 之間的最大容許偏差值,相對於 ab 的較大絕對值。例如,要設定 5% 的容許偏差,請傳遞 rel_tol=0.05。預設容許偏差是 1e-09,它確保兩個值在大約 9 位十進制數字內相同。 rel_tol 必須大於零。

abs_tol 是最小絕對容許偏差 -- 對於接近零的比較很有用。 abs_tol 必須至少為零。

如果未發生錯誤,結果將為: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)

IEEE 754 特殊值 NaNinf-inf 將會根據 IEEE 規則進行處理。具體來說, NaN 不被認為接近任何其他值,包括 NaNinf-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')

在 3.6 版被加入.

cmath.nanj

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

在 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.