附录C 常见报错与排查

文档摘要

附录 C 常见报错与排查

报错 → 原因 → 解决方案。配合第 4、6、9 章使用。

安装类

现象	可能原因	解决方案
pip install ripser 编译失败	无 C++ 工具链 / 旧 pip	升级 pip；用 wheel；Windows 装 Build Tools
ImportError: pyRipser	安装不完整	重装 ripser；避免混用 conda/pip 环境
Windows 本地源码编译	缺 MinGW	优先 wheel；或装 MinGW / MSVC

输入与参数

报错 / 警告	原因	解决方案
ValueError: distance matrix not square	D 非方阵	检查 X 形状；点云应为 (n,d)
UserWarning: square matrix without distance_matrix	方阵被当点云	设 `distance_matrix=True`
ValueError: n_perm and sparse	稀疏 + 贪心同用	二选一；稀疏用 thresh
ValueError: n_perm > n	子采样过多	减小 n_perm
ValueError: n_perm non positive	n_perm≤0	设为 None 或正整数
结果明显荒谬	距离矩阵未对称/负值	检查 D 对称、非负、对角 0

结果异常

现象	可能原因	解决方案
H1 为空	thresh 过小 / 无环结构	增大 thresh；验证玩具圆环
H1 满屏对角线	噪声大 / 随机点	正常；降噪或增大持久阈值
全是 inf death	thresh=inf 且特征未填平	正常；分析时用有限 death 或知悉截断
与论文图不一致	maxdim/coeff/metric 不同	对齐参数；检查归一化
n_perm 与全量差很大	n_perm 过小	增大 n_perm；看 r_cover
极慢	thresh 过大 / n 过大	降 thresh；稀疏化；n_perm

persim / 可视化

现象	原因	解决方案
plot 无窗口	无 GUI 后端	Agg 后端 + savefig
bottleneck 报错	含 inf 点	过滤 inf 行再比
图例混乱	多维 dgms 标签	设 labels=['H0','H1']

内存

现象	原因	解决方案
MemoryError	n、thresh 过大	thresh↓；n_perm；稀疏
do_cocycles 占内存大	存储所有代表元	仅必要时开启；降 maxdim

排查流程


结果不对？
    │
    ├─ 玩具圆环是否正常？ ─ 否 → 安装/参数基础问题（本章上表）
    │
    └─ 是 → 业务数据问题
              │
              ├─ 检查 distance_matrix 标志
              ├─ 扫 thresh 看 H1 稳定性
              ├─ 对比 n_perm vs 全量
              └─ 记录 num_edges 是否爆炸

快速诊断代码


import numpy as np
from ripser import ripser

def diagnose(X, **kwargs):
    r = ripser(X, **kwargs)
    for d, dgm in enumerate(r['dgms']):
        p = dgm[:, 1] - dgm[:, 0]
        fin = p[np.isfinite(p)]
        print(f"H{d}: n={len(dgm)}, max_pers={fin.max() if len(fin) else 0:.4f}")
    print("num_edges:", r['num_edges'])
    if r.get('r_cover', 0) > 0:
        print("r_cover:", r['r_cover'])
    return r

# 先用圆环验证环境
theta = np.linspace(0, 2*np.pi, 50, endpoint=False)
circle = np.column_stack([np.cos(theta), np.sin(theta)])
diagnose(circle, maxdim=1)

获取帮助

在 GitHub scikit-tda/ripser.py 提交 issue 时附上：Python 版本、ripser 版本、最小复现 X.shape 与参数、num_edges。
查阅官方交互 Notebook 中与你的场景最接近的示例。