Python 基础 (标准库)：math (数学函数)

1. 官方文档

math --- 数学函数 — Python 3.12.2 文档

cmath --- 关于复数的数学函数 — Python 3.12.2 文档

Python 中，可以使用内置的数学运算符，例如加法 (+)、减法 (-)、除法 (/) 和乘法 (*) 进行简单的数学运算。不过，更高级的运算，如指数函数、对数函数、三角函数或幂函数，并没有内置函数，需要使用 Python 标准库中一个专门为高级数学运算设计的模块：math 模块。

 2. 常量

名称	描述
Pi	圆周率 π 是圆的周长 (c) 与直径 (d) 之比，无理数。 math.pi 返回一个保留到小数点后 15 位的浮点数。
Tau	圆的周长与半径之比（Tau=2π），无理数。 math.tau 返回一个保留到小数点后 15 位的浮点数。 许多数学表达式使用 2π，因而使用 tau 可以简化方程。例如，不用 2πr 来计算圆的周长，用更简单的方程 τr。可以根据需要自由地使用 2π 或 τ。
Euler’s number	欧拉常数 (e) 是自然对数的底，无理数，约等于2.71828。 math.e 返回一个保留到小数点后 15 位的浮点数。 欧拉常数是一个重要常数，有许多实际用途，如计算人口随时间的增长率或放射性衰变率。
Infinity	无穷是一个数学概念，表示无限，分为正无穷大和负无穷大。 math.inf  等价于 float("inf")
Not a number (NaN)	NaN 不是一个数学概念，它起源于计算机科学领域，作为对非数字值的引用。NaN 值可能是由无效的输入产生的，或表示应该是数字的变量已被文本字符或符号损坏。 math.nan 等价于 float("nan") 请使用 math.isnan() 函数来检查一个数字是否为 NaN，而不能使用 is 或 ==。

 代码说明：

math.pi
# 3.141592653589793
math.tau
# 6.283185307179586
math.e
# 6.283185307179586
math.inf
# inf
math.nan
# nan

math.pi * 2 == math.tau
# True

float('inf') == math.inf
# True
math.inf == math.inf
# True
math.inf == -math.inf
# False


float('nan') == math.nan
# False
math.isnan(math.nan)
# True
math.isnan(float('nan'))
# True

3. 数论与表示函数

3.1 函数概览

math.factorial(n)	返回 n 的阶乘。 如果 n 不是正数或不是整数会引发 ValueError。 自 3.9 版本，接受具有整数值的浮点数 (例如 5.0) 的行为被弃用。
math.comb(n, k) 在 3.8 版本加入.	组合数，返回不重复且无顺序地从 n 项中选择 k 项的方式总数。 具体来说： 当 k <= n 时取值为 n! / (k! * (n - k)!)； 当 k > n 时取值为零。 也叫二项式系数，它也是 (1 + x)ⁿ 的多项式展开中第 k 项的系数。 如果任一参数不为整数则会引发 TypeError。 如果任一参数为负数则会引发 ValueError。
math.perm(n, k=None) 在 3.8 版本加入.	排列数，返回不重复且有顺序地从 n 项中选择 k 项的方式总数。 具体来说： 当 k <= n 时取值为 n! / (n - k)!； 当 k > n 时取值为零。 如果 k 未指定或为 None，则 k 默认值为 n 并且函数将返回 n!。 如果任一参数不为整数则会引发 TypeError。 如果任一参数为负数则会引发 ValueError。
math.ceil(x)	返回 x 的向上取整，即大于或等于 x 的最小的整数。 输入整数值时，返回相同的数字；输入非数值内容（如字符串）引发 TypeError。
math.floor(x)	返回 x 的向下取整，小于或等于 x 的最大整数。 输入整数值时，返回相同的数字；输入非数值内容（如字符串）引发 TypeError。
math.trunc(x)	返回去除小数部分的 x ，只留下整数部分。  trunc() 对于正的 x 相当于 floor() ，对于负的 x 相当于 ceil() ，向 0 取近似（rounded downward toward zero）。
math.modf(x)	返回 x 的小数和整数部分。 两个结果都带有 x 的符号并且是浮点数。
math.isinf(x)	如果 x 是正或负无穷大，则返回 True ，否则返回 False。
math.isnan(x)	如果 x 是 NaN，则返回 True ，否则返回 False。
math.isfinite(x)	如果 x 既不是无穷大也不是 NaN，返回 True，否则返回 False。
math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)	根据给定的绝对差值和相对差值，确定两个值是否可视为是接近的，若 a、b 的值比较接近返回 True，否则返回 False。 Relative tolerance (rel_tol): 百分数表示的相对于输入数据的量级的最大差值（也称差值容忍度或阈值，小于对应值时才能才认为两数接近） 例如，想要设置 5％ 的容差，需传递 rel_tol=0.05。 默认值是 1e-09=0.000000001，两数至少小数点后9位都一致。 Absolute tolerance (abs_tol): 绝对值形式的最大差值，不考虑输入数据的量级。默认值是 0。   判定规则可以概括为：  abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol) 。 对于特殊值： NaN 不接近任何其他值，包括 NaN；inf 和 -inf 只与自己接近。
math.fabs(x)	返回 x 的绝对值。 math.fabs 与 内置函数 abs 的区别： math.fabs 只能接收一个参数，即一个浮点数，返回该浮点数的绝对值，结果始终为浮点数。 abs 是 Python 内置函数，它可以接收一个参数，可以是整数、浮点数、复数等，返回该数的绝对值，结果的类型与参数的类型相同。
math.copysign(x, y)	返回一个基于 x 的绝对值和 y 的符号的浮点数。 copysign(1.0, -2) 返回值为 -1.0。
math.lcm(*integers)	返回给定整数参数的最小公倍数（lowest common multiple）。 如果所有参数均非零，返回所有参数的整数倍的最小正整数。 如果参数之一为零，则返回值为 0。 不带参数的 lcm() 返回 1。
math.gcd(*integers)	返回给定整数参数的最大公约数（greatest common divisor）。 如果有一个参数非零，返回能同时整除所有参数的最大正整数。 如果所有参数为零，则返回值为 0。 不带参数的 gcd() 返回 0。
math.fmod(x, y)	计算 x 除以 y 的余数（floating-point modulus 浮点数模）。 fmod(x, y) 等于 x - n*y ，其中，整数 n 使得结果与 x 符号相同且小于 abs(y) 。 math.fmod 与 % 运算符的区别： （1）前者始终返回浮点数；后者在x、y均为整型时，返回整型，其他情况下，即 x、y 任一为浮点型时，结果均返回浮点型。 （2）前者返回结果的符号（正负）始终与 x 相同；后者所得结果的符号（正负）始终与 y 相同。 （3）前者返回结果的绝对值始终等于“|x| % |y|”；后者若x与y符号相同，结果的绝对值为“|x| % |y|”，若x与y的符号不同，结果的绝对值为“|y| - (|x| % |y|)”。 注：当采用 % 运算符求模，且x与y的符号不同时，若同时还符合下面两个条件： <1> |x|远小于|y|； <2> x与y中至少有一个是浮点数（浮点数会导致精度损失）。 此时，|x| % |y| 的值相对较小（等于 |x|），|y| 又非常大，加上计算机对浮点数计算精度的损失，会出现 |y| - (|x| % |y|) 的结果被近似成 |y| 的奇怪现象。因此： 有浮点数首选 math.fmod()，整数首选 % 运算符。
math.isqrt(n)	返回非负整数 n 的整数平方根，即 n 的实际平方根向下取整的结果，相当于使得 a² <= n 的最大整数 a。 如果想获取使得 a² >= n² 的最小整数 a ，即 n 的实际平方根向上取整的值，可以使用 a = 1 + isqrt(n - 1) 。
math.ldexp(x, i)	返回 x * (2**i) ，函数 math.frexp 的反函数。
math.frexp(x)	返回(m, e) 满足x == m * 2**e，其中 m 是浮点数， e 是整数。 如果 x 为零，则返回 (0.0, 0) ，否则返回 0.5 <= abs(m) < 1 。
math.fsum(iterable)	返回可迭代对象中的值的精确浮点总计值。
math.prod(iterable, *, start=1)	计算输入的 iterable 中所有元素的积，默认乘积的start 值为 1。 当可迭代对象为空时，返回起始值。 此函数特别针对数字值使用，并会拒绝非数字类型。
math.sumprod(p, q) 在 3.12 版本加入.	两个可迭代对象 p 和 q 中的值的乘积的总计值。 如果输入值的长度不相等则会引发 ValueError。 大致相当于： sum(itertools.starmap(operator.mul, zip(p, q, strict=True))) 对于浮点数或混合整数/浮点数的输入，中间的乘积和总计值将使用扩展精度来计算。

3.2 细节

（1）math.factorial(n)

import timeit
import math

# 阶乘的三种实现方式

# 1. for循环
def fact_loop(num):
    if num < 0:
        return 0
    if num == 0:
        return 1

    factorial = 1
    for i in range(1, num+1):
        factorial = factorial * i

    return factorial

print(fact_loop(15))
# 1307674368000

# 2. 递归函数
def fact_recursion(num):
    if num < 0:
        return 0
    if num == 0:
        return 1

    return num * fact_recursion(num - 1)

print(fact_recursion(15))
# 1307674368000

# 3. math.factorial
print(math.factorial(15))
# 1307674368000

timeit.timeit("fact_loop(15)", globals=globals())        # 0.8621199000044726
timeit.timeit("fact_recursion(15)", globals=globals())   # 2.6800807999970857
timeit.timeit("math.factorial(15)", setup="import math") # 0.17294190000393428

从执行时间来看，递归方法是三种方法中最慢的，factorial() 明显比其他方法更快，这得益于它的底层用 C 实现。不同CPU可能得到不同的计时结果，但耗时大小的顺序应该是一样的。

factorial() 不仅比其他方法快，而且更稳定。自己手写函数时，需要显式地为异常情况编写代码，例如处理负数或小数。但当使用 factorial() 时，因为函数会处理所有异常情况，建议尽可能使用 factorial()。

（2）math.ceil(x)、math.floor(x)、math.trunc(x)、math.modf(x)

math.ceil(4.896)
# 5
math.ceil(-7.956)
# -7
math.ceil(4)
# 4
math.ceil(-7)
# -7

math.floor(4.896)
# 4
math.floor(-7.956)
# -8
math.floor(4)
# 4
math.floor(-7)
# -7

math.trunc(4.9)
# 4
math.trunc(-11.7)
# -11
math.trunc(4)
# 4

import math

math.modf(-4.123)
# (-0.12300000000000022, -4.0)

（3）math.isclose()

import math

math.isclose(6, 7)
# False
math.isclose(6.999999999, 7)
# True
math.isclose(6.999999992, 7)
# False
math.isclose(6.9999999963, 7)
# True

math.isclose(6, 7, rel_tol=0.2)
# True
math.isclose(5.6, 7, rel_tol=0.2)
# False
math.isclose(5.61, 7, rel_tol=0.2)
# True

math.isclose(6, 7, abs_tol=1.0)
# True
math.isclose(6, 7, abs_tol=0.2)
# False


math.isclose(1, 1+1e-08, abs_tol=1e-08)
# True
math.isclose(1, 1-1e-08, rel_tol=1e-08)
# False
math.isclose(1, 1-1e-08+1e-09, rel_tol=1e-08)
# True

特殊情况：

import math

math.isclose(math.nan, 1e308)
# False

math.isclose(math.nan, math.nan)
# False

math.isclose(math.inf, 1e308)
# False

math.isclose(math.inf, math.inf)
# True

（4）math.fabs(x)

import math

abs(-1.234)
abs(1)
abs(3+4j)


math.fabs(-1.234)
math.fabs(1)
math.fabs(3+4j)

在 Python 中，复数可以使用 `j` 或 `J` 表示虚部。例如，3 + 4j 表示实部为 3，虚部为 4 的复数。Python 还提供了一个内置函数 complex 用于创建复数：complex(3, 4) 返回值等同于 3 + 4j。

可以使用 type() 函数来检查一个变量是否为复数类型，例如， type(3+4j) 返回结果为：complex。复数的绝对值是一个数的大小，不考虑其正负（绝对值是一个数的物理意义上的‘长度’或‘大小’，不受正负影响）。对于一个复数，比如 a+bi,它的绝对值是|a+bi|=sqrt(a^2+b^2)。

（5）math.lcm(x)、math.gcd(x)

import math

math.lcm(2,3,6)
# 6
math.gcd(15,2)
# 1 
math.gcd(15,3)
# 3

（6）math.fsum(iterable)、math.prod(iterable, start=1)

list1 = [1.0, 2.0 , 3.3, 4.5]
list2 = [2, 2, 2, 2]
math.fsum(list1)
# 29.7
math.prod(list1, start=1)
# 29.7
math.prod(list1, start=2)
# 59.4

（7）math.isqrt(x)、math.frexp(x)、math.ldexp(x, i)

import math

math.frexp(5)
# (0.625, 3)

math.ldexp(0.625, 3)
# 5.0

math.isqrt(7)
# 2
math.isqrt(9)
# 3

math.frexp(x) 的应用场景包括：

将一个浮点数转换为二进制表示时，可以使用 math.frexp() 将其分解为尾数和指数的形式，方便进行计算和存储。

在科学计算、信号处理等领域中，经常需要对浮点数进行归一化处理，即将其表示为尾数乘以某个基数的指数形式。此时可以使用 math.frexp() 将浮点数分解为尾数和指数，然后将尾数除以基数，指数加上相应的偏移量，得到归一化后的结果。 

在一些算法中，需要对浮点数进行比较和排序。由于浮点数的精度有限，直接比较可能会出现误差。此时可以使用 math.frexp() 将浮点数分解为尾数和指数，然后按照指数大小进行比较和排序，可以避免精度误差的影响。

（8）math.fmod(x,y)

import math

x, y = -9, 4

x % y
# 3
math.fmod(x, y)
# -1.0
math.remainder(x, y)
# -1.0

下面这个例子中，使用 % 时得到了奇怪的结果，此时更适合用 math.fmod()。

import math

math.fmod(-2, 10)      # 返回值：-2.0
-2 % 10                # 返回值：8
math.fmod(10, 1e+10)   # 返回值：10.0
10 % 1e+10             # 返回值：10.0
math.fmod(-10, 1e+10)  # 返回值：-10.0
-10 % 1e+10            # 返回值：9999999990.0


# 一个使用 % 得到的结果很奇怪的例子
-1e-100 % 1e+100            # 返回值：1e+100
# 事实上，返回的结果应该是是1e100-1e-100, 但这个值无法表示成一个浮点数, 近似的表示成了1e100
# 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.
math.fmod(-1e-100, 1e+100)  # 返回值：-1e-100
# 使用math.fomd得到的结果显然更为合理。

（9）其他

import math

math.comb(4, 3)
# 4
math.perm(4, 3)
# 24

math.copysign(-2.3, 4.5)
# 2.3
math.copysign(2.3, -4.5)
# -2.3
math.copysign(-2.3, 0)
# 2.3
math.copysign(-2.3, -0)
# 2.3

4. 幂函数

函数	描述
math.pow(x, y)	返回 x 的 y 次幂。  pow(1.0, x) 和 pow(x, 0.0) 总是返回 1.0，即使 x 为零或 NaN。 如果 x 和 y 均为有限值，x 为负数，而 y 不是整数则 pow(x, y) 是未定义的，将引发 ValueError。
math.exp(x)	返回 e 的 x 次幂，其中 e = 2.718281... 是自然对数的基数。 math.exp 通常比 math.e ** x 或 pow(math.e, x) 更精确。
math.exp2(x) 在 3.11 版本加入.	返回 2 的 x 次幂。
math.cbrt(x) 在 3.11 版本加入.	返回 x 的立方根。
math.sqrt(x)	返回 x 的平方根。
math.expm1(x)	返回 e 的 x 次幂减1。对于值较小的浮点数 x，e 的 x 次幂减1中的减法运算可能导致明显的精度损失，expm1 函数提供了更高的计算精度。

细节

（1）math.pow(x,y)

Python 中，除了math.pow，还有两种方法计算幂：内置函数 pow(x, y[,z]) 和 x ** y。

内置函数 pow 可接收三个参数：The base number，The power number，The modulus number

最后一个参数是可选的，如果传递了第三个参数 z，返回结果将是：(x ** y) % z，

下面的代码显示了三种函数的使用效果以及耗时情况（math.pow 底层基于C实现，因而最快）。

import math


math.pow(1, math.nan)  # 1.0
math.pow(1, math.inf)  # 1.0
math.pow(1, 0)         # 1.0

math.pow(math.nan, 0)  # 1.0
math.pow(math.inf, 0)  # 1.0
math.pow(1, 0)         # 1.0

# math.pow(0, -1)      # ValueError: math domain error
math.pow(0, math.nan)  # nan
math.pow(0, math.inf)  # 0.0
math.pow(0, 0)         # 1.0

import math
import timeit

# 内置函数 pow(x, y[,z])
pow(2, 3)        # 8
pow(2, 3, 3)     # 2
pow(-2, 3)       # 8
pow(-2, 3, 3)    # 1
(-2 ** 3) % 3    # 1

# x ** y
2 ** 3           # 8

# 比较三种函数耗时
timeit.timeit("9 ** 293")                                 
timeit.timeit("pow(9, 293)")
timeit.timeit("math.pow(9, 293)", setup="import math")
# 返回结果：
# 0.7688344000000029
# 0.8183434000000034
# 0.20894989999999325

（2）math.exp(x)

import math

# 对比 math.exp(x) 与 math.pow(math.e, x)
a = math.pow(math.e, 3.5)
b = math.exp(3.5)

timeit.timeit("math.pow(math.e, 3.5)", setup="import math")
timeit.timeit("math.exp(3.5)", setup="import math")
# 返回结果
# math.exp 底层用C实现，更快
# 0.15435010000010152
# 0.10402529999987564

print('{:.30f}'.format(a))
# 33.115451958692304401665751356632
print('{:.30f}'.format(b))
# 33.115451958692311507093108957633

math.log(a)  # 3.4999999999999996
math.log(b)  # 3.5

（3）math.sqrt(x)

import math

math.sqrt(1024)
# 32.0

5. 对数函数

函数	描述
math.log(x[, base])	使用一个参数，返回 x 的自然对数（底为 e ）。 使用两个参数，返回给定的 base 的对数 x ，计算为 log(x)/log(base) 。
math.log2(x)	返回 x 以2为底的对数。这通常比 log(x, 2) 更准确。
math.log10(x)	返回 x 底为10的对数。这通常比 log(x, 10) 更准确。
math.log1p(x)	返回 1+x 的自然对数（以 e 为底）。 以对于 x 接近零时，建议使用 math.log1p。

6. 其他重要的数学函数

三角函数

函数	描述
math.sin(x)	返回 x 弧度的正弦值。
math.cos(x)	返回 x 弧度的余弦值。
math.tan(x)	返回 x 弧度的正切值。
math.asin(x)	返回以弧度为单位的 x 的反正弦值。 结果范围： -pi/2 到 pi/2 之间。
math.acos(x)	返回以弧度为单位的 x 的反余弦值。 结果范围： 0 到 pi 之间。
math.atan(x)	返回以弧度为单位的 x 的反正切值。 结果范围： -pi/2 到 pi/2 之间。.
math.atan2(y, x)	以弧度为单位返回 atan(y/x) ，结果范围： -pi 和 pi 。 atan2() 的两个输入的符号都是已知的，因此可以正确地计算象限， 例如， atan(1) 和 atan2(1,1) 都是 pi/4 ，但 atan2(-1, -1) 是 -3*pi/4 。
math.dist(p, q)	返回 p 与 q 两点之间的欧几里得距离，两个点必须具有相同的维度。 大致相当于：sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
math.hypot(*coordinates)	返回欧几里得范数。 相当于：sqrt(sum(x**2 for x in coordinates)) 对于一个二维点 (x, y)，等价于 sqrt(x*x + y*y) 。

细节

（1）math.atan2(y, x)

import math

math.atan(1)        # 0.7853981633974483
math.atan2(1, 1)    # 0.7853981633974483
math.atan2(-1, -1)  # -2.356194490192345

math.radians(45)    # 0.7853981633974483
math.radians(-135)  # -2.356194490192345

（2）math.dist、math.hypot

import math


# math.dist(p, q)
list1 = [-3, 4, 5]
list2 = [4, 5, 7]
math.dist(list1, list2)  
# 7.348469228349534
math.sqrt(math.fsum([math.pow(x-y, 2) for x, y in zip(list1,list2)]))
# 7.3484692283495345

list3 = [-3, 4, 5, 9]
list4 = [4, 5, 7, 2]
math.dist(list3, list4)  # 10.14889156509222


# math.hypot(*coordinates)
math.hypot(3, 4)
# 5.0

coordinates_list = [6, 7, 8]
math.hypot(*coordinates_list)
# 12.206555615733702
math.sqrt(math.fsum(map(lambda x: math.pow(x, 2), coordinates_list)))
# 12.206555615733702

角度转换

函数	描述
math.degrees(x)	将角度 x 从弧度转换为度数。
math.radians(x)	将角度 x 从度数转换为弧度。

这两个函数在处理几何问题时是非常实用的。

import math

math.radians(60)
# 1.0471975511965976

60 / 180 * math.pi
# 1.0471975511965976

math.degrees(1.0471975511965976)
# 59.99999999999999

双曲函数

函数	描述
math.sinh(x)	返回 x 的双曲正弦值。
math.cosh(x)	返回 x 的双曲余弦值。
math.tanh(x)	返回 x 的双曲正切值。
math.acosh(x)	返回 x 的反双曲正弦值。
math.asinh(x)	返回 x 的反双曲余弦值。
math.atanh(x)	返回 x 的反双曲正切值。

7. Python 标准库：cmath

复数是实数和虚数的组合，形如 a + bi，其中a是实数，bi是虚数（虚数是平方后得到负数）。
Python math 模块中的函数不能处理复数，不过，Python 提供了一个专门处理复数的模块 cmath 模块，cmath 实现了许多相同的函数，但可应用于复数。

8. Numpy

Python 标准库 math 和 NumPy 库都可以用于数学计算。二者有一些相似之处：NumPy 有一个函数子集，类似于 math，用于处理数学计算。NumPy 和 math 都提供了处理三角函数、指数函数、对数函数、双曲函数和算术计算的函数。

Python math 模块更适合处理标量值，而 NumPy 更适合处理数组、向量甚至矩阵。当处理标量值时，math 可能比 NumPy 对应函数更快，因为 NumPy 函数在底层会将值转换为数组，以便对它们执行计算，但 NumPy 在处理 n 维数组时要快得多。

9. 参考链接 

15.深入探究math.fmod与“%”求模运算符的区别，您注意到了吗？ - 数据类型（六） - 代码先锋网

The Python math Module: Everything You Need to Know – Real Python