NetworkX 3.0 迁移指南:从 2.X 到 3.0 的破坏性变更与升级实战

原创2026-09-20 13:19:561,977 阅读
文章标签:图计算数据分析科研

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 的优势:更好的统计特性与更高的性能。但需要注意两点:

  1. Generator 与 RandomState 流不兼容(相同的种子产生的随机序列不同);
  2. 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 的主要破坏性变更:

  1. 矩阵语义:搜索代码中的 numpy.matrix、scipy.sparse 矩阵用法,改为 ndarray / sparse array;把 *(矩阵乘)改为 @,移除 .I、.A、.H 等矩阵专属调用。
  2. 转换函数:把 to_numpy_matrix、to_scipy_sparse_matrix、to_numpy_recarray 分别替换为 to_numpy_array、to_scipy_sparse_array 与结构化 dtype 写法(见上文示例)。
  3. pagerank:确认环境已安装 SciPy;nx.pagerank 现在默认走 _pagerank_scipy,纯 Python 版本不再公开。
  4. 随机数:seed 参数可直接传 np.random.default_rng(...)(Generator)或 np.random.RandomState(...);需要跨版本精确复现时用 RandomState。
  5. IO 函数:read_gpickle/write_gpickle 改用 pickle,read_yaml/write_yaml 改用 yaml。
  6. 依赖:核心功能零依赖;使用 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 中直接验证。

登录后查看全文
networkx