math —- 数学函数

该模块提供了对C标准定义的数学函数的访问。

这些函数不适用于复数；如果你需要计算复数，请使用 cmath 模块中的同名函数。将支持计算复数的函数区分开的目的，在于大多数用户并不愿意为了理解复数而去学习太多数学知识。得到一个异常而不是一个复数结果能让复数当作参数的情况更早被监测到，进而程序员可以第一时间调查其产生的原因。

该模块提供了以下函数。除非另有明确说明，否则所有返回值均为浮点数。

Number-theoretic functions

• math.comb(n, k)
• 返回不重复且无顺序地从 n 项中选择 k 项的方式总数。

当 k <= n 时取值为 n! / (k! * (n - k)!)；当 k > n 时取值为零。

也称为二项式系数，因为它等价于 (1 + x)ⁿ 的多项式展开中第 k 项的系数。

如果任一参数不为整数则会引发 TypeError。 如果任一参数为负数则会引发 ValueError。

Added in version 3.8.

• math.factorial(n)
• 将 n 的阶乘作为整数返回。 如果 n 不是正数或为负值则会引发 ValueError。

在 3.10 版本发生变更: 具有整数值的浮点数 (如 5.0) 将不再被接受。

• math.gcd(*integers)
• 返回给定的整数参数的最大公约数。 如果有一个参数非零，则返回值将是能同时整除所有参数的最大正整数。 如果所有参数为零，则返回值为 0。 不带参数的 gcd() 返回 0。

Added in version 3.5.

在 3.9 版本发生变更: 添加了对任意数量的参数的支持。 之前的版本只支持两个参数。

• math.isqrt(n)
• 返回非负整数 n 的整数平方根。 这就是对 n 的实际平方根向下取整，或者相当于使得 a² ≤ n 的最大整数 a。

对于某些应用来说，可以更适合取值为使得 n ≤ a² 的最小整数 a ，或者换句话说就是 n 的实际平方根向上取整。 对于正数 n，这可以使用 a = 1 + isqrt(n - 1) 来计算。

Added in version 3.8.

• math.lcm(*integers)
• 返回给定的整数参数的最小公倍数。 如果所有参数均非零，则返回值将是为所有参数的整数倍的最小正整数。 如果参数之一为零，则返回值为 0。 不带参数的 lcm() 返回 1。

Added in version 3.9.

• math.perm(n, k=None)
• 返回不重复且有顺序地从 n 项中选择 k 项的方式总数。

当 k <= n 时取值为 n! / (n - k)!；当 k > n 时取值为零。

如果 k 未指定或为 None，则 k 默认值为 n 并且函数将返回 n!。

如果任一参数不为整数则会引发 TypeError。 如果任一参数为负数则会引发 ValueError。

Added in version 3.8.

Floating point arithmetic

• 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，且不会引发任何异常。

Added in version 3.13.

• math.fmod(x, y)
• Return the floating-point remainder of x / y, as defined by the platform C library function fmod(x, y). Note that the Python expression x % y may not return the same result. The intent of the C standard is that fmod(x, y) be exactly (mathematically; to infinite precision) equal to x - n*y for some integer n such that the result has the same sign as x and magnitude less than abs(y). Python's x % y returns a result with the sign of y instead, and may not be exactly computable for float arguments. For example, fmod(-1e-100, 1e100) is -1e-100, but the result of Python's -1e-100 % 1e100 is 1e100-1e-100, which cannot be represented exactly as a float, and rounds to the surprising 1e100. For this reason, function fmod() is generally preferred when working with floats, while Python's x % y is preferred when working with integers.

• math.modf(x)
• 返回 x 的小数和整数部分。两个结果都带有 x 的符号并且是浮点数。

Note that modf() has a different call/return pattern than its C equivalents: it takes a single argument and return a pair of values, rather than returning its second return value through an 'output parameter' (there is no such thing in Python).

• 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二进制浮点的平台上，此操作的结果始终可以完全表示：不会引入舍入错误。

Added in version 3.7.

• math.trunc(x)
• 返回去除小数部分的 x ，只留下整数部分。 这样就可以四舍五入到0了： trunc() 对于正的 x 相当于 floor() ，对于负的 x 相当于 ceil() 。如果 x 不是浮点数，委托给 x.__trunc__ ，它应该返回一个 Integral 值。

对于 ceil() ， floor() 和 modf() 函数，请注意 所有 足够大的浮点数都是精确整数。Python浮点数通常不超过53位的精度（与平台C double类型相同），在这种情况下，任何浮点 x 与 abs(x) >= 2**52 必然没有小数位。

Floating point manipulation functions

• math.copysign(x, y)
• 返回一个基于 x 的绝对值和 y 的符号的浮点数。在支持带符号零的平台上，copysign(1.0, -0.0) 返回 -1.0.

• math.frexp(x)
• 以 (m, e) 对的形式返回 x 的尾数和指数。 m 是一个浮点数， e 是一个整数，正好是 x == m * 2**e 。 如果 x 为零，则返回 (0.0, 0) ，否则返回 0.5 <= abs(m) < 1 。这用于以可移植方式“分离”浮点数的内部表示。

Note that frexp() has a different call/return pattern than its C equivalents: it takes a single argument and return a pair of values, rather than returning its second return value through an 'output parameter' (there is no such thing in 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 只被认为接近自己。

Added in version 3.5.

参见

PEP 485 [https://peps.python.org/pep-0485/] —— 用于测试近似相等的函数

• math.isfinite(x)
• 如果 x 既不是无穷大也不是NaN，则返回 True ，否则返回 False 。 （注意 0.0 被认为 是 有限的。）

Added in version 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)
• 返回从 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()。

Added in version 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。

Added in version 3.9.

Power, exponential and logarithmic functions

• math.cbrt(x)
• 返回 x 的立方根。

Added in version 3.11.

• math.exp(x)
• 返回 e 的 x 次幂，其中 e = 2.718281… 是自然对数的基数。这通常比 math.e ** x 或 pow(math.e, x) 更精确。

• math.exp2(x)
• 返回 2 的 x 次幂。

Added in version 3.11.

• math.expm1(x)
• 返回 e 的 x 次方减 1。 这里 e 是自然对数的底。 对于小浮点数 x，在 exp(x) - 1 中的减法运算可能导致 明显的精度损失 [https://en.wikipedia.org/wiki/Loss_of_significance]； 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

Added in version 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) 更准确。

Added in version 3.3.

参见

int.bit_length() 返回表示二进制整数所需的位数，不包括符号和前导零。

• math.log10(x)
• 返回 x 底为10的对数。这通常比 log(x, 10) 更准确。

• math.pow(x, y)
• Return x raised to the power y. Exceptional cases follow the IEEE 754 standard as far as possible. In particular, pow(1.0, x) and pow(x, 0.0) always return 1.0, even when x is a zero or a NaN. If both x and y are finite, x is negative, and y is not an integer then pow(x, y) is undefined, and raises ValueError.

与内置的 ** 运算符不同， math.pow() 将其参数转换为 float 类型。使用 ** 或内置的 pow() 函数来计算精确的整数幂。

在 3.11 版本发生变更: 特殊情况 pow(0.0, -inf) 和 pow(-0.0, -inf) 已改为返回 inf 而不是引发 ValueError，以便同 IEEE 754 保持一致。

• math.sqrt(x)
• 返回 x 的平方根。

Summation and product functions

• math.dist(p, q)
• 返回 p 与 q 两点之间的欧几里得距离，以一个坐标序列（或可迭代对象）的形式给出。 两个点必须具有相同的维度。

大致相当于：

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

Added in version 3.8.

• math.fsum(iterable)
• 返回可迭代对象中的值的精确浮点总计值。 通过跟踪多个中间部分和来避免精度损失。

该算法的准确性取决于IEEE-754算术保证和舍入模式为半偶的典型情况。在某些非Windows版本中，底层C库使用扩展精度添加，并且有时可能会使中间和加倍，导致它在最低有效位中关闭。

有关进一步的讨论和两种替代方式，请参阅 ASPN cookbook recipes for accurate floating-point summation [https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/]。

• 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。

当可迭代对象为空时，返回起始值。 此函数特别针对数字值使用，并会拒绝非数字类型。

Added in version 3.8.

• math.sumprod(p, q)
• 两个可迭代对象 p 和 q 中的值的乘积的总计值。

如果输入值的长度不相等则会引发 ValueError。

大致相当于：

sum(itertools.starmap(operator.mul, zip(p, q, strict=True)))

对于浮点数或混合整数/浮点数的输入，中间的乘积和总计值将使用扩展精度来计算。

Added in version 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 弧度的正切值。

双曲函数

双曲函数 [https://en.wikipedia.org/wiki/Hyperbolic_functions] 是基于双曲线而非圆来对三解函数进行的模拟。

• 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 处的 误差函数 [https://en.wikipedia.org/wiki/Error_function] 。

可以使用 erf() 函数来计算传统的统计函数如 累积标准正态分布 [https://en.wikipedia.org/wiki/Cumulative_distribution_function]:

def phi(x):
    '标准正态分布的累积分布函数'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0

Added in version 3.2.

• math.erfc(x)
• 返回 x 处的互补误差函数。 互补误差函数 [https://en.wikipedia.org/wiki/Error_function] 定义为 1.0 - erf(x)。 它用于大的 x 取值，以避免直接用 1 减其误差函数值导致的 有效位数损失 [https://en.wikipedia.org/wiki/Loss_of_significance]。

Added in version 3.2.

• math.gamma(x)
• 返回 x 处的 伽马函数 [https://en.wikipedia.org/wiki/Gamma_function] 值。

Added in version 3.2.

• math.lgamma(x)
• 返回Gamma函数在 x 绝对值的自然对数。

Added in version 3.2.

常量

• math.pi
• 数学常数 π = 3.141592…，精确到可用精度。

• math.e
• 数学常数 e = 2.718281…，精确到可用精度。

• math.tau
• 数学常数 τ = 6.283185…，精确到可用精度。Tau 是一个圆周常数，等于 2π，圆的周长与半径之比。更多关于 Tau 的信息可参考 Vi Hart 的视频 Pi is (still) Wrong [https://www.youtube.com/watch?v=jG7vhMMXagQ]。吃两倍多的派来庆祝 Tau 日 [https://tauday.com/] 吧！

Added in version 3.6.

• math.inf
• 浮点正无穷大。 （对于负无穷大，使用 -math.inf 。）相当于 float('inf') 的输出。

Added in version 3.5.

• math.nan
• 一个浮点数值 "Not a Number" (NaN)。 相当于 float('nan') 的输出。 根据 IEEE-754 标准 [https://en.wikipedia.org/wiki/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

Added in version 3.5.

在 3.11 版本发生变更: 该常量现在总是可用。

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 模块
• 这里很多函数的复数版本。