numpy-best-practices

NumPy 最佳实践

NumPy 开发专家指南，重点关注数组编程、数值计算和性能优化。

代码风格与结构

• 编写简洁、专业的 Python 代码，并提供准确的 NumPy 示例
• 为提升性能，优先使用向量化操作，而非显式循环
• 使用能反映数据内容的描述性变量名（例如，weights、gradients、input_array）
• 遵循 Python 代码的 PEP 8 风格指南
• 适当采用函数式编程模式

数组创建与操作

• 使用合适的数组创建函数：np.array()、np.zeros()、np.ones()、np.empty()、np.arange()、np.linspace()
• 数组大小已知时，优先使用 np.zeros() 或 np.empty() 预分配
• 使用 np.concatenate()、np.vstack()、np.hstack() 合并数组
• 利用广播机制对形状不同的数组执行运算

索引与切片

• 使用布尔数组进行高级索引，实现条件选择
• 尽可能优先使用视图而非副本，以节省内存
• 使用 np.where() 进行条件元素选择
• 理解花式索引（会创建副本）与基本切片（会创建视图）之间的区别

数据类型

• 使用 dtype 参数显式指定合适的数据类型
• 无需完整精度时，使用 np.float32 进行内存高效的计算
• 注意定长整数类型可能发生的整数溢出
• 使用 np.asarray() 转换类型，避免不必要的副本

性能优化

向量化

• 始终优先使用向量化操作，而非 Python 循环
• 使用 NumPy 通用函数（ufunc）执行逐元素操作
• 利用 np.einsum() 执行复杂的张量运算
• 使用 np.dot() 或 @ 运算符进行矩阵乘法

内存管理

• 使用 np.ndarray.flags 检查内存布局（C 连续或 Fortran 连续）
• 尽可能使用带 out 参数的原地操作
• 对大型数据集使用内存映射数组（np.memmap）
• 留意数组副本与视图的区别

计算效率

• 聚合时使用带 axis 参数的 np.sum()、np.mean()、np.std()
• 利用 np.cumsum()、np.cumprod() 执行累积运算
• 使用 np.searchsorted() 高效处理已排序数组

错误处理与验证

• 计算前验证输入的形状和数据类型
• 使用断言检查维度，并提供明确的错误信息
• 使用 np.isnan()、np.isinf() 适当处理 NaN 和 Inf 值
• 使用 np.errstate() 上下文管理器控制浮点错误处理

随机数生成

• 使用 np.random.default_rng() 生成随机数
• 设置种子以确保结果可复现：rng = np.random.default_rng(seed=42)
• 优先使用新的 Generator API，而非旧版 np.random 函数
• 使用合适的分布：rng.normal()、rng.uniform()、rng.choice()

线性代数

• 使用 np.linalg 执行线性代数运算
• 求解线性方程组时，使用 np.linalg.solve()，而非计算逆矩阵
• 使用 np.linalg.eig()、np.linalg.svd() 进行分解
• 求逆前使用 np.linalg.cond() 检查矩阵条件数

测试与文档

• 使用 pytest 编写单元测试，并使用 np.testing 断言
• 使用 np.testing.assert_array_equal() 进行精确比较
• 使用 np.testing.assert_array_almost_equal() 进行浮点数比较
• 按照 NumPy 文档字符串格式编写完整的文档字符串

主要约定

• 按照 import numpy as np 的方式导入
• 变量和函数使用 snake_case
• 在文档字符串中注明数组形状
• 使用 %timeit 对代码进行性能分析，找出瓶颈