math --- 數學函數

---

該模塊提供了對C標準定義的數學函數的訪問。

這些函數不適用于復數；如果你需要計算復數，請使用 cmath 模塊中的同名函數。將支持計算復數的函數區分開的目的，來自于大多數開發者并不愿意像數學家一樣需要學習復數的概念。得到一個異常而不是一個復數結果使得開發者能夠更早地監測到傳遞給這些函數的參數中包含復數，進而調查其產生的原因。

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

數論與表示函數

math.ceil(x)

返回 x 的上限，即大于或者等于 x 的最小整數。如果 x 不是一個浮點數，則委托 x.__ceil__(), 返回一個 Integral 類的值。

math.copysign(x, y)

返回一個基于 x 的絕對值和 y 的符號的浮點數。在支持帶符號零的平臺上，copysign(1.0, -0.0) 返回 -1.0.

math.fabs(x)

返回 x 的絕對值。

math.factorial(x)

以一個整數返回 x 的階乘。 如果 x 不是整數或為負數時則將引發 ValueError。

math.floor(x)

返回 x 的向下取整，小于或等于 x 的最大整數。如果 x 不是浮點數，則委托 x.__floor__() ，它應返回 Integral 值。

math.fmod(x, y)

返回 fmod(x, y) ，由平臺C庫定義。請注意，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.frexp(x)

以 (m, e) 對的形式返回 x 的尾數和指數。 m 是一個浮點數， e 是一個整數，正好是 x == m * 2**e 。 如果 x 為零，則返回 (0.0, 0) ，否則返回 0.5 <= abs(m) < 1 。這用于以可移植方式“分離”浮點數的內部表示。

math.fsum(iterable)

返回迭代中的精確浮點值。通過跟蹤多個中間部分和來避免精度損失:

>>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
0.9999999999999999
>>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
1.0

該算法的準確性取決于IEEE-754算術保證和舍入模式為半偶的典型情況。在某些非Windows版本中，底層C庫使用擴展精度添加，并且有時可能會使中間和加倍，導致它在最低有效位中關閉。

有關待進一步討論和兩種替代方法，參見 ASPN cookbook recipes for accurate floating point summation。

math.gcd(a, b)

返回整數 a 和 b 的最大公約數。如果 a 或 b 之一非零，則 gcd(a, b) 的值是能同時整除 a 和 b 的最大正整數。gcd(0, 0) 返回 0。

3.5 新版功能.

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

若 a 和 b 的值比較接近則返回 True，否則返回 False。

根據給定的絕對和相對容差確定兩個值是否被認為是接近的。

rel_tol 是相對容差 —— 它是 a 和 b 之間允許的最大差值，相對于 a 或 b 的較大絕對值。例如，要設置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特殊值 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.modf(x)

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

math.remainder(x, y)

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

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

在使用IEEE 754二進制浮點的平臺上，此操作的結果始終可以完全表示：不會引入舍入錯誤。

3.7 新版功能.

math.trunc(x)

返回 Real 值 x 截斷為 Integral （通常是整數）。 委托給 x.__trunc__()。

注意 frexp() 和 modf() 具有與它們的C等價函數不同的調用/返回模式：它們采用單個參數并返回一對值，而不是通過 '輸出形參' 返回它們的第二個返回參數（Python中沒有這樣的東西）。

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

冪函數與對數函數

math.exp(x)

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

math.expm1(x)

返回 e 的 x 次冪，減1。這里 e 是自然對數的基數。對于小浮點數 x ， exp(x) - 1 中的減法可能導致 significant loss of precision； 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 次冪。特殊情況盡可能遵循C99標準的附錄'F'。特別是， pow(1.0, x) 和 pow(x, 0.0) 總是返回 1.0 ，即使 x 是零或NaN。 如果 x 和 y 都是有限的， x 是負數， y 不是整數那么 pow(x, y) 是未定義的，并且引發 ValueError 。

與內置的 ** 運算符不同， math.pow() 將其參數轉換為 float 類型。使用 ** 或內置的 pow() 函數來計算精確的整數冪。

math.sqrt(x)

返回 x 的平方根。

三角函數

math.acos(x)

以弧度為單位返回 x 的反余弦值。

math.asin(x)

以弧度為單位返回 x 的反正弦值。

math.atan(x)

以弧度為單位返回 x 的反正切值。

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.hypot(x, y)

返回歐幾里德范數， sqrt(x*x + y*y) 。 這是從原點到點 (x, y) 的向量長度。

math.sin(x)

返回 x 弧度的正弦值。

math.tan(x)

返回 x 弧度的正切值。

角度轉換

math.degrees(x)

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

math.radians(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 處的 error function 。

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 的大值，從其中減去一個會導致 有效位數損失。

3.2 新版功能.

math.gamma(x)

返回 x 處的 伽馬函數 值。

3.2 新版功能.

math.lgamma(x)

返回Gamma函數在 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') 的輸出。

3.5 新版功能.

CPython implementation detail: math 模塊主要包含圍繞平臺C數學庫函數的簡單包裝器。特殊情況下的行為在適當情況下遵循C99標準的附錄F。當前的實現將引發 ValueError 用于無效操作，如 sqrt(-1.0) 或 log(0.0) （其中C99附件F建議發出無效操作信號或被零除）， 和 OverflowError 用于溢出的結果（例如， exp(1000.0) ）。除非一個或多個輸入參數是NaN，否則不會從上述任何函數返回NaN；在這種情況下，大多數函數將返回一個NaN，但是（再次遵循C99附件F）這個規則有一些例外，例如 pow(float('nan'), 0.0) 或 hypot(float('nan'), float('inf')) 。

請注意，Python不會將顯式NaN與靜默NaN區分開來，并且顯式NaN的行為仍未明確。典型的行為是將所有NaN視為靜默的。

參見

cmath 模塊

這里很多函數的復數版本。