"math" --- 数学函数
*******************

======================================================================

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

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

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


数论与表示函数
==============

math.ceil(x)

   返回 *x* 的向上取整，即大于或等于 *x* 的最小的整数。如果 *x* 不是浮
   点数，委托给 "x.__ceil__" ，它应该返回一个 "Integral" 的值。

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

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

math.fabs(x)

   返回 *x* 的绝对值。

math.factorial(n)

   将 *n* 的阶乘作为整数返回。 如果 *n* 不是正数或为负值则会引发
   "ValueError"。

   自 3.9 版本弃用: 接受具有整数值的浮点数 (例如 "5.0") 的行为已被弃用
   。

math.floor(x)

   返回 *x* 的向下取整，小于或等于 *x* 的最大整数。如果 *x* 不是浮点数
   ，则委托给 "x.__floor__" ，它应返回一个 "Integral" 值。

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.frexp(x)

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

math.fsum(iterable)

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

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

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

math.gcd(*integers)

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

   Added in version 3.5.

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

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.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.ldexp(x, i)

   返回 "x * (2**i)" 。 这基本上是函数  "frexp()"  的反函数。

math.modf(x)

   返回 *x* 的小数和整数部分。两个结果都带有 *x* 的符号并且是浮点数。

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.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.prod(iterable, *, start=1)

   计算输入的 *iterable* 中所有元素的积。 积的默认 *start* 值为 "1"。

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

   Added in version 3.8.

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.sumprod(p, q)

   两个可迭代对象 *p* 和 *q* 中的值的乘积的总计值。

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

   大致相当于：

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

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

   Added in version 3.12.

math.trunc(x)

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

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.

注意 "frexp()" 和 "modf()" 具有与它们的C等价函数不同的调用/返回模式：
它们采用单个参数并返回一对值，而不是通过 '输出形参' 返回它们的第二个返
回参数（Python中没有这样的东西）。

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


幂函数与对数函数
================

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.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.dist(p, q)

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

   大致相当于：

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

   Added in version 3.8.

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.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* 处的 误差函数 。

   可以使用 "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)

   返回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。吃两倍多的派来庆祝 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数学库函数的简单包装器。特殊情况下的行为在
适当情况下遵循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" 模块
     这里很多函数的复数版本。
