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(z)

Return the phase of z (also known as the argument of z), as a float. phase(z) is equivalent to math.atan2(z.imag, z.real). The result lies in the range [-π, π], and the branch cut for this operation lies along the negative real axis. The sign of the result is the same as the sign of z.imag, even when z.imag is zero:

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

Return the representation of z in polar coordinates. Returns a pair (r, phi) where r is the modulus of z and phi is the phase of z. polar(z) is equivalent to (abs(z), phase(z)).

cmath.rect(r, phi)

Return the complex number z with polar coordinates r and phi. Equivalent to complex(r * math.cos(phi), r * math.sin(phi)).

冪函數和對數函數

cmath.exp(z)

Return e raised to the power z, where e is the base of natural logarithms.

cmath.log(z[, base])

Return the logarithm of z to the given base. If the base is not specified, returns the natural logarithm of z. There is one branch cut, from 0 along the negative real axis to -∞.

cmath.log10(z)

Return the base-10 logarithm of z. This has the same branch cut as log().

cmath.sqrt(z)

Return the square root of z. This has the same branch cut as log().

三角函數

cmath.acos(z)

Return the arc cosine of z. There are two branch cuts: One extends right from 1 along the real axis to ∞. The other extends left from -1 along the real axis to -∞.

cmath.asin(z)

Return the arc sine of z. This has the same branch cuts as acos().

cmath.atan(z)

Return the arc tangent of z. There are two branch cuts: One extends from 1j along the imaginary axis to ∞j. The other extends from -1j along the imaginary axis to -∞j.

cmath.cos(z)

Return the cosine of z.

cmath.sin(z)

Return the sine of z.

cmath.tan(z)

Return the tangent of z.

雙曲函數

cmath.acosh(z)

Return the inverse hyperbolic cosine of z. There is one branch cut, extending left from 1 along the real axis to -∞.

cmath.asinh(z)

Return the inverse hyperbolic sine of z. There are two branch cuts: One extends from 1j along the imaginary axis to ∞j. The other extends from -1j along the imaginary axis to -∞j.

cmath.atanh(z)

Return the inverse hyperbolic tangent of z. There are two branch cuts: One extends from 1 along the real axis to ∞. The other extends from -1 along the real axis to -∞.

cmath.cosh(z)

Return the hyperbolic cosine of z.

cmath.sinh(z)

Return the hyperbolic sine of z.

cmath.tanh(z)

Return the hyperbolic tangent of z.

分類函式

cmath.isfinite(z)

Return True if both the real and imaginary parts of z are finite, and False otherwise.

在 3.2 版被加入.

cmath.isinf(z)

Return True if either the real or the imaginary part of z is an infinity, and False otherwise.

cmath.isnan(z)

Return True if either the real or the imaginary part of z is a NaN, and False otherwise.

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')。

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