3. SciPy调用基础与常见陷阱

SciPy 的调用方式看似简单，但真正决定代码能否一次跑通的，往往不是算法本身，而是几个基础约定：模块从哪里导入、函数接受什么形状的数组、广播在什么条件下成立、返回值到底是单个数组还是元组。本节围绕这四件事展开，并给出识别形状不匹配与数据类型错误的实用方法。

一、import 惯例：从子模块取函数，而不是从 scipy 顶层取

SciPy 顶层包只做子模块的组织，绝大多数数值函数位于具体子模块中。因此正确写法是从子模块导入，例如：

import numpy as np
from scipy import optimize, integrate, linalg, stats, interpolate

# 推荐：明确来源
root = optimize.brentq(lambda x: x**2 - 2, 0, 2)
val, err = integrate.quad(np.sin, 0, np.pi)

# 不推荐：scipy 顶层通常没有这些函数
# import scipy
# scipy.optimize 需先显式导入子模块

一个常见误区是 import scipy 后直接调用 scipy.optimize.brentq。在部分版本中这会因属性未加载而报 AttributeError。稳妥做法是显式 from scipy import optimize，或直接 from scipy.optimize import brentq。另外，scipy.linalg 与 numpy.linalg 功能重叠，前者通常更快且提供更多分解选项，但两者对输入的要求略有差异，混用时要注意。

二、数组接口：一切输入先过 numpy

SciPy 函数内部几乎都按 NumPy 数组处理数据。传入 Python 列表通常能工作，但会带来隐式转换开销，且某些函数对列表的嵌套层级判断不如数组严格。实践原则是：进入 SciPy 之前，用 np.asarray 统一转换，并显式检查 dtype 与 shape。

x = np.asarray([1.0, 2.0, 3.0], dtype=float)
A = np.asarray([[2.0, 1.0], [1.0, 3.0]])
print(x.shape, x.dtype)   # (3,) float64
print(A.shape, A.dtype)   # (2, 2) float64

这里有一个容易忽略的细节：一维数组的形状是 (n,)，而不是 (n, 1) 或 (1, n)。很多线性代数与插值函数对这一点敏感。例如求解线性方程组时，右端项若写成 (n, 1) 的二维列向量，solve 仍可处理，但后续与其他一维结果做运算时就会触发广播，产生意外的 (n, n) 矩阵。

三、广播规则：形状从右对齐，逐维比较

NumPy 广播的核心规则是：从尾部维度开始对齐，每一维要么相等，要么其中一个是 1，要么其中一个缺失（视为 1）。SciPy 中大量函数在内部对参数做逐元素运算，因此广播错误常以“结果形状不对”而非报错的形式出现，更具隐蔽性。

a = np.ones((3, 1))
b = np.ones((1, 4))
print((a + b).shape)   # (3, 4)，合法广播

c = np.ones((3, 2))
d = np.ones((3, 3))
# c + d 会抛出 ValueError: operands could not be broadcast

判断是否兼容，可以手动画出两个形状并从右往左逐位比较。下图给出这一判断路径，以及形状不匹配与数据类型错误两类典型故障的定位方式。

四、返回值结构：解包前先确认

SciPy 的返回值并不统一，这是新手最容易踩坑的地方。大致可分为四类：单个数组或标量、元组、结果对象、可调用对象。integrate.quad 返回 (value, abserr) 二元组，若只写 result = quad(...) 再对 result 做数值运算，就会得到元组而非数值。optimize.brentq 返回标量根，而 optimize.minimize 返回一个 OptimizeResult 对象，需要访问 .x、.fun、.success 等属性。stats.ttest_ind 在新版中返回带 .statistic 与 .pvalue 字段的结果对象，直接按元组解包会失败。

from scipy import integrate, optimize, stats

val, err = integrate.quad(lambda x: x**2, 0, 1)   # 正确解包
res = optimize.minimize(lambda p: (p[0]-1)**2, x0=[0.0])
print(res.x, res.success)                          # 访问属性

t = stats.ttest_ind([1,2,3], [2,3,4])
print(t.statistic, t.pvalue)                       # 字段访问

稳妥的写法是：调用前查一次文档字符串的 Returns 段，或先用 type() 与 len() 观察返回结构，再决定解包方式。对结果对象，优先用属性名而非位置索引，可避免版本升级带来的字段顺序变化。

五、两类高频错误的识别与处理

形状不匹配的典型报错是 ValueError: operands could not be broadcast together with shapes (3,2) (3,3)，或 ValueError: Expected 2D array, got 1D array instead。处理顺序是：打印参与运算各量的 .shape，从右往左对齐比较，确认是否需要 reshape(-1, 1) 或 ravel()。注意 reshape 不改变数据顺序，而 resize 会原地修改，二者不可混用。

数据类型错误更隐蔽。整数数组参与除法会得到截断结果（在旧式写法中），复数数组传入只接受实数的函数会抛 TypeError，而 float32 在迭代类算法中可能因精度不足导致不收敛。建议在入口处统一 astype(np.float64)，对可能含复数的输入先判断 np.iscomplexobj，必要时取 .real 并明确告知使用者。

把上述四点固化为编码习惯后，SciPy 的调用会从“试错”变为“可预期”：导入路径清晰、输入形状可控、广播条件明确、返回值解包有据，形状与类型两类错误也就有了稳定的定位入口。