math — 數學函式

---

此模組提供對常見數學函式和常量的訪問，包括 C 標準定義的那些。

這些函式不能用於複數；如果需要複數支援，請使用 cmath 模組中同名的函式。區分支援複數和不支援複數的函式是因為大多數使用者不想學習理解複數所需的那麼多數學知識。接收異常而不是複數結果允許更早地檢測到作為引數使用的意外複數，以便程式設計師可以確定它最初是如何以及為何生成的。

此模組提供以下函式。除非另有明確說明，否則所有返回值均為浮點數。

數論函式
comb(n, k)	從 n 個專案中選擇 k 個專案而無需重複且不考慮順序的方法數
factorial(n)	n 的階乘
gcd(*integers)	整數引數的最大公約數
isqrt(n)	非負整數 n 的整數平方根
lcm(*integers)	整數引數的最小公倍數
perm(n, k)	從 n 個專案中選擇 k 個專案而無需重複且考慮順序的方法數
浮點數運算
ceil(x)	x 的上限，即大於或等於 x 的最小整數
fabs(x)	x 的絕對值
floor(x)	x 的下限，即小於或等於 x 的最大整數
fma(x, y, z)	融合乘加運算：(x * y) + z
fmod(x, y)	除法 x / y 的餘數
modf(x)	x 的小數部分和整數部分
remainder(x, y)	x 相對於 y 的餘數
trunc(x)	x 的整數部分
浮點數操作函式
copysign(x, y)	x 的大小（絕對值），帶 y 的符號
frexp(x)	x 的尾數和指數
isclose(a, b, rel_tol, abs_tol)	檢查值 a 和 b 是否彼此接近
isfinite(x)	檢查 x 既不是無窮大也不是 NaN
isinf(x)	檢查 x 是否為正無窮大或負無窮大
isnan(x)	檢查 x 是否為 NaN（非數字）
ldexp(x, i)	x * (2**i)，函式 frexp() 的逆運算
nextafter(x, y, steps)	從 x 到 y 經過 steps 步的浮點值
ulp(x)	x 的最低有效位的數值
冪、指數和對數函式
cbrt(x)	x 的立方根
exp(x)	e 的 x 次冪
exp2(x)	2 的 x 次冪
expm1(x)	e 的 x 次冪，減去 1
log(x, base)	x 以給定底數（預設為 e）的對數
log1p(x)	1+x 的自然對數（底數為 e）
log2(x)	x 的以 2 為底的對數
log10(x)	x 的以 10 為底的對數
pow(x, y)	x 的 y 次冪
sqrt(x)	x 的平方根
求和與乘積函式
dist(p, q)	兩個點 p 和 q（作為座標的可迭代物件給出）之間的歐幾里得距離
fsum(iterable)	輸入 iterable 中值的和
hypot(*coordinates)	座標可迭代物件的歐幾里得範數
prod(iterable, start)	輸入 iterable 中元素的乘積，帶有一個 start 值
sumprod(p, q)	兩個可迭代物件 p 和 q 的乘積之和
角度轉換
degrees(x)	將角度 x 從弧度轉換為度數
radians(x)	將角度 x 從度數轉換為弧度
三角函式
acos(x)	x 的反餘弦
asin(x)	x 的反正弦
atan(x)	x 的反正切
atan2(y, x)	atan(y / x)
cos(x)	x 的餘弦
sin(x)	x 的正弦
tan(x)	x 的正切
雙曲函式
acosh(x)	x 的反雙曲餘弦
asinh(x)	x 的反雙曲正弦
atanh(x)	x 的反雙曲正切
cosh(x)	x 的雙曲餘弦
sinh(x)	x 的雙曲正弦
tanh(x)	x 的雙曲正切
特殊函式
erf(x)	x 處的誤差函式
erfc(x)	x 處的互補誤差函式
gamma(x)	x 處的伽馬函式
lgamma(x)	x 處伽馬函式絕對值的自然對數
常量
pi	π = 3.141592…
e	e = 2.718281…
tau	τ = 2π = 6.283185…
inf	正無窮大
nan	“非數字”（NaN）

數論函式

math.comb(n, k)

返回從 n 個專案中選擇 k 個專案而無需重複且不考慮順序的方法數。

當 k <= n 時，計算結果為 n! / (k! * (n - k)!)；當 k > n 時，計算結果為零。

也稱為二項式係數，因為它等同於多項式展開式 (1 + x)ⁿ 中第 k 項的係數。

如果任一引數不是整數，則引發 TypeError。如果任一引數為負數，則引發 ValueError。

在 3.8 版本加入。

math.factorial(n)

返回非負整數 n 的階乘。

版本 3.10 中有改變: 不再接受帶有整數值的浮點數（如 5.0）。

math.gcd(*integers)

返回指定整數引數的最大公約數。如果任何引數不為零，則返回值為所有引數的最大正整數公約數。如果所有引數均為零，則返回值為 0。gcd() 不帶引數時返回 0。

在 3.5 版本加入。

版本 3.9 中有改變: 增加了對任意數量引數的支援。以前只支援兩個引數。

math.isqrt(n)

返回非負整數 n 的整數平方根。這是 n 的精確平方根的下限，或者等價於最大的整數 a 使得 a² ≤ n。

對於某些應用，擁有最小整數 a 使得 n ≤ a² 可能更方便，換句話說，就是 n 的精確平方根的上限。對於正整數 n，可以使用 a = 1 + isqrt(n - 1) 進行計算。

在 3.8 版本加入。

math.lcm(*integers)

返回指定整數引數的最小公倍數。如果所有引數都不為零，則返回值為所有引數的最小正整數倍數。如果任何引數為零，則返回值為 0。lcm() 不帶引數時返回 1。

在 3.9 版本中新增。

math.perm(n, k=None)

返回從 n 個專案中選擇 k 個專案而無需重複且考慮順序的方法數。

當 k <= n 時，計算結果為 n! / (n - k)!；當 k > n 時，計算結果為零。

如果未指定 k 或 k 為 None，則 k 預設為 n，函式返回 n!。

如果任一引數不是整數，則引發 TypeError。如果任一引數為負數，則引發 ValueError。

在 3.8 版本加入。

浮點算術

math.ceil(x)

返回 x 的上限，即大於或等於 x 的最小整數。如果 x 不是浮點數，則委託給 x.__ceil__，它應該返回一個 Integral 值。

math.fabs(x)

返回 x 的絕對值。

math.floor(x)

返回 x 的下限，即小於或等於 x 的最大整數。如果 x 不是浮點數，則委託給 x.__floor__，它應該返回一個 Integral 值。

math.fma(x, y, z)

融合乘加運算。返回 (x * y) + z，計算過程如同具有無限精度和範圍，然後單次舍入到 float 格式。此操作通常比直接表示式 (x * y) + z 提供更好的精度。

此函式遵循 IEEE 754 標準中描述的 fusedMultiplyAdd 操作規範。該標準將一種情況的實現定義為 fma(0, inf, nan) 和 fma(inf, 0, nan) 的結果。在這些情況下，math.fma 返回 NaN，並且不引發任何異常。

在 3.13 版本加入。

math.fmod(x, y)

返回 x / y 的浮點餘數，由平臺 C 庫函式 fmod(x, y) 定義。請注意，Python 表示式 x % y 可能不會返回相同的結果。C 標準的意圖是 fmod(x, y) 嚴格地（數學上；無限精度）等於 x - n*y，其中 n 是一個整數，使得結果與 x 具有相同的符號且大小小於 abs(y)。Python 的 x % y 返回一個與 y 具有相同符號的結果，並且對於浮點引數可能無法精確計算。例如，fmod(-1e-100, 1e100) 是 -1e-100，但 Python 的 -1e-100 % 1e100 的結果是 1e100-1e-100，它無法精確表示為浮點數，並舍入到令人驚訝的 1e100。因此，在使用浮點數時，通常首選函式 fmod()，而使用整數時，首選 Python 的 x % y。

math.modf(x)

返回 x 的小數部分和整數部分。兩個結果都帶有 x 的符號，並且都是浮點數。

請注意，modf() 的呼叫/返回模式與其 C 等效函式不同：它接受一個引數並返回一對值，而不是透過“輸出引數”（Python 中沒有這樣的東西）返回其第二個返回值。

math.remainder(x, y)

返回 x 相對於 y 的 IEEE 754 風格的餘數。對於有限的 x 和有限的非零 y，這是差 x - n*y，其中 n 是最接近商 x / y 精確值的整數。如果 x / y 恰好位於兩個連續整數的中間，則使用最接近的 偶數 整數作為 n。因此，餘數 r = remainder(x, y) 始終滿足 abs(r) <= 0.5 * abs(y)。

特殊情況遵循 IEEE 754 標準：特別是，對於任何有限的 x，remainder(x, math.inf) 是 x；對於任何非 NaN 的 x，remainder(x, 0) 和 remainder(math.inf, x) 會引發 ValueError。如果餘數運算的結果為零，則該零將與 x 具有相同的符號。

在使用 IEEE 754 二進位制浮點數的平臺上，此操作的結果總是可以精確表示的：不會引入舍入誤差。

在 3.7 版本加入。

math.trunc(x)

返回 x 移除小數部分後的整數部分。這會向 0 舍入：trunc() 對於正 x 等價於 floor()，對於負 x 等價於 ceil()。如果 x 不是浮點數，則委託給 x.__trunc__，它應該返回一個 Integral 值。

對於 ceil()、floor() 和 modf() 函式，請注意，足夠大的所有浮點數都是精確整數。Python 浮點數通常不超過 53 位精度（與平臺 C 雙精度型別相同），在這種情況下，任何 abs(x) >= 2**52 的浮點數 x 必然沒有小數位。

浮點操作函式

math.copysign(x, y)

返回一個浮點數，其大小（絕對值）與 x 相同，但符號與 y 相同。在支援帶符號零的平臺上，copysign(1.0, -0.0) 返回 -1.0。

math.frexp(x)

返回 x 的尾數和指數作為對 (m, e)。m 是一個浮點數，e 是一個整數，使得 x == m * 2**e 精確成立。如果 x 為零，則返回 (0.0, 0)，否則 0.5 <= abs(m) < 1。這用於以可移植的方式“分解”浮點數的內部表示。

請注意，frexp() 的呼叫/返回模式與其 C 等效函式不同：它接受一個引數並返回一對值，而不是透過“輸出引數”（Python 中沒有這樣的東西）返回其第二個返回值。

math.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 只被認為與它們自己接近。

在 3.5 版本加入。

參見

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

math.isfinite(x)

如果 x 既不是無窮大也不是 NaN，則返回 True，否則返回 False。（請注意，0.0 被 視為有限。）

在 3.2 版本加入。

math.isinf(x)

如果 x 是正無窮大或負無窮大，則返回 True，否則返回 False。

math.isnan(x)

如果 x 是 NaN（非數字），則返回 True，否則返回 False。

math.ldexp(x, i)

返回 x * (2**i)。這實質上是函式 frexp() 的逆運算。

math.nextafter(x, y, steps=1)

返回浮點值 steps 步後 x 趨向 y。

如果 x 等於 y，則返回 y，除非 steps 為零。

示例：

• math.nextafter(x, math.inf) 向上：趨向正無窮大。

• math.nextafter(x, -math.inf) 向下：趨向負無窮大。

• math.nextafter(x, 0.0) 趨向零。

• math.nextafter(x, math.copysign(math.inf, x)) 遠離零。

另請參閱 math.ulp()。

在 3.9 版本中新增。

版本 3.12 中有改變: 添加了 steps 引數。

math.ulp(x)

返回浮點數 x 的最低有效位的數值。

• 如果 x 是 NaN（非數字），則返回 x。

• 如果 x 為負數，則返回 ulp(-x)。

• 如果 x 是正無窮大，則返回 x。

• 如果 x 等於零，則返回最小的正 非規範化 可表示浮點數（小於最小正 規範化 浮點數，sys.float_info.min）。

• 如果 x 等於最大的正可表示浮點數，則返回 x 的最低有效位的數值，使得小於 x 的第一個浮點數是 x - ulp(x)。

• 否則（x 是一個正有限數），返回 x 的最低有效位的數值，使得大於 x 的第一個浮點數是 x + ulp(x)。

ULP 代表“Unit in the Last Place”（最低有效位單元）。

另請參閱 math.nextafter() 和 sys.float_info.epsilon。

在 3.9 版本中新增。

冪、指數和對數函式

math.cbrt(x)

返回 x 的立方根。

在 3.11 版本中新增。

math.exp(x)

返回 e 的 x 次冪，其中 e = 2.718281… 是自然對數的底數。這通常比 math.e ** x 或 pow(math.e, x) 更精確。

math.exp2(x)

返回 2 的 x 次冪。

在 3.11 版本中新增。

math.expm1(x)

返回 e 的 x 次冪，減去 1。這裡 e 是自然對數的底數。對於小的浮點數 x，exp(x) - 1 中的減法可能導致顯著的精度損失；expm1() 函式提供了一種以全精度計算此量的方法。

>>> from math import exp, expm1
>>> exp(1e-5) - 1  # gives result accurate to 11 places
1.0000050000069649e-05
>>> expm1(1e-5)    # result accurate to full precision
1.0000050000166668e-05

在 3.2 版本加入。

math.log(x[, base])

帶一個引數時，返回 x 的自然對數（以 e 為底）。

帶兩個引數時，返回 x 以給定 base 為底的對數，計算方式為 log(x)/log(base)。

math.log1p(x)

返回 1+x 的自然對數（以 e 為底）。結果的計算方式對於接近零的 x 是精確的。

math.log2(x)

返回 x 的以 2 為底的對數。這通常比 log(x, 2) 更精確。

在 3.3 版本加入。

參見

int.bit_length() 返回表示一個整數所需的位數，不包括符號和前導零。

math.log10(x)

返回 x 的以 10 為底的對數。這通常比 log(x, 10) 更精確。

math.pow(x, y)

返回 x 的 y 次冪。特殊情況儘可能遵循 IEEE 754 標準。特別是，pow(1.0, x) 和 pow(x, 0.0) 始終返回 1.0，即使 x 是零或 NaN。如果 x 和 y 都是有限的，x 為負數，且 y 不是整數，則 pow(x, y) 未定義，並引發 ValueError。

與內建的 ** 運算子不同，math.pow() 將其兩個引數都轉換為 float 型別。對於精確整數冪的計算，請使用 ** 或內建的 pow() 函式。

版本 3.11 中有改變: 特殊情況 pow(0.0, -inf) 和 pow(-0.0, -inf) 已更改為返回 inf 而不是引發 ValueError，以與 IEEE 754 保持一致。

math.sqrt(x)

返回 x 的平方根。

求和與乘積函式

math.dist(p, q)

返回兩個點 p 和 q 之間的歐幾里得距離，每個點都作為座標序列（或可迭代物件）給出。這兩個點必須具有相同的維度。

大致相當於：

sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

在 3.8 版本加入。

math.fsum(iterable)

返回可迭代物件中值的精確浮點和。透過跟蹤多箇中間部分和來避免精度損失。

該演算法的準確性取決於 IEEE-754 算術保證以及舍入模式通常為“四捨五入到最近的偶數”的情況。在某些非 Windows 構建上，底層的 C 庫使用擴充套件精度加法，可能會偶爾對中間和進行二次舍入，導致其最低有效位出現偏差。

有關進一步討論和兩種替代方法，請參閱 ASPN cookbook 中的精確浮點求和食譜。

math.hypot(*coordinates)

返回歐幾里得範數，sqrt(sum(x**2 for x in coordinates))。這是從原點到座標給定點的向量的長度。

對於二維點 (x, y)，這等價於使用勾股定理計算直角三角形的斜邊，sqrt(x*x + y*y)。

版本 3.8 中有改變: 添加了對 n 維點的支援。以前只支援二維情況。

版本 3.10 中有改變: 改進了演算法的精度，使最大誤差小於 1 ulp（最低有效位單元）。更常見的是，結果幾乎總是正確舍入到 1/2 ulp 以內。

math.prod(iterable, *, start=1)

計算輸入 iterable 中所有元素的乘積。乘積的預設 start 值為 1。

當可迭代物件為空時，返回起始值。此函式專門用於數值，並且可能會拒絕非數值型別。

在 3.8 版本加入。

math.sumprod(p, q)

返回兩個可迭代物件 p 和 q 中值的乘積之和。

如果輸入長度不同，則引發 ValueError。

大致相當於：

sum(map(operator.mul, p, q, strict=True))

對於浮點數和混合整數/浮點數輸入，中間乘積和求和以擴充套件精度計算。

3.12 新版功能.

角度轉換

math.degrees(x)

將角度 x 從弧度轉換為度數。

math.radians(x)

將角度 x 從度數轉換為弧度。

三角函式

math.acos(x)

返回 x 的反餘弦，以弧度表示。結果介於 0 和 pi 之間。

math.asin(x)

返回 x 的反正弦，以弧度表示。結果介於 -pi/2 和 pi/2 之間。

math.atan(x)

返回 x 的反正切，以弧度表示。結果介於 -pi/2 和 pi/2 之間。

math.atan2(y, x)

返回 atan(y / x)，以弧度表示。結果介於 -pi 和 pi 之間。平面上從原點到點 (x, y) 的向量與正 X 軸形成此角度。atan2() 的作用是它知道兩個輸入的符號，因此可以計算角度的正確象限。例如，atan(1) 和 atan2(1, 1) 都是 pi/4，但 atan2(-1, -1) 是 -3*pi/4。

math.cos(x)

返回 x 弧度的餘弦。

math.sin(x)

返回 x 弧度的正弦。

math.tan(x)

返回 x 弧度的正切。

雙曲函式

雙曲函式 是基於雙曲線而非圓的三角函式的類似物。

math.acosh(x)

返回 x 的反雙曲餘弦。

math.asinh(x)

返回 x 的反雙曲正弦。

math.atanh(x)

返回 x 的反雙曲正切。

math.cosh(x)

返回 x 的雙曲餘弦。

math.sinh(x)

返回 x 的雙曲正弦。

math.tanh(x)

返回 x 的雙曲正切。

特殊函式

math.erf(x)

返回 x 處的誤差函式。

erf() 函式可用於計算傳統的統計函式，例如累積標準正態分佈

def phi(x):
    'Cumulative distribution function for the standard normal distribution'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0

在 3.2 版本加入。

math.erfc(x)

返回 x 處的互補誤差函式。互補誤差函式 定義為 1.0 - erf(x)。它用於 x 值較大時，此時從 1 中減去會導致精度損失。

在 3.2 版本加入。

math.gamma(x)

返回 x 處的伽馬函式。

在 3.2 版本加入。

math.lgamma(x)

返回 x 處伽馬函式絕對值的自然對數。

在 3.2 版本加入。

常量

math.pi

數學常數 π = 3.141592…，精確到可用精度。

math.e

數學常數 e = 2.718281…，精確到可用精度。

math.tau

數學常數 τ = 6.283185…，精確到可用精度。Tau 是一個圓周常數，等於 2π，是圓周長與其半徑之比。要了解更多關於 Tau 的資訊，請觀看 Vi Hart 的影片 Pi is (still) Wrong，並透過吃兩倍的派來慶祝Tau 日！

在 3.6 版本加入。

math.inf

一個浮點正無窮大。（對於負無窮大，使用 -math.inf。）等同於 float('inf') 的輸出。

在 3.5 版本加入。

math.nan

一個浮點數“不是數字”（NaN）的值。等同於 float('nan') 的輸出。由於 IEEE-754 標準 的要求，math.nan 和 float('nan') 不被認為等於任何其他數值，包括它們自身。要檢查一個數字是否是 NaN，請使用 isnan() 函式來測試 NaN，而不是使用 is 或 ==。示例

>>> import math
>>> math.nan == math.nan
False
>>> float('nan') == float('nan')
False
>>> math.isnan(math.nan)
True
>>> math.isnan(float('nan'))
True

在 3.5 版本加入。

版本 3.11 中有改變: 現在總是可用。

CPython 實現細節：math 模組主要由平臺 C 數學庫函式的薄包裝組成。在異常情況下的行為在適當時遵循 C99 標準的附錄 F。當前的實現將對 sqrt(-1.0) 或 log(0.0) 等無效操作（C99 附錄 F 建議發出無效操作或除以零訊號）引發 ValueError，並對溢位的結果（例如 exp(1000.0)）引發 OverflowError。除非一個或多個輸入引數是 NaN，否則上述任何函式都不會返回 NaN；在這種情況下，大多數函式將返回 NaN，但（再次遵循 C99 附錄 F）此規則也有一些例外，例如 pow(float('nan'), 0.0) 或 hypot(float('nan'), float('inf'))。

請注意，Python 不會努力區分信令 NaN 和靜默 NaN，並且信令 NaN 的行為未指定。典型的行為是將所有 NaN 視為靜默 NaN。

參見

模組 cmath

許多這些函式的複數版本。