canns 0.15.1__py3-none-any.whl → 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- canns-1.0.0.dist-info/METADATA +257 -0
- {canns-0.15.1.dist-info → canns-1.0.0.dist-info}/RECORD +5 -5
- canns-0.15.1.dist-info/METADATA +0 -245
- {canns-0.15.1.dist-info → canns-1.0.0.dist-info}/WHEEL +0 -0
- {canns-0.15.1.dist-info → canns-1.0.0.dist-info}/entry_points.txt +0 -0
- {canns-0.15.1.dist-info → canns-1.0.0.dist-info}/licenses/LICENSE +0 -0
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: canns
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A Python Library for Continuous Attractor Neural Networks
|
|
5
|
+
Project-URL: Repository, https://github.com/routhleck/canns
|
|
6
|
+
Author-email: Sichao He <sichaohe@outlook.com>
|
|
7
|
+
License-Expression: Apache-2.0
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Typing :: Typed
|
|
18
|
+
Requires-Python: <4.0,>=3.11
|
|
19
|
+
Requires-Dist: brainpy[cpu]
|
|
20
|
+
Requires-Dist: canns-lib>=0.6.2
|
|
21
|
+
Requires-Dist: climage>=0.2.2
|
|
22
|
+
Requires-Dist: furo>=2025.7.19
|
|
23
|
+
Requires-Dist: h5py>=3.7
|
|
24
|
+
Requires-Dist: igraph>=1.0.0
|
|
25
|
+
Requires-Dist: imageio[ffmpeg]>=2.37.0
|
|
26
|
+
Requires-Dist: leidenalg>=0.11.0
|
|
27
|
+
Requires-Dist: matplotlib>=3.5
|
|
28
|
+
Requires-Dist: notebook>=7.4.4
|
|
29
|
+
Requires-Dist: numba>=0.56.0
|
|
30
|
+
Requires-Dist: numpy<2.3,>=1.24
|
|
31
|
+
Requires-Dist: scikit-image>=0.19
|
|
32
|
+
Requires-Dist: scipy>=1.9.0
|
|
33
|
+
Requires-Dist: seaborn>=0.13.2
|
|
34
|
+
Requires-Dist: textual>=7.3.0
|
|
35
|
+
Requires-Dist: tqdm
|
|
36
|
+
Provides-Extra: cpu
|
|
37
|
+
Requires-Dist: brainpy[cpu]; extra == 'cpu'
|
|
38
|
+
Provides-Extra: cuda12
|
|
39
|
+
Requires-Dist: brainpy[cuda12]; (platform_system == 'Linux') and extra == 'cuda12'
|
|
40
|
+
Provides-Extra: cuda13
|
|
41
|
+
Requires-Dist: brainpy[cuda13]; (platform_system == 'Linux') and extra == 'cuda13'
|
|
42
|
+
Provides-Extra: gui
|
|
43
|
+
Requires-Dist: imageio; extra == 'gui'
|
|
44
|
+
Requires-Dist: pillow; extra == 'gui'
|
|
45
|
+
Requires-Dist: pyside6>=6.6.0; extra == 'gui'
|
|
46
|
+
Requires-Dist: qtawesome; extra == 'gui'
|
|
47
|
+
Requires-Dist: requests>=2.31.0; extra == 'gui'
|
|
48
|
+
Provides-Extra: tpu
|
|
49
|
+
Requires-Dist: brainpy[tpu]; (platform_system == 'Linux') and extra == 'tpu'
|
|
50
|
+
Description-Content-Type: text/markdown
|
|
51
|
+
|
|
52
|
+
# CANNs: Continuous Attractor Neural Networks Toolkit
|
|
53
|
+
|
|
54
|
+
<div align="center">
|
|
55
|
+
<img src="images/logo.svg" alt="CANNs Logo" width="350">
|
|
56
|
+
</div>
|
|
57
|
+
|
|
58
|
+
[<img src="https://badges.ws/badge/status-stable-green" />](https://github.com/routhleck/canns)
|
|
59
|
+
|
|
60
|
+
[<img src="https://badges.ws/maintenance/yes/2026" />](https://github.com/routhleck/canns)
|
|
61
|
+
<picture><img src="https://badges.ws/github/release/routhleck/canns" /></picture>
|
|
62
|
+
<picture><img src="https://badges.ws/github/license/routhleck/canns" /></picture>
|
|
63
|
+
[](https://doi.org/10.5281/zenodo.17412545)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
<picture><img src="https://badges.ws/github/stars/routhleck/canns?logo=github" /></picture>
|
|
67
|
+
[](https://pepy.tech/projects/canns)
|
|
68
|
+
[](https://deepwiki.com/Routhleck/canns)
|
|
69
|
+
[<img src="https://badges.ws/badge/Buy_Me_a_Coffee-ff813f?icon=buymeacoffee" />](https://buymeacoffee.com/forrestcai6)
|
|
70
|
+
|
|
71
|
+
> 中文说明请见 [README_zh.md](README_zh.md)
|
|
72
|
+
|
|
73
|
+
## Overview
|
|
74
|
+
|
|
75
|
+
CANNs (Continuous Attractor Neural Networks toolkit) is a research toolkit built on [BrainPy](https://github.com/brainpy/BrainPy) and [JAX](https://github.com/jax-ml/jax), with optional Rust-accelerated [`canns-lib`](https://github.com/Routhleck/canns-lib) for selected performance-critical routines (e.g., TDA/Ripser and task generation). It bundles model collections, task generators, analyzers, and the ASA pipeline (GUI/TUI) so researchers can run simulations and analyze results in a consistent workflow. The API separates models, tasks, analyzers, and trainers to keep experiments modular and extensible.
|
|
76
|
+
|
|
77
|
+
## Architecture
|
|
78
|
+
|
|
79
|
+
<p align="center">
|
|
80
|
+
<img src="images/architecture.png" alt="CANNs Architecture" width="900">
|
|
81
|
+
<br>
|
|
82
|
+
<span style="color: grey; font-size: 14px;">Library architecture overview: models, tasks, analyzers, trainers, and pipeline built on BrainPy/JAX with optional Rust acceleration.</span>
|
|
83
|
+
</p>
|
|
84
|
+
|
|
85
|
+
The CANNs library follows a modular architecture guided by two core principles: **separation of concerns** and **extensibility through
|
|
86
|
+
base classes**. The design separates functional responsibilities into five independent modules:
|
|
87
|
+
1. **Models** (`canns.models`) define neural network dynamics;
|
|
88
|
+
2. **Tasks** (`canns.task`) generate experimental paradigms and input data;
|
|
89
|
+
3. **Analyzers** (`canns.analyzer`) provide visualization and analysis tools;
|
|
90
|
+
4. **Trainers** (`canns.trainer`) implement learning rules for brain-inspired models;
|
|
91
|
+
5. **Pipeline** (`canns.pipeline`) orchestrates complete workflows.
|
|
92
|
+
|
|
93
|
+
Each module focuses on a single responsibility—models don't generate input data, tasks don't analyze results, and analyzers don't modify
|
|
94
|
+
parameters. This separation ensures maintainability, testability, and extensibility. All major components inherit from abstract base classes
|
|
95
|
+
(`BasicModel`, `BrainInspiredModel`, `Trainer`) that define standard interfaces, enabling users to create custom implementations that
|
|
96
|
+
seamlessly integrate with the built-in ecosystem.
|
|
97
|
+
|
|
98
|
+
## Core Features
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
- **Model collections**: basic CANNs (1D/2D, SFA), hierarchical path integration, theta-sweep models, brain-inspired models (e.g., Amari-Hopfield, linear/spiking layers)
|
|
103
|
+
- **Task generators**: smooth tracking, population coding, template matching, open/closed-loop navigation
|
|
104
|
+
- **Analyzer suite**: energy landscapes, tuning curves, raster/firing-rate plots, TDA and decoding utilities, cell classification
|
|
105
|
+
- **ASA pipeline & GUI/TUI**: end-to-end workflow for preprocessing, TDA, decoding, and result visualization (e.g., CohoMap/CohoSpace/PathCompare/FR/FRM/GridScore)
|
|
106
|
+
- **Training & extensibility**: HebbianTrainer plus base classes for consistent extension
|
|
107
|
+
- **Optional acceleration**: `canns-lib` for selected performance-critical routines
|
|
108
|
+
|
|
109
|
+
## Analyzer Visuals
|
|
110
|
+
|
|
111
|
+
<p align="center">
|
|
112
|
+
<img src="docs/_static/figure2_full.png" alt="Model Analysis Overview" width="900">
|
|
113
|
+
<br>
|
|
114
|
+
<span style="color: grey; font-size: 14px;">Overview of Neural Dynamics Models. Comparison of three basic models: (A) 1D CANN, (B) 2D CANN, and (C) Grid Cell Network</span>
|
|
115
|
+
</p>
|
|
116
|
+
|
|
117
|
+
<p align="center">
|
|
118
|
+
<img src="images/analyzer-display.png" alt="Analyzer Display" width="900">
|
|
119
|
+
<br>
|
|
120
|
+
<span style="color: grey; font-size: 14px;">Rich Analyzer Visualization Results</span>
|
|
121
|
+
</p>
|
|
122
|
+
<p align="center">
|
|
123
|
+
<img src="images/asa-gui.gif" alt="ASA GUI Preview" width="720">
|
|
124
|
+
<br>
|
|
125
|
+
<span style="color: grey; font-size: 14px;">ASA GUI preview</span>
|
|
126
|
+
</p>
|
|
127
|
+
<p align="center">
|
|
128
|
+
<a href="https://youtu.be/OoEo5Qa9f7M">
|
|
129
|
+
<img src="https://img.youtube.com/vi/OoEo5Qa9f7M/hqdefault.jpg" alt="ASA GUI Demo (YouTube)" width="720">
|
|
130
|
+
</a>
|
|
131
|
+
<br>
|
|
132
|
+
<span style="color: grey; font-size: 14px;">ASA GUI demo video</span>
|
|
133
|
+
</p>
|
|
134
|
+
|
|
135
|
+
<div align="center">
|
|
136
|
+
<table>
|
|
137
|
+
<tr>
|
|
138
|
+
<td align="center" width="50%" valign="top">
|
|
139
|
+
<h4>Smooth Tracking 1D</h4>
|
|
140
|
+
<img src="docs/_static/smooth_tracking_1d.gif" alt="Smooth Tracking 1D" width="320">
|
|
141
|
+
<br><em>Activity bump following a moving stimulus</em>
|
|
142
|
+
</td>
|
|
143
|
+
<td align="center" width="50%" valign="top">
|
|
144
|
+
<h4>CANN2D Encoding</h4>
|
|
145
|
+
<img src="docs/_static/CANN2D_encoding.gif" alt="CANN2D Encoding" width="320">
|
|
146
|
+
<br><em>2D population encoding patterns over time</em>
|
|
147
|
+
</td>
|
|
148
|
+
</tr>
|
|
149
|
+
<tr>
|
|
150
|
+
<td colspan="2" align="center">
|
|
151
|
+
<h4>Theta Sweep Animation</h4>
|
|
152
|
+
<img src="docs/_static/theta_sweep_animation.gif" alt="Theta Sweep Animation" width="600">
|
|
153
|
+
<br><em>Theta-modulated sweep dynamics</em>
|
|
154
|
+
</td>
|
|
155
|
+
</tr>
|
|
156
|
+
<tr>
|
|
157
|
+
<td align="center" width="50%" valign="top">
|
|
158
|
+
<h4>Bump Analysis</h4>
|
|
159
|
+
<img src="docs/_static/bump_analysis_demo.gif" alt="Bump Analysis Demo" width="320">
|
|
160
|
+
<br><em>Bump fitting and stability diagnostics</em>
|
|
161
|
+
</td>
|
|
162
|
+
<td align="center" width="50%" valign="top">
|
|
163
|
+
<h4>Torus Bump</h4>
|
|
164
|
+
<img src="docs/_static/torus_bump.gif" alt="Torus Bump" width="320">
|
|
165
|
+
<br><em>Bump dynamics projected onto a torus manifold</em>
|
|
166
|
+
</td>
|
|
167
|
+
</tr>
|
|
168
|
+
</table>
|
|
169
|
+
</div>
|
|
170
|
+
|
|
171
|
+
## Quick Start
|
|
172
|
+
|
|
173
|
+
1D CANN smooth tracking (imports → simulation → visualization)
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
import brainpy.math as bm
|
|
177
|
+
from canns.analyzer.visualization import PlotConfigs, energy_landscape_1d_animation
|
|
178
|
+
from canns.models.basic import CANN1D
|
|
179
|
+
from canns.task.tracking import SmoothTracking1D
|
|
180
|
+
|
|
181
|
+
# simulation time step
|
|
182
|
+
bm.set_dt(0.1)
|
|
183
|
+
|
|
184
|
+
# build model
|
|
185
|
+
cann = CANN1D(num=512)
|
|
186
|
+
|
|
187
|
+
# build tracking task (Iext length = duration length + 1)
|
|
188
|
+
task = SmoothTracking1D(
|
|
189
|
+
cann_instance=cann,
|
|
190
|
+
Iext=(0.0, 0.5, 1.0, 1.5),
|
|
191
|
+
duration=(5.0, 5.0, 5.0),
|
|
192
|
+
time_step=bm.get_dt(),
|
|
193
|
+
)
|
|
194
|
+
task.get_data()
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
# one-step simulation callback
|
|
198
|
+
def step(t, stimulus):
|
|
199
|
+
cann(stimulus)
|
|
200
|
+
return cann.u.value, cann.inp.value
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
# run simulation loop
|
|
204
|
+
us, inputs = bm.for_loop(
|
|
205
|
+
step,
|
|
206
|
+
operands=(task.run_steps, task.data),
|
|
207
|
+
)
|
|
208
|
+
|
|
209
|
+
# visualize with energy landscape animation
|
|
210
|
+
config = PlotConfigs.energy_landscape_1d_animation(
|
|
211
|
+
time_steps_per_second=int(1 / bm.get_dt()),
|
|
212
|
+
fps=20,
|
|
213
|
+
title="Smooth Tracking 1D",
|
|
214
|
+
xlabel="State",
|
|
215
|
+
ylabel="Activity",
|
|
216
|
+
show=True,
|
|
217
|
+
)
|
|
218
|
+
|
|
219
|
+
energy_landscape_1d_animation(
|
|
220
|
+
data_sets={"u": (cann.x, us), "Iext": (cann.x, inputs)},
|
|
221
|
+
config=config,
|
|
222
|
+
)
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## Installation
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
# CPU-only
|
|
229
|
+
pip install canns
|
|
230
|
+
|
|
231
|
+
# Optional accelerators (Linux)
|
|
232
|
+
pip install "canns[cuda12]"
|
|
233
|
+
pip install "canns[cuda13]"
|
|
234
|
+
pip install "canns[tpu]"
|
|
235
|
+
|
|
236
|
+
# GUI (ASA Pipeline)
|
|
237
|
+
pip install "canns[gui]"
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Optional (uv):
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
uv pip install canns
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
## Docs & Examples
|
|
247
|
+
|
|
248
|
+
- Documentation and tutorials: <https://routhleck.com/canns/>
|
|
249
|
+
- Local scripts: `examples/`
|
|
250
|
+
- Sphinx docs and notebooks: `docs/`
|
|
251
|
+
- ASA GUI entry: `canns-gui`
|
|
252
|
+
|
|
253
|
+
## Contributing & License
|
|
254
|
+
|
|
255
|
+
Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
|
|
256
|
+
|
|
257
|
+
Apache License 2.0. See [LICENSE](LICENSE).
|
|
@@ -165,8 +165,8 @@ canns/trainer/utils.py,sha256=ZdoLiRqFLfKXsWi0KX3wGUp0OqFikwiou8dPf3xvFhE,2847
|
|
|
165
165
|
canns/typing/__init__.py,sha256=mXySdfmD8fA56WqZTb1Nj-ZovcejwLzNjuk6PRfTwmA,156
|
|
166
166
|
canns/utils/__init__.py,sha256=OMyZ5jqZAIUS2Jr0qcnvvrx6YM-BZ1EJy5uZYeA3HC0,366
|
|
167
167
|
canns/utils/benchmark.py,sha256=oJ7nvbvnQMh4_MZh7z160NPLp-197X0rEnmnLHYlev4,1361
|
|
168
|
-
canns-0.
|
|
169
|
-
canns-0.
|
|
170
|
-
canns-0.
|
|
171
|
-
canns-0.
|
|
172
|
-
canns-0.
|
|
168
|
+
canns-1.0.0.dist-info/METADATA,sha256=6k3grZUT-4Iw_wi9nqHcJzcHBVJpQA76EowoG9IprvU,9699
|
|
169
|
+
canns-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
170
|
+
canns-1.0.0.dist-info/entry_points.txt,sha256=57YF2HZp_BG3GeGB8L0m3wR1sSfNyMXF1q4CKEjce6U,164
|
|
171
|
+
canns-1.0.0.dist-info/licenses/LICENSE,sha256=u6NJ1N-QSnf5yTwSk5UvFAdU2yKD0jxG0Xa91n1cPO4,11306
|
|
172
|
+
canns-1.0.0.dist-info/RECORD,,
|
canns-0.15.1.dist-info/METADATA
DELETED
|
@@ -1,245 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: canns
|
|
3
|
-
Version: 0.15.1
|
|
4
|
-
Summary: A Python Library for Continuous Attractor Neural Networks
|
|
5
|
-
Project-URL: Repository, https://github.com/routhleck/canns
|
|
6
|
-
Author-email: Sichao He <sichaohe@outlook.com>
|
|
7
|
-
License-Expression: Apache-2.0
|
|
8
|
-
License-File: LICENSE
|
|
9
|
-
Classifier: Development Status :: 4 - Beta
|
|
10
|
-
Classifier: Intended Audience :: Developers
|
|
11
|
-
Classifier: Operating System :: OS Independent
|
|
12
|
-
Classifier: Programming Language :: Python
|
|
13
|
-
Classifier: Programming Language :: Python :: 3
|
|
14
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
-
Classifier: Typing :: Typed
|
|
18
|
-
Requires-Python: <4.0,>=3.11
|
|
19
|
-
Requires-Dist: brainpy[cpu]
|
|
20
|
-
Requires-Dist: canns-lib>=0.6.2
|
|
21
|
-
Requires-Dist: climage>=0.2.2
|
|
22
|
-
Requires-Dist: furo>=2025.7.19
|
|
23
|
-
Requires-Dist: h5py>=3.7
|
|
24
|
-
Requires-Dist: igraph>=1.0.0
|
|
25
|
-
Requires-Dist: imageio[ffmpeg]>=2.37.0
|
|
26
|
-
Requires-Dist: leidenalg>=0.11.0
|
|
27
|
-
Requires-Dist: matplotlib>=3.5
|
|
28
|
-
Requires-Dist: notebook>=7.4.4
|
|
29
|
-
Requires-Dist: numba>=0.56.0
|
|
30
|
-
Requires-Dist: numpy<2.3,>=1.24
|
|
31
|
-
Requires-Dist: scikit-image>=0.19
|
|
32
|
-
Requires-Dist: scipy>=1.9.0
|
|
33
|
-
Requires-Dist: seaborn>=0.13.2
|
|
34
|
-
Requires-Dist: textual>=7.3.0
|
|
35
|
-
Requires-Dist: tqdm
|
|
36
|
-
Provides-Extra: cpu
|
|
37
|
-
Requires-Dist: brainpy[cpu]; extra == 'cpu'
|
|
38
|
-
Provides-Extra: cuda12
|
|
39
|
-
Requires-Dist: brainpy[cuda12]; (platform_system == 'Linux') and extra == 'cuda12'
|
|
40
|
-
Provides-Extra: cuda13
|
|
41
|
-
Requires-Dist: brainpy[cuda13]; (platform_system == 'Linux') and extra == 'cuda13'
|
|
42
|
-
Provides-Extra: gui
|
|
43
|
-
Requires-Dist: imageio; extra == 'gui'
|
|
44
|
-
Requires-Dist: pillow; extra == 'gui'
|
|
45
|
-
Requires-Dist: pyside6>=6.6.0; extra == 'gui'
|
|
46
|
-
Requires-Dist: qtawesome; extra == 'gui'
|
|
47
|
-
Requires-Dist: requests>=2.31.0; extra == 'gui'
|
|
48
|
-
Provides-Extra: tpu
|
|
49
|
-
Requires-Dist: brainpy[tpu]; (platform_system == 'Linux') and extra == 'tpu'
|
|
50
|
-
Description-Content-Type: text/markdown
|
|
51
|
-
|
|
52
|
-
# CANNs: Continuous Attractor Neural Networks Toolkit
|
|
53
|
-
|
|
54
|
-
<div align="center">
|
|
55
|
-
<img src="images/logo.svg" alt="CANNs Logo" width="350">
|
|
56
|
-
</div>
|
|
57
|
-
|
|
58
|
-
[<img src="https://badges.ws/badge/status-beta-yellow" />](https://github.com/routhleck/canns)
|
|
59
|
-
|
|
60
|
-
[<img src="https://badges.ws/maintenance/yes/2026" />](https://github.com/routhleck/canns)
|
|
61
|
-
<picture><img src="https://badges.ws/github/release/routhleck/canns" /></picture>
|
|
62
|
-
<picture><img src="https://badges.ws/github/license/routhleck/canns" /></picture>
|
|
63
|
-
[](https://doi.org/10.5281/zenodo.17412545)
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
<picture><img src="https://badges.ws/github/stars/routhleck/canns?logo=github" /></picture>
|
|
67
|
-
[](https://pepy.tech/projects/canns)
|
|
68
|
-
[](https://deepwiki.com/Routhleck/canns)
|
|
69
|
-
[<img src="https://badges.ws/badge/Buy_Me_a_Coffee-ff813f?icon=buymeacoffee" />](https://buymeacoffee.com/forrestcai6)
|
|
70
|
-
|
|
71
|
-
> 中文说明请见 [README_zh.md](README_zh.md)
|
|
72
|
-
|
|
73
|
-
CANNs is a Python library built on top of brainpy with performance‑critical modules accelerated by a dedicated Rust backend (`canns-lib`). It streamlines experimentation with continuous attractor neural networks and related brain‑inspired models, providing ready‑to‑use models, task generators, analysis tools, and pipelines so neuroscience and AI researchers can move from ideas to reproducible simulations quickly.
|
|
74
|
-
|
|
75
|
-
## Highlights
|
|
76
|
-
|
|
77
|
-
- **Model families** – `canns.models.basic` ships 1D/2D CANNs (including SFA variants and hierarchical networks), while `canns.models.brain_inspired` adds Hopfield-style systems.
|
|
78
|
-
- **Task-first API** – `canns.task.tracking` and `canns.task.open_loop_navigation` generate smooth tracking inputs, population coding stimuli, or import experimental trajectories.
|
|
79
|
-
- **Rich analysis suite** – `canns.analyzer` covers energy landscapes, tuning curves, spike embeddings, UMAP/TDA helpers, and theta-sweep animations.
|
|
80
|
-
- **Unified training** – `canns.trainer.HebbianTrainer` implements generic Hebbian learning and prediction, layered on the abstract `Trainer` base.
|
|
81
|
-
- **Pipeline workspace** – the ASA GUI (Attractor Structure Analyzer) provides an end-to-end analysis workflow (TDA → decode → CohoMap/CohoSpace/FR/FRM) with interactive visualization, help tips, and bilingual UI.
|
|
82
|
-
- **Extensible foundations** – base classes (`BasicModel`, `Task`, `Trainer`, `Pipeline`) keep custom components consistent with the built-in ecosystem.
|
|
83
|
-
|
|
84
|
-
## Visual Gallery
|
|
85
|
-
|
|
86
|
-
<div align="center">
|
|
87
|
-
<table>
|
|
88
|
-
<tr>
|
|
89
|
-
<td align="center" width="50%" valign="top">
|
|
90
|
-
<h4>1D CANN Smooth Tracking</h4>
|
|
91
|
-
<img src="docs/_static/smooth_tracking_1d.gif" alt="1D CANN Smooth Tracking" width="320">
|
|
92
|
-
<br><em>Real-time dynamics during smooth tracking</em>
|
|
93
|
-
</td>
|
|
94
|
-
<td align="center" width="50%" valign="top">
|
|
95
|
-
<h4>2D CANN Population Encoding</h4>
|
|
96
|
-
<img src="docs/_static/CANN2D_encoding.gif" alt="2D CANN Encoding" width="320">
|
|
97
|
-
<br><em>Spatial information encoding patterns</em>
|
|
98
|
-
</td>
|
|
99
|
-
</tr>
|
|
100
|
-
<tr>
|
|
101
|
-
<td colspan="2" align="center">
|
|
102
|
-
<h4>Theta Sweep Analysis</h4>
|
|
103
|
-
<img src="docs/_static/theta_sweep_animation.gif" alt="Theta Sweep Animation" width="600">
|
|
104
|
-
<br><em>Grid cell and head direction networks with theta rhythm modulation</em>
|
|
105
|
-
</td>
|
|
106
|
-
</tr>
|
|
107
|
-
<tr>
|
|
108
|
-
<td align="center" width="50%" valign="top">
|
|
109
|
-
<h4>Bump Analysis</h4>
|
|
110
|
-
<img src="docs/_static/bump_analysis_demo.gif" alt="Bump Analysis Demo" width="320">
|
|
111
|
-
<br><em>1D bump fitting and analysis</em>
|
|
112
|
-
</td>
|
|
113
|
-
<td align="center" width="50%" valign="top">
|
|
114
|
-
<h4>Torus Topology Analysis</h4>
|
|
115
|
-
<img src="docs/_static/torus_bump.gif" alt="Torus Bump Analysis" width="320">
|
|
116
|
-
<br><em>3D torus visualization and decoding</em>
|
|
117
|
-
</td>
|
|
118
|
-
</tr>
|
|
119
|
-
</table>
|
|
120
|
-
</div>
|
|
121
|
-
|
|
122
|
-
## Installation
|
|
123
|
-
|
|
124
|
-
```bash
|
|
125
|
-
# CPU-only installation
|
|
126
|
-
pip install canns
|
|
127
|
-
|
|
128
|
-
# Optional accelerators (Linux only)
|
|
129
|
-
pip install canns[cuda12]
|
|
130
|
-
pip install canns[tpu]
|
|
131
|
-
|
|
132
|
-
# GUI (recommended for pipeline usage)
|
|
133
|
-
pip install canns[gui]
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
## Quick Start
|
|
138
|
-
|
|
139
|
-
```python
|
|
140
|
-
import brainpy as bp
|
|
141
|
-
import brainpy.math as bm
|
|
142
|
-
from canns.models.basic import CANN1D
|
|
143
|
-
from canns.task.tracking import SmoothTracking1D
|
|
144
|
-
|
|
145
|
-
bm.set_dt(0.1)
|
|
146
|
-
|
|
147
|
-
cann = CANN1D(num=512)
|
|
148
|
-
|
|
149
|
-
task = SmoothTracking1D(
|
|
150
|
-
cann_instance=cann,
|
|
151
|
-
Iext=(0.0, 0.5, 1.0, 1.5),
|
|
152
|
-
duration=(5.0, 5.0, 5.0, 5.0),
|
|
153
|
-
time_step=bm.get_dt(),
|
|
154
|
-
)
|
|
155
|
-
task.get_data()
|
|
156
|
-
|
|
157
|
-
def step(t, stimulus):
|
|
158
|
-
cann(stimulus)
|
|
159
|
-
return cann.u.value, cann.inp.value
|
|
160
|
-
|
|
161
|
-
us, inputs = bm.for_loop(
|
|
162
|
-
step,
|
|
163
|
-
task.run_steps,
|
|
164
|
-
task.data,
|
|
165
|
-
)
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
For the ASA pipeline, the recommended entrypoint is the GUI:
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
canns-gui
|
|
172
|
-
# or
|
|
173
|
-
python -m canns.pipeline.asa_gui
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
> Note: ASA TUI (`python -m canns.pipeline.asa` / `canns-tui`) is a legacy interface kept for transition.
|
|
177
|
-
|
|
178
|
-
## Documentation & Notebooks
|
|
179
|
-
|
|
180
|
-
- [Quick Start Guide](https://routhleck.com/canns/en/notebooks/01_quick_start.html) – condensed tour of the library layout.
|
|
181
|
-
- [Design Philosophy](https://routhleck.com/canns/en/notebooks/00_design_philosophy.html) – detailed design rationale for each module.
|
|
182
|
-
- Interactive launchers: [](https://mybinder.org/v2/gh/routhleck/canns/HEAD?filepath=docs%2Fen%2Fnotebooks) [](https://colab.research.google.com/github/routhleck/canns/blob/master/docs/en/notebooks/)
|
|
183
|
-
- Tutorials (Chinese, online):
|
|
184
|
-
- [ASA GUI end-to-end](https://routhleck.com/canns/zh/3_full_detail_tutorials/04_pipeline/03_asa_gui.html)
|
|
185
|
-
- [ASA pipeline principles & parameters](https://routhleck.com/canns/zh/3_full_detail_tutorials/02_data_analysis/01_asa_pipeline.html)
|
|
186
|
-
- [Cell classification](https://routhleck.com/canns/zh/3_full_detail_tutorials/02_data_analysis/04_cell_classification.html)
|
|
187
|
-
|
|
188
|
-
## Development Workflow
|
|
189
|
-
|
|
190
|
-
```bash
|
|
191
|
-
# Create the dev environment (uv-based)
|
|
192
|
-
make install
|
|
193
|
-
|
|
194
|
-
# Format and lint (ruff, codespell, etc.)
|
|
195
|
-
make lint
|
|
196
|
-
|
|
197
|
-
# Run the test suite (pytest)
|
|
198
|
-
make test
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
Additional scripts live under `devtools/` and `scripts/`.
|
|
202
|
-
|
|
203
|
-
## Repository Layout
|
|
204
|
-
|
|
205
|
-
```
|
|
206
|
-
src/canns/ Core library modules (models, tasks, analyzers, trainer, pipeline)
|
|
207
|
-
docs/ Sphinx documentation and notebooks
|
|
208
|
-
examples/ Ready-to-run scripts for models, analysis, and pipelines
|
|
209
|
-
tests/ Pytest coverage for key behaviours
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
## Citation
|
|
213
|
-
|
|
214
|
-
If you use CANNs in your research, please cite it using the information from our [CITATION.cff](CITATION.cff) file or use the following:
|
|
215
|
-
|
|
216
|
-
[](https://doi.org/10.5281/zenodo.17412545)
|
|
217
|
-
|
|
218
|
-
```bibtex
|
|
219
|
-
@software{he_2025_canns,
|
|
220
|
-
author = {He, Sichao},
|
|
221
|
-
title = {CANNs: Continuous Attractor Neural Networks Toolkit},
|
|
222
|
-
year = 2025,
|
|
223
|
-
publisher = {Zenodo},
|
|
224
|
-
version = {v0.9.0},
|
|
225
|
-
doi = {10.5281/zenodo.17412545},
|
|
226
|
-
url = {https://github.com/Routhleck/canns}
|
|
227
|
-
}
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
## Contributing
|
|
231
|
-
|
|
232
|
-
Contributions are welcome! Please open an issue or discussion if you plan significant changes. Pull requests should follow the existing lint/test workflow (`make lint && make test`).
|
|
233
|
-
|
|
234
|
-
## License
|
|
235
|
-
|
|
236
|
-
Apache License 2.0. See [LICENSE](LICENSE) for details.
|
|
237
|
-
|
|
238
|
-
[contributors-shield]: https://img.shields.io/github/contributors/routhleck/canns.svg?style=for-the-badge
|
|
239
|
-
[contributors-url]: https://github.com/routhleck/canns/graphs/contributors
|
|
240
|
-
[stars-shield]: https://img.shields.io/github/stars/routhleck/canns.svg?style=for-the-badge
|
|
241
|
-
[stars-url]: https://github.com/routhleck/canns/stargazers
|
|
242
|
-
[issues-shield]: https://img.shields.io/github/issues/routhleck/canns.svg?style=for-the-badge
|
|
243
|
-
[issues-url]: https://github.com/routhleck/canns/issues
|
|
244
|
-
[license-shield]: https://img.shields.io/github/license/routhleck/canns.svg?style=for-the-badge
|
|
245
|
-
[license-url]: https://github.com/routhleck/canns/blob/master/LICENSE
|
|
File without changes
|
|
File without changes
|
|
File without changes
|