# `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)` | 带有 y 的符号的 x 的绝对值
`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)` | 具有 start 值的输入 iterable 中元素的积
`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`。

  Added in version 3.8.

math.factorial(n)

  返回非负整数 n 的阶乘。

  在 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.

## 浮点算术

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)

  返回 `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)

  返回 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)` 对于任何非 NaN 的 x 会引发 `ValueError`。如果余数运算的结果为零，则该零将具有与 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 类型相同），在这种情况下，任何满足 `abs(x) >= 2**52` 的浮点数 x 必然没有小数位。

## 浮点操作函数

math.copysign(x, y)

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

math.frexp(x)

  Return the mantissa and exponent of x as the pair `(m, e)`. If x is a finite nonzero number, then m is a float with `0.5 <= abs(m) < 1.0` and an integer e is such that `x == m * 2**e` exactly. Else, return `(x, 0)`. This is used to "pick apart" the internal representation of a float in a portable way.

  注意 `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` 只被认为接近自己。

  Added in version 3.5.

  参见

  PEP 485 —— 用于测试近似相等的函数

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.

## 幂、指数和对数函数

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` 中的减法运算可能导致 明显的精度损失； `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)

  返回 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)))

  Added in version 3.8.

math.fsum(iterable)

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

  该算法的准确性取决于 IEEE-754 算术保证和舍入模式为半偶的典型情况。在某些非 Windows 构建中，底层 C 库使用扩展精度加法，偶尔可能会对中间部分和进行双重舍入，导致其最低有效位产生偏差。

  有关进一步的讨论和两种替代方式，请参阅 ASPN cookbook recipes for accurate floating-point summation。

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(map(operator.mul, 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 弧度的正切值。

## 双曲函数

双曲函数 是基于双曲线而非圆来对三角函数进行的模拟。

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):
          '标准正态分布的累积分布函数'
          return (1.0 + erf(x / sqrt(2.0))) / 2.0

  Added in version 3.2.

math.erfc(x)

  返回 x 处的互补误差函数。 互补误差函数 定义为 `1.0 - erf(x)`。 它用于大的 x 取值，以避免直接用 1 减其误差函数值导致的 有效位数损失。

  Added in version 3.2.

math.gamma(x)

  返回 x 处的 伽马函数 值。

  Added in version 3.2.

math.lgamma(x)

  返回 x 处的 Gamma 函数绝对值的自然对数。

  Added in version 3.2.

## 常量

math.pi

  数学常数 π = 3.141592...，精确到可用精度。

math.e

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

math.tau

  数学常数 τ = 6.283185...，精确到可用精度。Tau 是一个圆周常数，等于 2π，圆的周长与半径之比。更多关于 Tau 的信息可参考 Vi Hart 的视频 圆周率仍然是错误的。吃两倍多的派来庆祝 Tau 日 吧！

  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 标准 要求，`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 math 库函数的简单包装器组成。 特殊情况下的行为遵循 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 视为静默的。

参见

`cmath` 模块

  这里很多函数的复数版本。