Skip to main contentcanns-toolkit-attractor-networks
Comprehensive open-source toolkit unifying continuous attractor neural network (CANN) research workflow. Three co-designed components (Python/Rust/GUI) for 1D/2D attractor modeling, spike-frequency adaptation, grid cells, path integration, and persistent homology-based attractor detection in neural recordings.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/hiyenwong/ai_collection --skill canns-toolkit-attractor-networks命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
| name | canns-toolkit-attractor-networks |
| description | Comprehensive open-source toolkit unifying continuous attractor neural network (CANN) research workflow. Three co-designed components (Python/Rust/GUI) for 1D/2D attractor modeling, spike-frequency adaptation, grid cells, path integration, and persistent homology-based attractor detection in neural recordings. |
| version | 1.0.0 |
| tags | ["neuroscience","continuous-attractor","grid-cells","place-cells","head-direction","path-integration","persistent-homology","topological-data-analysis","BrainPy","JAX","hippocampus","entorhinal-cortex"] |
| arxiv | 2606.27783 |
| authors | ["Sichao He","Aiersi Tuerhong","Shangjun She","Tianhao Chu","Yuling Wu","Junfeng Zuo","Si Wu"] |
| institution | Peking University |
| published | 2026-06-30 |
CANNs: A Toolkit for Research on Continuous Attractor Neural Networks
Core Methodology
1. What are Continuous Attractor Neural Networks (CANNs)?
Canonical computational framework for how the brain encodes continuous variables:
- Spatial position (hippocampal place cells)
- Head direction (head-direction cells)
- Movement direction (entorhinal grid cells)
Key properties:
- Recurrently connected population with localized "bump" of activity
- Bump smoothly translates along low-dimensional manifold
- Provides stability, noise robustness, and integration
- Manifold topology: ring (S¹) for 1D, torus (T²) for 2D
Biological grounding:
- Place cells (O'Keefe & Dostrovsky, 1971)
- Grid cells (Hafting et al., 2005)
- Head-direction cells (Taube et al., 1990)
2. Mathematical Core (Wu-Amari-Wong Model)
Network architecture:
- N neurons on 1D ring or 2D torus
- Translation-invariant recurrent connectivity (Gaussian kernel)
- Divisive normalization implements global inhibition
- Continuum of stable bump states parameterized by continuous variable
Dynamics:
τ du/dt = -u + ∫ J(u,v) r(v) dv + I_ext
r = [u]² / (1 + k ∫ [u]² du) # divisive normalization
Where:
- u: internal state
- r: firing rate
- J: recurrent connectivity kernel (Gaussian)
- k: global inhibition strength
- I_ext: external input
Energy landscape:
E(r) = -1/2 r^T W r + I^T r
Key behaviors:
- Bump can be moved arbitrarily by localized input
- When input disappears, bump remains (short-term memory)
- Attractor structure provides built-in integrator
3. CANNs Toolkit Architecture
Three co-designed components:
A. canns (Python library on BrainPy/JAX)
Modules:
-
Models (canns.models): Neural network dynamics
- 1D ring CANN (head-direction)
- 2D torus CANN (place fields)
Tasks (canns.task): Experimental paradigms
- Spatial navigation
- Head-direction tracking
- Grid cell firing field generation
- Parametric working memory
Analyzers (canns.analyzer): Visualization and analysis
- Energy landscape computation
- Manifold extraction (PCA, UMAP)
- Tuning curve fitting
- Topological data analysis integration
Trainers (canns.trainer): Biologically plausible learning
- Hebbian plasticity
- STDP-like rules
- Homeostatic mechanisms
Pipeline (canns.pipeline): Orchestration
- Full workflow from simulation to analysis
- Reproducible experiment scripts
B. canns-lib (Rust acceleration backend)
Performance-critical operations:
- Ripser-based persistent homology (hundreds-of-times speedup)
- Long spatial navigation trajectories
- Bulk task generation
- Python FFI for seamless integration
C. ASA (Attractor Structure Analyzer - PySide6 GUI)
Purpose: Detect attractor topology in experimental neural recordings
- Data ingestion (.npz format)
- Preprocessing (spike/rate extraction)
- Point cloud construction (time-indexed or spatially-indexed)
- Persistent homology computation
- Shuffle controls (statistical significance)
- Persistent cohomology decoding (CohoMap/EcohoMap)
- Circular coordinate extraction
- Grid score computation
- Module-level workflows
- GUI + CLI interfaces
- Ring (S¹): One dominant H₁ barcode → head-direction cells, band cells, 1D CANN
- Torus (T² = S¹×S¹): Two stable H₁ features → grid-cell modules, 2D CANN
4. Advanced CANN Variants
A. Spike-Frequency Adaptation (SFA)
Mechanism: Activity-dependent negative feedback
- Turns static bump into moving wave
- Enables anticipative tracking
- Models theta sweeps and phase precession
τ_a da/dt = -a + b * r
τ du/dt = -u + ∫ J r dv - g_a * a + I_ext
- a: adaptation current
- b: adaptation strength
- g_a: adaptation conductance
B. Theta-Rhythmic Modulation
- Theta sweeps (forward/backward)
- Phase precession
- Phase procession
theta(t) = sin(2π f_theta t + φ)
I_mod = I_baseline + A_theta * theta(t)
C. Hierarchical Path Integration
Architecture: Multiple grid-cell modules with different spatial scales
- Coarse modules: large grid spacing
- Fine modules: small grid spacing
- Hierarchical combination → precise position coding
5. Topological Data Analysis (TDA) for Attractor Detection
- Track topological features (connected components, loops, voids) across scales
- Barcode: persistence of features vs. scale parameter
- Stable features = true topology; transient = noise
Application to neural data:
from ripser import ripser
r(t) = [r₁(t), r₂(t), ..., rₙ(t)]^T ∈ ℝ^N
X_t = {r(tⱼ) : j = 1, ..., T} ⊂ ℝ^N
result = ripser(X_t, maxdim=2)
diagrams = result['dgms']
ring_signature = len(diagrams[1]) > 0 and diagrams[1][0, 1] > threshold
torus_signature = len(diagrams[1]) >= 2 and diagrams[1][1, 1] > threshold
Persistent Cohomology Decoding:
- Extract circular coordinates from cohomology generators
- Map high-dimensional activity to S¹ (ring) or T² (torus)
- Validate by alignment with behavioral variables
- Efficient cohomology computation
- Cache-aware result management
- Module-level workflows
- Surrogate data with destroyed topology
- Statistical significance testing
- Distinguish true attractor from noise
6. Reproducible Research Pipelines
Example: 1D Ring CANN (Head Direction)
from canns.models import CANN1D
from canns.task import HeadDirectionTracking
from canns.analyzer import EnergyLandscape, ManifoldAnalysis
net = CANN1D(N=512, J0=1.0, a=0.5, k=0.1)
task = HeadDirectionTracking(n_directions=4, delay=500)
inputs = task.sample()
outputs, states = net.simulate(inputs, T=2000)
energy = EnergyLandscape(net.W)
energy.plot()
manifold = ManifoldAnalysis(states)
manifold.pca(n_components=3)
manifold.umap(n_neighbors=15)
from canns.analyzer import PersistentHomology
ph = PersistentHomology()
barcode = ph.compute(states)
assert ph.is_ring_attractor(barcode)
Example: Real Neural Recording Analysis with ASA
from asa import AttractorStructureAnalyzer
data = asa.load('mec_grid_cells.npz')
rates = asa.extract_rates(data, bin_size=50)
asa_pipeline = AttractorStructureAnalyzer()
result = asa_pipeline.analyze(
rates,
method='persistent_cohomology',
maxdim=2,
shuffle_controls=100
)
if result.is_torus():
print("Grid-cell module detected: toroidal topology")
circular_coords = result.decode_circular_coordinates()
grid_score = result.compute_grid_score(circular_coords)
elif result.is_ring():
print("Head-direction or band-cell ring attractor")
phase = result.decode_ring_phase()
7. Key Capabilities
- SFA-driven anticipative tracking
- Theta sweeps in head-direction/place/grid systems
- Hierarchical path integration
- Real MEC grid-cell module analysis (heterogeneous topology)
- Head-direction cell ring attractor detection
- GridScore: quantify hexagonal firing fields
- CohoScore: topological signature strength
- PathCompare: compare trajectories across conditions
- Module-level workflows for common analyses
8. Installation and Usage
pip install canns
pip install canns[gui]
pip install asa-attractor-analyzer
import canns
net = canns.models.GridCellNetwork(module_id=1)
positions, firing_rates = net.simulate_navigation(
trajectory='random_walk',
duration=600
)
from canns.analyzer import GridFieldAnalysis
gfa = GridFieldAnalysis()
grid_score = gfa.compute_score(firing_rates, positions)
gfa.plot_firing_fields(firing_rates, positions)
Key Insights
1. Unification of CANN Research
Problem: CANN research fragmented across:
- Lab-specific implementations
- General-purpose simulators (NEURON, BRIAN) lack CANN-specific abstractions
- No standardized path from spike trains to attractor geometry
Solution: Unified toolkit covering:
- Modeling (canns)
- Acceleration (canns-lib)
- Experimental analysis (ASA)
- Reproducible pipelines
2. Topological Signatures as Biomarkers
Finding: Real MEC grid-cell modules show heterogeneous topology
- Some modules: clear toroidal signature
- Others: partial or unstable topology
- Suggests: not all grid-cell modules are perfect CANNs
Implication: Persistent homology provides quantitative biomarker for:
- Attractor quality (how "perfect" is the CANN?)
- Disease states (does Alzheimer's degrade toroidal topology?)
- Development (how does topology emerge during learning?)
3. Rust Acceleration Matters
- Persistent homology: 100-1000× speedup
- Spatial navigation: efficient long trajectories
- Enables: real-time analysis of large datasets
- Memory safety without garbage collection
- Zero-cost abstractions
- Seamless Python FFI
4. Separation of Concerns
- Models: define dynamics
- Tasks: generate inputs
- Analyzers: visualize/analyze (no state modification)
- Trainers: update parameters
- Pipeline: orchestrate
Benefit: Modular, extensible, reproducible
Experimental Validation
Predictions for Empirical Testing
-
Topology heterogeneity: Different grid-cell modules should show varying topological "perfection" (testable with large-scale MEC recordings)
-
Disease biomarkers: Neurodegenerative diseases should degrade toroidal topology (Alzheimer's → entorhinal cortex degradation)
-
Development trajectory: Toroidal topology should emerge during learning (young animals → less stable topology)
-
SFA signature: Theta sweeps and phase precession should correlate with SFA strength (testable via pharmacological manipulation)
Limitations
- Rate-based models (most implementations) → cannot capture spike timing
- Assumes translation-invariant connectivity → biological networks have variability
- Persistent homology computationally expensive for very large populations (>10,000 neurons)
- No direct spike-train analysis (requires rate conversion)
Extensions
- Spiking CANNs: Implement leaky integrate-and-fire or adaptive exponential integrate-and-fire neurons
- Learning rules: Add biologically plausible synaptic plasticity (STDP, homeostatic)
- Multi-region models: Connect hippocampus, entorhinal cortex, head-direction circuits
- Behavioral coupling: Link attractor dynamics to decision-making and navigation behavior
- GPU acceleration: JAX backend already supports GPU; extend Rust backend for CUDA
References
- arXiv:2606.27783 - Original paper
- Amari (1977a) - Lateral-inhibition neural fields
- Wu et al. (2008, 2016) - Analytically solvable CANN model
- Gardner et al. (2022) - Toroidal population geometry in grid cells
- Mi et al. (2014) - Spike-frequency adaptation in CANNs
- Chu et al. (2024, 2025) - Theta rhythms and hierarchical path integration
Activation Keywords
continuous attractor neural network, CANN, grid cells, place cells, head-direction cells, path integration, persistent homology, topological data analysis, BrainPy, JAX, hippocampus, entorhinal cortex, spatial navigation, ring attractor, torus attractor, spike-frequency adaptation, theta sweeps, phase precession, manifold learning, neural manifold, attractor analysis, ASA toolkit
