NetworkX 3.0 迁移指南:从 2.X 到 3.0 的破坏性变更与升级实战
NetworkX 3.0 迁移指南:从 2.X 到 3.0 的破坏性变更与升级实战
导读
本文基于 doc/release/migration_guide_from_2.x_to_3.0.rst 整理,系统讲解从 NetworkX 2.X 升级到 3.0 时必须了解的破坏性变更:NumPy/SciPy 矩阵被数组语义全面取代、pagerank 默认切换到 SciPy 实现、随机数接口支持 numpy.random.Generator、多属性邻接矩阵改用结构化 dtype,以及 read_gpickle/write_gpickle、read_yaml/write_yaml 等函数的移除。读完本文,你将能对照迁移清单逐项改造现有代码,平滑升级到 3.0 及之后版本。
说明:迁移指南本身是面向 3.0 的规划与变更记录,其中大量弃用动作是在 2.6、2.7、2.8 三个中间版本陆续落地的;3.0 的正式发布日期为 2023 年 1 月 7 日,支持 Python 3.8–3.11(见 doc/release/release_3.0.rst)。
3.0 的总体目标:偿还技术债与现代化
迁移指南明确写道,3.0 的发布聚焦于 偿还多年积累的技术债务(technical debt)、现代化代码库、提升性能,并降低贡献门槛。理解这一目标有助于解释为什么 3.0 会有一批"不兼容"的改动——它们绝大多数是为了消除历史遗留的设计问题:
- 移除被官方长期不推荐的
numpy.matrix/scipy.sparse矩阵接口,全面转向ndarray/ sparse array 语义; - 把性能更好的线性代数实现(如
pagerank的 SciPy 版本)设为默认; - 拥抱 NumPy 新一代随机数接口
numpy.random.Generator; - 用更通用的结构化 dtype 替代专用的 recarray 支持;
- 清理一批与第三方库职责重叠的 IO 函数(pickle、YAML)。
这些改动同时改善了与科学计算生态(numpy、scipy、matplotlib、pandas)的集成,这也正是 3.0 及后续版本的发展方向。
默认依赖变化:核心零依赖,科学计算为可选增强
迁移指南明确:NetworkX 3.0 不再依赖 decorator 库,因此 NetworkX 本身没有任何强制依赖。
这意味着:
- 核心数据结构(
Graph、DiGraph、MultiGraph、MultiDiGraph)和常见算法可以脱离任何第三方库直接使用; - 部分功能(例如 networkx/linalg 包中的矩阵相关函数)只有在安装了
numpy、scipy等库后才可用。
但 3.0 同时做了大量"与科学计算生态更紧密集成"的改进,因此实际使用中 numpy、scipy、matplotlib、pandas 仍是最常见的伴随依赖。当前仓库的依赖约束文件 requirements/default.txt 中列出了 numpy>=2 与 scipy>=1.13,反映了仓库在当前版本下的配套要求;具体以你所安装的 NetworkX 版本为准。
核心变更一:NumPy/SciPy 矩阵全面替换为数组
为什么必须替换 numpy.matrix
numpy.matrix 长期被 NumPy 官方不推荐使用,原因是它与 ndarray 的接口存在显著分歧:
- 矩阵永远是二维的:索引和广播(broadcasting)行为与普通数组不同,导致同样的操作在不同维度输入下结果不一致;
- 乘法运算符语义不同:
*在矩阵上被解释为矩阵乘法,而不是逐元素乘法。
这两点差异让代码难以阅读,并经常需要大量样板代码来兼容多种数据格式。
3.0 的替换动作
随着 scipy 1.8 引入 sparse array 接口,NetworkX 3.0 得以将所有 scipy.sparse 矩阵和 numpy 矩阵替换为对应的数组版本:
| 旧接口(已移除) | 新接口(3.0 起) |
|---|---|
scipy.sparse.spmatrix 对象 |
scipy.sparse._sparray(sparse array) |
numpy.matrix 对象 |
numpy.ndarray |
nx.to_numpy_matrix 等显式矩阵转换函数 |
已删除,改用数组语义转换 |
具体到当前仓库源码,矩阵时代的转换入口已彻底消失:对 networkx/convert_matrix.py 的检索确认,to_numpy_matrix、to_scipy_sparse_matrix、to_numpy_recarray 均已不存在,取而代之的是:
to_scipy_sparse_array(G, nodelist=None, dtype=None, weight="weight", format="csr")(convert_matrix.py):返回图的邻接 sparse array,默认格式为 CSR;to_numpy_array(G, nodelist=None, dtype=None, order=None, multigraph_weight=sum, weight="weight", nonedge=0.0)(convert_matrix.py):返回图的邻接ndarray。
升级要点:3.X 中所有 numpy 和 scipy.sparse 对象都应按照 array 语义来对待。如果你的代码里出现了 A * B(期望矩阵乘法)或 .I、.H、.A 之类的矩阵专属用法,需要改写为 A @ B、np.linalg.inv 等数组化写法。
核心变更二:pagerank 默认切换到 SciPy 实现
背景:三个实现的历史
在 NetworkX 2.0 时代,pagerank 算法存在多个实现:
pagerank:纯 Python 实现;pagerank_numpy:面向稠密邻接矩阵;pagerank_scipy:面向稀疏邻接矩阵。
在实际使用场景中,SciPy 实现(基于稀疏线性代数)在绝大多数情况下性能远超其他实现。
3.0 的变更
3.0 中 nx.pagerank 默认调用 SciPy 实现。查看源码 networkx/algorithms/link_analysis/pagerank_alg.py,pagerank 函数(L9)的返回语句直接是:
return _pagerank_scipy(
G, alpha, personalization, max_iter, tol, nstart, weight, dangling
)
而纯 Python 版本则保留为 _pagerank_python(L121),不对外公开,仅用于教学目的,以引导用户使用高性能实现。
升级要点:
- 调用
nx.pagerank现在要求安装 SciPy; pagerank的参数保持一致:alpha(阻尼系数,默认 0.85)、personalization(个性化向量)、max_iter(幂法最大迭代次数,默认 100)、tol(收敛容差,默认 1e-6)、nstart(迭代初值)、weight(边权重键,默认"weight")、dangling(悬空节点出边分配);- 若未收敛,会抛出
PowerIterationFailedConvergence异常;文档特别提示,对大图要谨慎选择容差,当len(G) * tol >= 2时幂迭代可能在一轮后就"假收敛"。
核心变更三:随机数接口支持 numpy.random.Generator
NumPy 1.17 引入了新一代伪随机数生成接口 numpy.random.Generator。NetworkX 3.0 中,networkx/utils/misc.py 的 py_random_state 与 np_random_state 装饰器(以及底层的 create_random_state,见 misc.py)已支持把 Generator 实例作为 seed 参数传入:
>>> G = nx.barbell_graph(6, 2)
>>> pos = nx.spring_layout(G, seed=np.random.default_rng(123456789))
Generator 相比旧版 RandomState 的优势:更好的统计特性与更高的性能。但需要注意两点:
Generator与RandomState流不兼容(相同的种子产生的随机序列不同);Generator不保证与未来 NumPy 版本的流兼容性。
因此迁移指南给出了明确的选型建议:
- 需要跨 NetworkX 版本精确复现随机数(过去与未来),推荐使用
RandomState:
>>> rng = np.random.RandomState(12345)
>>> pos = nx.spring_layout(G, seed=rng)
- 新代码中不要求精确流复现,推荐使用
Generator:
>>> rng = np.random.default_rng(12345)
>>> pos = nx.spring_layout(G, seed=rng)
注意:
Generator也能实现精确复现,但可能要求安装特定版本的 NumPy。
从 create_random_state 的源码(misc.py)可以看到其完整的接受类型:None 或 np.random 模块(返回全局随机数生成器)、np.random.RandomState 实例(原样返回)、整数(作为种子构造 RandomState)、np.random.Generator 实例(原样返回),其他类型则抛出 ValueError。
核心变更四:结构化 dtype 替代 recarray
变更内容
3.0 之前,多属性邻接矩阵通过 nx.to_numpy_recarray 转换函数支持。numpy.recarray 本质上是带结构化 dtype 的 ndarray 便捷包装。3.0 中:
to_numpy_recarray被移除;- 结构化 dtype 支持加入
to_numpy_array,从而更通用地支持多属性邻接矩阵的数组表示。
新写法示例
迁移指南给出了完整的迁移示例——把每条边的 weight 与 cost 两个属性同时编码进一个结构化数组:
>>> import numpy as np
>>> edges = [
... (0, 1, {"weight": 10, "cost": 2}),
... (1, 2, {"weight": 5, "cost": 100})
... ]
>>> G = nx.Graph(edges)
>>> # Create an adjacency matrix with "weight" and "cost" attributes
>>> dtype = np.dtype([("weight", float), ("cost", int)])
>>> A = nx.to_numpy_array(G, dtype=dtype, weight=None)
>>> A
array([[( 0., 0), (10., 2), ( 0., 0)],
[(10., 2), ( 0., 0), ( 5., 100)],
[( 0., 0), ( 5., 100), ( 0., 0)]],
dtype=[('weight', '<f8'), ('cost', '<i8')])
>>> A["cost"]
array([[ 0, 2, 0],
[ 2, 0, 100],
[ 0, 100, 0]])
>>> # The recarray interface can be recovered with ``view``
>>> A = nx.to_numpy_array(G, dtype=dtype, weight=None).view(np.recarray)
>>> A
rec.array([[( 0., 0), (10., 2), ( 0., 0)],
[(10., 2), ( 0., 0), ( 5., 100)],
[( 0., 0), ( 5., 100), ( 0., 0)]],
dtype=[('weight', '<f8'), ('cost', '<i8')])
>>> A.weight
array([[ 0., 10., 0.],
[10., 0., 5.],
[ 0., 5., 0.]])
关键规则(与源码 convert_matrix.py 的 docstring 一致):
- 使用结构化 dtype 时,
weight参数必须为None,此时 dtype 的字段名被用来查找对应的边属性; - 若
dtype为结构化 dtype 且图是 multigraph,抛出NetworkXError;若weight非None,抛出ValueError; - 需要旧式 recarray 行为时,可以用
.view(np.recarray)恢复,实现向后兼容的过渡。
已移除的函数:pickle 与 YAML 读写
read_gpickle / write_gpickle
这两个函数在 3.0 中被移除。NetworkX 图对象本身就是可 pickle 的 Python 对象,直接用标准库 pickle 即可:
>>> import pickle
>>> G = nx.path_graph(4)
>>> with open('test.gpickle', 'wb') as f:
... pickle.dump(G, f, pickle.HIGHEST_PROTOCOL)
...
>>> with open('test.gpickle', 'rb') as f:
... G = pickle.load(f)
...
read_yaml / write_yaml
同样在 3.0 中被移除,改用 pyyaml 直接序列化图对象:
>>> import yaml
>>> G = nx.path_graph(4)
>>> with open('test.yaml', 'w') as f:
... yaml.dump(G, f)
...
>>> with open('test.yaml', 'r') as f:
... G = yaml.load(f, Loader=yaml.Loader)
升级要点:如果你的代码中出现了 nx.read_gpickle、nx.write_gpickle、nx.read_yaml、nx.write_yaml 的调用,直接替换为上面的标准库写法即可;对 networkx/readwrite 目录的检索也确认,当前仓库中已不存在这四个函数的实现。
快速迁移检查清单
对照以下清单检查你的代码,即可覆盖 3.0 的主要破坏性变更:
- 矩阵语义:搜索代码中的
numpy.matrix、scipy.sparse矩阵用法,改为ndarray/ sparse array;把*(矩阵乘)改为@,移除.I、.A、.H等矩阵专属调用。 - 转换函数:把
to_numpy_matrix、to_scipy_sparse_matrix、to_numpy_recarray分别替换为to_numpy_array、to_scipy_sparse_array与结构化 dtype 写法(见上文示例)。 - pagerank:确认环境已安装 SciPy;
nx.pagerank现在默认走_pagerank_scipy,纯 Python 版本不再公开。 - 随机数:
seed参数可直接传np.random.default_rng(...)(Generator)或np.random.RandomState(...);需要跨版本精确复现时用RandomState。 - IO 函数:
read_gpickle/write_gpickle改用pickle,read_yaml/write_yaml改用yaml。 - 依赖:核心功能零依赖;使用
networkx.linalg、pagerank 等线性代数相关功能前,确认已安装numpy/scipy。
如需进一步了解 3.0 的完整发布内容(数据结构同步改进、G.adj 改为缓存属性等),可继续阅读 doc/release/release_3.0.rst;上述源码证据均可在 networkx/convert_matrix.py、networkx/algorithms/link_analysis/pagerank_alg.py 与 networkx/utils/misc.py 中直接验证。