更新日志¶
btorch 的所有重要变更都将记录在此文件中。
本格式基于 Keep a Changelog, 并且本项目遵循 语义化版本控制。
[Unreleased]¶
新增¶
btorch.sparse:SciPy/PyTorch 风格的稀疏数组 API(Sparse、COO、CSR、CSC、sparse.from_edges、sparse.asarray、A @ x、sparse.stack、to_torch()/to_scipy());采用标准矩阵方向,转换从不转置、也不稠密化。btorch.models.connection:SparseConnection(from_adjacency、from_edges、from_hetersynapse)、Synapse、EdgeWeight、ConstantWeight、ConstrainedWeight;受体与延迟作为边属性;支持网络批。矩阵方向统一命名为"pre_post"(行为源神经元,from_adjacency与FromSparse的默认值)和"post_pre"(算子)。新增访问器conn.pre、conn.post、conn.find_edges(pre, post)、conn.orientation;Projection.weight、edge_table()、to_sparse()、n_delay、n_receptor。- CUDA graph 捕获协议:
conn.capture_version、conn.capture_incompatibility(),以及btorch.models.cudagraph.capture_versions/capture_incompatibilities。 btorch.sparse.runtime:执行层(注册算子、后端注册表、规划器);编写模型时无需使用。Triton pull 后端(csr_matvec、edge_grad)在安装了 Triton 的 CUDA 上为默认后端。- 连接规则与
Projection:NEST 风格的构建方式(Projection(pre, post, rule, synapse);OneToOne、AllToAll、FixedIndegree、FixedOutdegree、PairwiseBernoulli、DistanceDependent、FromEdges、FromSparse)。 btorch.sparse.operator:无需存储矩阵的线性算子(ConstantOperator、DiagonalOperator、LowRankOperator、ImplicitOperator、惰性组合),以及StructuredConnection/ImplicitConnection/HybridConnection。sparse.einsum(实验性):一个 N 维稀疏操作数与稠密张量缩并,输出为稠密张量。HardDeepR:面向SparseConnection的固定槽位硬 Deep Rewiring(attach(optimizer));未实现软 Deep R。- 指南:稀疏连接。
变更¶
- 破坏性变更(相对于尚未发布的连接 API 的早期版本;没有别名):方向字符串统一为
"pre_post"/"post_pre"("src_dst"/"dst_src"已移除);FromSparse默认"pre_post";conn.to_sparse()默认返回构建连接时所用的方向;set_edges_(slots, *, pre, post, ...)的索引参数仅限关键字;HardDeepROptions.candidate以candidate(pre, post)调用。 - 破坏性变更: 权重按对象身份绑定:传入
Synapse(weight=...)的Weight模块就是conn.weight(每个连接一个模块);nn.Parameter在边顺序保持不变时直接成为conn.weight.value,否则复制并给出警告。Synapse(weight=<数值>, dale=True)与Synapse(plasticity=...)会抛出异常。 - 破坏性变更: 规划器区分
"push"(CUDA 上的 Triton;结果不保证逐位可复现)与"adaptive-push"(参考后端;无法被 CUDA graph 捕获)。conn.value_version现在会随优化器更新而变化。btorch.sparse.runtime.__all__不再列出ops与kernels_aten。 - 破坏性变更:
btorch.models.linear中的SparseConn、SparseConstrainedConn、BaseSparseConn、SparseBackend、available_sparse_backends以及sparse_backend=参数已移除,没有兼容层。请改用SparseConnection.from_adjacency(conn, Synapse(dale=...));Dale 定律现需显式开启,state_dict的键也已改变;旧层写出的检查点会被拒绝并给出迁移提示。迁移对照表见稀疏连接指南。 - 破坏性变更:
memories_to_xarray/save_memories_to_xarray的选项归入DimLayout、SparseOptions与ZarrStoreOptions(btorch.io);neuron_ids与partial_map变为仅关键字参数。 - 破坏性变更: 在第
t步送达的脉冲现在会影响第t步返回的 PSC,所有 PSC 类型一致(此前AlphaPSC、AlphaPSCBilleh、DualExponentialPSC多花一个dt)。 - 破坏性变更:
GLIF3.forward_exact_no_spike(x, t=None, v0=None, Iasc0=None, t_mode="homo")现为纯函数(不再更新状态);逐元素原语exact_no_spike_at(x, t, v0, Iasc0)支持批量的异质时间与状态,例如用于迭代求根。t_mode="heter"表示逐元素时间。 - 破坏性变更: 绘图与拟合选项归入数据类(
TbpttConfig、GlobalSearchConfig、StagedConfig、FitLossConfig、raster 选项),见分析与可视化页面。 - 破坏性变更: 六边形
scatter/quiver使用HexGeometry、HexColorMap、HexPatchStyle、HexReference;plot_grouped_spectrum使用SpectrumGrouping与SpectrumStyle。quiver现在会遵循rotation_deg与颜色范围。 - 破坏性变更: 包布局按层次调整。
btorch.datasets.noise->btorch.models.noise;btorch.datasets.transforms->btorch.utils.hex.augment;btorch.analysis.two_compartment_fit->btorch.fitting.two_compartment,btorch.analysis.tuning->btorch.fitting.tuning(拟合相关名称不再从btorch.analysis重新导出)。btorch.datasets包已移除。 - 分析函数命名规则:估计器/流水线统一为
compute_*。重命名:branching_ratio->compute_branching_ratio,get_slopes->compute_lagged_slopes,get_continuous_spiking_rate->compute_continuous_spiking_rate,voltage_overshoot->compute_voltage_overshoot。 - 移除
plot_group_violin、plot_group_box、plot_group_ecdf;请使用plot_group_distribution(..., kind="violin" | "box" | "ecdf")。 - 较重的依赖现为可选扩展(
io、config、fast、gpu、analysis、viz、sparse、examples、all),见安装。 fano_population/kurtosis_population标注为StatsResult;多输出的装饰器分析函数(compute_lag_correlation、E/I 平衡)标注为MultiStatsResult(新增,位于btorch.analysis.statistics)。make_hetersynapse_constraint在同一处构造约束键;结果不变。
修复¶
- 稀疏连接的 Dale 符号与约束结构现保存在
state_dict中;此前在load_state_dict之后会过期。 - 稀疏连接无需
torch_sparse即可通过torch.compile(conn, fullgraph=True)编译。 - 纯 PyTorch 稀疏路径的反向传播在约 10 万神经元规模下不再内存不足。
make_hetersynapse_conn的延迟处理。plot_multiscale_fano使用不支持的group_by时现抛出ValueError,而非NameError。- 幂律缩放拟合在输入为常数时
r_squared返回NaN,不再除以零。
[0.1.0]¶
新增¶
- 双室神经元(
TwoCompartmentGLIF)——具有非线性顶端平台电位、双向耦合和可选自适应阈值的体树突神经元。参见教程。 - 混合神经元群体(
MixedNeuronPopulation)——在单个循环层中混合多种神经元类型(如 GLIF3 + TwoCompartmentGLIF),支持自动电流切片与脉冲拼接。 - 异构 RNN(
HeteroRecurrentNN)——RecurrentNN的替代实现,接受MixedNeuronPopulation。 - 六边形网格模块(
btorch.utils.hex)——坐标系统(axial、doubled、zigzag、flywire)、结构体数组数据类型、卷积层、眼渲染模型,以及带叠加层和指南针的 SVG 可视化。参见六边形文档。 - 类型注解——
btorch/py.typed(PEP 561)以及btorch.analysis.spiking、btorch.models.neurons.two_compartment、btorch.utils.hex中完整的返回类型注解。 - 发布 CI——GitHub Actions 工作流,当推送
v*标签时构建分发包并通过可信发布上传至 PyPI(仅手动触发)。 - Codecov——配置文件,包含覆盖率阈值、标志管理和行内 PR 注解。
变更¶
- 代理梯度重构——所有代理梯度导数现在对任意
alpha值均满足g(v=0, damping_factor=1) == 1.0(Zenke & Neftci 2021), 且alpha = 1/HWHM在所有代理函数中统一成立。默认alpha值已更新。 参见代理梯度指南 了解迁移说明。 - 构建系统迁移至 uv——
uv.lock取代 pip 锁文件;CI 使用uv sync配合 PyTorch CPU 索引。 - 文档迁移至 Zensicle——使用 Zensicle + mkdocstrings 取代 mkdocs/myst/sphinx。英文和中文文档现在通过同一条流水线构建,并支持 AI 辅助翻译。
- Conda 环境重命名——
dev-requirements.yaml→environment.yml。 - RNN 类重命名——清理了公开导出名称。
破坏性变更¶
所有代理梯度导数已重新归一化,使得对任意 alpha 值均满足
g(v=0, damping_factor=1) == 1.0
(Zenke & Neftci 2021,Neural Computation 33(4))。
此前,各导数均被缩放至在电压上积分为 1——其动机类比于概率密度函数。 但事实证明这并非正确的不变量:对稳定学习真正重要的是在阈值处的单位响应, 而非单位积分。
| 代理函数 | 旧峰值(v=0 处) | 施加因子 | 新峰值 |
|---|---|---|---|
Triangle |
alpha |
1/alpha |
1 |
Sigmoid |
alpha/4 |
4/alpha |
1 |
Erf |
alpha/√π |
√π/alpha |
1 |
ATan |
alpha/2 |
2/alpha |
1 |
ATanApprox |
alpha/2 |
2/alpha |
1 |
SuperSpike 及 Heaviside 前向传播不受影响。
迁移建议: 使用上述任意代理函数训练的模型将产生不同的有效梯度幅值。
建议从头重新训练,或将现有 damping_factor 乘以旧峰值的倒数以保持幅值
(例如:ATan 在 alpha=2 时旧峰值为 1.0,无需调整;在 alpha=4 时
旧峰值为 2.0,需设置 damping_factor=2.0)。
所有代理梯度已重新参数化,使得 alpha = 1/HWHM 对所有代理梯度统一成立。
g(v) 的半高全宽(HWHM)现在精确等于 1/alpha(ATanApprox 因有理近似存在约 8% 误差)。
| 代理梯度 | 内部常数 | 新默认 α | 旧默认 α |
|---|---|---|---|
Triangle |
k = 1/2 | 2.0 | 1.0 |
Sigmoid |
k = 2ln(√2+1)≈1.763 | 2.0 | 1.0 |
Erf |
k = √ln2≈0.833 | 4.0 | 2.0 |
ATan |
k = 1(原为 π/2) | 2.0 | 2.0 |
ATanApprox |
k ≈ 1 | 2.0 | 2.0 |
SuperSpike |
k = √2−1≈0.414 | 2.0 | 4.0 |
迁移建议: 如果依赖之前的 alpha 值,在旧 alpha 处的梯度宽度现在有所不同。
建议通过搜索重新调整 alpha。
移除¶
- 移除
pytorch_sparse硬依赖——稀疏线性层现在默认使用 PyTorch 原生的torch.sparse后端。torch_sparse仍可作为可选安装用于大规模稀疏网络场景。 - Sphinx、myst-parser 和已废弃的 pip 锁文件。
- README 中的 AI 智能体提示章节(已替换为清晰的安装说明)。