English version: README.md
CANNs（Continuous Attractor Neural Networks toolkit）是基于 BrainPy 和 JAX 构建的研究工具库，并可选使用 Rust 加速库 canns-lib 优化部分性能敏感例程（如 TDA/Ripser 与任务生成）。它提供模型集合、任务生成器、分析器以及 ASA 流水线（GUI/TUI），帮助研究者在统一工作流中完成仿真与分析。API 按模型、任务、分析器和训练器分层设计，便于模块化扩展。
CANNs 库的层级结构，展示了五个层级：应用层（流水线编排）、功能层（任务、训练器、分析器、工具模块）、核心模型层（CANN 实现）、基础层（BrainPy/JAX 和 Rust FFI 后端）以及硬件层（CPU/GPU/TPU 支持）
CANNs 采用模块化架构，遵循两条核心原则：关注点分离 与 通过基类实现可扩展性。 设计将功能职责拆分为五个独立模块：
- 模型（
canns.models）定义神经网络动力学； - 任务（
canns.task）生成实验范式与输入数据； - 分析器（
canns.analyzer）提供可视化与分析工具； - 训练器（
canns.trainer）实现类脑模型的学习规则； - 流水线（
canns.pipeline）端到端完整工作流。
各模块职责单一——模型不生成输入、任务不分析结果、分析器不修改参数。
这种设计有利于维护、测试与扩展。核心组件继承抽象基类
（BasicModel、BrainInspiredModel、Trainer），
保证自定义实现能与内置生态无缝集成。
- 模型集合：基础 CANN（1D/2D、SFA）、层级路径积分、theta-sweep 模型、类脑模型（如 Amari-Hopfield、线性/脉冲层）
- 任务生成：平滑追踪、群体编码、模板匹配、开/闭环导航
- 分析器能力：能量景观、调谐曲线、栅格/放电率图、TDA 与解码工具、细胞分类
- ASA 流水线 & GUI/TUI：端到端流程（预处理、TDA、解码与结果可视化，如 CohoMap/CohoSpace/PathCompare/FR/FRM/GridScore）
- 训练与扩展：HebbianTrainer 与统一基类便于扩展
- 可选加速：
canns-lib覆盖部分性能敏感例程
神经动力学模型对比概览。 该图比较了三种经典基础模型：(A) 一维连续吸引子网络 (CANN 1D)，(B) 二维连续吸引子网络 (CANN 2D)，以及 (C) 网格细胞网络 (Grid Cell)
丰富的 Analyzer 可视化结果
ASA GUI 预览
ASA GUI 演示视频
活动波包随刺激移动 |
二维群体编码的演化过程 |
Theta 调制下的扫描动力学 |
|
波包拟合与稳定性分析 |
环面流形上的波包投影 |
1D CANN 平滑追踪（导入 → 仿真 → 可视化）
import brainpy.math as bm
from canns.analyzer.visualization import PlotConfigs, energy_landscape_1d_animation
from canns.models.basic import CANN1D
from canns.task.tracking import SmoothTracking1D
# 模拟时间步长
bm.set_dt(0.1)
# 构建模型
cann = CANN1D(num=512)
# 构建追踪任务（Iext 长度 = duration 长度 + 1）
task = SmoothTracking1D(
cann_instance=cann,
Iext=(0.0, 0.5, 1.0, 1.5),
duration=(5.0, 5.0, 5.0),
time_step=bm.get_dt(),
)
task.get_data()
# 单步仿真回调
def step(t, stimulus):
cann(stimulus)
return cann.u.value, cann.inp.value
# 运行仿真循环
us, inputs = bm.for_loop(
step,
operands=(task.run_steps, task.data),
)
# 能量景观动画可视化
config = PlotConfigs.energy_landscape_1d_animation(
time_steps_per_second=int(1 / bm.get_dt()),
fps=20,
title="Smooth Tracking 1D",
xlabel="State",
ylabel="Activity",
show=True,
)
energy_landscape_1d_animation(
data_sets={"u": (cann.x, us), "Iext": (cann.x, inputs)},
config=config,
)# 仅 CPU
pip install canns
# 可选加速（Linux）
pip install canns[cuda12]
pip install canns[cuda13]
pip install canns[tpu]
# GUI（ASA Pipeline）
pip install canns[gui]可选（uv）：
uv pip install canns- 文档与教程：https://routhleck.com/canns/
- 快速入门与设计笔记：https://routhleck.com/canns/en/notebooks/
- 本地示例脚本：
examples/ - Sphinx 文档与 Notebook：
docs/ - ASA GUI 入口：
canns-gui
如果您在研究中使用了 CANNs，请优先引用 arXiv 预印本：
@misc{he2026canns,
author = {He, Sichao and
Tuerhong, Aiersi and
She, Shangjun and
Chu, Tianhao and
Wu, Yuling and
Zuo, Junfeng and
Wu, Si},
title = {CANNs: A Toolkit for Research on Continuous Attractor Neural Networks},
year = {2026},
eprint = {2606.27783},
archivePrefix = {arXiv},
primaryClass = {q-bio.NC},
doi = {10.48550/arXiv.2606.27783},
url = {https://arxiv.org/abs/2606.27783}
}如果您需要引用软件的特定版本，也可以补充 Zenodo 归档：
@software{he_2026_canns,
author = {He, Sichao and
Tuerhong, Aiersi and
She, Shangjun and
Chu, Tianhao and
Wu, Yuling and
Zuo, Junfeng and
Wu, Si},
title = {CANNs: Continuous Attractor Neural Networks Toolkit},
month = feb,
year = {2026},
publisher = {Zenodo},
version = {v1.0.0},
doi = {10.5281/zenodo.18453893},
url = {https://doi.org/10.5281/zenodo.18453893}
}纯文本格式（主引用）：
He, S., Tuerhong, A., She, S., Chu, T., Wu, Y., Zuo, J., & Wu, S. (2026). CANNs: A Toolkit for Research on Continuous Attractor Neural Networks. arXiv:2606.27783. https://arxiv.org/abs/2606.27783
纯文本格式（版本归档）：
He, S., Tuerhong, A., She, S., Chu, T., Wu, Y., Zuo, J., & Wu, S. (2026). CANNs: Continuous Attractor Neural Networks Toolkit (v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.18453893
欢迎提交 Issue / PR。请先阅读 CONTRIBUTING.md。
Apache License 2.0。详见 LICENSE。