math — 數學函式¶
此模組提供對 C 標準定義的數學函式的訪問。
這些函式不能與複數一起使用；如果需要支援複數，請使用 cmath 模組中同名的函式。之所以區分支援複數的函式和不支援複數的函式，是因為大多數使用者並不想學習理解複數所需的那麼多數學知識。接收異常而不是複數結果可以及早檢測到用作引數的意外複數，以便程式設計師可以確定它是如何以及為什麼首先生成的。
此模組提供了以下函式。除非另有明確說明，否則所有返回值均為浮點數。
數論函式 |
|
從 n 個專案中選擇 k 個專案的方式數，無需重複且無需順序 |
|
n 的階乘 |
|
整數引數的最大公約數 |
|
非負整數 n 的整數平方根 |
|
整數引數的最小公倍數 |
|
從 n 個專案中選擇 k 個專案的方式數，無需重複但需要順序 |
|
浮點數算術 |
|
x 的上限，即大於或等於 x 的最小整數 |
|
x 的絕對值 |
|
x 的下限，即小於或等於 x 的最大整數 |
|
融合乘加運算： |
|
除法 |
|
x 的小數部分和整數部分 |
|
x 相對於 y 的餘數 |
|
x 的整數部分 |
|
浮點數操作函式 |
|
x 的大小（絕對值）與 y 的符號 |
|
x 的尾數和指數 |
|
檢查值 a 和 b 是否彼此接近 |
|
檢查 x 是否既不是無窮大也不是 NaN |
|
檢查 x 是否是正無窮大或負無窮大 |
|
檢查 x 是否是 NaN（非數字） |
|
|
|
在 x 之後向 y 方向移動 steps 步的浮點數值 |
|
x 的最低有效位的值 |
|
冪、指數和對數函式 |
|
x 的立方根 |
|
e 的 x 次冪 |
|
2 的 x 次冪 |
|
e 的 x 次冪，減 1 |
|
x 以給定底數（預設為 e）的對數 |
|
1+x 的自然對數（底數為 e） |
|
x 的以 2 為底的對數 |
|
x 的以 10 為底的對數 |
|
x 的 y 次冪 |
|
x 的平方根 |
|
求和與乘積函式 |
|
給定為座標的可迭代物件的兩個點 p 和 q 之間的歐幾里得距離 |
|
輸入 iterable 中值的總和 |
|
座標可迭代物件的歐幾里得範數 |
|
輸入 iterable 中元素的乘積，帶有一個 start 值 |
|
來自兩個可迭代物件 p 和 q 的乘積之和 |
|
角度轉換 |
|
將角度 x 從弧度轉換為度 |
|
將角度 x 從度轉換為弧度 |
|
三角函式 |
|
x 的反餘弦 |
|
x 的反正弦 |
|
x 的反正切 |
|
|
|
x 的餘弦 |
|
x 的正弦 |
|
x 的正切 |
|
雙曲函式 |
|
x 的反雙曲餘弦 |
|
x 的反雙曲正弦 |
|
x 的反雙曲正切 |
|
x 的雙曲餘弦 |
|
x 的雙曲正弦 |
|
x 的雙曲正切 |
|
特殊函式 |
|
x 處的誤差函式 |
|
x 處的互補誤差函式 |
|
x 處的伽瑪函式 |
|
x 處的伽瑪函式的絕對值的自然對數 |
|
常量 |
|
π = 3.141592… |
|
e = 2.718281… |
|
τ = 2π = 6.283185… |
|
正無窮大 |
|
“非數字”（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 的階乘。如果 n 不是整數或為負數，則引發
ValueError異常。在 3.10 版本中更改: 不再接受具有整數值的浮點數（例如
5.0）。
- math.gcd(*integers)¶
返回指定整數引數的最大公約數。如果任何引數非零，則返回值為所有引數的約數的最大正整數。如果所有引數均為零，則返回值為
0。不帶引數的gcd()返回0。在 3.5 版本中新增。
在 3.9 版本中更改: 添加了對任意數量引數的支援。以前，只支援兩個引數。
- math.isqrt(n)¶
返回非負整數 n 的整數平方根。這是 n 的精確平方根的向下取整，或者等效地，是滿足 a² ≤ n 的最大整數 a。
對於某些應用，可能需要最小整數 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 或為
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)¶
返回平臺 C 庫定義的
fmod(x, y)。請注意，Python 表示式x % y可能不會返回相同的結果。C 標準的意圖是fmod(x, y)在數學上（具有無限精度）完全等於x - n*y，對於某個整數 n，使得結果與 x 具有相同的符號，並且大小小於abs(y)。Python 的x % y返回一個符號與 y 相同的result，並且可能無法為浮點引數精確計算。例如，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 舍入：對於正數 x，
trunc()等效於floor()，對於負數 x，等效於ceil()。如果 x 不是浮點數，則委託給x.__trunc__，該方法應返回一個Integral值。
對於 ceil()、floor() 和 modf() 函式，請注意，足夠大的幅度的所有浮點數都是精確的整數。Python 浮點數通常不超過 53 位的精度（與平臺 C 的 double 型別相同），在這種情況下，任何滿足 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.nextafter(x, y, steps=1)¶
返回 x 向 y 方向移動 steps 步之後的浮點數值。
如果 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 為底）。
使用兩個引數，返回以給定 base 為底的 x 的對數，計算方式為
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 食譜中關於精確浮點求和的內容。
- 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(itertools.starmap(operator.mul, zip(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.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 day，吃雙倍的派！
在 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)）會引發 ValueError （C99 附件 F 建議標記無效操作或除以零），並且對於溢位的結果（例如，exp(1000.0)）會引發 OverflowError。除非一個或多個輸入引數是 NaN，否則上述任何函式都不會返回 NaN；在這種情況下，大多數函式將返回 NaN，但（再次遵循 C99 附件 F）此規則有一些例外，例如 pow(float('nan'), 0.0) 或 hypot(float('nan'), float('inf'))。
請注意，Python 不會嘗試區分 signaling NaN 和 quiet NaN，並且 signaling NaN 的行為仍然未指定。典型的行為是將所有 NaN 都視為 quiet NaN。
另請參閱
- 模組
cmath 這些函式的許多複數版本。