NumPy

NumPy 包总览：子模块、ufunc、where/排序/集合、einsum、插值与拟合、随机与 FFT；与 ndarray 分工及生态互操作。

NumPy 是 Python 科学计算的 基础数值库：核心类型为 numpy.ndarray，并提供 ufunc、线性代数、随机数、FFT 等子模块。安装后通常 import numpy as np。标准库无等价物，需 pip install numpy。

pip install numpy

适用性：Pyodide 可装 NumPy，但包体大、加载慢；超大数组受 WASM 内存限制。数组的 dtype、切片、广播等细节见 ndarray。

何时用 NumPy

场景	建议
向量、矩阵、批量数值运算	`ndarray` + ufunc；见 ndarray
随机采样、统计模拟	`np.random`（推荐 `default_rng()`）
频域滤波、谱分析	`np.fft`
曲线拟合、插值、多项式	`np.polyfit` / `np.interp` / `np.polynomial`
与 cv2、pandas、scipy 协作	多数以 `ndarray` 为桥梁
少量异构、频繁变长拼接	先用 `list`，再一次 `np.array()`

分工：本页讲 包级 API 与子模块；ndarray 专讲数组对象本身（形状、视图、广播、持久化等）。

性能：优先 向量化 与内置 C 实现；np.vectorize 只是语法糖，不释放 GIL，慢循环仍应改写为 ufunc 或 Numba/Cython。

模块成员总览

顶层常用

名称	说明
`array` / `zeros` / `arange` 等	创建数组；见 ndarray
`where(cond, x, y)`	按条件选元素；仅 `cond` 时返回索引元组
`clip(a, min, max)`	截断到区间
`select(condlist, choicelist)`	多分支条件赋值
`sort` / `argsort` / `partition`	排序
`unique`	去重；可返回计数、索引
`concatenate` / `stack` / `split`	拼接与拆分
`meshgrid` / `mgrid` / `ogrid`	坐标网格
`einsum`	Einstein 求和约定，表达批量点积、迹等
`polyfit` / `polyval`	最小二乘多项式拟合
`interp` / `searchsorted`	一维插值与有序查找
`set_printoptions`	控制打印精度、省略号
`version`	版本字符串

子模块

子模块	用途
`numpy.linalg`	范数、行列式、特征值、`solve`、`lstsq`；见 ndarray 线性代数小节
`numpy.random`	随机数；`Generator` + `default_rng()` 为推荐 API
`numpy.fft`	`fft`、`ifft`、`fft2`、`fftn`、`fftshift`
`numpy.polynomial`	多项式类（`Polynomial` 等），比裸 `polyfit` 更结构化
`numpy.ma`	带掩码数组，忽略无效值参与运算
`numpy.testing`	数组断言（`assert_allclose` 等），多用于单元测试

随机（`numpy.random`）

名称	说明
`default_rng(seed=)`	创建 `Generator`（新 API，可复现）
`rng.random(size)`	`[0, 1)` 均匀分布
`rng.integers(low, high, size)`	整数均匀
`rng.normal` / `rng.uniform`	正态、均匀等
`rng.choice(a, size, replace=)`	从序列或有放回抽样
`rng.shuffle(x)`	原地打乱（一维）

旧 API（np.random.rand 等）仍常见，新项目优先 default_rng。

FFT（`numpy.fft`）

名称	说明
`fft` / `ifft`	一维复数 FFT / 逆变换
`rfft` / `irfft`	实数输入，只保留非负频率一半
`fft2` / `fftn`	二维 / N 维
`fftshift`	将零频移到中心，便于可视化

导入与版本

import numpy as np

print(np.__version__)
np.set_printoptions(precision=3, suppress=True)

条件与分支（向量化）

a = np.array([-1, 0, 2, 5])
np.where(a > 0, a, 0)          # [0, 0, 2, 5]
idx = np.where(a > 0)        # (array([2, 3]),)

conds = [a < 0, a == 0, a > 0]
choices = [-1, 0, 1]
np.select(conds, choices)    # 多分支

避免对 ndarray 写 if arr:（布尔歧义）；用 arr.size、arr.any()、np.all()。

排序、去重与集合

x = np.array([3, 1, 2, 1])
np.sort(x)                   # 排序副本
np.argsort(x)                # 索引
u, counts = np.unique(x, return_counts=True)

a = np.array([1, 2, 3])
b = np.array([2, 3, 4])
np.intersect1d(a, b)
np.union1d(a, b)

`einsum` 与网格

A = np.arange(6).reshape(2, 3)
B = np.arange(12).reshape(3, 4)
C = np.einsum("ij,jk->ik", A, B)   # 矩阵乘

x = np.linspace(0, 1, 3)
y = np.linspace(0, 1, 2)
X, Y = np.meshgrid(x, y)           # 形状 (len(y), len(x))

字符串下标：i,j 为输入维，-> 后为输出；重复字母表示对该维求和。

插值与拟合

xp = np.array([0.0, 1.0, 2.0])
fp = np.array([0.0, 1.0, 0.0])
x = np.linspace(0, 2, 5)
y = np.interp(x, xp, fp)

coef = np.polyfit(xp, fp, deg=2)
y2 = np.polyval(coef, x)

高维、边界、外推更复杂时考虑 SciPy 的 interp1d / splrep。

随机示例

rng = np.random.default_rng(42)
u = rng.random((2, 3))
n = rng.normal(loc=0.0, scale=1.0, size=1000)
idx = rng.choice(10, size=5, replace=False)

FFT 示例

t = np.linspace(0, 1, 256, endpoint=False)
sig = np.sin(2 * np.pi * 10 * t) + 0.5 * np.sin(2 * np.pi * 25 * t)
spec = np.fft.rfft(sig)
freqs = np.fft.rfftfreq(sig.size, d=1 / sig.size)

掩码数组（简要）

import numpy.ma as ma

x = np.array([1.0, 2.0, -999.0, 4.0])
m = ma.masked_values(x, -999)
print(m.mean())   # 忽略掩码元素

适合缺测、传感器无效值；与 np.nan 浮点策略二选一，勿混用语义。

模块	关系
ndarray	核心数组类型与索引、广播、`.npy`
opencv-cv2	图像矩阵多为 `ndarray`
`pandas`	`DataFrame.values` / `to_numpy()`
`scipy`	建立在 NumPy 上的科学算法
`array`（标准库）	定长缓冲；可经 `memoryview` 与 NumPy 协作

易错点（排错速记）

np.vectorize 当加速：仍是 Python 循环包装，真加速靠 ufunc 或外部编译。
where 三参数形状：cond、x、y 需可广播，否则 ValueError。
interp 要求 xp 递增：未排序结果无定义；用 searchsorted 辅助分段。
随机种子：default_rng(seed) 可复现；全局 np.random.seed 影响旧 API 与第三方库，慎用。
FFT 长度：非 2 的幂仍可做，速度可能不如 next_fast_len 补零（SciPy）。
与 ndarray 重复踩坑：视图、 axis、float == 等见该文。

资料：NumPy 用户指南 · API 参考 · 随机数新 API · ndarray