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 这些函数的许多复数版本。